mirror of
https://github.com/glfw/glfw.git
synced 2026-09-21 16:44:11 +00:00
Add runtime platform selection
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
This commit is contained in:
Camilla Löwy
+79
-6
@@ -30,6 +30,7 @@ successfully initialized, and only from the main thread.
|
||||
|
||||
- @ref glfwGetVersion
|
||||
- @ref glfwGetVersionString
|
||||
- @ref glfwPlatformSupported
|
||||
- @ref glfwGetError
|
||||
- @ref glfwSetErrorCallback
|
||||
- @ref glfwInitHint
|
||||
@@ -89,6 +90,15 @@ Setting these hints requires no platform specific headers or functions.
|
||||
|
||||
@subsubsection init_hints_shared Shared init hints
|
||||
|
||||
@anchor GLFW_PLATFORM
|
||||
__GLFW_PLATFORM__ specifies the platform to use for windowing and input.
|
||||
Possible values are `GLFW_ANY_PLATFORM`, `GLFW_PLATFORM_WIN32`,
|
||||
`GLFW_PLATFORM_COCOA`, `GLFW_PLATFORM_X11`, `GLFW_PLATFORM_WAYLAND` and
|
||||
`GLFW_PLATFORM_NULL`. The default value is `GLFW_ANY_PLATFORM`, which will
|
||||
choose any platform the library includes support for except for the Null
|
||||
backend.
|
||||
|
||||
|
||||
@anchor GLFW_JOYSTICK_HAT_BUTTONS
|
||||
__GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as
|
||||
buttons, for compatibility with earlier versions of GLFW that did not have @ref
|
||||
@@ -137,6 +147,7 @@ the `VK_KHR_xlib_surface` extension. Possible values are `GLFW_TRUE` and
|
||||
|
||||
Initialization hint | Default value | Supported values
|
||||
-------------------------------- | ------------------------------- | ----------------
|
||||
@ref GLFW_PLATFORM | `GLFW_ANY_PLATFORM` | `GLFW_ANY_PLATFORM`, `GLFW_PLATFORM_WIN32`, `GLFW_PLATFORM_COCOA`, `GLFW_PLATFORM_X11`, `GLFW_PLATFORM_WAYLAND` or `GLFW_PLATFORM_NULL`
|
||||
@ref GLFW_JOYSTICK_HAT_BUTTONS | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
||||
@ref GLFW_ANGLE_PLATFORM_TYPE | `GLFW_ANGLE_PLATFORM_TYPE_NONE` | `GLFW_ANGLE_PLATFORM_TYPE_NONE`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGL`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGLES`, `GLFW_ANGLE_PLATFORM_TYPE_D3D9`, `GLFW_ANGLE_PLATFORM_TYPE_D3D11`, `GLFW_ANGLE_PLATFORM_TYPE_VULKAN` or `GLFW_ANGLE_PLATFORM_TYPE_METAL`
|
||||
@ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
||||
@@ -144,6 +155,48 @@ Initialization hint | Default value | Supported v
|
||||
@ref GLFW_X11_XCB_VULKAN_SURFACE | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
||||
|
||||
|
||||
@subsection platform Runtime platform selection
|
||||
|
||||
GLFW can be compiled for more than one platform (window system) at once. This lets
|
||||
a single library binary support both X11 and Wayland on Linux and other Unix-like systems.
|
||||
|
||||
You can control platform selection via the @ref GLFW_PLATFORM initialization hint. By
|
||||
default this is set to @ref GLFW_ANY_PLATFORM, which will look for supported window
|
||||
systems in order of priority and select the first one it finds. It can also be set to any
|
||||
specific platform to have GLFW only look for that one.
|
||||
|
||||
@code
|
||||
glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_X11);
|
||||
@endcode
|
||||
|
||||
This mechanism also provides the Null platform, which is always supported but needs to be
|
||||
explicitly requested. This platform is effectively a stub, emulating a window system on
|
||||
a single 1080p monitor, but will not interact with any actual window system.
|
||||
|
||||
@code
|
||||
glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_NULL);
|
||||
@endcode
|
||||
|
||||
You can test whether a library binary was compiled with support for a specific platform
|
||||
with @ref glfwPlatformSupported.
|
||||
|
||||
@code
|
||||
if (glfwPlatformSupported(GLFW_PLATFORM_WAYLAND))
|
||||
glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_WAYLAND);
|
||||
@endcode
|
||||
|
||||
Once GLFW has been initialized, you can query which platform was selected with @ref
|
||||
glfwGetPlatform.
|
||||
|
||||
@code
|
||||
int platform = glfwGetPlatform();
|
||||
@endcode
|
||||
|
||||
If you are using any [native access functions](@ref native), especially on Linux and other
|
||||
Unix-like systems, then you may need to check that you are calling the ones matching the
|
||||
selected platform.
|
||||
|
||||
|
||||
@subsection init_allocator Custom heap memory allocator
|
||||
|
||||
The heap memory allocator can be customized before initialization with @ref
|
||||
@@ -437,6 +490,11 @@ Library version information may be queried from any thread.
|
||||
- @ref glfwGetVersion
|
||||
- @ref glfwGetVersionString
|
||||
|
||||
Platform information may be queried from any thread.
|
||||
|
||||
- @ref glfwPlatformSupported
|
||||
- @ref glfwGetPlatform
|
||||
|
||||
All Vulkan related functions may be called from any thread.
|
||||
|
||||
- @ref glfwVulkanSupported
|
||||
@@ -529,17 +587,32 @@ __Do not use the version string__ to parse the GLFW library version. The @ref
|
||||
glfwGetVersion function already provides the version of the running library
|
||||
binary.
|
||||
|
||||
__Do not use the version string__ to parse what platforms are supported. The @ref
|
||||
glfwPlatformSupported function lets you query platform support.
|
||||
|
||||
__GLFW 3.4:__ The format of this string was changed to support the addition of
|
||||
[runtime platform selection](@ref platform).
|
||||
|
||||
The format of the string is as follows:
|
||||
- The version of GLFW
|
||||
- The name of the window system API
|
||||
- The name of the context creation API
|
||||
- Any additional options or APIs
|
||||
- For each supported platform:
|
||||
- The name of the window system API
|
||||
- The name of the window system specific context creation API, if applicable
|
||||
- The names of the always supported context creation APIs EGL and OSMesa
|
||||
- Any additional compile-time options, APIs and (on Windows) what compiler was used
|
||||
|
||||
For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
|
||||
back ends, the version string may look something like this:
|
||||
For example, GLFW 3.4 compiled as a DLL for Windows with MinGW may have a version string
|
||||
like this:
|
||||
|
||||
@code
|
||||
3.0.0 Win32 WGL MinGW
|
||||
3.4.0 Win32 WGL Null EGL OSMesa MinGW DLL
|
||||
@endcode
|
||||
|
||||
While GLFW compiled as as static library for Linux with both Wayland and X11 enabled may
|
||||
have a version string like this:
|
||||
|
||||
@code
|
||||
3.4.0 Wayland X11 GLX Null EGL OSMesa monotonic
|
||||
@endcode
|
||||
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user