glfw/docs/news.dox

/*!

@page news Release notes

@tableofcontents


@section news_34 Release notes for version 3.4

@subsection features_34 New features in version 3.4

@subsubsection context_user_34 Multiple window contexts

GLFW now provides the ability to create multiple OpenGL and OpenGL ES
contexts for a given window. Called user contexts, a [GLFWusercontext](@ref context_user)
can be created using @ref glfwCreateUserContext,
destroyed using @ref glfwDestroyUserContext, and managed with
@ref glfwMakeUserContextCurrent and @ref glfwGetCurrentUserContext.
For more information see the [user context](@ref context_user) documentation.

@subsubsection standard_cursors_34 More standard cursors

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
for omni-directional resizing and @ref GLFW_NOT_ALLOWED_CURSOR for showing an
action is not allowed.

Unlike the original set, these shapes may not be available everywhere and
creation will then fail with the new @ref GLFW_CURSOR_UNAVAILABLE error.

The cursors for horizontal and vertical resizing are now referred to as @ref
GLFW_RESIZE_EW_CURSOR and @ref GLFW_RESIZE_NS_CURSOR, and the pointing hand
cursor is now referred to as @ref GLFW_POINTING_HAND_CURSOR.  The older names
are still available.

For more information see @ref cursor_standard.


@subsubsection mouse_passthrough_34 Mouse event 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
to whatever window is behind it.  This can also be changed after window
creation with the matching [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib).


@subsubsection features_34_angle_backend Support for ANGLE rendering backend selection

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](https://chromium.googlesource.com/angle/angle/) to create OpenGL ES
contexts.


@subsubsection features_34_init_allocator Support for custom memory 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`,
`realloc` and `free`.

For more information see @ref init_allocator.


@subsubsection features_34_win32_keymenu Support for keyboard access to Windows window menu

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.


@subsection caveats_34 Caveats for version 3.4

@subsubsection joysticks_34 Joystick support is initialized on demand

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.

To work around this, call any joystick function before waiting for events, for
example by setting a [joystick callback](@ref joystick_event).


@subsubsection standalone_34 Tests and examples are disabled when built as a sub-project

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.

@code{.cmake}
set(GLFW_BUILD_EXAMPLES ON CACHE BOOL "" FORCE)
set(GLFW_BUILD_TESTS ON CACHE BOOL "" FORCE)
add_subdirectory(path/to/glfw)
@endcode


@subsubsection initmenu_34 macOS main menu now created at initialization

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.


@subsubsection corevideo_34 CoreVideo dependency has been removed

GLFW no longer depends on the CoreVideo framework on macOS and it no longer
needs to be specified during compilation or linking.


@subsubsection caveat_fbtransparency_34 Framebuffer transparency requires DWM transparency

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).


@subsection deprecations_34 Deprecations in version 3.4

@subsection removals_34 Removals in 3.4

@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
the XDG-Shell protocol.  If your Wayland compositor does not support XDG-Shell
then GLFW will fail to initialize.


@subsection symbols_34 New symbols in version 3.4

@subsubsection functions_34 New functions in version 3.4

 - @ref glfwInitAllocator


@subsubsection types_34 New types in version 3.4

 - @ref GLFWallocator
 - @ref GLFWallocatefun
 - @ref GLFWreallocatefun
 - @ref GLFWdeallocatefun


@subsubsection constants_34 New constants in version 3.4

 - @ref GLFW_POINTING_HAND_CURSOR
 - @ref GLFW_RESIZE_EW_CURSOR
 - @ref GLFW_RESIZE_NS_CURSOR
 - @ref GLFW_RESIZE_NWSE_CURSOR
 - @ref GLFW_RESIZE_NESW_CURSOR
 - @ref GLFW_RESIZE_ALL_CURSOR
 - @ref GLFW_MOUSE_PASSTHROUGH
 - @ref GLFW_NOT_ALLOWED_CURSOR
 - @ref GLFW_CURSOR_UNAVAILABLE
 - @ref GLFW_WIN32_KEYBOARD_MENU
 - @ref GLFW_CONTEXT_DEBUG
 - @ref GLFW_FEATURE_UNAVAILABLE
 - @ref GLFW_FEATURE_UNIMPLEMENTED
 - @ref GLFW_ANGLE_PLATFORM_TYPE
 - @ref GLFW_ANGLE_PLATFORM_TYPE_NONE
 - @ref GLFW_ANGLE_PLATFORM_TYPE_OPENGL
 - @ref GLFW_ANGLE_PLATFORM_TYPE_OPENGLES
 - @ref GLFW_ANGLE_PLATFORM_TYPE_D3D9
 - @ref GLFW_ANGLE_PLATFORM_TYPE_D3D11
 - @ref GLFW_ANGLE_PLATFORM_TYPE_VULKAN
 - @ref GLFW_ANGLE_PLATFORM_TYPE_METAL
 - @ref GLFW_X11_XCB_VULKAN_SURFACE


@section news_archive Release notes for earlier versions

- [Release notes for 3.3](https://www.glfw.org/docs/3.3/news.html)
- [Release notes for 3.2](https://www.glfw.org/docs/3.2/news.html)
- [Release notes for 3.1](https://www.glfw.org/docs/3.1/news.html)
- [Release notes for 3.0](https://www.glfw.org/docs/3.0/news.html)

*/