EmuWindow: Add documentation.

This commit is contained in:
Tony Wasserka 2014-11-13 18:12:27 +01:00
parent 722ce22589
commit ded9c8a826
1 changed files with 57 additions and 18 deletions

View File

@ -9,13 +9,26 @@
#include "common/string_util.h" #include "common/string_util.h"
#include "common/key_map.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 class EmuWindow
{ {
public: public:
/// Data structure to store an emuwindow configuration /// Data structure to store emuwindow configuration
struct WindowConfig { struct WindowConfig {
bool fullscreen; bool fullscreen;
int res_width; int res_width;
@ -43,37 +56,64 @@ public:
/// Signals a key release action to the HID module /// Signals a key release action to the HID module
static void KeyReleased(KeyMap::HostDeviceKey key); 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 { const WindowConfig& GetActiveConfig() const {
return active_config; 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) { void SetConfig(const WindowConfig& val) {
config = 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 { const std::pair<unsigned,unsigned> GetFramebufferSize() const {
return framebuffer_size; 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 { std::pair<unsigned,unsigned> GetClientAreaSize() const {
return std::make_pair(client_area_width, client_area_height); return std::make_pair(client_area_width, client_area_height);
} }
// TODO: Remove
std::string GetWindowTitle() const { std::string GetWindowTitle() const {
return window_title; return window_title;
} }
// TODO: Remove
void SetWindowTitle(const std::string& val) { void SetWindowTitle(const std::string& val) {
window_title = 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() { void ProcessConfigurationChanges() {
// TODO: For proper thread safety, we should eventually implement a proper // TODO: For proper thread safety, we should eventually implement a proper
// multiple-writer/single-reader queue... // multiple-writer/single-reader queue...
@ -84,20 +124,18 @@ public:
} }
} }
protected: /**
EmuWindow() : * Update internal framebuffer size with the given parameter.
window_title(Common::StringFromFormat("Citra | %s-%s", Common::g_scm_branch, Common::g_scm_desc)) * @note EmuWindow implementations will usually use this in window resize event handlers.
{ */
// TODO void NotifyFramebufferSizeChanged(const std::pair<unsigned,unsigned>& size) {
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) {
framebuffer_size = 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) { void NotifyClientAreaSizeChanged(const std::pair<unsigned,unsigned>& size) {
client_area_width = size.first; client_area_width = size.first;
client_area_height = size.second; client_area_height = size.second;
@ -107,6 +145,7 @@ private:
virtual void OnMinimalClientAreaChangeRequest(const std::pair<unsigned,unsigned>& minimal_size) { 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::string window_title; ///< Current window title, should be used by window impl.
std::pair<unsigned,unsigned> framebuffer_size; std::pair<unsigned,unsigned> framebuffer_size;