From 7b6aead9fb88b3623e3b3725ebb42670cbe4c579 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilla=20L=C3=B6wy?= Date: Thu, 22 Feb 2024 22:22:47 +0100 Subject: [PATCH] Documentation updates for 3.4 release --- README.md | 8 +- docs/main.md | 2 +- docs/news.md | 282 ++++++++++++++++++++++++++++++++------------------- 3 files changed, 180 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index c1e9f27a..efd1383f 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ GLFW is licensed under the [zlib/libpng license](https://www.glfw.org/license.html). You can [download](https://www.glfw.org/download.html) the latest stable release -as source or Windows binaries, or fetch the `latest` branch from GitHub. Each -release starting with 3.0 also has a corresponding [annotated -tag](https://github.com/glfw/glfw/releases) with source and binary archives. +as source or Windows binaries. Each release starting with 3.0 also has +a corresponding [annotated tag](https://github.com/glfw/glfw/releases) with +source and binary archives. The [documentation](https://www.glfw.org/docs/latest/) is available online and is included in all source and binary archives. See the [release @@ -170,7 +170,7 @@ information on what to include when reporting a bug. - Made joystick subsystem initialize at first use (#1284,#1646) - Made `GLFW_DOUBLEBUFFER` a read-only window attribute - Made Wayland the preferred platform over X11 if both are available (#2035) - - Updated the minimum required CMake version to 3.1 + - Updated the minimum required CMake version to 3.4 - Updated gamepad mappings from upstream - Renamed `GLFW_USE_WAYLAND` CMake option to `GLFW_BUILD_WAYLAND` (#1958) - Disabled tests and examples by default when built as a CMake subdirectory diff --git a/docs/main.md b/docs/main.md index 974e5fce..c70f735f 100644 --- a/docs/main.md +++ b/docs/main.md @@ -4,7 +4,7 @@ GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan application development. It provides a simple, platform-independent API for creating windows, contexts and surfaces, reading input, handling events, etc. -@ref news_34 list new features, caveats and deprecations. +@ref news list new features, caveats and deprecations. @ref quick_guide is a guide for users new to GLFW. It takes you through how to write a small but complete program. diff --git a/docs/news.md b/docs/news.md index e68464f6..3be95488 100644 --- a/docs/news.md +++ b/docs/news.md @@ -1,27 +1,21 @@ -# Release notes {#news} +# Release notes for version 3.4 {#news} [TOC] -## Release notes for version 3.4 {#news_34} +## New features {#features} -### New features in version 3.4 {#features_34} - -#### Cocoa NSView native access function {#native_cocoa_nsview_34} - -GLFW now provides the @ref glfwGetCocoaView native access function -for returning the Cocoa NSView. - - -#### Runtime platform selection {#runtime_platform_34} +### Runtime platform selection {#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. +For more information see @ref platform. -#### More standard cursor shapes {#standard_cursors_34} + +### More standard cursor shapes {#more_cursor_shapes} GLFW now provides the standard cursor shapes @ref GLFW_RESIZE_NWSE_CURSOR and @ref GLFW_RESIZE_NESW_CURSOR for diagonal resizing, @ref GLFW_RESIZE_ALL_CURSOR @@ -39,7 +33,7 @@ are still available. For more information see @ref cursor_standard. -#### Mouse event passthrough {#mouse_passthrough_34} +### Mouse event passthrough {#mouse_input_passthrough} GLFW now provides the [GLFW_MOUSE_PASSTHROUGH](@ref GLFW_MOUSE_PASSTHROUGH_hint) window hint for making a window transparent to mouse input, lettings events pass @@ -47,7 +41,7 @@ to whatever window is behind it. This can also be changed after window creation with the matching [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib). -#### Ability to get window title {#features_34_window_title} +### Ability to get window title {#window_title_function} GLFW now supports querying the title of a window with the @ref glfwGetWindowTitle function. @@ -55,7 +49,7 @@ function. For more information see @ref window_title. -#### Captured cursor mode {#captured_cursor_34} +### Captured cursor mode {#captured_cursor_mode} GLFW now supports confining the cursor to the window content area with the @ref GLFW_CURSOR_CAPTURED cursor mode. @@ -63,17 +57,17 @@ GLFW_CURSOR_CAPTURED cursor mode. For more information see @ref cursor_mode. -#### Support for custom heap memory allocator {#features_34_init_allocator} +### Support for custom heap memory allocator {#custom_heap_allocator} -GLFW now supports plugging a custom memory allocator at initialization with @ref -glfwInitAllocator. The allocator is a struct of type @ref GLFWallocator with -function pointers corresponding to the standard library functions `malloc`, +GLFW now supports plugging a custom heap memory allocator at initialization with +@ref glfwInitAllocator. The allocator is a struct of type @ref GLFWallocator +with function pointers corresponding to the standard library functions `malloc`, `realloc` and `free`. For more information see @ref init_allocator. -#### Window hint for framebuffer scaling {#scale_framebuffer_34} +### Window hint for framebuffer scaling {#scale_framebuffer_hint} GLFW now allows provides the [GLFW_SCALE_FRAMEBUFFER](@ref GLFW_SCALE_FRAMEBUFFER_hint) window hint for @@ -83,13 +77,12 @@ allow framebuffer scaling. This was already possible on macOS via the [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint) window -hint. This hint is now another name for -[GLFW_SCALE_FRAMEBUFFER](@ref GLFW_SCALE_FRAMEBUFFER_hint). +hint. This is now another name for the same hint value. For more information see @ref window_scale. -#### Window hints for initial window position {#features_34_position_hint} +### Window hints for initial window position {#window_position_hint} GLFW now provides the @ref GLFW_POSITION_X and @ref GLFW_POSITION_Y window hints for specifying the initial position of the window. This removes the need to create a hidden @@ -99,39 +92,7 @@ window, move it and then show it. The default value of these hints is For more information see @ref window_pos. -#### Support for keyboard access to Windows window menu {#features_34_win32_keymenu} - -GLFW now provides the -[GLFW_WIN32_KEYBOARD_MENU](@ref GLFW_WIN32_KEYBOARD_MENU_hint) window hint for -enabling keyboard access to the window menu via the Alt+Space and -Alt-and-then-Space shortcuts. This may be useful for more GUI-oriented -applications. - - -#### Support for applying STARTUPINFO show command {#features_34_win32_showdefault} - -GLFW now provides the [GLFW_WIN32_SHOWDEFAULT](@ref GLFW_WIN32_SHOWDEFAULT_hint) window -hint for applying the show command in the program's `STARTUPINFO` when showing the window -for the first time. This may be useful for the main window of a windowed-mode tool. - - -#### Wayland libdecor decorations {#wayland_libdecor_34} - -GLFW now supports improved fallback window decorations via -[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor). - -Support for libdecor can be toggled before GLFW is initialized with the -[GLFW_WAYLAND_LIBDECOR](@ref GLFW_WAYLAND_LIBDECOR_hint) init hint. It is -enabled by default. - - -#### Window hint for Wayland app_id {#wayland_app_id_34} - -GLFW now supports specifying the app_id for a Wayland window using the -[GLFW_WAYLAND_APP_ID](@ref GLFW_WAYLAND_APP_ID_hint) window hint string. - - -#### Support for ANGLE rendering backend selection {#features_34_angle_backend} +### ANGLE rendering backend hint {#angle_renderer_hint} GLFW now provides the [GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for @@ -141,9 +102,59 @@ contexts. [ANGLE]: https://chromium.googlesource.com/angle/angle/ -### Caveats for version 3.4 {#caveats} +### Windows window menu keyboard access hint {#win32_keymenu_hint} -#### Multiple sets of native access functions {#native_34} +GLFW now provides the +[GLFW_WIN32_KEYBOARD_MENU](@ref GLFW_WIN32_KEYBOARD_MENU_hint) window hint for +enabling keyboard access to the window menu via the Alt+Space and +Alt-and-then-Space shortcuts. This may be useful for more GUI-oriented +applications. + + +### Windows STARTUPINFO show command hint {#win32_showdefault_hint} + +GLFW now provides the [GLFW_WIN32_SHOWDEFAULT](@ref GLFW_WIN32_SHOWDEFAULT_hint) window +hint for applying the show command in the program's `STARTUPINFO` when showing the window +for the first time. This may be useful for the main window of a windowed-mode tool. + + +### Cocoa NSView native access function {#cocoa_nsview_function} + +GLFW now provides the @ref glfwGetCocoaView native access function +for returning the Cocoa NSView. + + +### Wayland libdecor decorations {#wayland_libdecor_decorations} + +GLFW now supports improved client-side window decorations via +[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor). This provides +fully featured window decorations on desktop environments like GNOME. + +Support for libdecor can be toggled before GLFW is initialized with the +[GLFW_WAYLAND_LIBDECOR](@ref GLFW_WAYLAND_LIBDECOR_hint) init hint. It is +enabled by default. + +This feature has also been available in GLFW 3.3 since 3.3.9. + + +### Wayland surface app_id hint {#wayland_app_id_hint} + +GLFW now supports specifying the app_id for a Wayland window using the +[GLFW_WAYLAND_APP_ID](@ref GLFW_WAYLAND_APP_ID_hint) window hint string. + + +### X11 Vulkan window surface hint {#x11_xcb_vulkan_surface} + +GLFW now supports disabling the use of `VK_KHR_xcb_surface` over +`VK_KHR_xlib_surface` where available, with the +[GLFW_X11_XCB_VULKAN_SURFACE](@ref GLFW_X11_XCB_VULKAN_SURFACE_hint) init hint. +This affects @ref glfwGetRequiredInstanceExtensions and @ref +glfwCreateWindowSurface. + + +## Caveats {#caveats} + +### Multiple sets of native access functions {#multiplatform_caveat} 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 @@ -152,47 +163,40 @@ functions for it. After initialization, you can query the selected platform wit glfwGetPlatform. -#### Version string format has been changed {#version_string_34} +### Version string format has been changed {#version_string_caveat} 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. +The version string is intended for bug reporting and should not be parsed. See +@ref glfwGetVersion and @ref glfwPlatformSupported instead. -#### Joystick support is initialized on demand {#joysticks_34} + +### Joystick support is initialized on demand {#joystick_init_caveat} The joystick part of GLFW is now initialized when first used, primarily to work around faulty Windows drivers that cause DirectInput to take up to several seconds to enumerate devices. -This change will usually not be observable. However, if your application waits -for events without having first called any joystick function or created any -visible windows, the wait may never unblock as GLFW may not yet have subscribed -to joystick related OS events. +This change is mostly not observable. However, if your application waits for +events without having first called any joystick function or created any visible +windows, the wait may never unblock as GLFW may not yet have subscribed to +joystick related OS events. To work around this, call any joystick function before waiting for events, for example by setting a [joystick callback](@ref joystick_event). -#### Framebuffer may lack alpha channel on older Wayland systems {#wayland_alpha_34} +### Tests and examples are disabled when built as a subproject {#standalone_caveat} -On Wayland, when creating an EGL context on a machine lacking the new -`EGL_EXT_present_opaque` extension, the @ref GLFW_ALPHA_BITS window hint will be -ignored and the framebuffer will have no alpha channel. This is because some -Wayland compositors treat any buffer with an alpha channel as per-pixel -transparent. +GLFW now by default does not build the tests or examples when it is added as +a subdirectory of another CMake project. If you were setting @ref +GLFW_BUILD_TESTS or @ref GLFW_BUILD_EXAMPLES to false in your CMake files, you +can now remove this. -If you want a per-pixel transparent window, see the -[GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) window -hint. - - -#### Tests and examples are disabled when built as a subproject {#standalone_34} - -GLFW now does not build the tests and examples when it is added as -a subdirectory of another CMake project. To enable these, set the @ref -GLFW_BUILD_TESTS and @ref GLFW_BUILD_EXAMPLES cache variables before adding the -GLFW subdirectory. +If you do want these to be built, set @ref GLFW_BUILD_TESTS and @ref +GLFW_BUILD_EXAMPLES in your CMake files before adding the GLFW subdirectory. ```cmake set(GLFW_BUILD_EXAMPLES ON CACHE BOOL "" FORCE) @@ -201,37 +205,86 @@ add_subdirectory(path/to/glfw) ``` -#### macOS main menu now created at initialization {#initmenu_34} +### Configuration header is no longer generated {#config_header_caveat} + +The `glfw_config.h` configuration header is no longer generated by CMake and the +platform selection macros are now part of the GLFW CMake target. The +`_GLFW_USE_CONFIG_H` macro is still supported in case you are generating +a configuration header in a custom build setup. + + +### Documentation generation requires Doxygen 1.9.8 or later {#docs_target_caveat} + +Doxygen 1.9.8 or later is now required for the `docs` CMake target to be +generated. This is because the documentation now uses more of the Markdown +support in Doxygen and this support has until recently been relatively unstable. + + +### Windows 7 framebuffer transparency requires DWM transparency {#win7_framebuffer_caveat} + +GLFW no longer supports per-pixel framebuffer transparency via @ref +GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off +(the Transparency setting under Personalization > Window Color). + + +### macOS main menu now created at initialization {#macos_menu_caveat} GLFW now creates the main menu and completes the initialization of NSApplication during initialization. Programs that do not want a main menu can disable it with the [GLFW_COCOA_MENUBAR](@ref GLFW_COCOA_MENUBAR_hint) init hint. -#### CoreVideo dependency has been removed {#corevideo_34} +### macOS CoreVideo dependency has been removed {#corevideo_caveat} GLFW no longer depends on the CoreVideo framework on macOS and it no longer needs to be specified during compilation or linking. -#### Framebuffer transparency requires DWM transparency {#caveat_fbtransparency_34} +### Wayland framebuffer may lack alpha channel on older systems {#wayland_alpha_caveat} -GLFW no longer supports framebuffer transparency enabled via @ref -GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off -(the Transparency setting under Personalization > Window Color). +On Wayland, when creating an EGL context on a machine lacking the new +`EGL_EXT_present_opaque` extension, the @ref GLFW_ALPHA_BITS window hint will be +ignored and the framebuffer will not have an alpha channel. This is because +some Wayland compositors treat any buffer with an alpha channel as per-pixel +transparent. + +If you want a per-pixel transparent window, see the +[GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) window +hint. -#### Empty events on X11 no longer round-trip to server {#emptyevents_34} +### X11 empty events no longer round-trip to server {#x11_emptyevent_caveat} Events posted with @ref glfwPostEmptyEvent now use a separate unnamed pipe instead of sending an X11 client event to the helper window. -### Deprecations in version 3.4 {#deprecations_34} +## Deprecations {#deprecations} -### Removals in 3.4 {#removals_34} +### Windows XP and Vista support is deprecated {#winxp_deprecated} -#### GLFW_VULKAN_STATIC CMake option has been removed {#vulkan_static_34} +Support for Windows XP and Vista has been deprecated and will be removed in +a future release. Windows XP has been out of extended support since 2014. + + +### Original MinGW support is deprecated {#mingw_deprecated} + +Support for the now unmaintained original MinGW distribution has been deprecated +and will be removed in a future release. + +This does not apply to the much more capable MinGW-w64, which remains fully +supported, actively maintained and available on many platforms. + + +### OS X Yosemite support is deprecated {#yosemite_deprecated} + +Support for OS X 10.10 Yosemite and earlier has been deprecated and will be +removed in a future release. OS X 10.10 has been out of support since 2017. + + +## Removals {#removals} + +### GLFW_VULKAN_STATIC CMake option has been removed {#vulkan_static_removed} This option was used to compile GLFW directly linked with the Vulkan loader, instead of using dynamic loading to get hold of `vkGetInstanceProcAddr` at initialization. This is @@ -242,28 +295,43 @@ have no effect. The call to @ref glfwInitVulkanLoader can be conditionally enab your code by checking the @ref GLFW_VERSION_MAJOR and @ref GLFW_VERSION_MINOR macros. -#### GLFW_USE_OSMESA CMake option has been removed {#osmesa_option_34} +### GLFW_USE_WAYLAND CMake option has been removed {#use_wayland_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. +This option was used to compile GLFW for Wayland instead of X11. GLFW now +supports selecting the platform at run-time. By default GLFW is compiled for +both Wayland and X11 on Linux and other Unix-like systems. -You can set all of them to false and the ones that don't apply for the target OS will be -ignored. +To disable Wayland or X11 or both, set the @ref GLFW_BUILD_WAYLAND and @ref +GLFW_BUILD_X11 CMake options. + +The `GLFW_USE_WAYLAND` CMake variable must not be present in the CMake cache at +all, or GLFW will fail to configure. If you are getting this error, delete the +CMake cache for GLFW and configure again. -#### Support for the wl_shell protocol has been removed {#wl_shell_34} +### GLFW_USE_OSMESA CMake option has been removed {#use_osmesa_removed} -Support for the wl_shell protocol has been removed and GLFW now only supports -the XDG-Shell protocol. If your Wayland compositor does not support XDG-Shell -then GLFW will fail to initialize. +This option was used to compile GLFW for the Null platform. The Null platform +is now always available. 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 platforms for the target OS. This means setting the @ref +GLFW_BUILD_WIN32, @ref GLFW_BUILD_COCOA or @ref GLFW_BUILD_WAYLAND and @ref +GLFW_BUILD_X11 CMake options to false. + +You can set all of them to false and the ones that don't apply for the target OS +will be ignored. -### New symbols in version 3.4 {#symbols_34} +### wl_shell protocol support has been removed {#wl_shell_removed} -#### New functions in version 3.4 {#functions_34} +Support for the deprecated wl_shell protocol has been removed and GLFW now only +supports the XDG-Shell protocol. If your Wayland compositor does not support +XDG-Shell then GLFW will fail to initialize. + + +## New symbols {#new_symbols} + +### New functions {#new_functions} - @ref glfwInitAllocator - @ref glfwGetPlatform @@ -273,7 +341,7 @@ then GLFW will fail to initialize. - @ref glfwGetCocoaView -#### New types in version 3.4 {#types_34} +### New types {#new_types} - @ref GLFWallocator - @ref GLFWallocatefun @@ -281,7 +349,7 @@ then GLFW will fail to initialize. - @ref GLFWdeallocatefun -#### New constants in version 3.4 {#constants_34} +### New constants {#new_constants} - @ref GLFW_PLATFORM - @ref GLFW_ANY_PLATFORM