From 3817771a408780625c42d535f68969ea6f88675e Mon Sep 17 00:00:00 2001 From: Camilla Berglund Date: Wed, 2 Jan 2013 02:21:38 +0100 Subject: [PATCH] Started adding documentation for internal APIs. --- src/init.c | 10 +- src/internal.h | 454 +++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 385 insertions(+), 79 deletions(-) diff --git a/src/init.c b/src/init.c index 54fc94be..672e01ff 100644 --- a/src/init.c +++ b/src/init.c @@ -37,16 +37,10 @@ //------------------------------------------------------------------------ -// Flag indicating whether GLFW has been successfully initialized +// Global state shared between compilation units of GLFW +// These are documented in internal.h //------------------------------------------------------------------------ GLboolean _glfwInitialized = GL_FALSE; - - -//------------------------------------------------------------------------ -// All shared and API-specific global data protected by _glfwInitialized -// This should only be touched after a call to glfwInit that has not been -// followed by a call to glfwTerminate -//------------------------------------------------------------------------ _GLFWlibrary _glfw; diff --git a/src/internal.h b/src/internal.h index 778694f4..7e9ecafa 100644 --- a/src/internal.h +++ b/src/internal.h @@ -32,6 +32,33 @@ #define _internal_h_ +//======================================================================== +// Doxygen group definitions +//======================================================================== + +/*! @defgroup platform Platform API + * @brief The API implemented by the platform-specific code. + * + * The platform API is the interface exposed by the platform-specific code for + * each platform and is called by the shared code of the public API It mirrors + * the public API except it uses objects instead of handles. + */ +/*! @defgroup event Event API + * @brief The API used by the platform-specific code to report events. + * + * The event API is used by the platform-specific code to notify the shared + * code of events that can be translated into state changes and/or callback + * calls. + */ +/*! @defgroup utility Utility functions + * @brief Various utility functions. + * + * These functions are shared code and may be used by any part of GLFW + * Each platform may add its own utility functions, but those may only be + * called by the platform-specific code + */ + + //======================================================================== // Input handling definitions //======================================================================== @@ -52,11 +79,6 @@ typedef struct _GLFWlibrary _GLFWlibrary; typedef struct _GLFWmonitor _GLFWmonitor; -//------------------------------------------------------------------------ -// Platform specific definitions goes in platform.h (which also includes -// glfw.h) -//------------------------------------------------------------------------ - #include "config.h" // Disable the inclusion of the platform glext.h by gl.h to allow proper @@ -81,12 +103,15 @@ typedef struct _GLFWmonitor _GLFWmonitor; #endif -//------------------------------------------------------------------------ -// Window hints, set by glfwWindowHint and consumed by glfwCreateWindow -// A bucket of semi-random stuff lumped together for historical reasons -// This is used only by the platform independent code and only to store -// parameters passed to us by glfwWindowHint -//------------------------------------------------------------------------ +//======================================================================== +// Internal type definitions +//======================================================================== + +/*! @brief Window, framebuffer and context hints. + * + * It is used only by shared code and only to store parameters passed to us by + * @ref glfwWindowHint for use by @ref glfwCreateWindow. + */ struct _GLFWhints { int redBits; @@ -117,12 +142,12 @@ struct _GLFWhints }; -//------------------------------------------------------------------------ -// Parameters relating to the creation of the context and window but not -// directly related to the properties of the framebuffer -// This is used to pass window and context creation parameters from the -// platform independent code to the platform specific code -//------------------------------------------------------------------------ +/*! @brief Window and context configuration. + * + * Parameters relating to the creation of the context and window but not + * directly related to the framebuffer. This is used to pass window and + * context creation parameters from shared code to the platform API. + */ struct _GLFWwndconfig { const char* title; @@ -142,13 +167,14 @@ struct _GLFWwndconfig }; -//------------------------------------------------------------------------ -// Framebuffer configuration descriptor, i.e. buffers and their sizes -// Also a platform specific ID used to map back to the actual backend APIs -// This is used to pass framebuffer parameters from the platform independent -// code to the platform specific code, and also to enumerate and select -// available framebuffer configurations -//------------------------------------------------------------------------ +/*! @brief Framebuffer configuration. + * + * This describes buffers and their sizes. It also contains + * a platform-specific ID used to map back to the backend API's object. + * + * It is used to pass framebuffer parameters from shared code to the + * platform API and also to enumerate and select available framebuffer configs. + */ struct _GLFWfbconfig { int redBits; @@ -169,9 +195,8 @@ struct _GLFWfbconfig }; -//------------------------------------------------------------------------ -// Window structure -//------------------------------------------------------------------------ +/*! @brief Window and context structure. + */ struct _GLFWwindow { struct _GLFWwindow* next; @@ -216,15 +241,15 @@ struct _GLFWwindow GLFWkeyfun keyCallback; GLFWcharfun charCallback; - // These are defined in the current port's platform.h + // This is defined in the window API's platform.h _GLFW_PLATFORM_WINDOW_STATE; + // This is defined in the context API's platform.h _GLFW_PLATFORM_CONTEXT_STATE; }; -//------------------------------------------------------------------------ -// Display structure -//------------------------------------------------------------------------ +/*! @brief Monitor structure. + */ struct _GLFWmonitor { char* name; @@ -241,13 +266,13 @@ struct _GLFWmonitor GLFWvidmode* modes; int modeCount; - // These are defined in the current port's platform.h + // This is defined in the window API's platform.h _GLFW_PLATFORM_MONITOR_STATE; }; -//------------------------------------------------------------------------ -// Library global data -//------------------------------------------------------------------------ + +/*! @brief Library global data. + */ struct _GLFWlibrary { _GLFWhints hints; @@ -264,145 +289,432 @@ struct _GLFWlibrary int originalRampSize; GLboolean rampChanged; - // This is defined in the current port's platform.h + // This is defined in the window API's platform.h _GLFW_PLATFORM_LIBRARY_WINDOW_STATE; + // This is defined in the context API's platform.h _GLFW_PLATFORM_LIBRARY_OPENGL_STATE; }; -//------------------------------------------------------------------------ +//======================================================================== // Global state shared between compilation units of GLFW -// These are exported from and documented in init.c -//------------------------------------------------------------------------ +//======================================================================== + +/*! @brief Flag indicating whether GLFW has been successfully initialized. + */ extern GLboolean _glfwInitialized; + +/*! @brief All global data protected by @ref _glfwInitialized. + * This should only be touched after a call to @ref glfwInit that has not been + * followed by a call to @ref glfwTerminate. + */ extern _GLFWlibrary _glfw; //======================================================================== -// Prototypes for the platform API -// This is the interface exposed by the platform-specific code for each -// platform and is called by the shared code of the public API -// It mirrors the public API except it uses objects instead of handles +// Platform API functions //======================================================================== -// Platform init and version +/*! @brief Initializes the platform-specific part of the library. + * @return @c GL_TRUE if successful, or @c GL_FALSE if an error occurred. + * @ingroup platform + */ int _glfwPlatformInit(void); + +/*! @brief Terminates the platform-specific part of the library. + * @ingroup platform + */ void _glfwPlatformTerminate(void); + +/*! @brief Returns a string describing the compile-time configuration of the + * platform-specific part of the library. + * @return The version string. + * @ingroup platform + * + * The format of the string is as follows: + * @arg The name of the window system API used + * @arg The name of the context creation API used + * @arg Any additional options or APIs + * + * @note The returned string must be available for the duration of the program. + * + * @note The returned string must not change for the duration of the program. + */ const char* _glfwPlatformGetVersionString(void); -// Input mode support +/*! @brief Sets the position of the system cursor. + * @param[in] window The window whose client area the specified posiiton is + * relative to. + * @param[in] x The new x-coordinate of the cursor, relative to the left edge + * of the client area of the window. + * @param[in] y The new y-coordinate of the cursor, relative to the top edge + * of the client area of the window. + * @ingroup platform + */ void _glfwPlatformSetCursorPos(_GLFWwindow* window, int x, int y); + +/*! @brief Sets up the specified cursor mode for the specified window. + * @param[in] window The window whose cursor mode to change. + * @param[in] mode The desired cursor mode. + * @ingroup platform + */ void _glfwPlatformSetCursorMode(_GLFWwindow* window, int mode); -// Monitor support +/*! @ingroup platform + */ _GLFWmonitor** _glfwPlatformGetMonitors(int* count); + +/*! @ingroup platform + */ void _glfwPlatformDestroyMonitor(_GLFWmonitor* monitor); -// Video mode support +/*! @ingroup platform + */ GLFWvidmode* _glfwPlatformGetVideoModes(_GLFWmonitor* monitor, int* count); + +/*! @ingroup platform + */ void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode* mode); -// Gamma ramp support +/*! @brief Returns the current system gamma ramp. + * @param[out] ramp The current system gamma ramp. + * @ingroup platform + */ void _glfwPlatformGetGammaRamp(GLFWgammaramp* ramp); + +/*! @brief Sets the system gamma ramp. + * @param[in] ramp The desired system gamma ramp. + * @ingroup platform + */ void _glfwPlatformSetGammaRamp(const GLFWgammaramp* ramp); -// Clipboard support +/*! @brief Sets the system clipboard to the specified string. + * @param[in] window The window who will own the system clipboard contents, on + * systems where this is necessary. + * @param[in] string The UTF-8 encoded string to use. + * @ingroup platform + */ void _glfwPlatformSetClipboardString(_GLFWwindow* window, const char* string); + +/*! @brief Returns the string in the system clipboard. + * @param[in] window The window who will request the system clipboard contents, + * on systems where this is necessary. + * @return The UTF-8 encoded contents, or @c NULL if the system clipboard did + * not contain a string. + * @ingroup platform + * + * @note The returned string must be valid until the next call to @ref + * _glfwPlatformGetClipboardString or @ref _glfwPlatformSetClipboardString. + */ const char* _glfwPlatformGetClipboardString(_GLFWwindow* window); -// Joystick input +/*! @brief Returns the value of the specified joystick property. + * @param[in] joy The joystick to use. + * @param[in] param The property whose value to return. + * @return The value of the specified property, or zero if an error occurred. + * @ingroup platform + */ int _glfwPlatformGetJoystickParam(int joy, int param); + +/*! @ingroup platform + */ int _glfwPlatformGetJoystickAxes(int joy, float* axes, int numaxes); + +/*! @ingroup platform + */ int _glfwPlatformGetJoystickButtons(int joy, unsigned char* buttons, int numbuttons); + +/*! @ingroup platform + */ const char* _glfwPlatformGetJoystickName(int joy); -// Time input +/*! @brief Returns the current value of the timer. + * @return The value, in seconds, of the timer. + * @ingroup platform + */ double _glfwPlatformGetTime(void); + +/*! @brief Sets the value of the timer. + * @param[in] time The new value, in seconds, of the timer. + * @ingroup platform + */ void _glfwPlatformSetTime(double time); -// Window management -int _glfwPlatformCreateWindow(_GLFWwindow* window, const _GLFWwndconfig* wndconfig, const _GLFWfbconfig* fbconfig); +/*! @ingroup platform + */ +int _glfwPlatformCreateWindow(_GLFWwindow* window, + const _GLFWwndconfig* wndconfig, + const _GLFWfbconfig* fbconfig); + +/*! @ingroup platform + */ void _glfwPlatformDestroyWindow(_GLFWwindow* window); + +/*! @ingroup platform + */ void _glfwPlatformSetWindowTitle(_GLFWwindow* window, const char* title); + +/*! @ingroup platform + */ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height); + +/*! @ingroup platform + */ void _glfwPlatformIconifyWindow(_GLFWwindow* window); + +/*! @ingroup platform + */ void _glfwPlatformRestoreWindow(_GLFWwindow* window); + +/*! @ingroup platform + */ void _glfwPlatformShowWindow(_GLFWwindow* window); + +/*! @ingroup platform + */ void _glfwPlatformHideWindow(_GLFWwindow* window); -// Event processing +/*! @ingroup platform + */ void _glfwPlatformPollEvents(void); + +/*! @ingroup platform + */ void _glfwPlatformWaitEvents(void); -// OpenGL context management +/*! @ingroup platform + */ void _glfwPlatformMakeContextCurrent(_GLFWwindow* window); + +/*! @ingroup platform + */ _GLFWwindow* _glfwPlatformGetCurrentContext(void); + +/*! @ingroup platform + */ void _glfwPlatformSwapBuffers(_GLFWwindow* window); + +/*! @ingroup platform + */ void _glfwPlatformSwapInterval(int interval); -int _glfwPlatformExtensionSupported(const char* extension); + +/*! @ingroup platform + */ +int _glfwPlatformExtensionSupported(const char* extension); + +/*! @ingroup platform + */ +GLFWglproc _glfwPlatformGetProcAddress(const char* procname); + +/*! @ingroup platform + */ +int _glfwPlatformExtensionSupported(const char* extension); + +/*! @brief Returns the address of the specified client API function. + * @param[in] procname The name of the desired function. + * @return The address of the function, or @c NULL if it is not available. + * @ingroup platform + */ GLFWglproc _glfwPlatformGetProcAddress(const char* procname); //======================================================================== -// Prototypes for the event API -// This is used by the platform-specific code to notify the shared code of -// events that can be translated into state changes and/or callback calls, -// instead of directly calling callbacks or modifying shared state +// Event API functions //======================================================================== -// Window event notification (window.c) +/*! @brief Notifies shared code of a window focus event. + * @param[in] window The window that received the event. + * @param[in] focused @c GL_TRUE if the window received focus, or @c GL_FALSE + * if it lost focus. + * @ingroup event + */ void _glfwInputWindowFocus(_GLFWwindow* window, GLboolean focused); + +/*! @brief Notifies shared code of a window movement event. + * @param[in] window The window that received the event. + * @param[in] x The new x-coordinate of the client area of the window. + * @param[in] x The new y-coordinate of the client area of the window. + * @ingroup event + */ void _glfwInputWindowPos(_GLFWwindow* window, int x, int y); + +/*! @brief Notifies shared code of a window resize event. + * @param[in] window The window that received the event. + * @param[in] width The new width of the client area of the window. + * @param[in] height The new height of the client area of the window. + * @ingroup event + */ void _glfwInputWindowSize(_GLFWwindow* window, int width, int height); + +/*! @brief Notifies shared code of a window iconification event. + * @param[in] window The window that received the event. + * @param[in] iconified @c GL_TRUE if the window was iconified, or @c GL_FALSE + * if it was restored. + * @ingroup event + */ void _glfwInputWindowIconify(_GLFWwindow* window, int iconified); + +/*! @brief Notifies shared code of a window show/hide event. + * @param[in] window The window that received the event. + * @param[in] visible @c GL_TRUE if the window was shown, or @c GL_FALSE if it + * was hidden. + * @ingroup event + */ void _glfwInputWindowVisibility(_GLFWwindow* window, int visible); + +/*! @brief Notifies shared code of a window damage event. + * @param[in] window The window that received the event. + */ void _glfwInputWindowDamage(_GLFWwindow* window); + +/*! @brief Notifies shared code of a window close request event + * @param[in] window The window that received the event. + * @ingroup event + */ void _glfwInputWindowCloseRequest(_GLFWwindow* window); -// Input event notification (input.c) +/*! @brief Notifies shared code of a physical key event. + * @param[in] window The window that received the event. + * @param[in] key The key that was pressed or released. + * @param[in] action @ref GLFW_PRESS or @ref GLFW_RELEASE. + * @ingroup event + */ void _glfwInputKey(_GLFWwindow* window, int key, int action); + +/*! @brief Notifies shared code of a Unicode character input event. + * @param[in] window The window that received the event. + * @param[in] character The Unicode code point of the input character. + * @ingroup event + */ void _glfwInputChar(_GLFWwindow* window, int character); + +/*! @brief Notifies shared code of a scroll event. + * @param[in] window The window that received the event. + * @param[in] x The scroll offset along the x-axis. + * @param[in] y The scroll offset along the y-axis. + * @ingroup event + */ void _glfwInputScroll(_GLFWwindow* window, double x, double y); + +/*! @brief Notifies shared code of a mouse button click event. + * @param[in] window The window that received the event. + * @param[in] button The button that was pressed or released. + * @param[in] action @ref GLFW_PRESS or @ref GLFW_RELEASE. + * @ingroup event + */ void _glfwInputMouseClick(_GLFWwindow* window, int button, int action); + +/*! @brief Notifies shared code of a cursor motion event. + * @param[in] window The window that received the event. + * @param[in] x The new x-coordinate of the cursor, relative to the left edge + * of the client area of the window. + * @param[in] y The new y-coordinate of the cursor, relative to the top edge + * of the client area of the window. + * @ingroup event + */ void _glfwInputCursorMotion(_GLFWwindow* window, int x, int y); + +/*! @brief Notifies shared code of a cursor enter/leave event. + * @param[in] window The window that received the event. + * @param[in] entered @c GL_TRUE if the cursor entered the client area of the + * window, or @c GL_FALSE if it left it. + * @ingroup event + */ void _glfwInputCursorEnter(_GLFWwindow* window, int entered); -// Monitor event notification (monitor.c) +/*! @ingroup event + */ void _glfwInputMonitorChange(void); -// Error event notification (init.c) +/*! @brief Notifies shared code of an error. + * @param[in] error The error code most suitable for the error. + * @param[in] format The @c printf style format string of the error + * description. + * @ingroup event + */ void _glfwInputError(int error, const char* format, ...); //======================================================================== -// Prototypes for internal utility functions -// These functions are shared code and may be used by any part of GLFW -// Each platform may add its own utility functions, but those may only be -// called by the platform-specific code +// Utility functions //======================================================================== -// Fullscren management (fullscreen.c) +/*! @ingroup utility + */ const GLFWvidmode* _glfwChooseVideoMode(const GLFWvidmode* desired, const GLFWvidmode* alternatives, unsigned int count); + +/*! @brief Performs lexical comparison between two @ref GLFWvidmode structures. + * @ingroup utility + */ int _glfwCompareVideoModes(const GLFWvidmode* first, const GLFWvidmode* second); + +/*! @brief Splits a color depth into red, green and blue bit depths. + * @ingroup utility + */ void _glfwSplitBPP(int bpp, int* red, int* green, int* blue); -// OpenGL context helpers (opengl.c) +/*! @brief Searches an extension string for the specified extension. + * @param[in] string The extension string to search. + * @param[in] extension The extension to search for. + * @return @c GL_TRUE if the extension was found, or @c GL_FALSE otherwise. + * @ingroup utility + */ int _glfwStringInExtensionString(const char* string, const GLubyte* extensions); + +/*! @brief Chooses the framebuffer config that best matches the desired one. + * @param[in] desired The desired framebuffer config. + * @param[in] alternatives The framebuffer configs supported by the system. + * @param[in] count The number of entries in the alternatives array. + * @return The framebuffer config most closely matching the desired one, or @c + * NULL if none fulfilled the hard constraints of the desired values. + * @ingroup utility + */ const _GLFWfbconfig* _glfwChooseFBConfig(const _GLFWfbconfig* desired, const _GLFWfbconfig* alternatives, unsigned int count); + +/*! @brief Checks and reads back properties from the current context. + * @return @c GL_TRUE if successful, or @c GL_FALSE if the context is unusable. + * @ingroup utility + */ GLboolean _glfwRefreshContextParams(void); + +/*! @brief Checks whether the desired context properties are valid. + * @param[in] wndconfig The context properties to check. + * @return @c GL_TRUE if the context properties are valid, or @c GL_FALSE + * otherwise. + * @ingroup utility + * + * This function checks things like whether the specified client API version + * exists and whether all relevant options have supported and non-conflicting + * values. + */ GLboolean _glfwIsValidContextConfig(_GLFWwndconfig* wndconfig); + +/*! @brief Checks whether the current context fulfils the specified hard + * constraints. + * @param[in] wndconfig The desired context properties. + * @return @c GL_TRUE if the context fulfils the hard constraints, or @c + * GL_FALSE otherwise. + * @ingroup utility + */ GLboolean _glfwIsValidContext(_GLFWwndconfig* wndconfig); -// Monitor management (monitor.c) +/*! @ingroup utility + */ _GLFWmonitor* _glfwCreateMonitor(const char* name, GLboolean primary, int physicalWidth, int physicalHeight, int x, int y); + +/*! @ingroup utility + */ void _glfwDestroyMonitor(_GLFWmonitor* monitor); + +/*! @ingroup utility + */ void _glfwDestroyMonitors(void); #endif // _internal_h_