56a4cb0a3a
This adds compile-time support for multiple platforms and runtime detection of them. Window system related platform functions are now called from shared code via the function pointer struct _GLFWplatform. The timer, thread and module loading platform functions are still called directly by name and the implementation chosen at link-time. These functions are the same for any backend on a given OS, including the Null backend. The platforms are now enabled via CMake dependent options following the GLFW_BUILD_<platform> pattern instead of a mix of automagic and ad-hoc option names. There is no longer any option for the Null backend as it is now always enabled. Much of the struct stitching work in platform.h was based on an earlier experimental branch for runtime platform selection by @ronchaine. Every platform function related to windows, contexts, monitors, input, event processing and Vulkan have been renamed so that multiple sets of them can exist without colliding. Calls to these are now routed through the _glfw.platform struct member. These changes makes up most of this commit. For Wayland and X11 the client library loading and display creation is used to detect a running compositor/server. The XDG_SESSION_TYPE environment variable is ignored for now, as X11 is still by far the more complete implementation. Closes #1655 Closes #1958
124 lines
4.6 KiB
Plaintext
124 lines
4.6 KiB
Plaintext
/*!
|
|
|
|
@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`
|
|
|
|
*/
|
