Convert Doxygen headings to Markdown
diff --git a/docs/build.md b/docs/build.md
index 512a17b..43f351d 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -1,4 +1,4 @@
-@page build_guide Building applications
+# Building applications {#build_guide}
@tableofcontents
@@ -14,7 +14,7 @@
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
GLFW.
@@ -66,7 +66,7 @@
@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
its behavior.
@@ -140,7 +140,7 @@
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
needs to link against many different system libraries. If you are using GLFW as
@@ -158,7 +158,7 @@
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
version, it is also necessary to link with some libraries that GLFW uses.
@@ -174,7 +174,7 @@
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
application. If you want to use an installed binary instead, see @ref
@@ -220,7 +220,7 @@
[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
installed. If you want to build it along with your application instead, see
@@ -259,7 +259,7 @@
@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/),
and the `glfw3.pc` pkg-config file is generated when the GLFW library is built
@@ -300,7 +300,7 @@
@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
dependencies.
@@ -310,7 +310,7 @@
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
building from the command line on macOS. That way you will get any new
diff --git a/docs/compat.md b/docs/compat.md
index e590ccf..0d363a7 100644
--- a/docs/compat.md
+++ b/docs/compat.md
@@ -1,4 +1,4 @@
-@page compat_guide Standards conformance
+# Standards conformance {#compat_guide}
@tableofcontents
@@ -13,7 +13,7 @@
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
library, it has sole responsibility for interacting well with the many and
@@ -91,7 +91,7 @@
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
has sole responsibility for interacting well with every compositor in use on
@@ -144,7 +144,7 @@
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
systems using the X Window System.
@@ -184,7 +184,7 @@
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
implementations of the Win32 API, such as Wine.
@@ -225,7 +225,7 @@
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
only forward-compatible, core profile contexts are supported. Support for
@@ -247,7 +247,7 @@
`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
Vulkan API on all platforms except macOS. This is installed by both graphics
@@ -257,7 +257,7 @@
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
all supported platforms.
diff --git a/docs/compile.md b/docs/compile.md
index 65a8261..cc3c899 100644
--- a/docs/compile.md
+++ b/docs/compile.md
@@ -1,4 +1,4 @@
-@page compile_guide Compiling GLFW
+# Compiling GLFW {#compile_guide}
@tableofcontents
@@ -8,7 +8,7 @@
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
describes the standard configure, generate and compile sequence. If you are already
@@ -33,14 +33,14 @@
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
all necessary dependencies for compiling GLFW, but on Unix-like systems like
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
systems (except macOS). To disable one or both of these, set the @ref GLFW_BUILD_WAYLAND
@@ -85,7 +85,7 @@
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
files or makefiles for your development environment. CMake needs two paths for
@@ -107,7 +107,7 @@
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
described above. Then press _Configure_ and _Generate_.
@@ -125,7 +125,7 @@
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`
command. These can be relative or absolute paths. The build directory is
@@ -163,7 +163,7 @@
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
necessary to compile GLFW. Go ahead and compile the actual GLFW library with
@@ -199,7 +199,7 @@
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
available on all supported platforms. Some of these are de facto standards
@@ -219,7 +219,7 @@
@endcode
-@subsection compile_options_shared Shared CMake options
+### Shared CMake options {#compile_options_shared}
@anchor BUILD_SHARED_LIBS
__BUILD_SHARED_LIBS__ determines whether GLFW is built as a static library or as
@@ -251,7 +251,7 @@
[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
__GLFW_BUILD_WIN32__ determines whether to include support for Win32 when compiling the
@@ -276,7 +276,7 @@
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
__GLFW_BUILD_COCOA__ determines whether to include support for Cocoa when compiling the
@@ -284,7 +284,7 @@
default.
-@subsection compile_options_unix Unix-like system specific CMake options
+### Unix-like system specific CMake options {#compile_options_unix}
@anchor GLFW_BUILD_WAYLAND
__GLFW_BUILD_WAYLAND__ determines whether to include support for Wayland when compiling
@@ -297,7 +297,7 @@
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
example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
@@ -330,7 +330,7 @@
[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
at least some platform-detection yourself. There are preprocessor macros for
diff --git a/docs/context.md b/docs/context.md
index eb1b243..c900a8b 100644
--- a/docs/context.md
+++ b/docs/context.md
@@ -1,4 +1,4 @@
-@page context_guide Context guide
+# Context guide {#context_guide}
@tableofcontents
@@ -13,7 +13,7 @@
- @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
context. It is created with @ref glfwCreateWindow and destroyed with @ref
@@ -32,14 +32,14 @@
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
what kind of context is created. See
[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
glfwCreateWindow, you can specify another window whose context the new one
@@ -62,7 +62,7 @@
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,
contexts with hidden windows can be created with the
@@ -83,7 +83,7 @@
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
[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint to `GLFW_NO_API`.
@@ -92,7 +92,7 @@
@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
context of the correct type. A context can only be current for a single thread
@@ -122,12 +122,12 @@
- @ref glfwGetProcAddress
-@section context_swap Buffer swapping
+## Buffer swapping {#context_swap}
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.
Hardware vendors may include extensions in their implementations that extend the
@@ -150,7 +150,7 @@
[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
OpenGL ES extensions and modern versions of the core OpenGL or OpenGL ES APIs.
@@ -231,7 +231,7 @@
@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
[extension loader library](@ref context_glext_auto) will save you a ton of
@@ -246,7 +246,7 @@
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
interfaces for all OpenGL extensions. The latest version of this can always be
@@ -271,7 +271,7 @@
@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
drivers or a graphics card that lacks the necessary hardware features), so it
@@ -290,7 +290,7 @@
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.
These functions often do not have entry points in the client API libraries of
diff --git a/docs/input.md b/docs/input.md
index 4c51e02..bc5cc46 100644
--- a/docs/input.md
+++ b/docs/input.md
@@ -1,4 +1,4 @@
-@page input_guide Input guide
+# Input guide {#input_guide}
@tableofcontents
@@ -27,7 +27,7 @@
information.
-@section events Event processing
+## Event processing {#events}
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
@@ -89,7 +89,7 @@
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
events. Key events relate to actual physical keyboard keys, whereas character
@@ -101,7 +101,7 @@
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
repeats, set a key callback.
@@ -201,7 +201,7 @@
[key token](@ref keys).
-@subsection input_char Text input
+### Text input {#input_char}
GLFW supports text input in the form of a stream of
[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
@@ -230,7 +230,7 @@
@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
dependent name of printable keys with @ref glfwGetKeyName.
@@ -246,14 +246,14 @@
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
scrolling offsets. The cursor appearance can also be changed, either to
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
position callback.
@@ -281,7 +281,7 @@
@endcode
-@subsection cursor_mode Cursor mode
+### Cursor mode {#cursor_mode}
@anchor GLFW_CURSOR
The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
@@ -336,7 +336,7 @@
@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
be enabled if available.
@@ -360,7 +360,7 @@
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
as @ref GLFWcursor objects. They are created with @ref glfwCreateCursor or @ref
@@ -368,7 +368,7 @@
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
the created cursor object. For example, this creates a 16x16 white square
@@ -394,7 +394,7 @@
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
theme can be created with @ref glfwCreateStandardCursor.
@@ -410,7 +410,7 @@
`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.
@@ -423,7 +423,7 @@
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.
@@ -447,7 +447,7 @@
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
a window, set a cursor enter/leave callback.
@@ -483,7 +483,7 @@
@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
a mouse button callback.
@@ -543,7 +543,7 @@
[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
touchpad gesture, set a scroll callback.
@@ -563,7 +563,7 @@
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
referred to as joysticks. It supports up to sixteen joysticks, ranging from
@@ -593,7 +593,7 @@
`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
glfwGetJoystickAxes. See the reference documentation for the lifetime of the
@@ -607,7 +607,7 @@
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
glfwGetJoystickButtons. See the reference documentation for the lifetime of the
@@ -625,7 +625,7 @@
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
reference documentation for the lifetime of the returned array.
@@ -665,7 +665,7 @@
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
glfwGetJoystickName. See the reference documentation for the lifetime of the
@@ -680,7 +680,7 @@
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
glfwSetJoystickUserPointer and queried with @ref glfwGetJoystickUserPointer.
@@ -691,7 +691,7 @@
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
a joystick callback.
@@ -728,7 +728,7 @@
returns.
-@subsection gamepad Gamepad input
+### Gamepad input {#gamepad}
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
@@ -809,7 +809,7 @@
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
[SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB) at the
@@ -892,7 +892,7 @@
and described above.
-@section time Time input
+## Time input {#time}
GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
@@ -929,7 +929,7 @@
@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
converted to one, you can retrieve it with @ref glfwGetClipboardString. See the
@@ -954,7 +954,7 @@
@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
a window, set a file drop callback.
diff --git a/docs/internal.md b/docs/internal.md
index ff281e4..46fc8ba 100644
--- a/docs/internal.md
+++ b/docs/internal.md
@@ -1,4 +1,4 @@
-@page internals_guide Internal structure
+# Internal structure {#internals_guide}
@tableofcontents
@@ -6,7 +6,7 @@
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
file. This is implemented in source files shared by all platforms and these
@@ -20,7 +20,7 @@
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
but platform-specific functions, described in the glfw3native.h header file and
@@ -34,7 +34,7 @@
Examples: `glfwGetX11Window`, `glfwGetWGLContext`
-@section internals_internal Internal interface
+## Internal interface {#internals_internal}
The internal interface consists of utility functions used by all other
interfaces. It is shared code implemented in the same shared source files as
@@ -50,7 +50,7 @@
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
to the public interface. This includes event processing. The platform
@@ -88,7 +88,7 @@
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
interface and is responsible for delivering the events it receives to the
@@ -100,7 +100,7 @@
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.
These use headless camel case.
@@ -108,7 +108,7 @@
Examples: `isValidElementForJoystick`
-@section internals_config Configuration macros
+## Configuration macros {#internals_config}
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.
diff --git a/docs/intro.md b/docs/intro.md
index 085cdd7..35334c7 100644
--- a/docs/intro.md
+++ b/docs/intro.md
@@ -1,4 +1,4 @@
-@page intro_guide Introduction to the API
+# Introduction to the API {#intro_guide}
@tableofcontents
@@ -16,7 +16,7 @@
- @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.
This initialization checks what features are available on the machine,
@@ -41,7 +41,7 @@
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
error occurred.
@@ -69,7 +69,7 @@
hint.
-@subsection init_hints Initialization hints
+### Initialization hints {#init_hints}
Initialization hints are set before @ref glfwInit and affect how the library
behaves until termination. Hints are set with @ref glfwInitHint.
@@ -87,7 +87,7 @@
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
__GLFW_PLATFORM__ specifies the platform to use for windowing and input.
@@ -118,7 +118,7 @@
`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
__GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to
@@ -133,7 +133,7 @@
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
__GLFW_X11_XCB_VULKAN_SURFACE__ specifies whether to prefer the
@@ -142,7 +142,7 @@
`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
__GLFW_WAYLAND_LIBDECOR__ specifies whether to use
@@ -151,7 +151,7 @@
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
-------------------------------- | ------------------------------- | ----------------
@@ -164,7 +164,7 @@
@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
a single library binary support both X11 and Wayland on Linux and other Unix-like systems.
@@ -206,7 +206,7 @@
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
glfwInitAllocator.
@@ -273,7 +273,7 @@
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
been initialized. This is done with @ref glfwTerminate.
@@ -292,7 +292,7 @@
immediately.
-@section error_handling Error handling
+## Error handling {#error_handling}
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.
@@ -367,7 +367,7 @@
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
_content area_ or _content area_. Both use the same unit: _virtual screen
@@ -404,7 +404,7 @@
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
function, barring bugs in the operating system or drivers. Use of GLFW outside
@@ -413,7 +413,7 @@
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
pointer it provides to you.
@@ -433,7 +433,7 @@
releases.
-@subsection reentrancy Reentrancy
+### Reentrancy {#reentrancy}
GLFW event processing and object destruction are not reentrant. This means that
the following functions must not be called from any callback function:
@@ -449,7 +449,7 @@
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
calls main), but some may be called from any thread once the library has been
@@ -530,7 +530,7 @@
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
and binary backward compatibility with earlier minor versions of the API. This
@@ -550,14 +550,14 @@
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
across platforms. The exception is synthetic key and mouse button release
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
was compiled against as well as what version it is currently running against.
@@ -565,7 +565,7 @@
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
`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
@@ -578,7 +578,7 @@
@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
may be called regardless of whether GLFW is initialized.
@@ -591,7 +591,7 @@
@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
version, platform, compiler and any platform-specific compile-time options.
diff --git a/docs/main.md b/docs/main.md
index 53faeea..4f86b8a 100644
--- a/docs/main.md
+++ b/docs/main.md
@@ -1,6 +1,4 @@
-@mainpage notitle
-
-@section main_intro Introduction
+# Introduction {#mainpage}
GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and
Vulkan application development. It provides a simple, platform-independent API
diff --git a/docs/monitor.md b/docs/monitor.md
index 5aa5ed7..b4ba75c 100644
--- a/docs/monitor.md
+++ b/docs/monitor.md
@@ -1,4 +1,4 @@
-@page monitor_guide Monitor guide
+# Monitor guide {#monitor_guide}
@tableofcontents
@@ -13,7 +13,7 @@
- @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 pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
@@ -34,7 +34,7 @@
`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
preferred monitor and is usually the one with global UI elements like task bar
@@ -57,7 +57,7 @@
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
a monitor callback.
@@ -89,14 +89,14 @@
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,
a virtual position, a content scale, a human-readable name, a user pointer, an
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
a full screen window, change its video mode or make a windowed one full
@@ -123,7 +123,7 @@
[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
retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its
@@ -140,7 +140,7 @@
[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
glfwGetMonitorContentScale.
@@ -162,7 +162,7 @@
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
[screen coordinates](@ref coordinate_systems), can be retrieved with @ref
@@ -174,7 +174,7 @@
@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
area. This is specified in [screen coordinates](@ref coordinate_systems) and
@@ -186,7 +186,7 @@
@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
glfwGetMonitorName. See the reference documentation for the lifetime of the
@@ -201,7 +201,7 @@
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
glfwSetMonitorUserPointer and queried with @ref glfwGetMonitorUserPointer. This
@@ -212,7 +212,7 @@
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
a monitor handle and a pointer to a @ref GLFWgammaramp structure.
diff --git a/docs/moving.md b/docs/moving.md
index fe4f30b..86068db 100644
--- a/docs/moving.md
+++ b/docs/moving.md
@@ -1,4 +1,4 @@
-@page moving_guide Moving from GLFW 2 to 3
+# Moving from GLFW 2 to 3 {#moving_guide}
@tableofcontents
@@ -9,9 +9,9 @@
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
avoid collisions with the headers of other major versions. Similarly, the GLFW
@@ -30,7 +30,7 @@
@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
function. They were fairly primitive, under-used, poorly integrated and took
@@ -63,7 +63,7 @@
`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 Targa image format, making them mostly useful for beginner level examples.
@@ -82,7 +82,7 @@
`glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`.
-@subsection moving_stdcall Removal of GLFWCALL macro
+### Removal of GLFWCALL macro {#moving_stdcall}
The `GLFWCALL` macro, which made callback functions use
[__stdcall](https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
@@ -103,7 +103,7 @@
@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
added to all window-related GLFW functions and callbacks. The handle of
@@ -122,7 +122,7 @@
@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,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
@@ -146,7 +146,7 @@
[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
you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. Unlike
@@ -175,7 +175,7 @@
@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
programmer, can know which context should be current on which thread at any
@@ -185,7 +185,7 @@
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
as pixels on machines with high-DPI monitors. This is important as OpenGL uses
@@ -208,7 +208,7 @@
@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
not been destroyed, whether through @ref glfwDestroyWindow or @ref
@@ -260,7 +260,7 @@
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.
@@ -269,7 +269,7 @@
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
now returns all available modes for a specific monitor instead of requiring you
@@ -278,7 +278,7 @@
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
removed. This was an artefact of the origin of GLFW, i.e. being developed in
@@ -297,7 +297,7 @@
@endcode
-@subsection moving_cursorpos Cursor position changes
+### Cursor position changes {#moving_cursorpos}
The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos,
`glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref
@@ -313,7 +313,7 @@
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
offsets and has no absolute position. The mouse wheel callback has been
@@ -335,7 +335,7 @@
`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
for both keys and characters. A new key action, `GLFW_REPEAT`, has been added
@@ -344,7 +344,7 @@
`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
the values generated by the current keyboard layout. The tokens are named
@@ -364,7 +364,7 @@
@ref GLFW_KEY_A.
-@subsection moving_joystick Joystick function changes
+### Joystick function changes {#moving_joystick}
The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.
@@ -374,7 +374,7 @@
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
[MBCS mode](https://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
@@ -385,7 +385,7 @@
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.
There is no code that actively prevents GLFW 3 from running on these earlier
@@ -405,7 +405,7 @@
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
removed. Modern applications, whether they're games, scientific visualisations
@@ -413,7 +413,7 @@
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,
because `exit` calls registered functions from the calling thread and while it
@@ -426,7 +426,7 @@
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
deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New
@@ -453,10 +453,10 @@
[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 |
| --------------------------- | ----------------------------- | ----- |
@@ -476,7 +476,7 @@
| `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 |
| ------------------- | --------------------- | |
@@ -484,7 +484,7 @@
| `GLFWmouseposfun` | @ref GLFWcursorposfun | |
-@subsection moving_renamed_tokens Renamed tokens
+### Renamed tokens {#moving_renamed_tokens}
| GLFW 2 | GLFW 3 | Notes |
| --------------------------- | ---------------------------- | ----- |
diff --git a/docs/news.md b/docs/news.md
index b316b8d..7592886 100644
--- a/docs/news.md
+++ b/docs/news.md
@@ -1,13 +1,13 @@
-@page news Release notes
+# Release notes {#news}
@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
them at runtime with the @ref GLFW_PLATFORM init hint. After initialization the
@@ -15,7 +15,7 @@
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
@ref GLFW_RESIZE_NESW_CURSOR for diagonal resizing, @ref GLFW_RESIZE_ALL_CURSOR
@@ -33,7 +33,7 @@
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)
window hint for making a window transparent to mouse input, lettings events pass
@@ -41,7 +41,7 @@
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
[libdecor](https://gitlab.freedesktop.org/libdecor/libdecor).
@@ -51,13 +51,13 @@
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_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_ANGLE_PLATFORM_TYPE](@ref GLFW_ANGLE_PLATFORM_TYPE_hint) init hint for
@@ -66,7 +66,7 @@
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_CURSOR_CAPTURED cursor mode.
@@ -74,7 +74,7 @@
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
glfwInitAllocator. The allocator is a struct of type @ref GLFWallocator with
@@ -84,7 +84,7 @@
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
specifying the initial position of the window. This removes the need to create a hidden
@@ -92,7 +92,7 @@
`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_WIN32_KEYBOARD_MENU](@ref GLFW_WIN32_KEYBOARD_MENU_hint) window hint for
@@ -101,16 +101,16 @@
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
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.
-@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
may export native access functions for multiple platforms. Starting with version 3.4 you
@@ -119,14 +119,14 @@
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
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.
-@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
around faulty Windows drivers that cause DirectInput to take up to several
@@ -141,7 +141,7 @@
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
`EGL_EXT_present_opaque` extension, the @ref GLFW_ALPHA_BITS window hint will be
@@ -154,7 +154,7 @@
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
a subdirectory of another CMake project. To enable these, set the @ref
@@ -168,37 +168,37 @@
@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
during initialization. Programs that do not want a main menu can disable it
with the [GLFW_COCOA_MENUBAR](@ref GLFW_COCOA_MENUBAR_hint) init hint.
-@subsubsection corevideo_34 CoreVideo dependency has been removed
+#### CoreVideo dependency has been removed {#corevideo_34}
GLFW no longer depends on the CoreVideo framework on macOS and it no longer
needs to be specified during compilation or linking.
-@subsubsection caveat_fbtransparency_34 Framebuffer transparency requires DWM transparency
+#### Framebuffer transparency requires DWM transparency {#caveat_fbtransparency_34}
GLFW no longer supports framebuffer transparency enabled via @ref
GLFW_TRANSPARENT_FRAMEBUFFER on Windows 7 if DWM transparency is off
(the Transparency setting under Personalization > Window Color).
-@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
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
using dynamic loading to get hold of `vkGetInstanceProcAddr` at initialization. This is
@@ -209,7 +209,7 @@
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
always supported. To produce a library binary that only supports this platform, the way
@@ -221,16 +221,16 @@
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
the XDG-Shell protocol. If your Wayland compositor does not support XDG-Shell
then GLFW will fail to initialize.
-@subsection symbols_34 New symbols in version 3.4
+### 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 glfwGetPlatform
@@ -238,7 +238,7 @@
- @ref glfwInitVulkanLoader
-@subsubsection types_34 New types in version 3.4
+#### New types in version 3.4 {#types_34}
- @ref GLFWallocator
- @ref GLFWallocatefun
@@ -246,7 +246,7 @@
- @ref GLFWdeallocatefun
-@subsubsection constants_34 New constants in version 3.4
+#### New constants in version 3.4 {#constants_34}
- @ref GLFW_PLATFORM
- @ref GLFW_ANY_PLATFORM
@@ -289,7 +289,7 @@
- @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.2](https://www.glfw.org/docs/3.2/news.html)
diff --git a/docs/quick.md b/docs/quick.md
index 03688d5..1ac22e5 100644
--- a/docs/quick.md
+++ b/docs/quick.md
@@ -1,4 +1,4 @@
-@page quick_guide Getting started
+# Getting started {#quick_guide}
@tableofcontents
@@ -12,9 +12,9 @@
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
its header file.
@@ -53,7 +53,7 @@
@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
successful initialization, `GLFW_TRUE` is returned. If an error occurred,
@@ -80,7 +80,7 @@
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,
a GLFW window being moved, or an error occurring. Callbacks are C functions (or
@@ -107,7 +107,7 @@
@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
glfwCreateWindow, which returns a handle to the created combined window and
@@ -157,7 +157,7 @@
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.
@@ -179,7 +179,7 @@
@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.
@@ -205,7 +205,7 @@
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
various kinds of events. To receive key press and release events, create a key
@@ -229,7 +229,7 @@
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
tutorial, a multicolored rotating triangle will be rendered. The framebuffer
@@ -256,7 +256,7 @@
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
returns the number of seconds since initialization. The time source used is the
@@ -268,7 +268,7 @@
@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
two rendering buffers; a front buffer and a back buffer. The front buffer is
@@ -302,7 +302,7 @@
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
receive events and to show that the application hasn't locked up. Event
@@ -325,7 +325,7 @@
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
keyboard input, it's possible to create a small program.
diff --git a/docs/vulkan.md b/docs/vulkan.md
index 9208c00..b96e4c6 100644
--- a/docs/vulkan.md
+++ b/docs/vulkan.md
@@ -1,4 +1,4 @@
-@page vulkan_guide Vulkan guide
+# Vulkan guide {#vulkan_guide}
@tableofcontents
@@ -27,7 +27,7 @@
- @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.
@@ -52,7 +52,7 @@
[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
the GLFW header.
@@ -82,7 +82,7 @@
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
section. The canonical desktop loader library exports all Vulkan core and
@@ -106,7 +106,7 @@
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
glfwGetInstanceProcAddress. To load functions needed for instance creation,
@@ -145,7 +145,7 @@
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 use Vulkan to render to a window, you must enable the instance extensions
@@ -194,7 +194,7 @@
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.
To check whether a specific queue family of a physical device supports image
@@ -213,7 +213,7 @@
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,
there is no need to create a context. You can disable context creation with the
@@ -227,7 +227,7 @@
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)
for a GLFW window with @ref glfwCreateWindowSurface.
diff --git a/docs/window.md b/docs/window.md
index 8988371..e3c8f7a 100644
--- a/docs/window.md
+++ b/docs/window.md
@@ -1,4 +1,4 @@
-@page window_guide Window guide
+# Window guide {#window_guide}
@tableofcontents
@@ -13,7 +13,7 @@
- @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
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or
@@ -24,7 +24,7 @@
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
glfwCreateWindow, which returns a handle to the created window object. For
@@ -42,7 +42,7 @@
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
should use. In most cases, the user's primary monitor is a good choice.
@@ -91,7 +91,7 @@
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
mode will not be changed, making window creation faster and application
@@ -123,7 +123,7 @@
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.
@@ -139,7 +139,7 @@
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
context. Some affect the window itself, others affect the framebuffer or
@@ -158,7 +158,7 @@
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
capabilities _exactly_ for window and context creation to succeed. Hints
@@ -177,7 +177,7 @@
- [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
__GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable
@@ -263,7 +263,7 @@
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_GREEN_BITS
@@ -322,7 +322,7 @@
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
__GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen
@@ -330,7 +330,7 @@
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
__GLFW_CLIENT_API__ specifies which client API to create the context for.
@@ -453,7 +453,7 @@
extension.
-@subsubsection window_hints_win32 Win32 specific hints
+#### Win32 specific hints {#window_hints_win32}
@anchor GLFW_WIN32_KEYBOARD_MENU_hint
__GLFW_WIN32_KEYBOARD_MENU__ specifies whether to allow access to the window
@@ -469,7 +469,7 @@
`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
__GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution
@@ -498,7 +498,7 @@
`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_INSTANCE_NAME_hint
@@ -507,7 +507,7 @@
hints need to be set to something other than an empty string for them to take effect.
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
__GLFW_WAYLAND_APP_ID__ specifies the Wayland app_id for a window, used
@@ -515,7 +515,7 @@
@ref glfwWindowHintString.
-@subsubsection window_hints_values Supported and default values
+#### Supported and default values {#window_hints_values}
Window hint | Default value | Supported values
----------------------------- | --------------------------- | ----------------
@@ -568,14 +568,14 @@
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.
-@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
glfwSetWindowUserPointer and queried with @ref glfwGetWindowUserPointer. This
@@ -585,7 +585,7 @@
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
widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
@@ -626,7 +626,7 @@
@endcode
-@subsection window_size Window size
+### Window size {#window_size}
The size of a window can be changed with @ref glfwSetWindowSize. For windowed
mode windows, this sets the size, in
@@ -685,7 +685,7 @@
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
pixels. The size you pass into `glViewport`, for example, should be in pixels.
@@ -723,7 +723,7 @@
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
glfwGetWindowContentScale.
@@ -768,7 +768,7 @@
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
be enforced with @ref glfwSetWindowSizeLimits. The user may resize the window
@@ -814,7 +814,7 @@
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
windows, based on its size and which monitor the user appears to be working on.
@@ -863,7 +863,7 @@
@endcode
-@subsection window_title Window title
+### Window title {#window_title}
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
@@ -890,7 +890,7 @@
@endcode
-@subsection window_icon Window icon
+### Window icon {#window_icon}
Decorated windows have icons on some platforms. You can set this icon by
specifying a list of candidate images with @ref glfwSetWindowIcon.
@@ -914,7 +914,7 @@
@endcode
-@subsection window_monitor Window monitor
+### Window monitor {#window_monitor}
Full screen windows are associated with a specific monitor. You can get the
handle for this monitor with @ref glfwGetWindowMonitor.
@@ -952,7 +952,7 @@
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.
@@ -1003,7 +1003,7 @@
@endcode
-@subsection window_maximize Window maximization
+### Window maximization {#window_maximize}
Windows can be maximized (i.e. zoomed) with @ref glfwMaximizeWindow.
@@ -1059,7 +1059,7 @@
@endcode
-@subsection window_hide Window visibility
+### Window visibility {#window_hide}
Windowed mode windows can be hidden with @ref glfwHideWindow.
@@ -1101,7 +1101,7 @@
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
glfwFocusWindow.
@@ -1152,7 +1152,7 @@
@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
attention with @ref glfwRequestWindowAttention.
@@ -1166,7 +1166,7 @@
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
to be refreshed, set a window refresh callback.
@@ -1191,7 +1191,7 @@
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
and whole window transparency. A single window may not use both methods. The
@@ -1255,7 +1255,7 @@
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
glfwGetWindowAttrib. Some reflect state that may change as a result of user
@@ -1283,7 +1283,7 @@
-@subsubsection window_attribs_wnd Window related attributes
+#### Window related attributes {#window_attribs_wnd}
@anchor GLFW_FOCUSED_attrib
__GLFW_FOCUSED__ indicates whether the specified window has input focus. See
@@ -1351,7 +1351,7 @@
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
__GLFW_CLIENT_API__ indicates the client API provided by the window's context;
@@ -1415,7 +1415,7 @@
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
framebuffer attached to the window) as these can be queried directly with either
@@ -1453,7 +1453,7 @@
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
rendering buffers; a front buffer and a back buffer. The front buffer is
