1/*! 2 3@page internals_guide Internal structure 4 5@tableofcontents 6 7There are several interfaces inside GLFW. Each interface has its own area of 8responsibility and its own naming conventions. 9 10 11@section internals_public Public interface 12 13The most well-known is the public interface, described in the glfw3.h header 14file. This is implemented in source files shared by all platforms and these 15files contain no platform-specific code. This code usually ends up calling the 16platform and internal interfaces to do the actual work. 17 18The public interface uses the OpenGL naming conventions except with GLFW and 19glfw instead of GL and gl. For struct members, where OpenGL sets no precedent, 20it use headless camel case. 21 22Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits, 23`GLFW_RED_BITS` 24 25 26@section internals_native Native interface 27 28The [native interface](@ref native) is a small set of publicly available 29but platform-specific functions, described in the glfw3native.h header file and 30used to gain access to the underlying window, context and (on some platforms) 31display handles used by the platform interface. 32 33The function names of the native interface are similar to those of the public 34interface, but embeds the name of the interface that the returned handle is 35from. 36 37Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext 38 39 40@section internals_internal Internal interface 41 42The internal interface consists of utility functions used by all other 43interfaces. It is shared code implemented in the same shared source files as 44the public and event interfaces. The internal interface is described in the 45internal.h header file. 46 47The internal interface is in charge of GLFW's global data, which it stores in 48a `_GLFWlibrary` struct named `_glfw`. 49 50The internal interface uses the same style as the public interface, except all 51global names have a leading underscore. 52 53Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp` 54 55 56@section internals_platform Platform interface 57 58The platform interface implements all platform-specific operations as a service 59to the public interface. This includes event processing. The platform 60interface is never directly called by application code and never directly calls 61application-provided callbacks. It is also prohibited from modifying the 62platform-independent part of the internal structs. Instead, it calls the event 63interface when events interesting to GLFW are received. 64 65The platform interface mirrors those parts of the public interface that needs to 66perform platform-specific operations on some or all platforms. The are also 67named the same except that the glfw function prefix is replaced by 68_glfwPlatform. 69 70Examples: @ref _glfwPlatformCreateWindow 71 72The platform interface also defines structs that contain platform-specific 73global and per-object state. Their names mirror those of the internal 74interface, except that an interface-specific suffix is added. 75 76Examples: `_GLFWwindowX11`, `_GLFWcontextWGL` 77 78These structs are incorporated as members into the internal interface structs 79using special macros that name them after the specific interface used. This 80prevents shared code from accidentally using these members. 81 82Examples: `window.win32.handle`, `_glfw.x11.display` 83 84 85@section internals_event Event interface 86 87The event interface is implemented in the same shared source files as the public 88interface and is responsible for delivering the events it receives to the 89application, either via callbacks, via window state changes or both. 90 91The function names of the event interface use a `_glfwInput` prefix and the 92ObjectEvent pattern. 93 94Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion 95 96 97@section internals_static Static functions 98 99Static functions may be used by any interface and have no prefixes or suffixes. 100These use headless camel case. 101 102Examples: `clearScrollOffsets` 103 104 105@section internals_config Configuration macros 106 107GLFW uses a number of configuration macros to select at compile time which 108interfaces and code paths to use. They are defined in the glfw_config.h header file, 109which is generated from the `glfw_config.h.in` file by CMake. 110 111Configuration macros the same style as tokens in the public interface, except 112with a leading underscore. 113 114Examples: `_GLFW_HAS_XF86VM` 115 116*/ 117