You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and dots ('.'), can be up to 35 characters long. Letters must be lowercase.
120 lines
4.5 KiB
120 lines
4.5 KiB
@page internals_guide Internal structure |
|
|
|
@tableofcontents |
|
|
|
There are several interfaces inside GLFW. Each interface has its own area of |
|
responsibility and its own naming conventions. |
|
|
|
|
|
@section internals_public Public interface |
|
|
|
The most well-known is the public interface, described in the glfw3.h header |
|
file. This is implemented in source files shared by all platforms and these |
|
files contain no platform-specific code. This code usually ends up calling the |
|
platform and internal interfaces to do the actual work. |
|
|
|
The public interface uses the OpenGL naming conventions except with GLFW and |
|
glfw instead of GL and gl. For struct members, where OpenGL sets no precedent, |
|
it use headless camel case. |
|
|
|
Examples: `glfwCreateWindow`, `GLFWwindow`, `GLFW_RED_BITS` |
|
|
|
|
|
@section internals_native Native interface |
|
|
|
The [native interface](@ref native) is a small set of publicly available |
|
but platform-specific functions, described in the glfw3native.h header file and |
|
used to gain access to the underlying window, context and (on some platforms) |
|
display handles used by the platform interface. |
|
|
|
The function names of the native interface are similar to those of the public |
|
interface, but embeds the name of the interface that the returned handle is |
|
from. |
|
|
|
Examples: `glfwGetX11Window`, `glfwGetWGLContext` |
|
|
|
|
|
@section internals_internal Internal interface |
|
|
|
The internal interface consists of utility functions used by all other |
|
interfaces. It is shared code implemented in the same shared source files as |
|
the public and event interfaces. The internal interface is described in the |
|
internal.h header file. |
|
|
|
The internal interface is in charge of GLFW's global data, which it stores in |
|
a `_GLFWlibrary` struct named `_glfw`. |
|
|
|
The internal interface uses the same style as the public interface, except all |
|
global names have a leading underscore. |
|
|
|
Examples: `_glfwIsValidContextConfig`, `_GLFWwindow`, `_glfw.monitorCount` |
|
|
|
|
|
@section internals_platform Platform interface |
|
|
|
The platform interface implements all platform-specific operations as a service |
|
to the public interface. This includes event processing. The platform |
|
interface is never directly called by application code and never directly calls |
|
application-provided callbacks. It is also prohibited from modifying the |
|
platform-independent part of the internal structs. Instead, it calls the event |
|
interface when events interesting to GLFW are received. |
|
|
|
The platform interface mostly mirrors those parts of the public interface that needs to |
|
perform platform-specific operations on some or all platforms. |
|
|
|
The window system bits of the platform API is called through the `_GLFWplatform` struct of |
|
function pointers, to allow runtime selection of platform. This includes the window and |
|
context creation, input and event processing, monitor and Vulkan surface creation parts of |
|
GLFW. This is located in the global `_glfw` struct. |
|
|
|
Examples: `_glfw.platform.createWindow` |
|
|
|
The timer, threading and module loading bits of the platform API are plain functions with |
|
a `_glfwPlatform` prefix, as these things are independent of what window system is being |
|
used. |
|
|
|
Examples: `_glfwPlatformGetTimerValue` |
|
|
|
The platform interface also defines structs that contain platform-specific |
|
global and per-object state. Their names mirror those of the internal |
|
interface, except that an interface-specific suffix is added. |
|
|
|
Examples: `_GLFWwindowX11`, `_GLFWcontextWGL` |
|
|
|
These structs are incorporated as members into the internal interface structs |
|
using special macros that name them after the specific interface used. This |
|
prevents shared code from accidentally using these members. |
|
|
|
Examples: `window->win32.handle`, `_glfw.x11.display` |
|
|
|
|
|
@section internals_event Event interface |
|
|
|
The event interface is implemented in the same shared source files as the public |
|
interface and is responsible for delivering the events it receives to the |
|
application, either via callbacks, via window state changes or both. |
|
|
|
The function names of the event interface use a `_glfwInput` prefix and the |
|
ObjectEvent pattern. |
|
|
|
Examples: `_glfwInputWindowFocus`, `_glfwInputCursorPos` |
|
|
|
|
|
@section internals_static Static functions |
|
|
|
Static functions may be used by any interface and have no prefixes or suffixes. |
|
These use headless camel case. |
|
|
|
Examples: `isValidElementForJoystick` |
|
|
|
|
|
@section internals_config Configuration macros |
|
|
|
GLFW uses a number of configuration macros to select at compile time which |
|
interfaces and code paths to use. They are defined in the GLFW CMake target. |
|
|
|
Configuration macros the same style as tokens in the public interface, except |
|
with a leading underscore. |
|
|
|
Examples: `_GLFW_WIN32`, `_GLFW_BUILD_DLL` |
|
|
|
|