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