Documentation updates for 3.4 release

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
+as source or Windows binaries.  Each release starting with 3.0 also has
-release starting with 3.0 also has a corresponding [annotated
+a corresponding [annotated tag](https://github.com/glfw/glfw/releases) with
-tag](https://github.com/glfw/glfw/releases) with source and binary archives.
+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

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.

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}
+### Runtime platform selection {#runtime_platform_selection}
-
-#### 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}
 
 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
+GLFW now supports plugging a custom heap memory allocator at initialization with
-glfwInitAllocator.  The allocator is a struct of type @ref GLFWallocator with
+@ref glfwInitAllocator.  The allocator is a struct of type @ref GLFWallocator
-function pointers corresponding to the standard library functions `malloc`,
+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
+hint.  This is now another name for the same hint value.
-[GLFW_SCALE_FRAMEBUFFER](@ref GLFW_SCALE_FRAMEBUFFER_hint).
 
 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,7 +92,17 @@ 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}
+### ANGLE rendering backend hint {#angle_renderer_hint}
+
+GLFW now provides the
+[GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for
+requesting a specific rendering backend when using [ANGLE][] to create OpenGL ES
+contexts.
+
+[ANGLE]: https://chromium.googlesource.com/angle/angle/
+
+
+### Windows window menu keyboard access hint {#win32_keymenu_hint}
 
 GLFW now provides the
 [GLFW_WIN32_KEYBOARD_MENU](@ref GLFW_WIN32_KEYBOARD_MENU_hint) window hint for
@@ -108,42 +111,50 @@ Alt-and-then-Space shortcuts.  This may be useful for more GUI-oriented
 applications.
 
 
-#### Support for applying STARTUPINFO show command {#features_34_win32_showdefault}
+### 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.
 
 
-#### Wayland libdecor decorations {#wayland_libdecor_34}
+### Cocoa NSView native access function {#cocoa_nsview_function}
+
+GLFW now provides the @ref glfwGetCocoaView native access function
+for returning the Cocoa NSView.
 
-GLFW now supports improved fallback window decorations via
+
-[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor).
+### 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.
+
 
-#### Window hint for Wayland app_id {#wayland_app_id_34}
+### 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.
 
 
-#### Support for ANGLE rendering backend selection {#features_34_angle_backend}
+### X11 Vulkan window surface hint {#x11_xcb_vulkan_surface}
 
-GLFW now provides the
+GLFW now supports disabling the use of `VK_KHR_xcb_surface` over
-[GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for
+`VK_KHR_xlib_surface` where available, with the
-requesting a specific rendering backend when using [ANGLE][] to create OpenGL ES
+[GLFW_X11_XCB_VULKAN_SURFACE](@ref GLFW_X11_XCB_VULKAN_SURFACE_hint) init hint.
-contexts.
+This affects @ref glfwGetRequiredInstanceExtensions and @ref
-
+glfwCreateWindowSurface.
-[ANGLE]: https://chromium.googlesource.com/angle/angle/
 
 
-### Caveats for version 3.4 {#caveats}
+## Caveats {#caveats}
 
-#### Multiple sets of native access functions {#native_34}
+### 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
+This change is mostly not observable.  However, if your application waits for
-for events without having first called any joystick function or created any
+events without having first called any joystick function or created any visible
-visible windows, the wait may never unblock as GLFW may not yet have subscribed
+windows, the wait may never unblock as GLFW may not yet have subscribed to
-to joystick related OS events.
+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.
-
-If you want a per-pixel transparent window, see the
-[GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) window
-hint.
 
+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.
 
-#### Tests and examples are disabled when built as a subproject {#standalone_34}
+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.
-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.
 
 ```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
+On Wayland, when creating an EGL context on a machine lacking the new
-GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off
+`EGL_EXT_present_opaque` extension, the @ref GLFW_ALPHA_BITS window hint will be
-(the Transparency setting under Personalization > Window Color).
+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}
+
+### Windows XP and Vista support is deprecated {#winxp_deprecated}
+
+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.
 
-### Removals in 3.4 {#removals_34}
 
-#### GLFW_VULKAN_STATIC CMake option has been removed {#vulkan_static_34}
+### 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 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.
+
+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.
+
+
+### GLFW_USE_OSMESA CMake option has been removed {#use_osmesa_removed}
 
-This option was used to compile GLFW for the Null platform.  The Null platform is now
+This option was used to compile GLFW for the Null platform.  The Null platform
-always supported.  To produce a library binary that only supports this platform, the way
+is now always available.  To produce a library binary that only supports this
-this CMake option used to do, you will instead need to disable the default platform for
+platform, the way this CMake option used to do, you will instead need to disable
-the target OS.  This means setting the @ref GLFW_BUILD_WIN32, @ref GLFW_BUILD_COCOA or
+the default platforms for the target OS.  This means setting the @ref
-@ref GLFW_BUILD_X11 CMake option to false.
+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
+You can set all of them to false and the ones that don't apply for the target OS
-ignored.
+will be ignored.
 
 
-#### Support for the wl_shell protocol has been removed {#wl_shell_34}
+### wl_shell protocol support has been removed {#wl_shell_removed}
 
-Support for the wl_shell protocol has been removed and GLFW now only supports
+Support for the deprecated wl_shell protocol has been removed and GLFW now only
-the XDG-Shell protocol.  If your Wayland compositor does not support XDG-Shell
+supports the XDG-Shell protocol.  If your Wayland compositor does not support
-then GLFW will fail to initialize.
+XDG-Shell then GLFW will fail to initialize.
 
 
-### New symbols in version 3.4 {#symbols_34}
+## New symbols {#new_symbols}
 
-#### New functions in version 3.4 {#functions_34}
+### 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