mirror of
https://github.com/glfw/glfw.git
synced 2026-02-17 21:12:34 +01: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
@@ -71,37 +71,42 @@ pkg install xorgproto
|
||||
On Cygwin the `xorgproto` package in the Devel section of the GUI installer will
|
||||
install the headers and other development related files for all of X11.
|
||||
|
||||
Once you have the required depdendencies, move on to @ref compile_generate.
|
||||
Once you have the required dependencies, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsubsection compile_deps_wayland Dependencies for Wayland on Unix-like systems
|
||||
@subsubsection compile_deps_wayland Dependencies for Wayland and X11 on Unix-like systems
|
||||
|
||||
To compile GLFW for Wayland, you need to have the Wayland and xkbcommon
|
||||
development packages installed. They are not needed to build or run programs
|
||||
that use GLFW.
|
||||
To compile GLFW for both Wayland and X11, you need to have the X11, Wayland and xkbcommon
|
||||
development packages installed. They are not needed to build or run programs that use
|
||||
GLFW. You will also need to set the @ref GLFW_BUILD_WAYLAND CMake option in the next
|
||||
step when generating build files.
|
||||
|
||||
On Debian and derivates like Ubuntu and Linux Mint you will need the
|
||||
`libwayland-dev`, `libxkbcommon-dev` and `wayland-protocols` packages.
|
||||
On Debian and derivates like Ubuntu and Linux Mint you will need the `libwayland-dev`,
|
||||
`libxkbcommon-dev` and `wayland-protocols` packages and the `xorg-dev` meta-package.
|
||||
These will pull in all other dependencies.
|
||||
|
||||
@code{.sh}
|
||||
sudo apt install libwayland-dev libxkbcommon-dev wayland-protocols
|
||||
sudo apt install libwayland-dev libxkbcommon-dev wayland-protocols xorg-dev
|
||||
@endcode
|
||||
|
||||
On Fedora and derivatives like Red Hat you will need the `wayland-devel`,
|
||||
`libxkbcommon-devel` and `wayland-protocols-devel` packages.
|
||||
`libxkbcommon-devel`, `wayland-protocols-devel`, `libXcursor-devel`, `libXi-devel`,
|
||||
`libXinerama-devel` and `libXrandr-devel` packages. These will pull in all other
|
||||
dependencies.
|
||||
|
||||
@code{.sh}
|
||||
sudo dnf install wayland-devel libxkbcommon-devel wayland-protocols-devel
|
||||
sudo dnf install wayland-devel libxkbcommon-devel wayland-protocols-devel libXcursor-devel libXi-devel libXinerama-devel libXrandr-devel
|
||||
@endcode
|
||||
|
||||
On FreeBSD you will need the `wayland`, `libxkbcommon` and `wayland-protocols`
|
||||
packages.
|
||||
On FreeBSD you will need the `wayland`, `libxkbcommon` and `wayland-protocols` packages.
|
||||
The X11 headers are installed along the end-user X11 packages, so if you have an X server
|
||||
running you should have the headers as well. If not, install the `xorgproto` package.
|
||||
|
||||
@code{.sh}
|
||||
pkg install wayland libxkbcommon wayland-protocols
|
||||
pkg install wayland libxkbcommon wayland-protocols xorgproto
|
||||
@endcode
|
||||
|
||||
Once you have the required depdendencies, move on to @ref compile_generate.
|
||||
Once you have the required dependencies, move on to @ref compile_generate.
|
||||
|
||||
|
||||
@subsection compile_generate Generating build files with CMake
|
||||
@@ -135,9 +140,9 @@ If you wish change any CMake variables in the list, press _Configure_ and then
|
||||
_Generate_ to have the new values take effect. The variable list will be
|
||||
populated after the first configure step.
|
||||
|
||||
By default GLFW will use X11 on Linux and other Unix-like systems other
|
||||
than macOS. To use Wayland instead, set the `GLFW_USE_WAYLAND` option in the
|
||||
GLFW section of the variable list, then apply the new value as described above.
|
||||
By default GLFW will use X11 on Linux and other Unix-like systems other than macOS. To
|
||||
include support for Wayland as well, set the @ref GLFW_BUILD_WAYLAND option in the GLFW
|
||||
section of the variable list, then apply the new value as described above.
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
development environment, move on to @ref compile_compile.
|
||||
@@ -170,10 +175,11 @@ cmake -S path/to/glfw -B path/to/build -G Xcode
|
||||
@endcode
|
||||
|
||||
By default GLFW will use X11 on Linux and other Unix-like systems other
|
||||
than macOS. To use Wayland instead, set the `GLFW_USE_WAYLAND` CMake option.
|
||||
than macOS. To also include support for Wayland, set the @ref GLFW_BUILD_WAYLAND CMake
|
||||
option.
|
||||
|
||||
@code{.sh}
|
||||
cmake -S path/to/glfw -B path/to/build -D GLFW_USE_WAYLAND=1
|
||||
cmake -S path/to/glfw -B path/to/build -D GLFW_BUILD_WAYLAND=1
|
||||
@endcode
|
||||
|
||||
Once you have generated the project files or makefiles for your chosen
|
||||
@@ -274,6 +280,11 @@ directly with the application. This is disabled by default.
|
||||
|
||||
@subsection compile_options_win32 Windows specific CMake options
|
||||
|
||||
@anchor GLFW_BUILD_WIN32
|
||||
__GLFW_BUILD_WIN32__ determines whether to include support for Win32 when compiling the
|
||||
library. This option is only available when compiling for Windows. This is enabled by
|
||||
default.
|
||||
|
||||
@anchor USE_MSVC_RUNTIME_LIBRARY_DLL
|
||||
__USE_MSVC_RUNTIME_LIBRARY_DLL__ determines whether to use the DLL version or the
|
||||
static library version of the Visual C++ runtime library. When enabled, the
|
||||
@@ -292,12 +303,25 @@ will not work if GLFW is built as a DLL. This is disabled by default, letting
|
||||
the operating system and driver decide.
|
||||
|
||||
|
||||
@subsection compile_options_wayland Wayland specific CMake options
|
||||
@subsection compile_options_macos macOS specific CMake options
|
||||
|
||||
@anchor GLFW_USE_WAYLAND
|
||||
__GLFW_USE_WAYLAND__ determines whether to compile the library for Wayland.
|
||||
This option is only available on Linux and other Unix-like systems other than
|
||||
macOS. This is disabled by default.
|
||||
@anchor GLFW_BUILD_COCOA
|
||||
__GLFW_BUILD_COCOA__ determines whether to include support for Cocoa when compiling the
|
||||
library. This option is only available when compiling for macOS. This is enabled by
|
||||
default.
|
||||
|
||||
|
||||
@subsection compile_options_unix Unix-like system specific CMake options
|
||||
|
||||
@anchor GLFW_BUILD_WAYLAND
|
||||
__GLFW_BUILD_WAYLAND__ determines whether to include support for Wayland when compiling
|
||||
the library. This option is only available when compiling for Linux and other Unix-like
|
||||
systems other than macOS. This is disabled by default.
|
||||
|
||||
@anchor GLFW_BUILD_X11
|
||||
__GLFW_BUILD_X11__ determines whether to include support for X11 when compiling the
|
||||
library. This option is only available when compiling for Linux and other Unix-like
|
||||
systems other than macOS. This is enabled by default.
|
||||
|
||||
|
||||
@section compile_mingw_cross Cross-compilation with CMake and MinGW
|
||||
@@ -335,25 +359,26 @@ For more details see the
|
||||
|
||||
@section compile_manual Compiling GLFW manually
|
||||
|
||||
If you wish to compile GLFW without its CMake build environment then you will
|
||||
have to do at least some of the platform detection yourself. GLFW needs
|
||||
a configuration macro to be defined in order to know what window system it is
|
||||
being compiled for and also has optional, platform-specific ones for various
|
||||
features.
|
||||
If you wish to compile GLFW without its CMake build environment then you will have to do
|
||||
at least some of the platform detection yourself. There are preprocessor macros for
|
||||
enabling support for the platforms (window systems) available. There are also optional,
|
||||
platform-specific macros for various features.
|
||||
|
||||
When building, GLFW will expect the necessary configuration macros to be defined
|
||||
on the command-line. The GLFW CMake files set these as private compile
|
||||
definitions on the GLFW target but if you compile the GLFW sources manually you
|
||||
will need to define them yourself.
|
||||
|
||||
The window creation API is used to create windows, handle input, monitors, gamma
|
||||
ramps and clipboard. The options are:
|
||||
The window system is used to create windows, handle input, monitors, gamma ramps and
|
||||
clipboard. The options are:
|
||||
|
||||
- @b _GLFW_COCOA to use the Cocoa frameworks
|
||||
- @b _GLFW_WIN32 to use the Win32 API
|
||||
- @b _GLFW_X11 to use the X Window System
|
||||
- @b _GLFW_WAYLAND to use the Wayland API (experimental and incomplete)
|
||||
- @b _GLFW_OSMESA to use the OSMesa API (headless and non-interactive)
|
||||
- @b _GLFW_WAYLAND to use the Wayland API (incomplete)
|
||||
|
||||
The @b _GLFW_WAYLAND and @b _GLFW_X11 macros may be combined and produces a library that
|
||||
attempts to detect the appropriate platform at initialization.
|
||||
|
||||
If you are building GLFW as a shared library / dynamic library / DLL then you
|
||||
must also define @b _GLFW_BUILD_DLL. Otherwise, you must not define it.
|
||||
|
||||
@@ -61,12 +61,21 @@ 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 mirrors those parts of the public interface that needs to
|
||||
perform platform-specific operations on some or all platforms. The are also
|
||||
named the same except that the glfw function prefix is replaced by
|
||||
_glfwPlatform.
|
||||
The platform interface mostly mirrors those parts of the public interface that needs to
|
||||
perform platform-specific operations on some or all platforms.
|
||||
|
||||
Examples: `_glfwPlatformCreateWindow`
|
||||
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
|
||||
|
||||
@@ -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
|
||||
|
||||
*/
|
||||
|
||||
@@ -9,6 +9,14 @@
|
||||
|
||||
@subsection features_34 New features in version 3.4
|
||||
|
||||
@subsubsection runtime_platform_34 Runtime platform selection
|
||||
|
||||
GLFW now supports being compiled for multiple backends and selecting between
|
||||
them at runtime with the @ref GLFW_PLATFORM init hint. After initialization the
|
||||
selected platform can be queried with @ref glfwGetPlatform. You can check if
|
||||
support for a given platform is compiled in with @ref glfwPlatformSupported.
|
||||
|
||||
|
||||
@subsubsection standard_cursors_34 More standard cursors
|
||||
|
||||
GLFW now provides the standard cursor shapes @ref GLFW_RESIZE_NWSE_CURSOR and
|
||||
@@ -63,7 +71,23 @@ Alt-and-then-Space shortcuts. This may be useful for more GUI-oriented
|
||||
applications.
|
||||
|
||||
|
||||
@subsection caveats_34 Caveats for version 3.4
|
||||
@subsection caveats Caveats for version 3.4
|
||||
|
||||
@subsubsection native_34 Multiple sets of native access functions
|
||||
|
||||
Because GLFW now supports runtime selection of platform (window system), a library binary
|
||||
may export native access functions for multiple platforms. Starting with version 3.4 you
|
||||
must not assume that GLFW is running on a platform just because it exports native access
|
||||
functions for it. After initialization you can query the selected platform with @ref
|
||||
glfwGetPlatform.
|
||||
|
||||
|
||||
@subsubsection version_string_34 Version string format has been changed
|
||||
|
||||
Because GLFW now supports runtime selection of platform (window system), the version
|
||||
string returned by @ref glfwGetVersionString has been expanded. It now contains the names
|
||||
of all APIs for all the platforms that the library binary supports.
|
||||
|
||||
|
||||
@subsubsection joysticks_34 Joystick support is initialized on demand
|
||||
|
||||
@@ -118,6 +142,18 @@ GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off
|
||||
|
||||
@subsection removals_34 Removals in 3.4
|
||||
|
||||
@subsubsection osmesa_option_34 GLFW_USE_OSMESA CMake option has been removed
|
||||
|
||||
This option was used to compile GLFW for the Null platform. The Null platform is now
|
||||
always supported. To produce a library binary that only supports this platform, the way
|
||||
this CMake option used to do, you will instead need to disable the default platform for
|
||||
the target OS. This means setting the @ref GLFW_BUILD_WIN32, @ref GLFW_BUILD_COCOA or
|
||||
@ref GLFW_BUILD_X11 CMake option to false.
|
||||
|
||||
You can set all of them to false and the ones that don't apply for the target OS will be
|
||||
ignored.
|
||||
|
||||
|
||||
@subsubsection wl_shell_34 Support for the wl_shell protocol has been removed
|
||||
|
||||
Support for the wl_shell protocol has been removed and GLFW now only supports
|
||||
@@ -130,6 +166,8 @@ then GLFW will fail to initialize.
|
||||
@subsubsection functions_34 New functions in version 3.4
|
||||
|
||||
- @ref glfwInitAllocator
|
||||
- @ref glfwGetPlatform
|
||||
- @ref glfwPlatformSupported
|
||||
|
||||
|
||||
@subsubsection types_34 New types in version 3.4
|
||||
@@ -142,6 +180,14 @@ then GLFW will fail to initialize.
|
||||
|
||||
@subsubsection constants_34 New constants in version 3.4
|
||||
|
||||
- @ref GLFW_PLATFORM
|
||||
- @ref GLFW_ANY_PLATFORM
|
||||
- @ref GLFW_PLATFORM_WIN32
|
||||
- @ref GLFW_PLATFORM_COCOA
|
||||
- @ref GLFW_PLATFORM_WAYLAND
|
||||
- @ref GLFW_PLATFORM_X11
|
||||
- @ref GLFW_PLATFORM_NULL
|
||||
- @ref GLFW_PLATFORM_UNAVAILABLE
|
||||
- @ref GLFW_POINTING_HAND_CURSOR
|
||||
- @ref GLFW_RESIZE_EW_CURSOR
|
||||
- @ref GLFW_RESIZE_NS_CURSOR
|
||||
|
||||
Reference in New Issue
Block a user