mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-22 04:54:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Convert Doxygen headings to Markdown

Browse Source
This commit is contained in:
Camilla Löwy 2024-02-13 20:45:29 +01:00
parent 3e73a5c76c
commit 611099f745
14 changed files with 250 additions and 252 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/build.md
View File

@ -1,4 +1,4 @@
@page build_guide Building applications # Building applications {#build_guide}
@tableofcontents @tableofcontents
@ -14,7 +14,7 @@ and linking process should be explained in your C programming material and in
the documentation for your development environment. the documentation for your development environment.
@section build_include Including the GLFW header file ## Including the GLFW header file {#build_include}
You should include the GLFW header in the source files where you use OpenGL or You should include the GLFW header in the source files where you use OpenGL or
GLFW. GLFW.
@ -66,7 +66,7 @@ headers in any order.
@endcode @endcode
@subsection build_macros GLFW header option macros ### GLFW header option macros {#build_macros}
These macros may be defined before the inclusion of the GLFW header and affect These macros may be defined before the inclusion of the GLFW header and affect
its behavior. its behavior.
@ -140,7 +140,7 @@ If your build includes GLFW and you define any these in your build files, make
sure they are not applied to the GLFW sources. sure they are not applied to the GLFW sources.
@section build_link Link with the right libraries ## Link with the right libraries {#build_link}
GLFW is essentially a wrapper of various platform-specific APIs and therefore GLFW is essentially a wrapper of various platform-specific APIs and therefore
needs to link against many different system libraries. If you are using GLFW as needs to link against many different system libraries. If you are using GLFW as
@ -158,7 +158,7 @@ A good general introduction to linking is
David Drysdale. David Drysdale.
@subsection build_link_win32 With MinGW or Visual C++ on Windows ### With MinGW or Visual C++ on Windows {#build_link_win32}
The static version of the GLFW library is named `glfw3`. When using this The static version of the GLFW library is named `glfw3`. When using this
version, it is also necessary to link with some libraries that GLFW uses. version, it is also necessary to link with some libraries that GLFW uses.
@ -174,7 +174,7 @@ GLFW_DLL macro _before_ any inclusion of the GLFW header. This can be done
either with a compiler switch or by defining it in your source code. either with a compiler switch or by defining it in your source code.
@subsection build_link_cmake_source With CMake and GLFW source ### With CMake and GLFW source {#build_link_cmake_source}
This section is about using CMake to compile and link GLFW along with your This section is about using CMake to compile and link GLFW along with your
application. If you want to use an installed binary instead, see @ref application. If you want to use an installed binary instead, see @ref
@ -220,7 +220,7 @@ For a minimal example of a program and GLFW sources built with CMake, see the
[GLFW CMake Starter](https://github.com/juliettef/GLFW-CMake-starter) on GitHub. [GLFW CMake Starter](https://github.com/juliettef/GLFW-CMake-starter) on GitHub.
@subsection build_link_cmake_package With CMake and installed GLFW binaries ### With CMake and installed GLFW binaries {#build_link_cmake_package}
This section is about using CMake to link GLFW after it has been built and This section is about using CMake to link GLFW after it has been built and
installed. If you want to build it along with your application instead, see installed. If you want to build it along with your application instead, see
@ -259,7 +259,7 @@ target_link_libraries(myapp OpenGL::GL)
@endcode @endcode
@subsection build_link_pkgconfig With makefiles and pkg-config on Unix ### With makefiles and pkg-config on Unix {#build_link_pkgconfig}
GLFW supports [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/), GLFW supports [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/),
and the `glfw3.pc` pkg-config file is generated when the GLFW library is built and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
@ -300,7 +300,7 @@ cc $(pkg-config --cflags glfw3 gl) -o myprog myprog.c $(pkg-config --libs glfw3
@endcode @endcode
@subsection build_link_xcode With Xcode on macOS ### With Xcode on macOS {#build_link_xcode}
If you are using the dynamic library version of GLFW, add it to the project If you are using the dynamic library version of GLFW, add it to the project
dependencies. dependencies.
@ -310,7 +310,7 @@ OpenGL and IOKit frameworks to the project as dependencies. They can all be
found in `/System/Library/Frameworks`. found in `/System/Library/Frameworks`.
@subsection build_link_osx With command-line on macOS ### With command-line on macOS {#build_link_osx}
It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when It is recommended that you use [pkg-config](@ref build_link_pkgconfig) when
building from the command line on macOS. That way you will get any new building from the command line on macOS. That way you will get any new

16
docs/compat.md
View File

@ -1,4 +1,4 @@
@page compat_guide Standards conformance # Standards conformance {#compat_guide}
@tableofcontents @tableofcontents
@ -13,7 +13,7 @@ part of this information may change in future versions of GLFW and that will not
be considered a breaking API change. be considered a breaking API change.
@section compat_x11 X11 extensions, protocols and IPC standards ## X11 extensions, protocols and IPC standards {#compat_x11}
As GLFW uses Xlib directly, without any intervening toolkit As GLFW uses Xlib directly, without any intervening toolkit
library, it has sole responsibility for interacting well with the many and library, it has sole responsibility for interacting well with the many and
@ -91,7 +91,7 @@ conventions, the `GLFW_RESIZE_NWSE_CURSOR`, `GLFW_RESIZE_NESW_CURSOR` and
legacy images. legacy images.
@section compat_wayland Wayland protocols and IPC standards ## Wayland protocols and IPC standards {#compat_wayland}
As GLFW uses libwayland directly, without any intervening toolkit library, it As GLFW uses libwayland directly, without any intervening toolkit library, it
has sole responsibility for interacting well with every compositor in use on has sole responsibility for interacting well with every compositor in use on
@ -144,7 +144,7 @@ to implement window focus and attention requests. If the running compositor
does not support this protocol, window focus and attention requests do nothing. does not support this protocol, window focus and attention requests do nothing.
@section compat_glx GLX extensions ## GLX extensions {#compat_glx}
The GLX API is the default API used to create OpenGL contexts on Unix-like The GLX API is the default API used to create OpenGL contexts on Unix-like
systems using the X Window System. systems using the X Window System.
@ -184,7 +184,7 @@ extensions to provide support for sRGB framebuffers. Where both of these
extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect. extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
@section compat_wgl WGL extensions ## WGL extensions {#compat_wgl}
The WGL API is used to create OpenGL contexts on Microsoft Windows and other The WGL API is used to create OpenGL contexts on Microsoft Windows and other
implementations of the Win32 API, such as Wine. implementations of the Win32 API, such as Wine.
@ -225,7 +225,7 @@ extensions to provide support for sRGB framebuffers. When both of these
extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect. extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
@section compat_osx OpenGL on macOS ## OpenGL on macOS {#compat_osx}
Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
only forward-compatible, core profile contexts are supported. Support for only forward-compatible, core profile contexts are supported. Support for
@ -247,7 +247,7 @@ a non-default value will cause @ref glfwCreateWindow to fail and the
`GLFW_CONTEXT_DEBUG` hint is ignored. `GLFW_CONTEXT_DEBUG` hint is ignored.
@section compat_vulkan Vulkan loader and API ## Vulkan loader and API {#compat_vulkan}
By default, GLFW uses the standard system-wide Vulkan loader to access the By default, GLFW uses the standard system-wide Vulkan loader to access the
Vulkan API on all platforms except macOS. This is installed by both graphics Vulkan API on all platforms except macOS. This is installed by both graphics
@ -257,7 +257,7 @@ all other Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE
error. error.
@section compat_wsi Vulkan WSI extensions ## Vulkan WSI extensions {#compat_wsi}
The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on
all supported platforms. all supported platforms.

30
docs/compile.md
View File

@ -1,4 +1,4 @@
@page compile_guide Compiling GLFW # Compiling GLFW {#compile_guide}
@tableofcontents @tableofcontents
@ -8,7 +8,7 @@ build applications that use GLFW, see @ref build_guide.
GLFW uses some C99 features and does not support Visual Studio 2012 and earlier. GLFW uses some C99 features and does not support Visual Studio 2012 and earlier.
@section compile_cmake Using CMake ## Using CMake {#compile_cmake}
GLFW behaves like most other libraries that use CMake so this guide mostly GLFW behaves like most other libraries that use CMake so this guide mostly
describes the standard configure, generate and compile sequence. If you are already describes the standard configure, generate and compile sequence. If you are already
@ -33,14 +33,14 @@ that includes everything in this guide not specific to GLFW. It may be a useful
companion to this one. companion to this one.
@subsection compile_deps Installing dependencies ### Installing dependencies {#compile_deps}
The C/C++ development environments in Visual Studio, Xcode and MinGW come with The C/C++ development environments in Visual Studio, Xcode and MinGW come with
all necessary dependencies for compiling GLFW, but on Unix-like systems like all necessary dependencies for compiling GLFW, but on Unix-like systems like
Linux and FreeBSD you will need a few extra packages. Linux and FreeBSD you will need a few extra packages.
@subsubsection compile_deps_wayland Dependencies for Wayland and X11 #### Dependencies for Wayland and X11 {#compile_deps_wayland}
By default, both the Wayland and X11 backends are enabled on Linux and other Unix-like By default, both the Wayland and X11 backends are enabled on Linux and other Unix-like
systems (except macOS). To disable one or both of these, set the @ref GLFW_BUILD_WAYLAND systems (except macOS). To disable one or both of these, set the @ref GLFW_BUILD_WAYLAND
@ -85,7 +85,7 @@ pull in all other dependencies.
Once you have the required dependencies, move on to @ref compile_generate. Once you have the required dependencies, move on to @ref compile_generate.
@subsection compile_generate Generating build files with CMake ### Generating build files with CMake {#compile_generate}
Once you have all necessary dependencies it is time to generate the project Once you have all necessary dependencies it is time to generate the project
files or makefiles for your development environment. CMake needs two paths for files or makefiles for your development environment. CMake needs two paths for
@ -107,7 +107,7 @@ A common pattern when building a single configuration is to have a build
directory named `build` in the root of the source tree. directory named `build` in the root of the source tree.
@subsubsection compile_generate_gui Generating with the CMake GUI #### Generating with the CMake GUI {#compile_generate_gui}
Start the CMake GUI and set the paths to the source and build directories Start the CMake GUI and set the paths to the source and build directories
described above. Then press _Configure_ and _Generate_. described above. Then press _Configure_ and _Generate_.
@ -125,7 +125,7 @@ Once you have generated the project files or makefiles for your chosen
development environment, move on to @ref compile_compile. development environment, move on to @ref compile_compile.
@subsubsection compile_generate_cli Generating with command-line CMake #### Generating with command-line CMake {#compile_generate_cli}
To make a build directory, pass the source and build directories to the `cmake` To make a build directory, pass the source and build directories to the `cmake`
command. These can be relative or absolute paths. The build directory is command. These can be relative or absolute paths. The build directory is
@ -163,7 +163,7 @@ Once you have generated the project files or makefiles for your chosen
development environment, move on to @ref compile_compile. development environment, move on to @ref compile_compile.
@subsection compile_compile Compiling the library ### Compiling the library {#compile_compile}
You should now have all required dependencies and the project files or makefiles You should now have all required dependencies and the project files or makefiles
necessary to compile GLFW. Go ahead and compile the actual GLFW library with necessary to compile GLFW. Go ahead and compile the actual GLFW library with
@ -199,7 +199,7 @@ Once the GLFW library is compiled you are ready to build your application,
linking it to the GLFW library. See @ref build_guide for more information. linking it to the GLFW library. See @ref build_guide for more information.
@section compile_options CMake options ## CMake options {#compile_options}
The CMake files for GLFW provide a number of options, although not all are The CMake files for GLFW provide a number of options, although not all are
available on all supported platforms. Some of these are de facto standards available on all supported platforms. Some of these are de facto standards
@ -219,7 +219,7 @@ cmake -S path/to/glfw -B path/to/build -D BUILD_SHARED_LIBS=ON
@endcode @endcode
@subsection compile_options_shared Shared CMake options ### Shared CMake options {#compile_options_shared}
@anchor BUILD_SHARED_LIBS @anchor BUILD_SHARED_LIBS
__BUILD_SHARED_LIBS__ determines whether GLFW is built as a static library or as __BUILD_SHARED_LIBS__ determines whether GLFW is built as a static library or as
@ -251,7 +251,7 @@ with the library. This is enabled by default if
[Doxygen](https://www.doxygen.nl/) is found by CMake during configuration. [Doxygen](https://www.doxygen.nl/) is found by CMake during configuration.
@subsection compile_options_win32 Win32 specific CMake options ### Win32 specific CMake options {#compile_options_win32}
@anchor GLFW_BUILD_WIN32 @anchor GLFW_BUILD_WIN32
__GLFW_BUILD_WIN32__ determines whether to include support for Win32 when compiling the __GLFW_BUILD_WIN32__ determines whether to include support for Win32 when compiling the
@ -276,7 +276,7 @@ will not work if GLFW is built as a DLL. This is disabled by default, letting
the operating system and driver decide. the operating system and driver decide.
@subsection compile_options_macos macOS specific CMake options ### macOS specific CMake options {#compile_options_macos}
@anchor GLFW_BUILD_COCOA @anchor GLFW_BUILD_COCOA
__GLFW_BUILD_COCOA__ determines whether to include support for Cocoa when compiling the __GLFW_BUILD_COCOA__ determines whether to include support for Cocoa when compiling the
@ -284,7 +284,7 @@ library. This option is only available when compiling for macOS. This is enabl
default. default.
@subsection compile_options_unix Unix-like system specific CMake options ### Unix-like system specific CMake options {#compile_options_unix}
@anchor GLFW_BUILD_WAYLAND @anchor GLFW_BUILD_WAYLAND
__GLFW_BUILD_WAYLAND__ determines whether to include support for Wayland when compiling __GLFW_BUILD_WAYLAND__ determines whether to include support for Wayland when compiling
@ -297,7 +297,7 @@ library. This option is only available when compiling for Linux and other Unix-
systems other than macOS. This is enabled by default. systems other than macOS. This is enabled by default.
@section compile_mingw_cross Cross-compilation with CMake and MinGW ## Cross-compilation with CMake and MinGW {#compile_mingw_cross}
Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages. For Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages. For
example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
@ -330,7 +330,7 @@ For more details see the
[CMake toolchain guide](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html). [CMake toolchain guide](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html).
@section compile_manual Compiling GLFW manually ## Compiling GLFW manually {#compile_manual}
If you wish to compile GLFW without its CMake build environment then you will have to do If you wish to compile GLFW without its CMake build environment then you will have to do
at least some platform-detection yourself. There are preprocessor macros for at least some platform-detection yourself. There are preprocessor macros for

28
docs/context.md
View File

@ -1,4 +1,4 @@
@page context_guide Context guide # Context guide {#context_guide}
@tableofcontents @tableofcontents
@ -13,7 +13,7 @@ context. There are also guides for the other areas of the GLFW API.
- @ref input_guide - @ref input_guide
@section context_object Context objects ## Context objects {#context_object}
A window object encapsulates both a top-level window and an OpenGL or OpenGL ES A window object encapsulates both a top-level window and an OpenGL or OpenGL ES
context. It is created with @ref glfwCreateWindow and destroyed with @ref context. It is created with @ref glfwCreateWindow and destroyed with @ref
@ -32,14 +32,14 @@ context creation by setting the [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint)
hint to `GLFW_NO_API`. For more information, see the @ref vulkan_guide. hint to `GLFW_NO_API`. For more information, see the @ref vulkan_guide.
@subsection context_hints Context creation hints ### Context creation hints {#context_hints}
There are a number of hints, specified using @ref glfwWindowHint, related to There are a number of hints, specified using @ref glfwWindowHint, related to
what kind of context is created. See what kind of context is created. See
[context related hints](@ref window_hints_ctx) in the window guide. [context related hints](@ref window_hints_ctx) in the window guide.
@subsection context_sharing Context object sharing ### Context object sharing {#context_sharing}
When creating a window and its OpenGL or OpenGL ES context with @ref When creating a window and its OpenGL or OpenGL ES context with @ref
glfwCreateWindow, you can specify another window whose context the new one glfwCreateWindow, you can specify another window whose context the new one
@ -62,7 +62,7 @@ Contexts_.
GLFW comes with a bare-bones object sharing example program called `sharing`. GLFW comes with a bare-bones object sharing example program called `sharing`.
@subsection context_offscreen Offscreen contexts ### Offscreen contexts {#context_offscreen}
GLFW doesn't support creating contexts without an associated window. However, GLFW doesn't support creating contexts without an associated window. However,
contexts with hidden windows can be created with the contexts with hidden windows can be created with the
@ -83,7 +83,7 @@ You should still [process events](@ref events) as long as you have at least one
window, even if none of them are visible. window, even if none of them are visible.
@subsection context_less Windows without contexts ### Windows without contexts {#context_less}
You can disable context creation by setting the You can disable context creation by setting the
[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`. [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`.
@ -92,7 +92,7 @@ Windows without contexts should not be passed to @ref glfwMakeContextCurrent or
@ref glfwSwapBuffers. Doing this generates a @ref GLFW_NO_WINDOW_CONTEXT error. @ref glfwSwapBuffers. Doing this generates a @ref GLFW_NO_WINDOW_CONTEXT error.
@section context_current Current context ## Current context {#context_current}
Before you can make OpenGL or OpenGL ES calls, you need to have a current Before you can make OpenGL or OpenGL ES calls, you need to have a current
context of the correct type. A context can only be current for a single thread context of the correct type. A context can only be current for a single thread
@ -122,12 +122,12 @@ error.
- @ref glfwGetProcAddress - @ref glfwGetProcAddress
@section context_swap Buffer swapping ## Buffer swapping {#context_swap}
See @ref buffer_swap in the window guide. See @ref buffer_swap in the window guide.
@section context_glext OpenGL and OpenGL ES extensions ## OpenGL and OpenGL ES extensions {#context_glext}
One of the benefits of OpenGL and OpenGL ES is their extensibility. One of the benefits of OpenGL and OpenGL ES is their extensibility.
Hardware vendors may include extensions in their implementations that extend the Hardware vendors may include extensions in their implementations that extend the
@ -150,7 +150,7 @@ their specifications, can be found at the
[OpenGL ES Registry](https://www.khronos.org/registry/gles/). [OpenGL ES Registry](https://www.khronos.org/registry/gles/).
@subsection context_glext_auto Loading extension with a loader library ### Loading extension with a loader library {#context_glext_auto}
An extension loader library is the easiest and best way to access both OpenGL and An extension loader library is the easiest and best way to access both OpenGL and
OpenGL ES extensions and modern versions of the core OpenGL or OpenGL ES APIs. OpenGL ES extensions and modern versions of the core OpenGL or OpenGL ES APIs.
@ -231,7 +231,7 @@ if (GLAD_GL_ARB_gl_spirv)
@endcode @endcode
@subsection context_glext_manual Loading extensions manually ### Loading extensions manually {#context_glext_manual}
__Do not use this technique__ unless it is absolutely necessary. An __Do not use this technique__ unless it is absolutely necessary. An
[extension loader library](@ref context_glext_auto) will save you a ton of [extension loader library](@ref context_glext_auto) will save you a ton of
@ -246,7 +246,7 @@ This section will demonstrate manual loading of OpenGL extensions. The loading
of OpenGL ES extensions is identical except for the name of the extension header. of OpenGL ES extensions is identical except for the name of the extension header.
@subsubsection context_glext_header The glext.h header #### The glext.h header {#context_glext_header}
The `glext.h` extension header is a continually updated file that defines the The `glext.h` extension header is a continually updated file that defines the
interfaces for all OpenGL extensions. The latest version of this can always be interfaces for all OpenGL extensions. The latest version of this can always be
@ -271,7 +271,7 @@ the GLFW header.
@endcode @endcode
@subsubsection context_glext_string Checking for extensions #### Checking for extensions {#context_glext_string}
A given machine may not actually support the extension (it may have older A given machine may not actually support the extension (it may have older
drivers or a graphics card that lacks the necessary hardware features), so it drivers or a graphics card that lacks the necessary hardware features), so it
@ -290,7 +290,7 @@ extension is supported, @ref glfwExtensionSupported returns `GLFW_TRUE`,
otherwise it returns `GLFW_FALSE`. otherwise it returns `GLFW_FALSE`.
@subsubsection context_glext_proc Fetching function pointers #### Fetching function pointers {#context_glext_proc}
Many extensions, though not all, require the use of new OpenGL functions. Many extensions, though not all, require the use of new OpenGL functions.
These functions often do not have entry points in the client API libraries of These functions often do not have entry points in the client API libraries of

60
docs/input.md
View File

@ -1,4 +1,4 @@
@page input_guide Input guide # Input guide {#input_guide}
@tableofcontents @tableofcontents
@ -27,7 +27,7 @@ out all arguments provided for every event, along with time and sequence
information. information.
@section events Event processing ## Event processing {#events}
GLFW needs to poll the window system for events both to provide input to the GLFW needs to poll the window system for events both to provide input to the
application and to prove to the window system that the application hasn't locked application and to prove to the window system that the application hasn't locked
@ -89,7 +89,7 @@ a [window size callback](@ref window_size) GLFW will call it in turn with the
new size before everything returns back out of the @ref glfwSetWindowSize call. new size before everything returns back out of the @ref glfwSetWindowSize call.
@section input_keyboard Keyboard input ## Keyboard input {#input_keyboard}
GLFW divides keyboard input into two categories; key events and character GLFW divides keyboard input into two categories; key events and character
events. Key events relate to actual physical keyboard keys, whereas character events. Key events relate to actual physical keyboard keys, whereas character
@ -101,7 +101,7 @@ may not be the case on your machine, but your users are likely not all using the
same keyboard layout, input method or even operating system as you. same keyboard layout, input method or even operating system as you.
@subsection input_key Key input ### Key input {#input_key}
If you wish to be notified when a physical key is pressed or released or when it If you wish to be notified when a physical key is pressed or released or when it
repeats, set a key callback. repeats, set a key callback.
@ -201,7 +201,7 @@ The `GLFW_KEY_LAST` constant holds the highest value of any
[key token](@ref keys). [key token](@ref keys).
@subsection input_char Text input ### Text input {#input_char}
GLFW supports text input in the form of a stream of GLFW supports text input in the form of a stream of
[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the [Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
@ -230,7 +230,7 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
@endcode @endcode
@subsection input_key_name Key names ### Key names {#input_key_name}
If you wish to refer to keys by name, you can query the keyboard layout If you wish to refer to keys by name, you can query the keyboard layout
dependent name of printable keys with @ref glfwGetKeyName. dependent name of printable keys with @ref glfwGetKeyName.
@ -246,14 +246,14 @@ ignored. This matches the behavior of the key callback, meaning the callback
arguments can always be passed unmodified to this function. arguments can always be passed unmodified to this function.
@section input_mouse Mouse input ## Mouse input {#input_mouse}
Mouse input comes in many forms, including mouse motion, button presses and Mouse input comes in many forms, including mouse motion, button presses and
scrolling offsets. The cursor appearance can also be changed, either to scrolling offsets. The cursor appearance can also be changed, either to
a custom image or a standard cursor shape from the system theme. a custom image or a standard cursor shape from the system theme.
@subsection cursor_pos Cursor position ### Cursor position {#cursor_pos}
If you wish to be notified when the cursor moves over the window, set a cursor If you wish to be notified when the cursor moves over the window, set a cursor
position callback. position callback.
@ -281,7 +281,7 @@ glfwGetCursorPos(window, &xpos, &ypos);
@endcode @endcode
@subsection cursor_mode Cursor mode ### Cursor mode {#cursor_mode}
@anchor GLFW_CURSOR @anchor GLFW_CURSOR
The `GLFW_CURSOR` input mode provides several cursor modes for special forms of The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
@ -336,7 +336,7 @@ If the cursor was disabled, this will move it back to its last visible position.
@anchor GLFW_RAW_MOUSE_MOTION @anchor GLFW_RAW_MOUSE_MOTION
@subsection raw_mouse_motion Raw mouse motion ### Raw mouse motion {#raw_mouse_motion}
When the cursor is disabled, raw (unscaled and unaccelerated) mouse motion can When the cursor is disabled, raw (unscaled and unaccelerated) mouse motion can
be enabled if available. be enabled if available.
@ -360,7 +360,7 @@ If supported, raw mouse motion can be enabled or disabled per-window and at any
time but it will only be provided when the cursor is disabled. time but it will only be provided when the cursor is disabled.
@subsection cursor_object Cursor objects ### Cursor objects {#cursor_object}
GLFW supports creating both custom and system theme cursor images, encapsulated GLFW supports creating both custom and system theme cursor images, encapsulated
as @ref GLFWcursor objects. They are created with @ref glfwCreateCursor or @ref as @ref GLFWcursor objects. They are created with @ref glfwCreateCursor or @ref
@ -368,7 +368,7 @@ glfwCreateStandardCursor and destroyed with @ref glfwDestroyCursor, or @ref
glfwTerminate, if any remain. glfwTerminate, if any remain.
@subsubsection cursor_custom Custom cursor creation #### Custom cursor creation {#cursor_custom}
A custom cursor is created with @ref glfwCreateCursor, which returns a handle to A custom cursor is created with @ref glfwCreateCursor, which returns a handle to
the created cursor object. For example, this creates a 16x16 white square the created cursor object. For example, this creates a 16x16 white square
@ -394,7 +394,7 @@ per channel with the red channel first. The pixels are arranged canonically as
sequential rows, starting from the top-left corner. sequential rows, starting from the top-left corner.
@subsubsection cursor_standard Standard cursor creation #### Standard cursor creation {#cursor_standard}
A cursor with a [standard shape](@ref shapes) from the current system cursor A cursor with a [standard shape](@ref shapes) from the current system cursor
theme can be created with @ref glfwCreateStandardCursor. theme can be created with @ref glfwCreateStandardCursor.
@ -410,7 +410,7 @@ A few of these shapes are not available everywhere. If a shape is unavailable,
`NULL` is returned. See @ref glfwCreateStandardCursor for details. `NULL` is returned. See @ref glfwCreateStandardCursor for details.
@subsubsection cursor_destruction Cursor destruction #### Cursor destruction {#cursor_destruction}
When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor. When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
@ -423,7 +423,7 @@ that window will revert to the default cursor. This does not affect the cursor
mode. All remaining cursors are destroyed when @ref glfwTerminate is called. mode. All remaining cursors are destroyed when @ref glfwTerminate is called.
@subsubsection cursor_set Cursor setting #### Cursor setting {#cursor_set}
A cursor can be set as current for a window with @ref glfwSetCursor. A cursor can be set as current for a window with @ref glfwSetCursor.
@ -447,7 +447,7 @@ When a cursor is destroyed, any window that has it set will revert to the
default cursor. This does not affect the cursor mode. default cursor. This does not affect the cursor mode.
@subsection cursor_enter Cursor enter/leave events ### Cursor enter/leave events {#cursor_enter}
If you wish to be notified when the cursor enters or leaves the content area of If you wish to be notified when the cursor enters or leaves the content area of
a window, set a cursor enter/leave callback. a window, set a cursor enter/leave callback.
@ -483,7 +483,7 @@ if (glfwGetWindowAttrib(window, GLFW_HOVERED))
@endcode @endcode
@subsection input_mouse_button Mouse button input ### Mouse button input {#input_mouse_button}
If you wish to be notified when a mouse button is pressed or released, set If you wish to be notified when a mouse button is pressed or released, set
a mouse button callback. a mouse button callback.
@ -543,7 +543,7 @@ The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
[supported mouse button](@ref buttons). [supported mouse button](@ref buttons).
@subsection scrolling Scroll input ### Scroll input {#scrolling}
If you wish to be notified when the user scrolls, whether with a mouse wheel or If you wish to be notified when the user scrolls, whether with a mouse wheel or
touchpad gesture, set a scroll callback. touchpad gesture, set a scroll callback.
@ -563,7 +563,7 @@ void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
A normal mouse wheel, being vertical, provides offsets along the Y-axis. A normal mouse wheel, being vertical, provides offsets along the Y-axis.
@section joystick Joystick input ## Joystick input {#joystick}
The joystick functions expose connected joysticks and controllers, with both The joystick functions expose connected joysticks and controllers, with both
referred to as joysticks. It supports up to sixteen joysticks, ranging from referred to as joysticks. It supports up to sixteen joysticks, ranging from
@ -593,7 +593,7 @@ To see all the properties of all connected joysticks in real-time, run the
`joysticks` test program. `joysticks` test program.
@subsection joystick_axis Joystick axis states ### Joystick axis states {#joystick_axis}
The positions of all axes of a joystick are returned by @ref The positions of all axes of a joystick are returned by @ref
glfwGetJoystickAxes. See the reference documentation for the lifetime of the glfwGetJoystickAxes. See the reference documentation for the lifetime of the
@ -607,7 +607,7 @@ const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_5, &count);
Each element in the returned array is a value between -1.0 and 1.0. Each element in the returned array is a value between -1.0 and 1.0.
@subsection joystick_button Joystick button states ### Joystick button states {#joystick_button}
The states of all buttons of a joystick are returned by @ref The states of all buttons of a joystick are returned by @ref
glfwGetJoystickButtons. See the reference documentation for the lifetime of the glfwGetJoystickButtons. See the reference documentation for the lifetime of the
@ -625,7 +625,7 @@ glfwGetJoystickHats, the button array by default also includes all hats. See
the reference documentation for @ref glfwGetJoystickButtons for details. the reference documentation for @ref glfwGetJoystickButtons for details.
@subsection joystick_hat Joystick hat states ### Joystick hat states {#joystick_hat}
The states of all hats are returned by @ref glfwGetJoystickHats. See the The states of all hats are returned by @ref glfwGetJoystickHats. See the
reference documentation for the lifetime of the returned array. reference documentation for the lifetime of the returned array.
@ -665,7 +665,7 @@ glfwGetJoystickHats, all hats are by default also included in the button array.
See the reference documentation for @ref glfwGetJoystickButtons for details. See the reference documentation for @ref glfwGetJoystickButtons for details.
@subsection joystick_name Joystick name ### Joystick name {#joystick_name}
The human-readable, UTF-8 encoded name of a joystick is returned by @ref The human-readable, UTF-8 encoded name of a joystick is returned by @ref
glfwGetJoystickName. See the reference documentation for the lifetime of the glfwGetJoystickName. See the reference documentation for the lifetime of the
@ -680,7 +680,7 @@ and make may have the same name. Only the [joystick ID](@ref joysticks) is
guaranteed to be unique, and only until that joystick is disconnected. guaranteed to be unique, and only until that joystick is disconnected.
@subsection joystick_userptr Joystick user pointer ### Joystick user pointer {#joystick_userptr}
Each joystick has a user pointer that can be set with @ref Each joystick has a user pointer that can be set with @ref
glfwSetJoystickUserPointer and queried with @ref glfwGetJoystickUserPointer. glfwSetJoystickUserPointer and queried with @ref glfwGetJoystickUserPointer.
@ -691,7 +691,7 @@ terminated.
The initial value of the pointer is `NULL`. The initial value of the pointer is `NULL`.
@subsection joystick_event Joystick configuration changes ### Joystick configuration changes {#joystick_event}
If you wish to be notified when a joystick is connected or disconnected, set If you wish to be notified when a joystick is connected or disconnected, set
a joystick callback. a joystick callback.
@ -728,7 +728,7 @@ useful values for a disconnected joystick and only before the monitor callback
returns. returns.
@subsection gamepad Gamepad input ### Gamepad input {#gamepad}
The joystick functions provide unlabeled axes, buttons and hats, with no The joystick functions provide unlabeled axes, buttons and hats, with no
indication of where they are located on the device. Their order may also vary indication of where they are located on the device. Their order may also vary
@ -809,7 +809,7 @@ The `GLFW_GAMEPAD_BUTTON_LAST` and `GLFW_GAMEPAD_AXIS_LAST` constants equal
the largest available index for each array. the largest available index for each array.
@subsection gamepad_mapping Gamepad mappings ### Gamepad mappings {#gamepad_mapping}
GLFW contains a copy of the mappings available in GLFW contains a copy of the mappings available in
[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) at the [SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) at the
@ -892,7 +892,7 @@ were recently added to SDL. The input modifiers `+`, `-` and `~` are supported
and described above. and described above.
@section time Time input ## Time input {#time}
GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime. GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
@ -929,7 +929,7 @@ uint64_t frequency = glfwGetTimerFrequency();
@endcode @endcode
@section clipboard Clipboard input and output ## Clipboard input and output {#clipboard}
If the system clipboard contains a UTF-8 encoded string or if it can be If the system clipboard contains a UTF-8 encoded string or if it can be
converted to one, you can retrieve it with @ref glfwGetClipboardString. See the converted to one, you can retrieve it with @ref glfwGetClipboardString. See the
@ -954,7 +954,7 @@ glfwSetClipboardString(NULL, "A string with words in it");
@endcode @endcode
@section path_drop Path drop input ## Path drop input {#path_drop}
If you wish to receive the paths of files and/or directories dropped on If you wish to receive the paths of files and/or directories dropped on
a window, set a file drop callback. a window, set a file drop callback.

16
docs/internal.md
View File

@ -1,4 +1,4 @@
@page internals_guide Internal structure # Internal structure {#internals_guide}
@tableofcontents @tableofcontents
@ -6,7 +6,7 @@ There are several interfaces inside GLFW. Each interface has its own area of
responsibility and its own naming conventions. responsibility and its own naming conventions.
@section internals_public Public interface ## Public interface {#internals_public}
The most well-known is the public interface, described in the glfw3.h header The most well-known is the public interface, described in the glfw3.h header
file. This is implemented in source files shared by all platforms and these file. This is implemented in source files shared by all platforms and these
@ -20,7 +20,7 @@ it use headless camel case.
Examples: `glfwCreateWindow`, `GLFWwindow`, `GLFW_RED_BITS` Examples: `glfwCreateWindow`, `GLFWwindow`, `GLFW_RED_BITS`
@section internals_native Native interface ## Native interface {#internals_native}
The [native interface](@ref native) is a small set of publicly available The [native interface](@ref native) is a small set of publicly available
but platform-specific functions, described in the glfw3native.h header file and but platform-specific functions, described in the glfw3native.h header file and
@ -34,7 +34,7 @@ from.
Examples: `glfwGetX11Window`, `glfwGetWGLContext` Examples: `glfwGetX11Window`, `glfwGetWGLContext`
@section internals_internal Internal interface ## Internal interface {#internals_internal}
The internal interface consists of utility functions used by all other The internal interface consists of utility functions used by all other
interfaces. It is shared code implemented in the same shared source files as interfaces. It is shared code implemented in the same shared source files as
@ -50,7 +50,7 @@ global names have a leading underscore.
Examples: `_glfwIsValidContextConfig`, `_GLFWwindow`, `_glfw.monitorCount` Examples: `_glfwIsValidContextConfig`, `_GLFWwindow`, `_glfw.monitorCount`
@section internals_platform Platform interface ## Platform interface {#internals_platform}
The platform interface implements all platform-specific operations as a service The platform interface implements all platform-specific operations as a service
to the public interface. This includes event processing. The platform to the public interface. This includes event processing. The platform
@ -88,7 +88,7 @@ prevents shared code from accidentally using these members.
Examples: `window->win32.handle`, `_glfw.x11.display` Examples: `window->win32.handle`, `_glfw.x11.display`
@section internals_event Event interface ## Event interface {#internals_event}
The event interface is implemented in the same shared source files as the public The event interface is implemented in the same shared source files as the public
interface and is responsible for delivering the events it receives to the interface and is responsible for delivering the events it receives to the
@ -100,7 +100,7 @@ ObjectEvent pattern.
Examples: `_glfwInputWindowFocus`, `_glfwInputCursorPos` Examples: `_glfwInputWindowFocus`, `_glfwInputCursorPos`
@section internals_static Static functions ## Static functions {#internals_static}
Static functions may be used by any interface and have no prefixes or suffixes. Static functions may be used by any interface and have no prefixes or suffixes.
These use headless camel case. These use headless camel case.
@ -108,7 +108,7 @@ These use headless camel case.
Examples: `isValidElementForJoystick` Examples: `isValidElementForJoystick`
@section internals_config Configuration macros ## Configuration macros {#internals_config}
GLFW uses a number of configuration macros to select at compile time which GLFW uses a number of configuration macros to select at compile time which
interfaces and code paths to use. They are defined in the GLFW CMake target. interfaces and code paths to use. They are defined in the GLFW CMake target.

48
docs/intro.md
View File

@ -1,4 +1,4 @@
@page intro_guide Introduction to the API # Introduction to the API {#intro_guide}
@tableofcontents @tableofcontents
@ -16,7 +16,7 @@ There are also guides for the other areas of GLFW.
- @ref input_guide - @ref input_guide
@section intro_init Initialization and termination ## Initialization and termination {#intro_init}
Before most GLFW functions may be called, the library must be initialized. Before most GLFW functions may be called, the library must be initialized.
This initialization checks what features are available on the machine, This initialization checks what features are available on the machine,
@ -41,7 +41,7 @@ Calling any other function before successful initialization will cause a @ref
GLFW_NOT_INITIALIZED error. GLFW_NOT_INITIALIZED error.
@subsection intro_init_init Initializing GLFW ### Initializing GLFW {#intro_init_init}
The library is initialized with @ref glfwInit, which returns `GLFW_FALSE` if an The library is initialized with @ref glfwInit, which returns `GLFW_FALSE` if an
error occurred. error occurred.
@ -69,7 +69,7 @@ main menu and dock icon can be disabled with the @ref GLFW_COCOA_MENUBAR init
hint. hint.
@subsection init_hints Initialization hints ### Initialization hints {#init_hints}
Initialization hints are set before @ref glfwInit and affect how the library Initialization hints are set before @ref glfwInit and affect how the library
behaves until termination. Hints are set with @ref glfwInitHint. behaves until termination. Hints are set with @ref glfwInitHint.
@ -87,7 +87,7 @@ will only affect their specific platform. Other platforms will ignore them.
Setting these hints requires no platform specific headers or functions. Setting these hints requires no platform specific headers or functions.
@subsubsection init_hints_shared Shared init hints #### Shared init hints {#init_hints_shared}
@anchor GLFW_PLATFORM @anchor GLFW_PLATFORM
__GLFW_PLATFORM__ specifies the platform to use for windowing and input. __GLFW_PLATFORM__ specifies the platform to use for windowing and input.
@ -118,7 +118,7 @@ extension. This extension is not used if this hint is
`GLFW_ANGLE_PLATFORM_TYPE_NONE`, which is the default value. `GLFW_ANGLE_PLATFORM_TYPE_NONE`, which is the default value.
@subsubsection init_hints_osx macOS specific init hints #### macOS specific init hints {#init_hints_osx}
@anchor GLFW_COCOA_CHDIR_RESOURCES_hint @anchor GLFW_COCOA_CHDIR_RESOURCES_hint
__GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to __GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to
@ -133,7 +133,7 @@ a nib or manually by GLFW. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
This is ignored on other platforms. This is ignored on other platforms.
@subsubsection init_hints_x11 X11 specific init hints #### X11 specific init hints {#init_hints_x11}
@anchor GLFW_X11_XCB_VULKAN_SURFACE_hint @anchor GLFW_X11_XCB_VULKAN_SURFACE_hint
__GLFW_X11_XCB_VULKAN_SURFACE__ specifies whether to prefer the __GLFW_X11_XCB_VULKAN_SURFACE__ specifies whether to prefer the
@ -142,7 +142,7 @@ the `VK_KHR_xlib_surface` extension. Possible values are `GLFW_TRUE` and
`GLFW_FALSE`. This is ignored on other platforms. `GLFW_FALSE`. This is ignored on other platforms.
@subsubsection init_hints_wayland Wayland specific init hints #### Wayland specific init hints {#init_hints_wayland}
@anchor GLFW_WAYLAND_LIBDECOR_hint @anchor GLFW_WAYLAND_LIBDECOR_hint
__GLFW_WAYLAND_LIBDECOR__ specifies whether to use __GLFW_WAYLAND_LIBDECOR__ specifies whether to use
@ -151,7 +151,7 @@ decorations where available. Possible values are `GLFW_WAYLAND_PREFER_LIBDECOR`
and `GLFW_WAYLAND_DISABLE_LIBDECOR`. This is ignored on other platforms. and `GLFW_WAYLAND_DISABLE_LIBDECOR`. This is ignored on other platforms.
@subsubsection init_hints_values Supported and default values #### Supported and default values {#init_hints_values}
Initialization hint | Default value | Supported values Initialization hint | Default value | Supported values
-------------------------------- | ------------------------------- | ---------------- -------------------------------- | ------------------------------- | ----------------
@ -164,7 +164,7 @@ Initialization hint | Default value | Supported v
@ref GLFW_WAYLAND_LIBDECOR | `GLFW_WAYLAND_PREFER_LIBDECOR` | `GLFW_WAYLAND_PREFER_LIBDECOR` or `GLFW_WAYLAND_DISABLE_LIBDECOR` @ref GLFW_WAYLAND_LIBDECOR | `GLFW_WAYLAND_PREFER_LIBDECOR` | `GLFW_WAYLAND_PREFER_LIBDECOR` or `GLFW_WAYLAND_DISABLE_LIBDECOR`
@subsection platform Runtime platform selection ### Runtime platform selection {#platform}
GLFW can be compiled for more than one platform (window system) at once. This lets GLFW can be compiled for more than one platform (window system) at once. This lets
a single library binary support both X11 and Wayland on Linux and other Unix-like systems. a single library binary support both X11 and Wayland on Linux and other Unix-like systems.
@ -206,7 +206,7 @@ Unix-like systems, then you may need to check that you are calling the ones matc
selected platform. selected platform.
@subsection init_allocator Custom heap memory allocator ### Custom heap memory allocator {#init_allocator}
The heap memory allocator can be customized before initialization with @ref The heap memory allocator can be customized before initialization with @ref
glfwInitAllocator. glfwInitAllocator.
@ -273,7 +273,7 @@ The documentation for @ref GLFWdeallocatefun also lists the requirements and lim
for a deallocation function. If the active one does not meet all of these, GLFW may fail. for a deallocation function. If the active one does not meet all of these, GLFW may fail.
@subsection intro_init_terminate Terminating GLFW ### Terminating GLFW {#intro_init_terminate}
Before your application exits, you should terminate the GLFW library if it has Before your application exits, you should terminate the GLFW library if it has
been initialized. This is done with @ref glfwTerminate. been initialized. This is done with @ref glfwTerminate.
@ -292,7 +292,7 @@ library was not initialized or had already been terminated, it returns
immediately. immediately.
@section error_handling Error handling ## Error handling {#error_handling}
Some GLFW functions have return values that indicate an error, but this is often Some GLFW functions have return values that indicate an error, but this is often
not very helpful when trying to figure out what happened or why it occurred. not very helpful when trying to figure out what happened or why it occurred.
@ -367,7 +367,7 @@ Do not rely on a currently invalid call to generate a specific error, as in the
future that same call may generate a different error or become valid. future that same call may generate a different error or become valid.
@section coordinate_systems Coordinate systems ## Coordinate systems {#coordinate_systems}
GLFW has two primary coordinate systems: the _virtual screen_ and the window GLFW has two primary coordinate systems: the _virtual screen_ and the window
_content area_ or _content area_. Both use the same unit: _virtual screen _content area_ or _content area_. Both use the same unit: _virtual screen
@ -404,7 +404,7 @@ between screen coordinates and pixels may also change at run-time depending on
which monitor the window is currently considered to be on. which monitor the window is currently considered to be on.
@section guarantees_limitations Guarantees and limitations ## Guarantees and limitations {#guarantees_limitations}
This section describes the conditions under which GLFW can be expected to This section describes the conditions under which GLFW can be expected to
function, barring bugs in the operating system or drivers. Use of GLFW outside function, barring bugs in the operating system or drivers. Use of GLFW outside
@ -413,7 +413,7 @@ time, or on some versions of GLFW, but it may break at any time and this will
not be considered a bug. not be considered a bug.
@subsection lifetime Pointer lifetimes ### Pointer lifetimes {#lifetime}
GLFW will never free any pointer you provide to it, and you must never free any GLFW will never free any pointer you provide to it, and you must never free any
pointer it provides to you. pointer it provides to you.
@ -433,7 +433,7 @@ Pointer lifetimes are guaranteed not to be shortened in future minor or patch
releases. releases.
@subsection reentrancy Reentrancy ### Reentrancy {#reentrancy}
GLFW event processing and object destruction are not reentrant. This means that GLFW event processing and object destruction are not reentrant. This means that
the following functions must not be called from any callback function: the following functions must not be called from any callback function:
@ -449,7 +449,7 @@ These functions may be made reentrant in future minor or patch releases, but
functions not on this list will not be made non-reentrant. functions not on this list will not be made non-reentrant.
@subsection thread_safety Thread safety ### Thread safety {#thread_safety}
Most GLFW functions must only be called from the main thread (the thread that Most GLFW functions must only be called from the main thread (the thread that
calls main), but some may be called from any thread once the library has been calls main), but some may be called from any thread once the library has been
@ -530,7 +530,7 @@ but functions that are currently limited to the main thread may be updated to
allow calls from any thread in future releases. allow calls from any thread in future releases.
@subsection compatibility Version compatibility ### Version compatibility {#compatibility}
GLFW uses [Semantic Versioning](https://semver.org/). This guarantees source GLFW uses [Semantic Versioning](https://semver.org/). This guarantees source
and binary backward compatibility with earlier minor versions of the API. This and binary backward compatibility with earlier minor versions of the API. This
@ -550,14 +550,14 @@ fixed in the next release. The reference documentation will also take
precedence over anything stated in a guide. precedence over anything stated in a guide.
@subsection event_order Event order ### Event order {#event_order}
The order of arrival of related events is not guaranteed to be consistent The order of arrival of related events is not guaranteed to be consistent
across platforms. The exception is synthetic key and mouse button release across platforms. The exception is synthetic key and mouse button release
events, which are always delivered after the window defocus event. events, which are always delivered after the window defocus event.
@section intro_version Version management ## Version management {#intro_version}
GLFW provides mechanisms for identifying what version of GLFW your application GLFW provides mechanisms for identifying what version of GLFW your application
was compiled against as well as what version it is currently running against. was compiled against as well as what version it is currently running against.
@ -565,7 +565,7 @@ If you are loading GLFW dynamically (not just linking dynamically), you can use
this to verify that the library binary is compatible with your application. this to verify that the library binary is compatible with your application.
@subsection intro_version_compile Compile-time version ### Compile-time version {#intro_version_compile}
The compile-time version of GLFW is provided by the GLFW header with the The compile-time version of GLFW is provided by the GLFW header with the
`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros. `GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
@ -578,7 +578,7 @@ printf("Compiled against GLFW %i.%i.%i\n",
@endcode @endcode
@subsection intro_version_runtime Run-time version ### Run-time version {#intro_version_runtime}
The run-time version can be retrieved with @ref glfwGetVersion, a function that The run-time version can be retrieved with @ref glfwGetVersion, a function that
may be called regardless of whether GLFW is initialized. may be called regardless of whether GLFW is initialized.
@ -591,7 +591,7 @@ printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
@endcode @endcode
@subsection intro_version_string Version string ### Version string {#intro_version_string}
GLFW 3 also provides a compile-time generated version string that describes the GLFW 3 also provides a compile-time generated version string that describes the
version, platform, compiler and any platform-specific compile-time options. version, platform, compiler and any platform-specific compile-time options.

4
docs/main.md
View File

@ -1,6 +1,4 @@
@mainpage notitle # Introduction {#mainpage}
@section main_intro Introduction
GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
Vulkan application development. It provides a simple, platform-independent API Vulkan application development. It provides a simple, platform-independent API

26
docs/monitor.md
View File

@ -1,4 +1,4 @@
@page monitor_guide Monitor guide # Monitor guide {#monitor_guide}
@tableofcontents @tableofcontents
@ -13,7 +13,7 @@ guides for the other areas of GLFW.
- @ref input_guide - @ref input_guide
@section monitor_object Monitor objects ## Monitor objects {#monitor_object}
A monitor object represents a currently connected monitor and is represented as A monitor object represents a currently connected monitor and is represented as
a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
@ -34,7 +34,7 @@ To see how GLFW views your monitor setup and its available video modes, run the
`monitors` test program. `monitors` test program.
@subsection monitor_monitors Retrieving monitors ### Retrieving monitors {#monitor_monitors}
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's
preferred monitor and is usually the one with global UI elements like task bar preferred monitor and is usually the one with global UI elements like task bar
@ -57,7 +57,7 @@ monitors may be moved to a different index when a monitor is connected or
disconnected. disconnected.
@subsection monitor_event Monitor configuration changes ### Monitor configuration changes {#monitor_event}
If you wish to be notified when a monitor is connected or disconnected, set If you wish to be notified when a monitor is connected or disconnected, set
a monitor callback. a monitor callback.
@ -89,14 +89,14 @@ glfwGetMonitorName and @ref glfwGetMonitorUserPointer will return useful values
for a disconnected monitor and only before the monitor callback returns. for a disconnected monitor and only before the monitor callback returns.
@section monitor_properties Monitor properties ## Monitor properties {#monitor_properties}
Each monitor has a current video mode, a list of supported video modes, Each monitor has a current video mode, a list of supported video modes,
a virtual position, a content scale, a human-readable name, a user pointer, an a virtual position, a content scale, a human-readable name, a user pointer, an
estimated physical size and a gamma ramp. estimated physical size and a gamma ramp.
@subsection monitor_modes Video modes ### Video modes {#monitor_modes}
GLFW generally does a good job selecting a suitable video mode when you create GLFW generally does a good job selecting a suitable video mode when you create
a full screen window, change its video mode or make a windowed one full a full screen window, change its video mode or make a windowed one full
@ -123,7 +123,7 @@ The resolution of a video mode is specified in
[screen coordinates](@ref coordinate_systems), not pixels. [screen coordinates](@ref coordinate_systems), not pixels.
@subsection monitor_size Physical size ### Physical size {#monitor_size}
The physical size of a monitor in millimetres, or an estimation of it, can be The physical size of a monitor in millimetres, or an estimation of it, can be
retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its
@ -140,7 +140,7 @@ useful. Instead, use the [monitor content scale](@ref monitor_scale) and
[window content scale](@ref window_scale) to scale your content. [window content scale](@ref window_scale) to scale your content.
@subsection monitor_scale Content scale ### Content scale {#monitor_scale}
The content scale for a monitor can be retrieved with @ref The content scale for a monitor can be retrieved with @ref
glfwGetMonitorContentScale. glfwGetMonitorContentScale.
@ -162,7 +162,7 @@ and on user settings. It may be very different from the raw DPI calculated from
the physical size and current resolution. the physical size and current resolution.
@subsection monitor_pos Virtual position ### Virtual position {#monitor_pos}
The position of the monitor on the virtual desktop, in The position of the monitor on the virtual desktop, in
[screen coordinates](@ref coordinate_systems), can be retrieved with @ref [screen coordinates](@ref coordinate_systems), can be retrieved with @ref
@ -174,7 +174,7 @@ glfwGetMonitorPos(monitor, &xpos, &ypos);
@endcode @endcode
@subsection monitor_workarea Work area ### Work area {#monitor_workarea}
The area of a monitor not occupied by global task bars or menu bars is the work The area of a monitor not occupied by global task bars or menu bars is the work
area. This is specified in [screen coordinates](@ref coordinate_systems) and area. This is specified in [screen coordinates](@ref coordinate_systems) and
@ -186,7 +186,7 @@ glfwGetMonitorWorkarea(monitor, &xpos, &ypos, &width, &height);
@endcode @endcode
@subsection monitor_name Human-readable name ### Human-readable name {#monitor_name}
The human-readable, UTF-8 encoded name of a monitor is returned by @ref The human-readable, UTF-8 encoded name of a monitor is returned by @ref
glfwGetMonitorName. See the reference documentation for the lifetime of the glfwGetMonitorName. See the reference documentation for the lifetime of the
@ -201,7 +201,7 @@ and make may have the same name. Only the monitor handle is guaranteed to be
unique, and only until that monitor is disconnected. unique, and only until that monitor is disconnected.
@subsection monitor_userptr User pointer ### User pointer {#monitor_userptr}
Each monitor has a user pointer that can be set with @ref Each monitor has a user pointer that can be set with @ref
glfwSetMonitorUserPointer and queried with @ref glfwGetMonitorUserPointer. This glfwSetMonitorUserPointer and queried with @ref glfwGetMonitorUserPointer. This
@ -212,7 +212,7 @@ terminated.
The initial value of the pointer is `NULL`. The initial value of the pointer is `NULL`.
@subsection monitor_gamma Gamma ramp ### Gamma ramp {#monitor_gamma}
The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts
a monitor handle and a pointer to a @ref GLFWgammaramp structure. a monitor handle and a pointer to a @ref GLFWgammaramp structure.

58
docs/moving.md
View File

@ -1,4 +1,4 @@
@page moving_guide Moving from GLFW 2 to 3 # Moving from GLFW 2 to 3 {#moving_guide}
@tableofcontents @tableofcontents
@ -9,9 +9,9 @@ base onto the new API. For example, the new multi-monitor functions are
required to create full screen windows with GLFW 3. required to create full screen windows with GLFW 3.
@section moving_removed Changed and removed features ## Changed and removed features {#moving_removed}
@subsection moving_renamed_files Renamed library and header file ### Renamed library and header file {#moving_renamed_files}
The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
avoid collisions with the headers of other major versions. Similarly, the GLFW avoid collisions with the headers of other major versions. Similarly, the GLFW
@ -30,7 +30,7 @@ Unix-like systems, where it uses the
@endcode @endcode
@subsection moving_threads Removal of threading functions ### Removal of threading functions {#moving_threads}
The threading functions have been removed, including the per-thread sleep The threading functions have been removed, including the per-thread sleep
function. They were fairly primitive, under-used, poorly integrated and took function. They were fairly primitive, under-used, poorly integrated and took
@ -63,7 +63,7 @@ used from any thread and which must only be used from the main thread.
`GLFWthreadfun` `GLFWthreadfun`
@subsection moving_image Removal of image and texture loading ### Removal of image and texture loading {#moving_image}
The image and texture loading functions have been removed. They only supported The image and texture loading functions have been removed. They only supported
the Targa image format, making them mostly useful for beginner level examples. the Targa image format, making them mostly useful for beginner level examples.
@ -82,7 +82,7 @@ platform-independent, as both OpenGL and stdio are available wherever GLFW is.
`glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`. `glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`.
@subsection moving_stdcall Removal of GLFWCALL macro ### Removal of GLFWCALL macro {#moving_stdcall}
The `GLFWCALL` macro, which made callback functions use The `GLFWCALL` macro, which made callback functions use
[__stdcall](https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows, [__stdcall](https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
@ -103,7 +103,7 @@ void callback_function(...);
@endcode @endcode
@subsection moving_window_handles Window handle parameters ### Window handle parameters {#moving_window_handles}
Because GLFW 3 supports multiple windows, window handle parameters have been Because GLFW 3 supports multiple windows, window handle parameters have been
added to all window-related GLFW functions and callbacks. The handle of added to all window-related GLFW functions and callbacks. The handle of
@ -122,7 +122,7 @@ glfwSetWindowTitle(window, "New Window Title");
@endcode @endcode
@subsection moving_monitor Explicit monitor selection ### Explicit monitor selection {#moving_monitor}
GLFW 3 provides support for multiple monitors. To request a full screen mode window, GLFW 3 provides support for multiple monitors. To request a full screen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
@ -146,7 +146,7 @@ into [window hints](@ref window_hints), but as they have been given
[sane defaults](@ref window_hints_values) you rarely need to set these hints. [sane defaults](@ref window_hints_values) you rarely need to set these hints.
@subsection moving_autopoll Removal of automatic event polling ### Removal of automatic event polling {#moving_autopoll}
GLFW 3 does not automatically poll for events in @ref glfwSwapBuffers, meaning GLFW 3 does not automatically poll for events in @ref glfwSwapBuffers, meaning
you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. Unlike you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. Unlike
@ -175,7 +175,7 @@ while (...)
@endcode @endcode
@subsection moving_context Explicit context management ### Explicit context management {#moving_context}
Each GLFW 3 window has its own OpenGL context and only you, the application Each GLFW 3 window has its own OpenGL context and only you, the application
programmer, can know which context should be current on which thread at any programmer, can know which context should be current on which thread at any
@ -185,7 +185,7 @@ This means that you need to call @ref glfwMakeContextCurrent after creating
a window before you can call any OpenGL functions. a window before you can call any OpenGL functions.
@subsection moving_hidpi Separation of window and framebuffer sizes ### Separation of window and framebuffer sizes {#moving_hidpi}
Window positions and sizes now use screen coordinates, which may not be the same Window positions and sizes now use screen coordinates, which may not be the same
as pixels on machines with high-DPI monitors. This is important as OpenGL uses as pixels on machines with high-DPI monitors. This is important as OpenGL uses
@ -208,7 +208,7 @@ glViewport(0, 0, width, height);
@endcode @endcode
@subsection moving_window_close Window closing changes ### Window closing changes {#moving_window_close}
The `GLFW_OPENED` window parameter has been removed. As long as the window has The `GLFW_OPENED` window parameter has been removed. As long as the window has
not been destroyed, whether through @ref glfwDestroyWindow or @ref not been destroyed, whether through @ref glfwDestroyWindow or @ref
@ -260,7 +260,7 @@ for other reasons to close the window as well, for example the user choosing
Quit from an in-game menu. Quit from an in-game menu.
@subsection moving_hints Persistent window hints ### Persistent window hints {#moving_hints}
The `glfwOpenWindowHint` function has been renamed to @ref glfwWindowHint. The `glfwOpenWindowHint` function has been renamed to @ref glfwWindowHint.
@ -269,7 +269,7 @@ instead retain their values until modified by @ref glfwWindowHint or @ref
glfwDefaultWindowHints, or until the library is terminated and re-initialized. glfwDefaultWindowHints, or until the library is terminated and re-initialized.
@subsection moving_video_modes Video mode enumeration ### Video mode enumeration {#moving_video_modes}
Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
now returns all available modes for a specific monitor instead of requiring you now returns all available modes for a specific monitor instead of requiring you
@ -278,7 +278,7 @@ had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
returns the current mode of a monitor. returns the current mode of a monitor.
@subsection moving_char_up Removal of character actions ### Removal of character actions {#moving_char_up}
The action parameter of the [character callback](@ref GLFWcharfun) has been The action parameter of the [character callback](@ref GLFWcharfun) has been
removed. This was an artefact of the origin of GLFW, i.e. being developed in removed. This was an artefact of the origin of GLFW, i.e. being developed in
@ -297,7 +297,7 @@ void character_callback(GLFWwindow* window, int character);
@endcode @endcode
@subsection moving_cursorpos Cursor position changes ### Cursor position changes {#moving_cursorpos}
The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos, The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos,
`glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref `glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref
@ -313,7 +313,7 @@ glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
Unless the window is active, the function fails silently. Unless the window is active, the function fails silently.
@subsection moving_wheel Wheel position replaced by scroll offsets ### Wheel position replaced by scroll offsets {#moving_wheel}
The `glfwGetMouseWheel` function has been removed. Scrolling is the input of The `glfwGetMouseWheel` function has been removed. Scrolling is the input of
offsets and has no absolute position. The mouse wheel callback has been offsets and has no absolute position. The mouse wheel callback has been
@ -335,7 +335,7 @@ void scroll_callback(GLFWwindow* window, double xoffset, double yoffset);
`glfwGetMouseWheel` `glfwGetMouseWheel`
@subsection moving_repeat Key repeat action ### Key repeat action {#moving_repeat}
The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
for both keys and characters. A new key action, `GLFW_REPEAT`, has been added for both keys and characters. A new key action, `GLFW_REPEAT`, has been added
@ -344,7 +344,7 @@ from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
`GLFW_RELEASE`. `GLFW_RELEASE`.
@subsection moving_keys Physical key input ### Physical key input {#moving_keys}
GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
the values generated by the current keyboard layout. The tokens are named the values generated by the current keyboard layout. The tokens are named
@ -364,7 +364,7 @@ having to remember whether to check for `a` or `A`, you now check for
@ref GLFW_KEY_A. @ref GLFW_KEY_A.
@subsection moving_joystick Joystick function changes ### Joystick function changes {#moving_joystick}
The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes. The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.
@ -374,7 +374,7 @@ function as well as axis and button counts returned by the @ref
glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions. glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.
@subsection moving_mbcs Win32 MBCS support ### Win32 MBCS support {#moving_mbcs}
The Win32 port of GLFW 3 will not compile in The Win32 port of GLFW 3 will not compile in
[MBCS mode](https://msdn.microsoft.com/en-us/library/5z097dxa.aspx). [MBCS mode](https://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
@ -385,7 +385,7 @@ Therefore, even if an application using GLFW has MBCS mode code, there's no need
for GLFW itself to support it. for GLFW itself to support it.
@subsection moving_windows Support for versions of Windows older than XP ### Support for versions of Windows older than XP {#moving_windows}
All explicit support for version of Windows older than XP has been removed. All explicit support for version of Windows older than XP has been removed.
There is no code that actively prevents GLFW 3 from running on these earlier There is no code that actively prevents GLFW 3 from running on these earlier
@ -405,7 +405,7 @@ runtime checking for a number of functions that are present only on modern
version of Windows. version of Windows.
@subsection moving_syskeys Capture of system-wide hotkeys ### Capture of system-wide hotkeys {#moving_syskeys}
The ability to disable and capture system-wide hotkeys like Alt+Tab has been The ability to disable and capture system-wide hotkeys like Alt+Tab has been
removed. Modern applications, whether they're games, scientific visualisations removed. Modern applications, whether they're games, scientific visualisations
@ -413,7 +413,7 @@ or something else, are nowadays expected to be good desktop citizens and allow
these hotkeys to function even when running in full screen mode. these hotkeys to function even when running in full screen mode.
@subsection moving_terminate Automatic termination ### Automatic termination {#moving_terminate}
GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization, GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization,
because `exit` calls registered functions from the calling thread and while it because `exit` calls registered functions from the calling thread and while it
@ -426,7 +426,7 @@ destroys all windows not already destroyed with @ref glfwDestroyWindow,
invalidating any window handles you may still have. invalidating any window handles you may still have.
@subsection moving_glu GLU header inclusion ### GLU header inclusion {#moving_glu}
GLFW 3 does not by default include the GLU header and GLU itself has been GLFW 3 does not by default include the GLU header and GLU itself has been
deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New
@ -453,10 +453,10 @@ tessellation functions, see for example
[libtess2](https://github.com/memononen/libtess2). [libtess2](https://github.com/memononen/libtess2).
@section moving_tables Name change tables ## Name change tables {#moving_tables}
@subsection moving_renamed_functions Renamed functions ### Renamed functions {#moving_renamed_functions}
| GLFW 2 | GLFW 3 | Notes | | GLFW 2 | GLFW 3 | Notes |
| --------------------------- | ----------------------------- | ----- | | --------------------------- | ----------------------------- | ----- |
@ -476,7 +476,7 @@ tessellation functions, see for example
| `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons | | `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons |
@subsection moving_renamed_types Renamed types ### Renamed types {#moving_renamed_types}
| GLFW 2 | GLFW 3 | Notes | | GLFW 2 | GLFW 3 | Notes |
| ------------------- | --------------------- | | | ------------------- | --------------------- | |
@ -484,7 +484,7 @@ tessellation functions, see for example
| `GLFWmouseposfun` | @ref GLFWcursorposfun | | | `GLFWmouseposfun` | @ref GLFWcursorposfun | |
@subsection moving_renamed_tokens Renamed tokens ### Renamed tokens {#moving_renamed_tokens}
| GLFW 2 | GLFW 3 | Notes | | GLFW 2 | GLFW 3 | Notes |
| --------------------------- | ---------------------------- | ----- | | --------------------------- | ---------------------------- | ----- |

68
docs/news.md
View File

@ -1,13 +1,13 @@
@page news Release notes # Release notes {#news}
@tableofcontents @tableofcontents
@section news_34 Release notes for version 3.4 ## Release notes for version 3.4 {#news_34}
@subsection features_34 New features in version 3.4 ### New features in version 3.4 {#features_34}
@subsubsection runtime_platform_34 Runtime platform selection #### Runtime platform selection {#runtime_platform_34}
GLFW now supports being compiled for multiple backends and selecting between GLFW now supports being compiled for multiple backends and selecting between
them at runtime with the @ref GLFW_PLATFORM init hint. After initialization the them at runtime with the @ref GLFW_PLATFORM init hint. After initialization the
@ -15,7 +15,7 @@ selected platform can be queried with @ref glfwGetPlatform. You can check if
support for a given platform is compiled in with @ref glfwPlatformSupported. support for a given platform is compiled in with @ref glfwPlatformSupported.
@subsubsection standard_cursors_34 More standard cursors #### More standard cursors {#standard_cursors_34}
GLFW now provides the standard cursor shapes @ref GLFW_RESIZE_NWSE_CURSOR and 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 @ref GLFW_RESIZE_NESW_CURSOR for diagonal resizing, @ref GLFW_RESIZE_ALL_CURSOR
@ -33,7 +33,7 @@ are still available.
For more information see @ref cursor_standard. For more information see @ref cursor_standard.
@subsubsection mouse_passthrough_34 Mouse event passthrough #### Mouse event passthrough {#mouse_passthrough_34}
GLFW now provides the [GLFW_MOUSE_PASSTHROUGH](@ref GLFW_MOUSE_PASSTHROUGH_hint) 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 window hint for making a window transparent to mouse input, lettings events pass
@ -41,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). creation with the matching [window attribute](@ref GLFW_MOUSE_PASSTHROUGH_attrib).
@subsubsection wayland_libdecor_34 Wayland libdecor decorations #### Wayland libdecor decorations {#wayland_libdecor_34}
GLFW now supports improved fallback window decorations via GLFW now supports improved fallback window decorations via
[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor). [libdecor](https://gitlab.freedesktop.org/libdecor/libdecor).
@ -51,13 +51,13 @@ Support for libdecor can be toggled before GLFW is initialized with the
enabled by default. enabled by default.
@subsubsection wayland_app_id_34 Wayland app_id specification #### Wayland app_id specification {#wayland_app_id_34}
GLFW now supports specifying the app_id for a Wayland window using the 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. [GLFW_WAYLAND_APP_ID](@ref GLFW_WAYLAND_APP_ID_hint) window hint string.
@subsubsection features_34_angle_backend Support for ANGLE rendering backend selection #### Support for ANGLE rendering backend selection {#features_34_angle_backend}
GLFW now provides the GLFW now provides the
[GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for [GLFW_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for
@ -66,7 +66,7 @@ requesting a specific rendering backend when using
contexts. contexts.
@subsubsection captured_cursor_34 Captured cursor mode #### Captured cursor mode {#captured_cursor_34}
GLFW now supports confining the cursor to the window content area with the @ref GLFW now supports confining the cursor to the window content area with the @ref
GLFW_CURSOR_CAPTURED cursor mode. GLFW_CURSOR_CAPTURED cursor mode.
@ -74,7 +74,7 @@ GLFW_CURSOR_CAPTURED cursor mode.
For more information see @ref cursor_mode. For more information see @ref cursor_mode.
@subsubsection features_34_init_allocator Support for custom memory allocator #### Support for custom memory allocator {#features_34_init_allocator}
GLFW now supports plugging a custom memory allocator at initialization with @ref GLFW now supports plugging a custom memory allocator at initialization with @ref
glfwInitAllocator. The allocator is a struct of type @ref GLFWallocator with glfwInitAllocator. The allocator is a struct of type @ref GLFWallocator with
@ -84,7 +84,7 @@ function pointers corresponding to the standard library functions `malloc`,
For more information see @ref init_allocator. For more information see @ref init_allocator.
@subsubsection features_34_position_hint Window hints for initial position #### Window hints for initial position {#features_34_position_hint}
GLFW now provides the @ref GLFW_POSITION_X and @ref GLFW_POSITION_Y window hints for 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 specifying the initial position of the window. This removes the need to create a hidden
@ -92,7 +92,7 @@ window, move it and then show it. The default value of these hints is
`GLFW_ANY_POSITION`, which selects the previous behavior. `GLFW_ANY_POSITION`, which selects the previous behavior.
@subsubsection features_34_win32_keymenu Support for keyboard access to Windows window menu #### Support for keyboard access to Windows window menu {#features_34_win32_keymenu}
GLFW now provides the GLFW now provides the
[GLFW_WIN32_KEYBOARD_MENU](@ref GLFW_WIN32_KEYBOARD_MENU_hint) window hint for [GLFW_WIN32_KEYBOARD_MENU](@ref GLFW_WIN32_KEYBOARD_MENU_hint) window hint for
@ -101,16 +101,16 @@ Alt-and-then-Space shortcuts. This may be useful for more GUI-oriented
applications. applications.
@subsubsection features_34_win32_showdefault Support for applying STARTUPINFO show command #### Support for applying STARTUPINFO show command {#features_34_win32_showdefault}
GLFW now provides the [GLFW_WIN32_SHOWDEFAULT](@ref GLFW_WIN32_SHOWDEFAULT_hint) window 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 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. for the first time. This may be useful for the main window of a windowed-mode tool.
@subsection caveats Caveats for version 3.4 ### Caveats for version 3.4 {#caveats}
@subsubsection native_34 Multiple sets of native access functions #### Multiple sets of native access functions {#native_34}
Because GLFW now supports runtime selection of platform (window system), a library binary 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 may export native access functions for multiple platforms. Starting with version 3.4 you
@ -119,14 +119,14 @@ functions for it. After initialization, you can query the selected platform wit
glfwGetPlatform. glfwGetPlatform.
@subsubsection version_string_34 Version string format has been changed #### Version string format has been changed {#version_string_34}
Because GLFW now supports runtime selection of platform (window system), the version 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 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. of all APIs for all the platforms that the library binary supports.
@subsubsection joysticks_34 Joystick support is initialized on demand #### Joystick support is initialized on demand {#joysticks_34}
The joystick part of GLFW is now initialized when first used, primarily to work 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 around faulty Windows drivers that cause DirectInput to take up to several
@ -141,7 +141,7 @@ To work around this, call any joystick function before waiting for events, for
example by setting a [joystick callback](@ref joystick_event). example by setting a [joystick callback](@ref joystick_event).
@subsubsection wayland_alpha_34 Framebuffer may lack alpha channel on older Wayland systems #### 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 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 `EGL_EXT_present_opaque` extension, the @ref GLFW_ALPHA_BITS window hint will be
@ -154,7 +154,7 @@ If you want a per-pixel transparent window, see the
hint. hint.
@subsubsection standalone_34 Tests and examples are disabled when built as a subproject #### 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 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 a subdirectory of another CMake project. To enable these, set the @ref
@ -168,37 +168,37 @@ add_subdirectory(path/to/glfw)
@endcode @endcode
@subsubsection initmenu_34 macOS main menu now created at initialization #### macOS main menu now created at initialization {#initmenu_34}
GLFW now creates the main menu and completes the initialization of NSApplication 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 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. with the [GLFW_COCOA_MENUBAR](@ref GLFW_COCOA_MENUBAR_hint) init hint.
@subsubsection corevideo_34 CoreVideo dependency has been removed #### CoreVideo dependency has been removed {#corevideo_34}
GLFW no longer depends on the CoreVideo framework on macOS and it no longer GLFW no longer depends on the CoreVideo framework on macOS and it no longer
needs to be specified during compilation or linking. needs to be specified during compilation or linking.
@subsubsection caveat_fbtransparency_34 Framebuffer transparency requires DWM transparency #### Framebuffer transparency requires DWM transparency {#caveat_fbtransparency_34}
GLFW no longer supports framebuffer transparency enabled via @ref GLFW no longer supports framebuffer transparency enabled via @ref
GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off
(the Transparency setting under Personalization > Window Color). (the Transparency setting under Personalization > Window Color).
@subsubsection emptyevents_34 Empty events on X11 no longer round-trip to server #### Empty events on X11 no longer round-trip to server {#emptyevents_34}
Events posted with @ref glfwPostEmptyEvent now use a separate unnamed pipe Events posted with @ref glfwPostEmptyEvent now use a separate unnamed pipe
instead of sending an X11 client event to the helper window. instead of sending an X11 client event to the helper window.
@subsection deprecations_34 Deprecations in version 3.4 ### Deprecations in version 3.4 {#deprecations_34}
@subsection removals_34 Removals in 3.4 ### Removals in 3.4 {#removals_34}
@subsubsection vulkan_static_34 GLFW_VULKAN_STATIC CMake option has been removed #### GLFW_VULKAN_STATIC CMake option has been removed {#vulkan_static_34}
This option was used to compile GLFW directly linked with the Vulkan loader, instead of 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 using dynamic loading to get hold of `vkGetInstanceProcAddr` at initialization. This is
@ -209,7 +209,7 @@ 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. your code by checking the @ref GLFW_VERSION_MAJOR and @ref GLFW_VERSION_MINOR macros.
@subsubsection osmesa_option_34 GLFW_USE_OSMESA CMake option has been removed #### GLFW_USE_OSMESA CMake option has been removed {#osmesa_option_34}
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 is now
always supported. To produce a library binary that only supports this platform, the way always supported. To produce a library binary that only supports this platform, the way
@ -221,16 +221,16 @@ You can set all of them to false and the ones that don't apply for the target OS
ignored. ignored.
@subsubsection wl_shell_34 Support for the wl_shell protocol has been removed #### Support for the wl_shell protocol has been removed {#wl_shell_34}
Support for the wl_shell protocol has been removed and GLFW now only supports 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 the XDG-Shell protocol. If your Wayland compositor does not support XDG-Shell
then GLFW will fail to initialize. then GLFW will fail to initialize.
@subsection symbols_34 New symbols in version 3.4 ### New symbols in version 3.4 {#symbols_34}
@subsubsection functions_34 New functions in version 3.4 #### New functions in version 3.4 {#functions_34}
- @ref glfwInitAllocator - @ref glfwInitAllocator
- @ref glfwGetPlatform - @ref glfwGetPlatform
@ -238,7 +238,7 @@ then GLFW will fail to initialize.
- @ref glfwInitVulkanLoader - @ref glfwInitVulkanLoader
@subsubsection types_34 New types in version 3.4 #### New types in version 3.4 {#types_34}
- @ref GLFWallocator - @ref GLFWallocator
- @ref GLFWallocatefun - @ref GLFWallocatefun
@ -246,7 +246,7 @@ then GLFW will fail to initialize.
- @ref GLFWdeallocatefun - @ref GLFWdeallocatefun
@subsubsection constants_34 New constants in version 3.4 #### New constants in version 3.4 {#constants_34}
- @ref GLFW_PLATFORM - @ref GLFW_PLATFORM
- @ref GLFW_ANY_PLATFORM - @ref GLFW_ANY_PLATFORM
@ -289,7 +289,7 @@ then GLFW will fail to initialize.
- @ref GLFW_WAYLAND_DISABLE_LIBDECOR - @ref GLFW_WAYLAND_DISABLE_LIBDECOR
@section news_archive Release notes for earlier versions ## Release notes for earlier versions {#news_archive}
- [Release notes for 3.3](https://www.glfw.org/docs/3.3/news.html) - [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.2](https://www.glfw.org/docs/3.2/news.html)

28
docs/quick.md
View File

@ -1,4 +1,4 @@
@page quick_guide Getting started # Getting started {#quick_guide}
@tableofcontents @tableofcontents
@ -12,9 +12,9 @@ have used GLFW 2 in the past, read @ref moving_guide, as some functions
behave differently in GLFW 3. behave differently in GLFW 3.
@section quick_steps Step by step ## Step by step {#quick_steps}
@subsection quick_include Including the GLFW header ### Including the GLFW header {#quick_include}
In the source files of your application where you use GLFW, you need to include In the source files of your application where you use GLFW, you need to include
its header file. its header file.
@ -53,7 +53,7 @@ in any order.
@endcode @endcode
@subsection quick_init_term Initializing and terminating GLFW ### Initializing and terminating GLFW {#quick_init_term}
Before you can use most GLFW functions, the library must be initialized. On Before you can use most GLFW functions, the library must be initialized. On
successful initialization, `GLFW_TRUE` is returned. If an error occurred, successful initialization, `GLFW_TRUE` is returned. If an error occurred,
@ -80,7 +80,7 @@ GLFW. After this call, you must initialize GLFW again before using any GLFW
functions that require it. functions that require it.
@subsection quick_capture_error Setting an error callback ### Setting an error callback {#quick_capture_error}
Most events are reported through callbacks, whether it's a key being pressed, Most events are reported through callbacks, whether it's a key being pressed,
a GLFW window being moved, or an error occurring. Callbacks are C functions (or a GLFW window being moved, or an error occurring. Callbacks are C functions (or
@ -107,7 +107,7 @@ glfwSetErrorCallback(error_callback);
@endcode @endcode
@subsection quick_create_window Creating a window and context ### Creating a window and context {#quick_create_window}
The window and its OpenGL context are created with a single call to @ref The window and its OpenGL context are created with a single call to @ref
glfwCreateWindow, which returns a handle to the created combined window and glfwCreateWindow, which returns a handle to the created combined window and
@ -157,7 +157,7 @@ Once this function is called, no more events will be delivered for that window
and its handle becomes invalid. and its handle becomes invalid.
@subsection quick_context_current Making the OpenGL context current ### Making the OpenGL context current {#quick_context_current}
Before you can use the OpenGL API, you must have a current OpenGL context. Before you can use the OpenGL API, you must have a current OpenGL context.
@ -179,7 +179,7 @@ gladLoadGL(glfwGetProcAddress);
@endcode @endcode
@subsection quick_window_close Checking the window close flag ### Checking the window close flag {#quick_window_close}
Each window has a flag indicating whether the window should be closed. Each window has a flag indicating whether the window should be closed.
@ -205,7 +205,7 @@ useful if you want to interpret other kinds of input as closing the window, like
for example pressing the _Escape_ key. for example pressing the _Escape_ key.
@subsection quick_key_input Receiving input events ### Receiving input events {#quick_key_input}
Each window has a large number of callbacks that can be set to receive all the Each window has a large number of callbacks that can be set to receive all the
various kinds of events. To receive key press and release events, create a key various kinds of events. To receive key press and release events, create a key
@ -229,7 +229,7 @@ In order for event callbacks to be called when events occur, you need to process
events as described below. events as described below.
@subsection quick_render Rendering with OpenGL ### Rendering with OpenGL {#quick_render}
Once you have a current OpenGL context, you can use OpenGL normally. In this Once you have a current OpenGL context, you can use OpenGL normally. In this
tutorial, a multicolored rotating triangle will be rendered. The framebuffer tutorial, a multicolored rotating triangle will be rendered. The framebuffer
@ -256,7 +256,7 @@ These all happen to use GLFW, but OpenGL itself works the same whatever API you
use to create the window and context. use to create the window and context.
@subsection quick_timer Reading the timer ### Reading the timer {#quick_timer}
To create smooth animation, a time source is needed. GLFW provides a timer that To create smooth animation, a time source is needed. GLFW provides a timer that
returns the number of seconds since initialization. The time source used is the returns the number of seconds since initialization. The time source used is the
@ -268,7 +268,7 @@ double time = glfwGetTime();
@endcode @endcode
@subsection quick_swap_buffers Swapping buffers ### Swapping buffers {#quick_swap_buffers}
GLFW windows by default use double buffering. That means that each window has GLFW windows by default use double buffering. That means that each window has
two rendering buffers; a front buffer and a back buffer. The front buffer is two rendering buffers; a front buffer and a back buffer. The front buffer is
@ -302,7 +302,7 @@ This function acts on the current context and will fail unless a context is
current. current.
@subsection quick_process_events Processing events ### Processing events {#quick_process_events}
GLFW needs to communicate regularly with the window system both in order to GLFW needs to communicate regularly with the window system both in order to
receive events and to show that the application hasn't locked up. Event receive events and to show that the application hasn't locked up. Event
@ -325,7 +325,7 @@ all received events. This saves a great deal of CPU cycles and is useful for,
for example, many kinds of editing tools. for example, many kinds of editing tools.
@section quick_example Putting it together ## Putting it together {#quick_example}
Now that you know how to initialize GLFW, create a window and poll for Now that you know how to initialize GLFW, create a window and poll for
keyboard input, it's possible to create a small program. keyboard input, it's possible to create a small program.

18
docs/vulkan.md
View File

@ -1,4 +1,4 @@
@page vulkan_guide Vulkan guide # Vulkan guide {#vulkan_guide}
@tableofcontents @tableofcontents
@ -27,7 +27,7 @@ are also guides for the other areas of the GLFW API.
- @ref input_guide - @ref input_guide
@section vulkan_loader Finding the Vulkan loader ## Finding the Vulkan loader {#vulkan_loader}
GLFW itself does not ever need to be linked against the Vulkan loader. GLFW itself does not ever need to be linked against the Vulkan loader.
@ -52,7 +52,7 @@ bundle according to the LunarG SDK documentation. This is explained in more det
[SDK documentation for macOS](https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html). [SDK documentation for macOS](https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html).
@section vulkan_include Including the Vulkan header file ## Including the Vulkan header file {#vulkan_include}
To have GLFW include the Vulkan header, define @ref GLFW_INCLUDE_VULKAN before including To have GLFW include the Vulkan header, define @ref GLFW_INCLUDE_VULKAN before including
the GLFW header. the GLFW header.
@ -82,7 +82,7 @@ The `VK_USE_PLATFORM_*_KHR` macros do not need to be defined for the Vulkan part
of GLFW to work. Define them only if you are using these extensions directly. of GLFW to work. Define them only if you are using these extensions directly.
@section vulkan_support Querying for Vulkan support ## Querying for Vulkan support {#vulkan_support}
If you are linking directly against the Vulkan loader then you can skip this If you are linking directly against the Vulkan loader then you can skip this
section. The canonical desktop loader library exports all Vulkan core and section. The canonical desktop loader library exports all Vulkan core and
@ -106,7 +106,7 @@ If one or both were not found, calling any other Vulkan related GLFW function
will generate a @ref GLFW_API_UNAVAILABLE error. will generate a @ref GLFW_API_UNAVAILABLE error.
@subsection vulkan_proc Querying Vulkan function pointers ### Querying Vulkan function pointers {#vulkan_proc}
To load any Vulkan core or extension function from the found loader, call @ref To load any Vulkan core or extension function from the found loader, call @ref
glfwGetInstanceProcAddress. To load functions needed for instance creation, glfwGetInstanceProcAddress. To load functions needed for instance creation,
@ -145,7 +145,7 @@ dispatch internally based on the device passed to them. For more information
about `vkGetDeviceProcAddr`, see the Vulkan documentation. about `vkGetDeviceProcAddr`, see the Vulkan documentation.
@section vulkan_ext Querying required Vulkan extensions ## Querying required Vulkan extensions {#vulkan_ext}
To do anything useful with Vulkan you need to create an instance. If you want To do anything useful with Vulkan you need to create an instance. If you want
to use Vulkan to render to a window, you must enable the instance extensions to use Vulkan to render to a window, you must enable the instance extensions
@ -194,7 +194,7 @@ info flags for MoltenVK to show up in the list of physical devices. For more
information, see the Vulkan and MoltenVK documentation. information, see the Vulkan and MoltenVK documentation.
@section vulkan_present Querying for Vulkan presentation support ## Querying for Vulkan presentation support {#vulkan_present}
Not every queue family of every Vulkan device can present images to surfaces. Not every queue family of every Vulkan device can present images to surfaces.
To check whether a specific queue family of a physical device supports image To check whether a specific queue family of a physical device supports image
@ -213,7 +213,7 @@ The `VK_KHR_surface` extension additionally provides the
an existing Vulkan surface. an existing Vulkan surface.
@section vulkan_window Creating the window ## Creating the window {#vulkan_window}
Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan, Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan,
there is no need to create a context. You can disable context creation with the there is no need to create a context. You can disable context creation with the
@ -227,7 +227,7 @@ GLFWwindow* window = glfwCreateWindow(640, 480, "Window Title", NULL, NULL);
See @ref context_less for more information. See @ref context_less for more information.
@section vulkan_surface Creating a Vulkan window surface ## Creating a Vulkan window surface {#vulkan_surface}
You can create a Vulkan surface (as defined by the `VK_KHR_surface` extension) You can create a Vulkan surface (as defined by the `VK_KHR_surface` extension)
for a GLFW window with @ref glfwCreateWindowSurface. for a GLFW window with @ref glfwCreateWindowSurface.

82
docs/window.md
View File

@ -1,4 +1,4 @@
@page window_guide Window guide # Window guide {#window_guide}
@tableofcontents @tableofcontents
@ -13,7 +13,7 @@ guides for the other areas of GLFW.
- @ref input_guide - @ref input_guide
@section window_object Window objects ## Window objects {#window_object}
The @ref GLFWwindow object encapsulates both a window and a context. They are The @ref GLFWwindow object encapsulates both a window and a context. They are
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or
@ -24,7 +24,7 @@ To see the event stream provided to the various window related callbacks, run
the `events` test program. the `events` test program.
@subsection window_creation Window creation ### Window creation {#window_creation}
A window and its OpenGL or OpenGL ES context are created with @ref A window and its OpenGL or OpenGL ES context are created with @ref
glfwCreateWindow, which returns a handle to the created window object. For glfwCreateWindow, which returns a handle to the created window object. For
@ -42,7 +42,7 @@ along with all input events, so event handlers can tell which window received
the event. the event.
@subsubsection window_full_screen Full screen windows #### Full screen windows {#window_full_screen}
To create a full screen window, you need to specify which monitor the window To create a full screen window, you need to specify which monitor the window
should use. In most cases, the user's primary monitor is a good choice. should use. In most cases, the user's primary monitor is a good choice.
@ -91,7 +91,7 @@ If a monitor is disconnected, all windows that are full screen on that monitor
will be switched to windowed mode. See @ref monitor_event for more information. will be switched to windowed mode. See @ref monitor_event for more information.
@subsubsection window_windowed_full_screen "Windowed full screen" windows #### "Windowed full screen" windows {#window_windowed_full_screen}
If the closest match for the desired video mode is the current one, the video If the closest match for the desired video mode is the current one, the video
mode will not be changed, making window creation faster and application mode will not be changed, making window creation faster and application
@ -123,7 +123,7 @@ so if you already have a full screen window on that monitor that you want to
make windowed full screen, you need to have saved the desktop resolution before. make windowed full screen, you need to have saved the desktop resolution before.
@subsection window_destruction Window destruction ### Window destruction {#window_destruction}
When a window is no longer needed, destroy it with @ref glfwDestroyWindow. When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
@ -139,7 +139,7 @@ When a full screen window is destroyed, the original video mode of its monitor
is restored, but the gamma ramp is left untouched. is restored, but the gamma ramp is left untouched.
@subsection window_hints Window creation hints ### Window creation hints {#window_hints}
There are a number of hints that can be set before the creation of a window and There are a number of hints that can be set before the creation of a window and
context. Some affect the window itself, others affect the framebuffer or context. Some affect the window itself, others affect the framebuffer or
@ -158,7 +158,7 @@ you wish to have the specified attributes. They function as additional
arguments to @ref glfwCreateWindow. arguments to @ref glfwCreateWindow.
@subsubsection window_hints_hard Hard and soft constraints #### Hard and soft constraints {#window_hints_hard}
Some window hints are hard constraints. These must match the available Some window hints are hard constraints. These must match the available
capabilities _exactly_ for window and context creation to succeed. Hints capabilities _exactly_ for window and context creation to succeed. Hints
@ -177,7 +177,7 @@ context, but are ignored when requesting an OpenGL ES context:
- [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) - [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint)
@subsubsection window_hints_wnd Window related hints #### Window related hints {#window_hints_wnd}
@anchor GLFW_RESIZABLE_hint @anchor GLFW_RESIZABLE_hint
__GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable __GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable
@ -263,7 +263,7 @@ manager will position the window where it thinks the user will prefer it.
Possible values are any valid screen coordinates and `GLFW_ANY_POSITION`. Possible values are any valid screen coordinates and `GLFW_ANY_POSITION`.
@subsubsection window_hints_fb Framebuffer related hints #### Framebuffer related hints {#window_hints_fb}
@anchor GLFW_RED_BITS @anchor GLFW_RED_BITS
@anchor GLFW_GREEN_BITS @anchor GLFW_GREEN_BITS
@ -322,7 +322,7 @@ buffered. You nearly always want to use double buffering. This is a hard
constraint. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. constraint. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
@subsubsection window_hints_mtr Monitor related hints #### Monitor related hints {#window_hints_mtr}
@anchor GLFW_REFRESH_RATE @anchor GLFW_REFRESH_RATE
__GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen __GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen
@ -330,7 +330,7 @@ windows. A value of `GLFW_DONT_CARE` means the highest available refresh rate
will be used. This hint is ignored for windowed mode windows. will be used. This hint is ignored for windowed mode windows.
@subsubsection window_hints_ctx Context related hints #### Context related hints {#window_hints_ctx}
@anchor GLFW_CLIENT_API_hint @anchor GLFW_CLIENT_API_hint
__GLFW_CLIENT_API__ specifies which client API to create the context for. __GLFW_CLIENT_API__ specifies which client API to create the context for.
@ -453,7 +453,7 @@ The no error mode for OpenGL and OpenGL ES is described in detail by the
extension. extension.
@subsubsection window_hints_win32 Win32 specific hints #### Win32 specific hints {#window_hints_win32}
@anchor GLFW_WIN32_KEYBOARD_MENU_hint @anchor GLFW_WIN32_KEYBOARD_MENU_hint
__GLFW_WIN32_KEYBOARD_MENU__ specifies whether to allow access to the window __GLFW_WIN32_KEYBOARD_MENU__ specifies whether to allow access to the window
@ -469,7 +469,7 @@ GLFW behaves as if this hint was set to `GLFW_FALSE`. Possible values are
`GLFW_TRUE` and `GLFW_FALSE`. This is ignored on other platforms. `GLFW_TRUE` and `GLFW_FALSE`. This is ignored on other platforms.
@subsubsection window_hints_osx macOS specific hints #### macOS specific hints {#window_hints_osx}
@anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint @anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint
__GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution __GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution
@ -498,7 +498,7 @@ should also declare this in its `Info.plist` by setting the
`NSSupportsAutomaticGraphicsSwitching` key to `true`. `NSSupportsAutomaticGraphicsSwitching` key to `true`.
@subsubsection window_hints_x11 X11 specific window hints #### X11 specific window hints {#window_hints_x11}
@anchor GLFW_X11_CLASS_NAME_hint @anchor GLFW_X11_CLASS_NAME_hint
@anchor GLFW_X11_INSTANCE_NAME_hint @anchor GLFW_X11_INSTANCE_NAME_hint
@ -507,7 +507,7 @@ ASCII encoded class and instance parts of the ICCCM `WM_CLASS` window property.
hints need to be set to something other than an empty string for them to take effect. hints need to be set to something other than an empty string for them to take effect.
These are set with @ref glfwWindowHintString. These are set with @ref glfwWindowHintString.
@subsubsection window_hints_wayland Wayland specific window hints #### Wayland specific window hints {#window_hints_wayland}
@anchor GLFW_WAYLAND_APP_ID_hint @anchor GLFW_WAYLAND_APP_ID_hint
__GLFW_WAYLAND_APP_ID__ specifies the Wayland app_id for a window, used __GLFW_WAYLAND_APP_ID__ specifies the Wayland app_id for a window, used
@ -515,7 +515,7 @@ by window managers to identify types of windows. This is set with
@ref glfwWindowHintString. @ref glfwWindowHintString.
@subsubsection window_hints_values Supported and default values #### Supported and default values {#window_hints_values}
Window hint | Default value | Supported values Window hint | Default value | Supported values
----------------------------- | --------------------------- | ---------------- ----------------------------- | --------------------------- | ----------------
@ -568,14 +568,14 @@ GLFW_X11_INSTANCE_NAME | `""` | An ASCII encoded `
GLFW_WAYLAND_APP_ID | `""` | An ASCII encoded Wayland `app_id` name GLFW_WAYLAND_APP_ID | `""` | An ASCII encoded Wayland `app_id` name
@section window_events Window event processing ## Window event processing {#window_events}
See @ref events. See @ref events.
@section window_properties Window properties and events ## Window properties and events {#window_properties}
@subsection window_userptr User pointer ### User pointer {#window_userptr}
Each window has a user pointer that can be set with @ref Each window has a user pointer that can be set with @ref
glfwSetWindowUserPointer and queried with @ref glfwGetWindowUserPointer. This glfwSetWindowUserPointer and queried with @ref glfwGetWindowUserPointer. This
@ -585,7 +585,7 @@ the life-time of the window.
The initial value of the pointer is `NULL`. The initial value of the pointer is `NULL`.
@subsection window_close Window closing and close flag ### Window closing and close flag {#window_close}
When the user attempts to close the window, for example by clicking the close When the user attempts to close the window, for example by clicking the close
widget or using a key chord like Alt+F4, the _close flag_ of the window is set. widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
@ -626,7 +626,7 @@ void window_close_callback(GLFWwindow* window)
@endcode @endcode
@subsection window_size Window size ### Window size {#window_size}
The size of a window can be changed with @ref glfwSetWindowSize. For windowed The size of a window can be changed with @ref glfwSetWindowSize. For windowed
mode windows, this sets the size, in mode windows, this sets the size, in
@ -685,7 +685,7 @@ the content area to the corresponding edges of the full window. As they are
distances and not coordinates, they are always zero or positive. distances and not coordinates, they are always zero or positive.
@subsection window_fbsize Framebuffer size ### Framebuffer size {#window_fbsize}
While the size of a window is measured in screen coordinates, OpenGL works with While the size of a window is measured in screen coordinates, OpenGL works with
pixels. The size you pass into `glViewport`, for example, should be in pixels. pixels. The size you pass into `glViewport`, for example, should be in pixels.
@ -723,7 +723,7 @@ The size of a framebuffer may change independently of the size of a window, for
example if the window is dragged between a regular monitor and a high-DPI one. example if the window is dragged between a regular monitor and a high-DPI one.
@subsection window_scale Window content scale ### Window content scale {#window_scale}
The content scale for a window can be retrieved with @ref The content scale for a window can be retrieved with @ref
glfwGetWindowContentScale. glfwGetWindowContentScale.
@ -768,7 +768,7 @@ window is created and when its content scale later changes, set the @ref
GLFW_SCALE_TO_MONITOR window hint. GLFW_SCALE_TO_MONITOR window hint.
@subsection window_sizelimits Window size limits ### Window size limits {#window_sizelimits}
The minimum and maximum size of the content area of a windowed mode window can The minimum and maximum size of the content area of a windowed mode window can
be enforced with @ref glfwSetWindowSizeLimits. The user may resize the window be enforced with @ref glfwSetWindowSizeLimits. The user may resize the window
@ -814,7 +814,7 @@ You can have both size limits and aspect ratio set for a window, but the results
are undefined if they conflict. are undefined if they conflict.
@subsection window_pos Window position ### Window position {#window_pos}
By default, the window manager chooses the position of new windowed mode By default, the window manager chooses the position of new windowed mode
windows, based on its size and which monitor the user appears to be working on. windows, based on its size and which monitor the user appears to be working on.
@ -863,7 +863,7 @@ glfwGetWindowPos(window, &xpos, &ypos);
@endcode @endcode
@subsection window_title Window title ### Window title {#window_title}
All GLFW windows have a title, although undecorated or full screen windows may All GLFW windows have a title, although undecorated or full screen windows may
not display it or only display it in a task bar or similar interface. You can not display it or only display it in a task bar or similar interface. You can
@ -890,7 +890,7 @@ glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
@endcode @endcode
@subsection window_icon Window icon ### Window icon {#window_icon}
Decorated windows have icons on some platforms. You can set this icon by Decorated windows have icons on some platforms. You can set this icon by
specifying a list of candidate images with @ref glfwSetWindowIcon. specifying a list of candidate images with @ref glfwSetWindowIcon.
@ -914,7 +914,7 @@ glfwSetWindowIcon(window, 0, NULL);
@endcode @endcode
@subsection window_monitor Window monitor ### Window monitor {#window_monitor}
Full screen windows are associated with a specific monitor. You can get the Full screen windows are associated with a specific monitor. You can get the
handle for this monitor with @ref glfwGetWindowMonitor. handle for this monitor with @ref glfwGetWindowMonitor.
@ -952,7 +952,7 @@ that was originally windowed to its original size and position, save these
before making it full screen and then pass them in as above. before making it full screen and then pass them in as above.
@subsection window_iconify Window iconification ### Window iconification {#window_iconify}
Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow. Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
@ -1003,7 +1003,7 @@ int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
@endcode @endcode
@subsection window_maximize Window maximization ### Window maximization {#window_maximize}
Windows can be maximized (i.e. zoomed) with @ref glfwMaximizeWindow. Windows can be maximized (i.e. zoomed) with @ref glfwMaximizeWindow.
@ -1059,7 +1059,7 @@ glfwWindowHint(GLFW_MAXIMIZED, GLFW_TRUE);
@endcode @endcode
@subsection window_hide Window visibility ### Window visibility {#window_hide}
Windowed mode windows can be hidden with @ref glfwHideWindow. Windowed mode windows can be hidden with @ref glfwHideWindow.
@ -1101,7 +1101,7 @@ can be useful if you need to set up your window further before showing it, for
example moving it to a specific location. example moving it to a specific location.
@subsection window_focus Window input focus ### Window input focus {#window_focus}
Windows can be given input focus and brought to the front with @ref Windows can be given input focus and brought to the front with @ref
glfwFocusWindow. glfwFocusWindow.
@ -1152,7 +1152,7 @@ glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE);
@endcode @endcode
@subsection window_attention Window attention request ### Window attention request {#window_attention}
If you wish to notify the user of an event without interrupting, you can request If you wish to notify the user of an event without interrupting, you can request
attention with @ref glfwRequestWindowAttention. attention with @ref glfwRequestWindowAttention.
@ -1166,7 +1166,7 @@ not supported, the application as a whole. Once the user has given it
attention, the system will automatically end the request. attention, the system will automatically end the request.
@subsection window_refresh Window damage and refresh ### Window damage and refresh {#window_refresh}
If you wish to be notified when the contents of a window is damaged and needs If you wish to be notified when the contents of a window is damaged and needs
to be refreshed, set a window refresh callback. to be refreshed, set a window refresh callback.
@ -1191,7 +1191,7 @@ window contents are saved off-screen, this callback might only be called when
the window or framebuffer is resized. the window or framebuffer is resized.
@subsection window_transparency Window transparency ### Window transparency {#window_transparency}
GLFW supports two kinds of transparency for windows; framebuffer transparency GLFW supports two kinds of transparency for windows; framebuffer transparency
and whole window transparency. A single window may not use both methods. The and whole window transparency. A single window may not use both methods. The
@ -1255,7 +1255,7 @@ overlay like for example a notification, the @ref GLFW_FLOATING and @ref
GLFW_MOUSE_PASSTHROUGH window hints and attributes may be useful. GLFW_MOUSE_PASSTHROUGH window hints and attributes may be useful.
@subsection window_attribs Window attributes ### Window attributes {#window_attribs}
Windows have a number of attributes that can be returned using @ref Windows have a number of attributes that can be returned using @ref
glfwGetWindowAttrib. Some reflect state that may change as a result of user glfwGetWindowAttrib. Some reflect state that may change as a result of user
@ -1283,7 +1283,7 @@ glfwSetWindowAttrib(window, GLFW_RESIZABLE, GLFW_FALSE);
@subsubsection window_attribs_wnd Window related attributes #### Window related attributes {#window_attribs_wnd}
@anchor GLFW_FOCUSED_attrib @anchor GLFW_FOCUSED_attrib
__GLFW_FOCUSED__ indicates whether the specified window has input focus. See __GLFW_FOCUSED__ indicates whether the specified window has input focus. See
@ -1351,7 +1351,7 @@ with @ref glfwSetWindowAttrib. This is only supported for undecorated windows.
Decorated windows with this enabled will behave differently between platforms. Decorated windows with this enabled will behave differently between platforms.
@subsubsection window_attribs_ctx Context related attributes #### Context related attributes {#window_attribs_ctx}
@anchor GLFW_CLIENT_API_attrib @anchor GLFW_CLIENT_API_attrib
__GLFW_CLIENT_API__ indicates the client API provided by the window's context; __GLFW_CLIENT_API__ indicates the client API provided by the window's context;
@ -1415,7 +1415,7 @@ context. This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION`
if the window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise. if the window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
@subsubsection window_attribs_fb Framebuffer related attributes #### Framebuffer related attributes {#window_attribs_fb}
GLFW does not expose most attributes of the default framebuffer (i.e. the GLFW does not expose most attributes of the default framebuffer (i.e. the
framebuffer attached to the window) as these can be queried directly with either framebuffer attached to the window) as these can be queried directly with either
@ -1453,7 +1453,7 @@ when rendering with OpenGL or OpenGL ES. This can be set before creation with
the [GLFW_DOUBLEBUFFER](@ref GLFW_DOUBLEBUFFER_hint) window hint. the [GLFW_DOUBLEBUFFER](@ref GLFW_DOUBLEBUFFER_hint) window hint.
@section buffer_swap Buffer swapping ## Buffer swapping {#buffer_swap}
GLFW windows are by default double buffered. That means that you have two GLFW windows are by default double buffered. That means that you have two
rendering buffers; a front buffer and a back buffer. The front buffer is rendering buffers; a front buffer and a back buffer. The front buffer is