From ded9c8a826b2b69b4c7a63bf4cea9805b5244788 Mon Sep 17 00:00:00 2001 From: Tony Wasserka Date: Thu, 13 Nov 2014 18:12:27 +0100 Subject: EmuWindow: Add documentation. --- src/common/emu_window.h | 75 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 57 insertions(+), 18 deletions(-) (limited to 'src/common/emu_window.h') diff --git a/src/common/emu_window.h b/src/common/emu_window.h index baacc6da..1465743f 100644 --- a/src/common/emu_window.h +++ b/src/common/emu_window.h @@ -9,13 +9,26 @@ #include "common/string_util.h" #include "common/key_map.h" -// Abstraction class used to provide an interface between emulation code and the frontend (e.g. SDL, -// QGLWidget, GLFW, etc...) +/** + * Abstraction class used to provide an interface between emulation code and the frontend + * (e.g. SDL, QGLWidget, GLFW, etc...). + * + * Design notes on the interaction between EmuWindow and the emulation core: + * - Generally, decisions on anything visible to the user should be left up to the GUI. + * For example, the emulation core should not try to dictate some window title or size. + * This stuff is not the core's business and only causes problems with regards to thread-safety + * anyway. + * - Under certain circumstances, it may be desirable for the core to politely request the GUI + * to set e.g. a minimum window size. However, the GUI should always be free to ignore any + * such hints. + * - EmuWindow may expose some of its state as read-only to the emulation core, however care + * should be taken to make sure the provided information is self-consistent. This requires + * some sort of synchronization (most of this is still a TODO). + */ class EmuWindow { - public: - /// Data structure to store an emuwindow configuration + /// Data structure to store emuwindow configuration struct WindowConfig { bool fullscreen; int res_width; @@ -43,48 +56,51 @@ public: /// Signals a key release action to the HID module static void KeyReleased(KeyMap::HostDeviceKey key); + /** + * Returns currently active configuration. + * @note Accesses to the returned object need not be consistent because it may be modified in another thread + */ const WindowConfig& GetActiveConfig() const { return active_config; } + /** + * Requests the internal configuration to be replaced by the specified argument at some point in the future. + * @note This method is thread-safe, because it delays configuration changes to the GUI event loop. Hence there is no guarantee on when the requested configuration will be active. + */ void SetConfig(const WindowConfig& val) { config = val; } /** - * Gets the size of the framebuffer in pixels + * Gets the framebuffer size in pixels. + * @note This method is thread-safe */ const std::pair GetFramebufferSize() const { return framebuffer_size; } /** - * Gets window client area width in logical coordinates + * Gets window client area width in logical coordinates. + * @note For high-DPI systems, this is smaller than the framebuffer size. + * @note This method is thread-safe */ std::pair GetClientAreaSize() const { return std::make_pair(client_area_width, client_area_height); } + // TODO: Remove std::string GetWindowTitle() const { return window_title; } + // TODO: Remove void SetWindowTitle(const std::string& val) { window_title = val; } - // Only call this from the GUI thread! - void ProcessConfigurationChanges() { - // TODO: For proper thread safety, we should eventually implement a proper - // multiple-writer/single-reader queue... - - if (config.min_client_area_size != active_config.min_client_area_size) { - OnMinimalClientAreaChangeRequest(config.min_client_area_size); - config.min_client_area_size = active_config.min_client_area_size; - } - } - protected: + // TODO: Remove window title initialization EmuWindow() : window_title(Common::StringFromFormat("Citra | %s-%s", Common::g_scm_branch, Common::g_scm_desc)) { @@ -94,10 +110,32 @@ protected: } virtual ~EmuWindow() {} - std::pair NotifyFramebufferSizeChanged(const std::pair& size) { + /** + * Processes any pending configuration changes from the last SetConfig call. + * @note Implementations will usually want to call this from the GUI thread. + */ + void ProcessConfigurationChanges() { + // TODO: For proper thread safety, we should eventually implement a proper + // multiple-writer/single-reader queue... + + if (config.min_client_area_size != active_config.min_client_area_size) { + OnMinimalClientAreaChangeRequest(config.min_client_area_size); + config.min_client_area_size = active_config.min_client_area_size; + } + } + + /** + * Update internal framebuffer size with the given parameter. + * @note EmuWindow implementations will usually use this in window resize event handlers. + */ + void NotifyFramebufferSizeChanged(const std::pair& size) { framebuffer_size = size; } + /** + * Update internal client area size with the given parameter. + * @note EmuWindow implementations will usually use this in window resize event handlers. + */ void NotifyClientAreaSizeChanged(const std::pair& size) { client_area_width = size.first; client_area_height = size.second; @@ -107,6 +145,7 @@ private: virtual void OnMinimalClientAreaChangeRequest(const std::pair& minimal_size) { } + // TODO: Remove std::string window_title; ///< Current window title, should be used by window impl. std::pair framebuffer_size; -- cgit v1.2.3