diff --git a/.gitignore b/.gitignore index 17c3d9fa..e430d78f 100644 --- a/.gitignore +++ b/.gitignore @@ -26,4 +26,6 @@ packages/ !*.lib # Resources bin -*.aps \ No newline at end of file +*.aps + +docs/ \ No newline at end of file diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000..68464f37 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,86 @@ +# Doxyfile 1.8.16 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +PROJECT_NAME = "Kiwano Engine" +PROJECT_NUMBER = v1.0.0 +PROJECT_BRIEF = +PROJECT_LOGO = logo/logo_square_tiny.png + +DOXYFILE_ENCODING = UTF-8 +CREATE_SUBDIRS = YES + +OUTPUT_LANGUAGE = Chinese +OUTPUT_DIRECTORY = docs/ + +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = NO + +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = NO + +SHOW_INCLUDE_FILES = YES +SHOW_USED_FILES = NO +SHOW_FILES = NO +SHOW_NAMESPACES = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- + +INPUT = src/ +INPUT_ENCODING = gb2312 +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + +RECURSIVE = YES +EXCLUDE = src/3rd-party + +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +PREDEFINED = KGE_API= + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by the +# preprocessor. +# This tag requires that the tag SEARCH_INCLUDES is set to YES. + +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = + +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- + +GENERATE_HTML = YES +HTML_OUTPUT = html + +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = + +GENERATE_TREEVIEW = YES +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 + +#--------------------------------------------------------------------------- +# Configuration options related to the LATEX output +#--------------------------------------------------------------------------- + +GENERATE_LATEX = NO diff --git a/logo/logo_square_tiny.png b/logo/logo_square_tiny.png new file mode 100644 index 00000000..63829ef3 Binary files /dev/null and b/logo/logo_square_tiny.png differ diff --git a/src/3rd-party/OuterC/oc/intrusive_list.h b/src/3rd-party/OuterC/oc/intrusive_list.h index 4fc79ed3..7138a22c 100644 --- a/src/3rd-party/OuterC/oc/intrusive_list.h +++ b/src/3rd-party/OuterC/oc/intrusive_list.h @@ -31,7 +31,7 @@ private: pointer_type prev_; pointer_type next_; - friend class intrusive_list<_Ty>; + friend class intrusive_list<_Ty, _PTy>; }; diff --git a/src/kiwano-audio/AudioEngine.h b/src/kiwano-audio/AudioEngine.h index 9bb8e177..9d0fb384 100644 --- a/src/kiwano-audio/AudioEngine.h +++ b/src/kiwano-audio/AudioEngine.h @@ -33,7 +33,7 @@ namespace kiwano : public Singleton , public ComponentBase { - OC_DECLARE_SINGLETON(AudioEngine); + friend Singleton; public: // 开启设备 diff --git a/src/kiwano-imgui/ImGuiModule.h b/src/kiwano-imgui/ImGuiModule.h index f5e3fffa..5ec0e712 100644 --- a/src/kiwano-imgui/ImGuiModule.h +++ b/src/kiwano-imgui/ImGuiModule.h @@ -32,7 +32,7 @@ namespace kiwano , public UpdateComponent , public EventComponent { - OC_DECLARE_SINGLETON(ImGuiModule); + friend Singleton; private: void Init(HWND hwnd); diff --git a/src/kiwano-network/HttpClient.h b/src/kiwano-network/HttpClient.h index 7008b212..17ccaf6a 100644 --- a/src/kiwano-network/HttpClient.h +++ b/src/kiwano-network/HttpClient.h @@ -32,7 +32,7 @@ namespace kiwano : public Singleton , public ComponentBase { - OC_DECLARE_SINGLETON(HttpClient); + friend Singleton; public: void Send(HttpRequestPtr request); diff --git a/src/kiwano/core/Component.h b/src/kiwano/core/Component.h index 9dde2529..577e541d 100644 --- a/src/kiwano/core/Component.h +++ b/src/kiwano/core/Component.h @@ -27,11 +27,19 @@ namespace kiwano class RenderTarget; class Event; - // 基础组件 + /** + * \~chinese + * @brief 基础功能组件 + */ class KGE_API ComponentBase { public: + /// \~chinese + /// @brief 启动组件 virtual void SetupComponent() = 0; + + /// \~chinese + /// @brief 销毁组件 virtual void DestroyComponent() = 0; bool Check(const int flag); @@ -44,15 +52,25 @@ namespace kiwano }; - // 渲染支持组件 + /** + * \~chinese + * @brief 渲染支持组件 + */ class KGE_API RenderComponent : public virtual ComponentBase { public: + /// \~chinese + /// @brief 渲染前 virtual void BeforeRender() {} - virtual void OnRender(RenderTarget*) {} + /// \~chinese + /// @brief 渲染时 + /// @param rt 渲染目标 + virtual void OnRender(RenderTarget* rt) {} + /// \~chinese + /// @brief 渲染后 virtual void AfterRender() {} public: @@ -62,15 +80,25 @@ namespace kiwano }; - // 更新支持组件 + /** + * \~chinese + * @brief 更新支持组件 + */ class KGE_API UpdateComponent : public virtual ComponentBase { public: + /// \~chinese + /// @brief 更新前 virtual void BeforeUpdate() {} - virtual void OnUpdate(Duration) {} + /// \~chinese + /// @brief 更新时 + /// @param dt 间隔时间 + virtual void OnUpdate(Duration dt) {} + /// \~chinese + /// @brief 更新后 virtual void AfterUpdate() {} public: @@ -80,13 +108,21 @@ namespace kiwano }; - // 事件支持组件 + /** + * \~chinese + * @brief 事件支持组件 + */ class KGE_API EventComponent : public virtual ComponentBase { public: - virtual void HandleEvent(Event&) {} + /// \~chinese + /// @brief 事件处理 + /// @param evt 事件 + virtual void HandleEvent(Event& evt) {} + /// \~chinese + /// @brief Windows 消息处理 virtual void HandleMessage(HWND, UINT32, WPARAM, LPARAM) {} public: diff --git a/src/kiwano/core/Logger.h b/src/kiwano/core/Logger.h index 60e224eb..71f75403 100644 --- a/src/kiwano/core/Logger.h +++ b/src/kiwano/core/Logger.h @@ -55,7 +55,7 @@ namespace kiwano class KGE_API Logger : public Singleton { - OC_DECLARE_SINGLETON(Logger); + friend Singleton; public: // 显示或关闭控制台 diff --git a/src/kiwano/core/keys.h b/src/kiwano/core/keys.h index 4f2839dc..f259a0da 100644 --- a/src/kiwano/core/keys.h +++ b/src/kiwano/core/keys.h @@ -23,103 +23,105 @@ namespace kiwano { - // 鼠标按键 + /// \~chinese + /// @brief 鼠标按键 struct MouseButton { typedef int Value; enum : Value { - Left = VK_LBUTTON, // 鼠标左键 - Right = VK_RBUTTON, // 鼠标右键 - Middle = VK_MBUTTON // 鼠标中键 + Left = VK_LBUTTON, ///< 鼠标左键 + Right = VK_RBUTTON, ///< 鼠标右键 + Middle = VK_MBUTTON ///< 鼠标中键 }; }; - // 按键键值 + /// \~chinese + /// @brief 按键键值 struct KeyCode { typedef int Value; enum : Value { - Unknown = 0, - Up = VK_UP, - Left = VK_LEFT, - Right = VK_RIGHT, - Down = VK_DOWN, - Enter = VK_RETURN, - Space = VK_SPACE, - Esc = VK_ESCAPE, - Ctrl = VK_CONTROL, - Shift = VK_SHIFT, - Alt = VK_MENU, - Tab = VK_TAB, - Delete = VK_DELETE, - Back = VK_BACK, + Unknown = 0, ///< 未知 + Up = VK_UP, ///< 上键 + Left = VK_LEFT, ///< 左键 + Right = VK_RIGHT, ///< 右键 + Down = VK_DOWN, ///< 下键 + Enter = VK_RETURN, ///< 回车键 + Space = VK_SPACE, ///< 空格键 + Esc = VK_ESCAPE, ///< 退出键 + Ctrl = VK_CONTROL, ///< CTRL键 + Shift = VK_SHIFT, ///< SHIFT键 + Alt = VK_MENU, ///< ALT键 + Tab = VK_TAB, ///< TAB键 + Delete = VK_DELETE, ///< 删除键 + Back = VK_BACK, ///< 退格键 - A = 0x41, - B, - C, - D, - E, - F, - G, - H, - I, - J, - K, - L, - M, - N, - O, - P, - Q, - R, - S, - T, - U, - V, - W, - X, - Y, - Z, + A = 0x41, ///< A键 + B, ///< B键 + C, ///< C键 + D, ///< D键 + E, ///< E键 + F, ///< F键 + G, ///< G键 + H, ///< H键 + I, ///< I键 + J, ///< J键 + K, ///< K键 + L, ///< L键 + M, ///< M键 + N, ///< N键 + O, ///< O键 + P, ///< P键 + Q, ///< Q键 + R, ///< R键 + S, ///< S键 + T, ///< T键 + U, ///< U键 + V, ///< V键 + W, ///< W键 + X, ///< X键 + Y, ///< Y键 + Z, ///< Z键 - Num0 = 0x30, - Num1, - Num2, - Num3, - Num4, - Num5, - Num6, - Num7, - Num8, - Num9, + Num0 = 0x30, ///< 数字0键 + Num1, ///< 数字1键 + Num2, ///< 数字2键 + Num3, ///< 数字3键 + Num4, ///< 数字4键 + Num5, ///< 数字5键 + Num6, ///< 数字6键 + Num7, ///< 数字7键 + Num8, ///< 数字8键 + Num9, ///< 数字9键 - Numpad0 = VK_NUMPAD0, - Numpad1, - Numpad2, - Numpad3, - Numpad4, - Numpad5, - Numpad6, - Numpad7, - Numpad8, - Numpad9, + Numpad0 = VK_NUMPAD0, ///< 数字小键盘0键 + Numpad1, ///< 数字小键盘1键 + Numpad2, ///< 数字小键盘2键 + Numpad3, ///< 数字小键盘3键 + Numpad4, ///< 数字小键盘4键 + Numpad5, ///< 数字小键盘5键 + Numpad6, ///< 数字小键盘6键 + Numpad7, ///< 数字小键盘7键 + Numpad8, ///< 数字小键盘8键 + Numpad9, ///< 数字小键盘9键 - F1 = VK_F1, - F2, - F3, - F4, - F5, - F6, - F7, - F8, - F9, - F10, - F11, - F12, + F1 = VK_F1, ///< F1键 + F2, ///< F2键 + F3, ///< F3键 + F4, ///< F4键 + F5, ///< F5键 + F6, ///< F6键 + F7, ///< F7键 + F8, ///< F8键 + F9, ///< F9键 + F10, ///< F10键 + F11, ///< F11键 + F12, ///< F12键 }; }; } diff --git a/src/kiwano/core/time.cpp b/src/kiwano/core/time.cpp index ccdeb49f..b12bde7b 100644 --- a/src/kiwano/core/time.cpp +++ b/src/kiwano/core/time.cpp @@ -354,25 +354,24 @@ namespace kiwano return dur * val; } - Duration Duration::Parse(const String& str) + Duration Duration::Parse(const String& format) { - bool negative = false; - size_t len = str.length(); - size_t pos = 0; - Duration ret; + bool negative = false; + size_t len = format.length(); + size_t pos = 0; + Duration ret; - if (!std::regex_match(str.c_str(), duration_regex)) + if (!std::regex_match(format.c_str(), duration_regex)) { - KGE_ERROR(L"Duration::Parse failed, invalid duration"); - return ret; + throw std::runtime_error("Duration::Parse failed, invalid duration"); } - if (str.empty() || str == L"0") { return ret; } + if (format.empty() || format == L"0") { return ret; } // 符号位 - if (str[0] == L'-' || str[0] == L'+') + if (format[0] == L'-' || format[0] == L'+') { - negative = (str[0] == L'-'); + negative = (format[0] == L'-'); pos++; } @@ -382,32 +381,34 @@ namespace kiwano size_t i = pos; for (; i < len; ++i) { - wchar_t ch = str[i]; + wchar_t ch = format[i]; if (!(ch == L'.' || L'0' <= ch && ch <= L'9')) { break; } } - String num_str = str.substr(pos, i - pos); + String num_str = format.substr(pos, i - pos); pos = i; - KGE_ASSERT(!(num_str.empty() || num_str == L".") && "Duration::Parse failed, invalid duration"); + if (num_str.empty() || num_str == L".") + throw std::runtime_error("Duration::Parse failed, invalid duration"); // 单位 for (; i < len; ++i) { - wchar_t ch = str[i]; + wchar_t ch = format[i]; if (ch == L'.' || L'0' <= ch && ch <= L'9') { break; } } - String unit_str = str.substr(pos, i - pos); + String unit_str = format.substr(pos, i - pos); pos = i; - KGE_ASSERT(unit_map.find(unit_str) != unit_map.end() && "Duration::Parse failed, invalid duration"); + if (unit_map.find(unit_str) == unit_map.end()) + throw std::runtime_error("Duration::Parse failed, invalid duration"); double num = std::wcstod(num_str.c_str(), nullptr); Duration unit = unit_map.at(unit_str); diff --git a/src/kiwano/core/time.h b/src/kiwano/core/time.h index f6c47257..2e06bd74 100644 --- a/src/kiwano/core/time.h +++ b/src/kiwano/core/time.h @@ -24,51 +24,98 @@ namespace kiwano { - // 时间段 - // - // 时间段表示法: - // 5 秒: time::Second * 5 - // 1.5 小时: time::Hour * 1.5 - // 3 小时 45 分 15 秒: time::Hour * 3 + time::Minute * 45 + time::Second * 15 - // 在 VS2015 及更高版本可以使用 time literals: - // 5 秒: 5_s - // 1.5 小时: 1.5_h - // 3 小时 45 分 15 秒: 3_h + 45_m + 15_s - // + /** + * \~chinese + * @brief 时间段 + * @details + * 时间段表示法: + * 5 秒: time::Second * 5 + * 1.5 小时: time::Hour * 1.5 + * 3 小时 45 分 15 秒: time::Hour * 3 + time::Minute * 45 + time::Second * 15 + * 在 VS2015 及更高版本可以使用 time literals: + * 5 秒: 5_s + * 1.5 小时: 1.5_h + * 3 小时 45 分 15 秒: 3_h + 45_m + 15_s + */ struct KGE_API Duration { + /// \~chinese + /// @brief 构造时间段 Duration(); + /// \~chinese + /// @brief 构造时间段 + /// @param milliseconds 毫秒数 Duration( long milliseconds ); - // 转化为毫秒 + /// \~chinese + /// @brief 获取毫秒数 + /// @return 毫秒数 long Milliseconds() const; - // 转化为秒 + /// \~chinese + /// @brief 获取秒数 + /// @return 秒数 float Seconds() const; - // 转化为分钟 + /// \~chinese + /// @brief 获取分钟数 + /// @return 分钟数 float Minutes() const; - // 转化为小时 + /// \~chinese + /// @brief 获取小时数 + /// @return 小时数 float Hours() const; - // 时长是否是零 + /// \~chinese + /// @brief 时长是否是零 + /// @return 若时长是零,返回true bool IsZero() const; + /// \~chinese + /// @brief 设置毫秒数 + /// @param ms 毫秒数 void SetMilliseconds(long ms); + /// \~chinese + /// @brief 设置秒数 + /// @param seconds 秒数 void SetSeconds(float seconds); + /// \~chinese + /// @brief 设置分钟数 + /// @param minutes 分钟数 void SetMinutes(float minutes); + /// \~chinese + /// @brief 设置小时数 + /// @param hours 小时数 void SetHours(float hours); - // 转为字符串 + /// \~chinese + /// @brief 转为字符串 + /// @return 格式化后的字符串 String ToString() const; + /// \~chinese + /// @brief 时间段格式化 + /// @param format 格式 + /// @details + /// 时间段字符串允许是有符号的浮点数, 并且带有时间单位后缀 + /// 例如: "300ms", "-1.5h", "2h45m" + /// 允许的时间单位有 "ms", "s", "m", "h" + /// @return 解析出的时间段 + /// @throw std::runtime_error 传入了一个不合法的格式 + static Duration Parse(const String& str); + + static const Duration Ms; ///< 毫秒 + static const Duration Second; ///< 秒 + static const Duration Minute; ///< 分钟 + static const Duration Hour; ///< 小时 + bool operator== (const Duration &) const; bool operator!= (const Duration &) const; bool operator> (const Duration &) const; @@ -107,37 +154,38 @@ namespace kiwano friend const Duration operator/ (float, const Duration &); friend const Duration operator/ (double, const Duration &); - // 时间段格式化 - // - // 时间段字符串允许是有符号的浮点数, 并且带有时间单位后缀 - // 例如: "300ms", "-1.5h", "2h45m" - // 允许的时间单位有 "ms", "s", "m", "h" - static Duration Parse(const String& parse_str); - - static const Duration Ms; // 毫秒 - static const Duration Second; // 秒 - static const Duration Minute; // 分钟 - static const Duration Hour; // 小时 - private: long milliseconds_; }; - // 时间 - // - // 获取当前时间: Time now = Time::Now(); - // 两时间相减, 得到一个 Duration 对象, 例如: - // Time t1, t2; - // int ms = (t2 - t1).Milliseconds(); // 获取两时间相差的毫秒数 - // + /** + * \~chinese + * @brief 时间 + * @par 示例: + * @code + * // 两时间相减, 可得到一个 Duration 对象 + * Time t1 = Time::Now(); + * // 等待一段时间后 + * Time t2 = Time::Now(); + * int ms = (t2 - t1).Milliseconds(); // 获取两时间相差的毫秒数 + * @endcode + * @note 时间点与系统时钟无关,因此不能将时间点转化为时分秒 + */ struct KGE_API Time { Time(); - // 是否是零时 + /// \~chinese + /// @brief 是否是零时 + /// @return 若是零时,返回true bool IsZero() const; + /// \~chinese + /// @brief 获取当前时间 + /// @return 当前时间 + static Time Now() noexcept; + const Duration operator -(const Time&) const; const Time operator +(const Duration &) const; @@ -146,11 +194,6 @@ namespace kiwano Time& operator +=(const Duration &); Time& operator -=(const Duration &); - // 获取当前时间 - // 由于该时间点基于系统启动时间开始计算, 所以无法格式化该时间, - // 也无法获得该时间的 Unix 时间戳 - static Time Now() noexcept; - private: Time(long ms); diff --git a/src/kiwano/platform/Application.cpp b/src/kiwano/platform/Application.cpp index 62733d9f..3cd8c03c 100644 --- a/src/kiwano/platform/Application.cpp +++ b/src/kiwano/platform/Application.cpp @@ -262,10 +262,10 @@ namespace kiwano } } - void Application::PreformInMainThread(Function Function) + void Application::PreformInMainThread(Function func) { std::lock_guard lock(perform_mutex_); - functions_to_perform_.push(Function); + functions_to_perform_.push(func); } LRESULT CALLBACK Application::WndProc(HWND hwnd, UINT32 msg, WPARAM wparam, LPARAM lparam) diff --git a/src/kiwano/platform/Application.h b/src/kiwano/platform/Application.h index 7f6053ae..7c8efbc8 100644 --- a/src/kiwano/platform/Application.h +++ b/src/kiwano/platform/Application.h @@ -28,19 +28,36 @@ namespace kiwano { + /** + * \~chinese + * @brief 应用程序配置 + * @details 启动 Kiwano 应用程序前的初始化选项 + */ struct Config { - WindowConfig window; // 窗口设置 - RenderConfig render; // 渲染设置 - bool debug; // 调试模式 + WindowConfig window; ///< 窗口配置 + RenderConfig render; ///< 渲染配置 + bool debug; ///< 启用调试模式 + /** + * \~chinese + * @param title 窗口标题 + * @param width 窗口宽度 + * @param height 窗口高度 + * @param icon 窗口图标的资源ID + */ Config( - String const& title = L"Kiwano Game", + String const& title = L"Kiwano Game", uint32_t width = 640, - uint32_t height = 480, + uint32_t height = 480, uint32_t icon = 0 ); + /** + * \~chinese + * @param wnd_config 窗口配置 + * @param render_config 渲染配置 + */ Config( WindowConfig const& wnd_config, RenderConfig const& render_config = RenderConfig() @@ -48,7 +65,10 @@ namespace kiwano }; - // 应用 + /** + * \~chinese + * @brief 应用程序,控制游戏的整个生命周期,包括初始化、启动、结束以及事件分发等 + */ class KGE_API Application : protected Noncopyable { @@ -57,46 +77,94 @@ namespace kiwano virtual ~Application(); - // 初始化 + /** + * \~chinese + * @brief 初始化应用程序 + * @details 初始化所有功能组件后执行 OnReady 函数 + * @param config 初始化配置 + * @attention 应在使用其他功能前执行初始化,否则可能引发异常 + */ void Init( Config const& config = Config() ); - // 初始化成功时 + /** + * \~chinese + * @brief 初始化完成处理 + * @details 重载该函数以在应用程序初始化完成后自动执行 + */ virtual void OnReady() {} - // 窗口关闭时 + /** + * \~chinese + * @brief 窗口关闭处理 + * @details 重载该函数以处理用户关闭应用程序窗口时的行为 + * @return 返回 true 则正常关闭窗口,否则阻止窗口关闭 + */ virtual bool OnClosing() { return true; } - // 销毁时 + /** + * \~chinese + * @brief 应用程序销毁处理 + * @details 重载该函数以处理应用程序销毁时的行为,如完成资源回收等 + */ virtual void OnDestroy() {} - // 运行 + /** + * \~chinese + * @brief 启动应用程序 + * @note 该函数是阻塞的,应用程序结束时函数返回 + */ void Run(); - // 结束 + /** + * \~chinese + * @brief 终止应用程序 + */ void Quit(); - // 销毁 + /** + * \~chinese + * @brief 销毁游戏运行过程中产生的所有资源 + */ void Destroy(); - // 添加组件 + /** + * \~chinese + * @brief 添加功能组件 + * @param[in] component 功能组件 + */ void Use( ComponentBase* component ); - // 设置时间缩放因子 + /** + * \~chinese + * @brief 设置时间缩放因子 + * @details 设置时间缩放因子可等比例放大或缩小时间进度 + * @param scale_factor 缩放因子 + * @warning 设置为负数可能导致动画系统紊乱 + */ void SetTimeScale( float scale_factor ); - // 分发事件 + /** + * \~chinese + * @brief 分发事件 + * @details 将事件分发给所有事件功能组件 + * @param evt 事件 + */ void DispatchEvent(Event& evt); - // 在 Kiwano 主线程中执行函数 - // 当在其他线程调用 Kiwano 函数时使用 + /** + * \~chinese + * @brief 在主线程中执行函数 + * @details 提供在其他线程调用 Kiwano 函数的能力 + * @param func 需要执行的函数 + */ static void PreformInMainThread( - Function Function + Function func ); protected: diff --git a/src/kiwano/platform/Director.h b/src/kiwano/platform/Director.h index 4cd606b5..7c63666b 100644 --- a/src/kiwano/platform/Director.h +++ b/src/kiwano/platform/Director.h @@ -24,43 +24,75 @@ namespace kiwano { - // 导演 + /** + * \~chinese + * @brief 导演完成场景的渲染、更新、事件分发以及控制场景间跳转 + */ class KGE_API Director : public Singleton , public UpdateComponent , public RenderComponent , public EventComponent { - OC_DECLARE_SINGLETON(Director); + friend Singleton; public: - // 切换舞台 + /** + * \~chinese + * @brief 切换舞台 + * @param[in] stage 舞台 + * @param[in] transition 过渡动画 + */ void EnterStage( - StagePtr stage, /* 舞台 */ - TransitionPtr transition = nullptr /* 过渡动画 */ + StagePtr stage, + TransitionPtr transition = nullptr ); - // 舞台压栈 + /** + * \~chinese + * @brief 切换舞台,并将当前舞台压栈 + * @param[in] stage 舞台 + * @param[in] transition 过渡动画 + */ void PushStage( - StagePtr stage, /* 舞台 */ - TransitionPtr transition = nullptr /* 过渡动画 */ + StagePtr stage, + TransitionPtr transition = nullptr ); - // 舞台出栈 + /** + * \~chinese + * @brief 退出当前舞台,并切换到栈顶舞台 + * @param[in] transition 过渡动画 + */ void PopStage( - TransitionPtr transition = nullptr /* 过渡动画 */ + TransitionPtr transition = nullptr ); - // 获取当前舞台 + /** + * \~chinese + * @brief 获取当前舞台 + * @return 返回当前舞台的指针 + */ StagePtr GetCurrentStage(); - // 启用或禁用角色边界渲染功能 + /** + * \~chinese + * @brief 启用或禁用角色边界渲染功能 + * @param enabled 是否启用 + */ void SetRenderBorderEnabled(bool enabled); - // 显示调试信息 + /** + * \~chinese + * @brief 显示或隐藏调试信息 + * @param show 是否显示 + */ void ShowDebugInfo(bool show = true); - // 清空舞台 + /** + * \~chinese + * @brief 退出当前舞台并清空舞台栈 + */ void ClearStages(); public: diff --git a/src/kiwano/platform/FileSystem.h b/src/kiwano/platform/FileSystem.h index 9af781ad..7ac2089c 100644 --- a/src/kiwano/platform/FileSystem.h +++ b/src/kiwano/platform/FileSystem.h @@ -23,41 +23,87 @@ namespace kiwano { - // 文件 + /** + * \~chinese + * @brief 文件系统,为其他模块提供文件搜索规则等 + */ class KGE_API FileSystem : public Singleton { - OC_DECLARE_SINGLETON(FileSystem); + friend Singleton; public: - // 添加文件搜索路径 + /** + * \~chinese + * @brief 添加文件搜索路径 + * @param path 文件搜索路径 + */ void AddSearchPath(String const& path); - // 设置文件搜索路径 + /** + * \~chinese + * @brief 设置文件搜索路径 + * @param paths 搜索路径数组 + */ void SetSearchPaths(Vector const& paths); - // 获取文件的完整路径 + /** + * \~chinese + * @brief 在搜索列表中查找文件并获取完整路径 + * @param file 文件路径 + * @return 完整的文件路径 + */ String GetFullPathForFile(String const& file) const; - // 添加文件路径查找字典规则 + /** + * \~chinese + * @brief 添加文件路径查找字典规则 + * @param key 文件关键词 + * @param file_path 文件路径 + */ void AddFileLookupRule(String const& key, String const& file_path); - // 设置文件路径查找字典 + /** + * \~chinese + * @brief 设置文件路径查找字典 + * @param dict 文件路径查找字典 + */ void SetFileLookupDictionary(UnorderedMap const& dict); - // 文件是否存在 + /** + * \~chinese + * @brief 文件是否存在 + * @param file_path 文件路径 + * @return 若文件存在,返回 true + */ bool IsFileExists(String const& file_path) const; - // 判断路径是否是绝对路径 + /** + * \~chinese + * @brief 判断路径是否是绝对路径 + * @param path 文件路径 + * @return 若是绝对路径,返回 true + */ bool IsAbsolutePath(String const& path) const; - // 删除文件 + /** + * \~chinese + * @brief 删除文件 + * @param path 文件路径 + * @return 删除是否成功 + */ bool RemoveFile(String const& file_path) const; - // 释放二进制资源到临时文件目录 + /** + * \~chinese + * @brief 释放二进制资源到临时文件目录 + * @param res 资源 + * @param dest_file_name 目标文件名 + * @return 操作是否成功 + */ bool ExtractResourceToFile( - Resource const& res, /* 资源 */ - String const& dest_file_name /* 目标文件名 */ + Resource const& res, + String const& dest_file_name ) const; private: diff --git a/src/kiwano/platform/Input.h b/src/kiwano/platform/Input.h index 01e4197f..cc072cc1 100644 --- a/src/kiwano/platform/Input.h +++ b/src/kiwano/platform/Input.h @@ -27,36 +27,70 @@ namespace kiwano { + /** + * \~chinese + * @brief 输入设备实例,可获取鼠标和键盘的按键状态 + */ class KGE_API Input : public Singleton , public UpdateComponent , public EventComponent { - OC_DECLARE_SINGLETON(Input); + friend Singleton; public: - // 检测键盘或鼠标按键是否正被按下 + /** + * \~chinese + * @brief 检测键盘或鼠标按键是否正被按下 + * @param key_or_btn 键值 + * @return 是否正被按下 + * @see kiwano::KeyCode kiwano::MouseButton + */ bool IsDown( int key_or_btn ); - // 检测键盘或鼠标按键是否刚被点击 + /** + * \~chinese + * @brief 检测键盘或鼠标按键是否刚被点击 + * @param key_or_btn 键值 + * @return 是否刚被点击 + * @see kiwano::KeyCode kiwano::MouseButton + */ bool WasPressed( int key_or_btn ); - // 检测键盘或鼠标按键是否刚抬起 + /** + * \~chinese + * @brief 检测键盘或鼠标按键是否刚抬起 + * @param key_or_btn 键值 + * @return 是否刚抬起 + * @see kiwano::KeyCode kiwano::MouseButton + */ bool WasReleased( int key_or_btn ); - // 获得鼠标 x 坐标 + /** + * \~chinese + * @brief 获得鼠标 x 坐标 + * @return 鼠标 x 坐标 + */ float GetMouseX(); - // 获得鼠标 y 坐标 + /** + * \~chinese + * @brief 获得鼠标 y 坐标 + * @return 鼠标 y 坐标 + */ float GetMouseY(); - // 获得鼠标坐标 + /** + * \~chinese + * @brief 获得鼠标坐标 + * @return 鼠标坐标 + */ Point GetMousePos(); public: diff --git a/src/kiwano/platform/Window.h b/src/kiwano/platform/Window.h index 14798536..51dba59d 100644 --- a/src/kiwano/platform/Window.h +++ b/src/kiwano/platform/Window.h @@ -25,29 +25,45 @@ namespace kiwano { - // 鼠标指针类型 + /** + * \~chinese + * @brief 鼠标指针类型 + */ enum class CursorType { - Arrow, /* 指针 */ - TextInput, /* 文本 */ - Hand, /* 手指 */ - SizeAll, - SizeNESW, - SizeNS, - SizeNWSE, - SizeWE, + Arrow, ///< 指针 + TextInput, ///< 文本 + Hand, ///< 手 + SizeAll, ///< 指向四个方向的箭头 + SizeWE, ///< 指向左右方向的箭头 + SizeNS, ///< 指向上下方向的箭头 + SizeNESW, ///< 指向左下到右上方向的箭头 + SizeNWSE, ///< 指向左上到右下方向的箭头 }; - // 窗口设置 + /** + * \~chinese + * @brief 窗口设置 + */ struct WindowConfig { - String title; // 标题 - uint32_t width; // 宽度 - uint32_t height; // 高度 - uint32_t icon; // 图标资源 ID - bool resizable; // 窗口大小可拉伸 - bool fullscreen; // 全屏模式 + String title; ///< 标题 + uint32_t width; ///< 宽度 + uint32_t height; ///< 高度 + uint32_t icon; ///< 图标资源 ID + bool resizable; ///< 窗口大小可拉伸 + bool fullscreen; ///< 全屏模式 + /** + * \~chinese + * @brief 构建窗口设置 + * @param title 标题 + * @param width 宽度 + * @param height 高度 + * @param icon 图标资源ID + * @param resizable 窗口大小可拉伸 + * @param fullscreen 全屏模式 + */ WindowConfig( String const& title = L"Kiwano Game", uint32_t width = 640, @@ -59,38 +75,80 @@ namespace kiwano }; - // 窗口 + /** + * \~chinese + * @brief 窗口实例,控制窗口标题、大小、图标等 + */ class KGE_API Window : public Singleton { - OC_DECLARE_SINGLETON(Window); + friend Singleton; public: - // 获取标题 + /** + * \~chinese + * @brief 获取窗口标题 + * @return 窗口标题 + */ String GetTitle() const; - // 获取窗口大小 + /** + * \~chinese + * @brief 获取窗口大小 + * @return 窗口大小 + */ Size GetSize() const; - // 获取窗口宽度 + /** + * \~chinese + * @brief 获取窗口宽度 + * @return 窗口宽度 + */ float GetWidth() const; - // 获取窗口高度 + /** + * \~chinese + * @brief 获取窗口高度 + * @return 窗口高度 + */ float GetHeight() const; - // 设置标题 + /** + * \~chinese + * @brief 设置标题 + * @param title 标题 + */ void SetTitle(String const& title); - // 设置窗口图标 + /** + * \~chinese + * @brief 设置窗口图标 + * @param icon_resource 图标资源ID + */ void SetIcon(uint32_t icon_resource); - // 重设窗口大小 + /** + * \~chinese + * @brief 重设窗口大小 + * @param width 窗口宽度 + * @param height 窗口高度 + */ void Resize(int width, int height); - // 设置全屏模式 + /** + * \~chinese + * @brief 设置全屏模式 + * @param fullscreen 是否全屏 + * @param width 窗口宽度 + * @param height 窗口高度 + */ void SetFullscreen(bool fullscreen, int width, int height); - // 设置鼠标指针类型 + /** + * \~chinese + * @brief 设置鼠标指针类型 + * @param cursor 鼠标指针类型 + */ void SetCursor(CursorType cursor); public: diff --git a/src/kiwano/renderer/Renderer.h b/src/kiwano/renderer/Renderer.h index f3a2be25..bab77019 100644 --- a/src/kiwano/renderer/Renderer.h +++ b/src/kiwano/renderer/Renderer.h @@ -59,7 +59,7 @@ namespace kiwano , public EventComponent , public RenderTarget { - OC_DECLARE_SINGLETON(Renderer); + friend Singleton; public: // 设置清屏颜色 diff --git a/src/kiwano/renderer/TextureCache.h b/src/kiwano/renderer/TextureCache.h index e8c19dd7..990557b5 100644 --- a/src/kiwano/renderer/TextureCache.h +++ b/src/kiwano/renderer/TextureCache.h @@ -27,7 +27,7 @@ namespace kiwano class KGE_API TextureCache : public Singleton { - OC_DECLARE_SINGLETON(TextureCache); + friend Singleton; public: Texture AddOrGetTexture(String const& file_path); diff --git a/src/kiwano/utils/ResourceCache.h b/src/kiwano/utils/ResourceCache.h index b02febee..7055116e 100644 --- a/src/kiwano/utils/ResourceCache.h +++ b/src/kiwano/utils/ResourceCache.h @@ -30,7 +30,7 @@ namespace kiwano class KGE_API ResourceCache : public Singleton { - OC_DECLARE_SINGLETON(ResourceCache); + friend Singleton; public: // 从 JSON 文件加载资源信息 diff --git a/src/kiwano/utils/UserData.h b/src/kiwano/utils/UserData.h index 67ac9a64..e12f99c1 100644 --- a/src/kiwano/utils/UserData.h +++ b/src/kiwano/utils/UserData.h @@ -27,7 +27,7 @@ namespace kiwano class KGE_API UserData : public Singleton { - OC_DECLARE_SINGLETON(UserData); + friend Singleton; public: using DataMap = UnorderedMap;