From ded9c8a826b2b69b4c7a63bf4cea9805b5244788 Mon Sep 17 00:00:00 2001
From: Tony Wasserka <NeoBrainX@gmail.com>
Date: Thu, 13 Nov 2014 18:12:27 +0100
Subject: [PATCH] EmuWindow: Add documentation.
---
src/common/emu_window.h | 75 +++++++++++++++++++++++++++++++----------
1 file changed, 57 insertions(+), 18 deletions(-)
diff --git a/src/common/emu_window.h b/src/common/emu_window.h
index baacc6da22..1465743f26 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,37 +56,64 @@ 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<unsigned,unsigned> 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<unsigned,unsigned> 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!
+protected:
+ // TODO: Remove window title initialization
+ EmuWindow() :
+ window_title(Common::StringFromFormat("Citra | %s-%s", Common::g_scm_branch, Common::g_scm_desc))
+ {
+ // TODO
+ config.min_client_area_size = std::make_pair(300u, 500u);
+ active_config = config;
+ }
+ virtual ~EmuWindow() {}
+
+ /**
+ * 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...
@@ -84,20 +124,18 @@ public:
}
}
-protected:
- EmuWindow() :
- window_title(Common::StringFromFormat("Citra | %s-%s", Common::g_scm_branch, Common::g_scm_desc))
- {
- // TODO
- config.min_client_area_size = std::make_pair(300u, 500u);
- active_config = config;
- }
- virtual ~EmuWindow() {}
-
- std::pair<unsigned,unsigned> NotifyFramebufferSizeChanged(const std::pair<unsigned,unsigned>& 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<unsigned,unsigned>& 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<unsigned,unsigned>& size) {
client_area_width = size.first;
client_area_height = size.second;
@@ -107,6 +145,7 @@ private:
virtual void OnMinimalClientAreaChangeRequest(const std::pair<unsigned,unsigned>& minimal_size) {
}
+ // TODO: Remove
std::string window_title; ///< Current window title, should be used by window impl.
std::pair<unsigned,unsigned> framebuffer_size;