Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
G
glfw
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Model registry
Operate
Environments
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
GitLab community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
pirvi-public
glfw
Commits
7b6aead9
Commit
7b6aead9
authored
1 year ago
by
Camilla Löwy
Browse files
Options
Downloads
Patches
Plain Diff
Documentation updates for 3.4 release
parent
e14e72a2
Branches
Branches containing commit
No related tags found
No related merge requests found
Changes
3
Show whitespace changes
Inline
Side-by-side
Showing
3 changed files
README.md
+4
-4
4 additions, 4 deletions
README.md
docs/main.md
+1
-1
1 addition, 1 deletion
docs/main.md
docs/news.md
+155
-87
155 additions, 87 deletions
docs/news.md
with
160 additions
and
92 deletions
README.md
+
4
−
4
View file @
7b6aead9
...
...
@@ -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
...
...
This diff is collapsed.
Click to expand it.
docs/main.md
+
1
−
1
View file @
7b6aead9
...
...
@@ -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.
...
...
This diff is collapsed.
Click to expand it.
docs/news.md
+
155
−
87
View file @
7b6aead9
# 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,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_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/
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
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 usual
ly 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 most
ly 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}
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.
### Tests and examples are disabled when built as a subproject {#standalone_caveat}
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}
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.
###
# F
ramebuffer
transparency requires DWM transparency {#caveat_fbtransparency_34
}
###
Wayland f
ramebuffer
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.
###
# E
mpty events
on X11
no longer round-trip to server {#emptyevent
s_34
}
###
X11 e
mpty 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
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 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.
You can set all of them to false and the ones that don't apply for the target OS
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
the XDG-Shell protocol. If your Wayland compositor does not support
XDG-Shell
then GLFW will fail to initialize.
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
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
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment