Documentation updates for 3.4 release
diff --git a/README.md b/README.md
index c1e9f27..efd1383 100644
--- a/README.md
+++ b/README.md
@@ -16,9 +16,9 @@
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 @@
- 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 974e5fc..c70f735 100644
--- a/docs/main.md
+++ b/docs/main.md
@@ -4,7 +4,7 @@
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 e68464f..3be9548 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
[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 @@
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 @@
```
-#### 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 @@
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 @@
- @ref glfwGetCocoaView
-#### New types in version 3.4 {#types_34}
+### New types {#new_types}
- @ref GLFWallocator
- @ref GLFWallocatefun
@@ -281,7 +349,7 @@
- @ref GLFWdeallocatefun
-#### New constants in version 3.4 {#constants_34}
+### New constants {#new_constants}
- @ref GLFW_PLATFORM
- @ref GLFW_ANY_PLATFORM
