EmuWindow: Add documentation.

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;