Convert Doxygen code sections to Markdown

This commit is contained in:
Camilla Löwy 2024-02-13 20:57:45 +01:00
parent 611099f745
commit 1a0bae7fa8
11 changed files with 506 additions and 506 deletions

View File

@ -19,9 +19,9 @@ the documentation for your development environment.
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.
@code{.c} ```c
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
This header defines all the constants and declares all the types and function This header defines all the constants and declares all the types and function
prototypes of the GLFW API. By default, it also includes the OpenGL header from prototypes of the GLFW API. By default, it also includes the OpenGL header from
@ -48,10 +48,10 @@ ES header or extension loader header included before it and will then disable
the inclusion of the default OpenGL header. Most extension loaders also define the inclusion of the default OpenGL header. Most extension loaders also define
macros that disable similar headers below it. macros that disable similar headers below it.
@code{.c} ```c
#include <glad/gl.h> #include <glad/gl.h>
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
Both of these mechanisms depend on the extension loader header defining a known Both of these mechanisms depend on the extension loader header defining a known
macro. If yours doesn't or you don't know which one your users will pick, the macro. If yours doesn't or you don't know which one your users will pick, the
@ -59,11 +59,11 @@ macro. If yours doesn't or you don't know which one your users will pick, the
including the OpenGL header. This will also allow you to include the two including the OpenGL header. This will also allow you to include the two
headers in any order. headers in any order.
@code{.c} ```c
#define GLFW_INCLUDE_NONE #define GLFW_INCLUDE_NONE
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
#include <glad/gl.h> #include <glad/gl.h>
@endcode ```
### GLFW header option macros {#build_macros} ### GLFW header option macros {#build_macros}
@ -186,18 +186,18 @@ built along with your application.
Add the root directory of the GLFW source tree to your project. This will add Add the root directory of the GLFW source tree to your project. This will add
the `glfw` target to your project. the `glfw` target to your project.
@code{.cmake} ```cmake
add_subdirectory(path/to/glfw) add_subdirectory(path/to/glfw)
@endcode ```
Once GLFW has been added, link your application against the `glfw` target. Once GLFW has been added, link your application against the `glfw` target.
This adds the GLFW library and its link-time dependencies as it is currently This adds the GLFW library and its link-time dependencies as it is currently
configured, the include directory for the GLFW header and, when applicable, the configured, the include directory for the GLFW header and, when applicable, the
@ref GLFW_DLL macro. @ref GLFW_DLL macro.
@code{.cmake} ```cmake
target_link_libraries(myapp glfw) target_link_libraries(myapp glfw)
@endcode ```
Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL, Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL,
OpenGL ES or Vulkan libraries it needs at runtime. If your application calls OpenGL ES or Vulkan libraries it needs at runtime. If your application calls
@ -205,16 +205,16 @@ OpenGL directly, instead of using a modern
[extension loader library](@ref context_glext_auto), use the OpenGL CMake [extension loader library](@ref context_glext_auto), use the OpenGL CMake
package. package.
@code{.cmake} ```cmake
find_package(OpenGL REQUIRED) find_package(OpenGL REQUIRED)
@endcode ```
If OpenGL is found, the `OpenGL::GL` target is added to your project, containing If OpenGL is found, the `OpenGL::GL` target is added to your project, containing
library and include directory paths. Link against this like any other library. library and include directory paths. Link against this like any other library.
@code{.cmake} ```cmake
target_link_libraries(myapp OpenGL::GL) target_link_libraries(myapp OpenGL::GL)
@endcode ```
For a minimal example of a program and GLFW sources built with CMake, see the 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.
@ -229,17 +229,17 @@ installed. If you want to build it along with your application instead, see
With a few changes to your `CMakeLists.txt` you can locate the package and With a few changes to your `CMakeLists.txt` you can locate the package and
target files generated when GLFW is installed. target files generated when GLFW is installed.
@code{.cmake} ```cmake
find_package(glfw3 3.4 REQUIRED) find_package(glfw3 3.4 REQUIRED)
@endcode ```
Once GLFW has been added to the project, link against it with the `glfw` target. Once GLFW has been added to the project, link against it with the `glfw` target.
This adds the GLFW library and its link-time dependencies, the include directory This adds the GLFW library and its link-time dependencies, the include directory
for the GLFW header and, when applicable, the @ref GLFW_DLL macro. for the GLFW header and, when applicable, the @ref GLFW_DLL macro.
@code{.cmake} ```cmake
target_link_libraries(myapp glfw) target_link_libraries(myapp glfw)
@endcode ```
Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL, Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL,
OpenGL ES or Vulkan libraries it needs at runtime. If your application calls OpenGL ES or Vulkan libraries it needs at runtime. If your application calls
@ -247,16 +247,16 @@ OpenGL directly, instead of using a modern
[extension loader library](@ref context_glext_auto), use the OpenGL CMake [extension loader library](@ref context_glext_auto), use the OpenGL CMake
package. package.
@code{.cmake} ```cmake
find_package(OpenGL REQUIRED) find_package(OpenGL REQUIRED)
@endcode ```
If OpenGL is found, the `OpenGL::GL` target is added to your project, containing If OpenGL is found, the `OpenGL::GL` target is added to your project, containing
library and include directory paths. Link against this like any other library. library and include directory paths. Link against this like any other library.
@code{.cmake} ```cmake
target_link_libraries(myapp OpenGL::GL) target_link_libraries(myapp OpenGL::GL)
@endcode ```
### With makefiles and pkg-config on Unix {#build_link_pkgconfig} ### With makefiles and pkg-config on Unix {#build_link_pkgconfig}
@ -271,23 +271,23 @@ ones automatically.
A typical compile and link command-line when using the static version of the A typical compile and link command-line when using the static version of the
GLFW library may look like this: GLFW library may look like this:
@code{.sh} ```sh
cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --static --libs glfw3) cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --static --libs glfw3)
@endcode ```
If you are using the shared version of the GLFW library, omit the `--static` If you are using the shared version of the GLFW library, omit the `--static`
flag. flag.
@code{.sh} ```sh
cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3) cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3)
@endcode ```
You can also use the `glfw3.pc` file without installing it first, by using the You can also use the `glfw3.pc` file without installing it first, by using the
`PKG_CONFIG_PATH` environment variable. `PKG_CONFIG_PATH` environment variable.
@code{.sh} ```sh
env PKG_CONFIG_PATH=path/to/glfw/src cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3) env PKG_CONFIG_PATH=path/to/glfw/src cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3)
@endcode ```
The dependencies do not include OpenGL, as GLFW loads any OpenGL, OpenGL ES or The dependencies do not include OpenGL, as GLFW loads any OpenGL, OpenGL ES or
Vulkan libraries it needs at runtime. If your application calls OpenGL Vulkan libraries it needs at runtime. If your application calls OpenGL
@ -295,9 +295,9 @@ directly, instead of using a modern
[extension loader library](@ref context_glext_auto), you should add the `gl` [extension loader library](@ref context_glext_auto), you should add the `gl`
pkg-config package. pkg-config package.
@code{.sh} ```sh
cc $(pkg-config --cflags glfw3 gl) -o myprog myprog.c $(pkg-config --libs glfw3 gl) cc $(pkg-config --cflags glfw3 gl) -o myprog myprog.c $(pkg-config --libs glfw3 gl)
@endcode ```
### With Xcode on macOS {#build_link_xcode} ### With Xcode on macOS {#build_link_xcode}
@ -320,9 +320,9 @@ the `-l` and `-framework` switches.
If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do: If you are using the dynamic GLFW library, which is named `libglfw.3.dylib`, do:
@code{.sh} ```sh
cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit
@endcode ```
If you are using the static library, named `libglfw3.a`, substitute `-lglfw3` If you are using the static library, named `libglfw3.a`, substitute `-lglfw3`
for `-lglfw`. for `-lglfw`.

View File

@ -55,27 +55,27 @@ On Debian and derivatives like Ubuntu and Linux Mint you will need the `libwayla
and `libxkbcommon-dev` packages to compile for Wayland and the `xorg-dev` meta-package to and `libxkbcommon-dev` packages to compile for Wayland and the `xorg-dev` meta-package to
compile for X11. These will pull in all other dependencies. compile for X11. These will pull in all other dependencies.
@code{.sh} ```sh
sudo apt install libwayland-dev libxkbcommon-dev xorg-dev sudo apt install libwayland-dev libxkbcommon-dev xorg-dev
@endcode ```
On Fedora and derivatives like Red Hat you will need the `wayland-devel` and On Fedora and derivatives like Red Hat you will need the `wayland-devel` and
`libxkbcommon-devel` packages to compile for Wayland and the `libXcursor-devel`, `libxkbcommon-devel` packages to compile for Wayland and the `libXcursor-devel`,
`libXi-devel`, `libXinerama-devel` and `libXrandr-devel` packages to compile for X11. `libXi-devel`, `libXinerama-devel` and `libXrandr-devel` packages to compile for X11.
These will pull in all other dependencies. These will pull in all other dependencies.
@code{.sh} ```sh
sudo dnf install wayland-devel libxkbcommon-devel libXcursor-devel libXi-devel libXinerama-devel libXrandr-devel sudo dnf install wayland-devel libxkbcommon-devel libXcursor-devel libXi-devel libXinerama-devel libXrandr-devel
@endcode ```
On FreeBSD you will need the `wayland`, `libxkbcommon` and `evdev-proto` packages to On FreeBSD you will need the `wayland`, `libxkbcommon` and `evdev-proto` packages to
compile for Wayland. The X11 headers are installed along the end-user X11 packages, so if compile for Wayland. The X11 headers are installed along the end-user X11 packages, so if
you have an X server running you should have the headers as well. If not, install the you have an X server running you should have the headers as well. If not, install the
`xorgproto` package to compile for X11. `xorgproto` package to compile for X11.
@code{.sh} ```sh
pkg install wayland libxkbcommon evdev-proto xorgproto pkg install wayland libxkbcommon evdev-proto xorgproto
@endcode ```
On Cygwin Wayland is not supported but you will need the `libXcursor-devel`, On Cygwin Wayland is not supported but you will need the `libXcursor-devel`,
`libXi-devel`, `libXinerama-devel`, `libXrandr-devel` and `libXrender-devel` packages to `libXi-devel`, `libXinerama-devel`, `libXrandr-devel` and `libXrender-devel` packages to
@ -131,33 +131,33 @@ 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
created if it doesn't already exist. created if it doesn't already exist.
@code{.sh} ```sh
cmake -S path/to/glfw -B path/to/build cmake -S path/to/glfw -B path/to/build
@endcode ```
It is common to name the build directory `build` and place it in the root of the It is common to name the build directory `build` and place it in the root of the
source tree when only planning to build a single configuration. source tree when only planning to build a single configuration.
@code{.sh} ```sh
cd path/to/glfw cd path/to/glfw
cmake -S . -B build cmake -S . -B build
@endcode ```
Without other flags these will generate Visual Studio project files on Windows Without other flags these will generate Visual Studio project files on Windows
and makefiles on other platforms. You can choose other targets using the `-G` and makefiles on other platforms. You can choose other targets using the `-G`
flag. flag.
@code{.sh} ```sh
cmake -S path/to/glfw -B path/to/build -G Xcode cmake -S path/to/glfw -B path/to/build -G Xcode
@endcode ```
By default, GLFW will use Wayland and X11 on Linux and other Unix-like systems other than By default, GLFW will use Wayland and X11 on Linux and other Unix-like systems other than
macOS. To disable support for one or both of these, set the @ref GLFW_BUILD_WAYLAND macOS. To disable support for one or both of these, set the @ref GLFW_BUILD_WAYLAND
and/or @ref GLFW_BUILD_X11 CMake option. and/or @ref GLFW_BUILD_X11 CMake option.
@code{.sh} ```sh
cmake -S path/to/glfw -B path/to/build -D GLFW_BUILD_X11=0 cmake -S path/to/glfw -B path/to/build -D GLFW_BUILD_X11=0
@endcode ```
Once you have generated the project files or makefiles for your chosen 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.
@ -174,24 +174,24 @@ With Visual Studio open `GLFW.sln` and use the Build menu. With Xcode open
With Linux, macOS and other forms of Unix, run `make`. With Linux, macOS and other forms of Unix, run `make`.
@code{.sh} ```sh
cd path/to/build cd path/to/build
make make
@endcode ```
With MinGW, it is `mingw32-make`. With MinGW, it is `mingw32-make`.
@code{.sh} ```sh
cd path/to/build cd path/to/build
mingw32-make mingw32-make
@endcode ```
Any CMake build directory can also be built with the `cmake` command and the Any CMake build directory can also be built with the `cmake` command and the
`--build` flag. `--build` flag.
@code{.sh} ```sh
cmake --build path/to/build cmake --build path/to/build
@endcode ```
This will run the platform specific build tool the directory was generated for. This will run the platform specific build tool the directory was generated for.
@ -214,9 +214,9 @@ distributions based on Debian GNU/Linux have this tool in a separate
Finally, if you don't want to use any GUI, you can set options from the `cmake` Finally, if you don't want to use any GUI, you can set options from the `cmake`
command-line with the `-D` flag. command-line with the `-D` flag.
@code{.sh} ```sh
cmake -S path/to/glfw -B path/to/build -D BUILD_SHARED_LIBS=ON cmake -S path/to/glfw -B path/to/build -D BUILD_SHARED_LIBS=ON
@endcode ```
### Shared CMake options {#compile_options_shared} ### Shared CMake options {#compile_options_shared}
@ -309,9 +309,9 @@ cross-compilation of Windows binaries. To use these files you set the
`CMAKE_TOOLCHAIN_FILE` CMake variable with the `-D` flag add an option when `CMAKE_TOOLCHAIN_FILE` CMake variable with the `-D` flag add an option when
configuring and generating the build files. configuring and generating the build files.
@code{.sh} ```sh
cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=path/to/file cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=path/to/file
@endcode ```
The exact toolchain file to use depends on the prefix used by the MinGW or The exact toolchain file to use depends on the prefix used by the MinGW or
MinGW-w64 binaries on your system. You can usually see this in the /usr MinGW-w64 binaries on your system. You can usually see this in the /usr
@ -319,9 +319,9 @@ directory. For example, both the Ubuntu and Cygwin MinGW-w64 packages have
`/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct invocation `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct invocation
would be: would be:
@code{.sh} ```sh
cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake cmake -S path/to/glfw -B path/to/build -D CMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake
@endcode ```
The path to the toolchain file is relative to the path to the GLFW source tree The path to the toolchain file is relative to the path to the GLFW source tree
passed to the `-S` flag, not to the current directory. passed to the `-S` flag, not to the current directory.

View File

@ -45,9 +45,9 @@ 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
should share its objects (textures, vertex and element buffers, etc.) with. should share its objects (textures, vertex and element buffers, etc.) with.
@code{.c} ```c
GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window); GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window);
@endcode ```
Object sharing is implemented by the operating system and graphics driver. On Object sharing is implemented by the operating system and graphics driver. On
platforms where it is possible to choose which types of objects are shared, GLFW platforms where it is possible to choose which types of objects are shared, GLFW
@ -68,11 +68,11 @@ 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
[GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint. [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint.
@code{.c} ```c
glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE); glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL); GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL);
@endcode ```
The window never needs to be shown and its context can be used as a plain The window never needs to be shown and its context can be used as a plain
offscreen context. Depending on the window manager, the size of a hidden offscreen context. Depending on the window manager, the size of a hidden
@ -103,15 +103,15 @@ thread before making it current on the new one.
The context of a window is made current with @ref glfwMakeContextCurrent. The context of a window is made current with @ref glfwMakeContextCurrent.
@code{.c} ```c
glfwMakeContextCurrent(window); glfwMakeContextCurrent(window);
@endcode ```
The window of the current context is returned by @ref glfwGetCurrentContext. The window of the current context is returned by @ref glfwGetCurrentContext.
@code{.c} ```c
GLFWwindow* window = glfwGetCurrentContext(); GLFWwindow* window = glfwGetCurrentContext();
@endcode ```
The following GLFW functions require a context to be current. Calling any these The following GLFW functions require a context to be current. Calling any these
functions without a current context will generate a @ref GLFW_NO_CURRENT_CONTEXT functions without a current context will generate a @ref GLFW_NO_CURRENT_CONTEXT
@ -167,9 +167,9 @@ both GLFW and glad, but loaders for OpenGL ES, as well as loaders for specific
API versions and extension sets can be generated. The generated files are API versions and extension sets can be generated. The generated files are
written to the `output` directory. written to the `output` directory.
@code{.sh} ```sh
python main.py --generator c --no-loader --out-path output python main.py --generator c --no-loader --out-path output
@endcode ```
The `--no-loader` option is added because GLFW already provides a function for The `--no-loader` option is added because GLFW already provides a function for
loading OpenGL and OpenGL ES function pointers, one that automatically uses the loading OpenGL and OpenGL ES function pointers, one that automatically uses the
@ -183,14 +183,14 @@ include the glad header file, which will replace the OpenGL header of your
development environment. By including the glad header before the GLFW header, development environment. By including the glad header before the GLFW header,
it suppresses the development environment's OpenGL or OpenGL ES header. it suppresses the development environment's OpenGL or OpenGL ES header.
@code{.c} ```c
#include <glad/glad.h> #include <glad/glad.h>
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
Finally, you need to initialize glad once you have a suitable current context. Finally, you need to initialize glad once you have a suitable current context.
@code{.c} ```c
window = glfwCreateWindow(640, 480, "My Window", NULL, NULL); window = glfwCreateWindow(640, 480, "My Window", NULL, NULL);
if (!window) if (!window)
{ {
@ -200,7 +200,7 @@ if (!window)
glfwMakeContextCurrent(window); glfwMakeContextCurrent(window);
gladLoadGLLoader((GLADloadproc) glfwGetProcAddress); gladLoadGLLoader((GLADloadproc) glfwGetProcAddress);
@endcode ```
Once glad has been loaded, you have access to all OpenGL core and extension Once glad has been loaded, you have access to all OpenGL core and extension
functions supported by both the context you created and the glad loader you functions supported by both the context you created and the glad loader you
@ -213,22 +213,22 @@ check the actual OpenGL or OpenGL ES version with
a specific version is supported by the current context with the a specific version is supported by the current context with the
`GLAD_GL_VERSION_x_x` booleans. `GLAD_GL_VERSION_x_x` booleans.
@code{.c} ```c
if (GLAD_GL_VERSION_3_2) if (GLAD_GL_VERSION_3_2)
{ {
// Call OpenGL 3.2+ specific code // Call OpenGL 3.2+ specific code
} }
@endcode ```
To check whether a specific extension is supported, use the `GLAD_GL_xxx` To check whether a specific extension is supported, use the `GLAD_GL_xxx`
booleans. booleans.
@code{.c} ```c
if (GLAD_GL_ARB_gl_spirv) if (GLAD_GL_ARB_gl_spirv)
{ {
// Use GL_ARB_gl_spirv // Use GL_ARB_gl_spirv
} }
@endcode ```
### Loading extensions manually {#context_glext_manual} ### Loading extensions manually {#context_glext_manual}
@ -265,10 +265,10 @@ to function) and `PROC` (procedure) are added to the ends.
To include the extension header, define @ref GLFW_INCLUDE_GLEXT before including To include the extension header, define @ref GLFW_INCLUDE_GLEXT before including
the GLFW header. the GLFW header.
@code{.c} ```c
#define GLFW_INCLUDE_GLEXT #define GLFW_INCLUDE_GLEXT
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
#### Checking for extensions {#context_glext_string} #### Checking for extensions {#context_glext_string}
@ -278,12 +278,12 @@ drivers or a graphics card that lacks the necessary hardware features), so it
is necessary to check at run-time whether the context supports the extension. is necessary to check at run-time whether the context supports the extension.
This is done with @ref glfwExtensionSupported. This is done with @ref glfwExtensionSupported.
@code{.c} ```c
if (glfwExtensionSupported("GL_ARB_gl_spirv")) if (glfwExtensionSupported("GL_ARB_gl_spirv"))
{ {
// The extension is supported by the current context // The extension is supported by the current context
} }
@endcode ```
The argument is a null terminated ASCII string with the extension name. If the The argument is a null terminated ASCII string with the extension name. If the
extension is supported, @ref glfwExtensionSupported returns `GLFW_TRUE`, extension is supported, @ref glfwExtensionSupported returns `GLFW_TRUE`,
@ -297,9 +297,9 @@ These functions often do not have entry points in the client API libraries of
your operating system, making it necessary to fetch them at run time. You can your operating system, making it necessary to fetch them at run time. You can
retrieve pointers to these functions with @ref glfwGetProcAddress. retrieve pointers to these functions with @ref glfwGetProcAddress.
@code{.c} ```c
PFNGLSPECIALIZESHADERARBPROC pfnSpecializeShaderARB = glfwGetProcAddress("glSpecializeShaderARB"); PFNGLSPECIALIZESHADERARBPROC pfnSpecializeShaderARB = glfwGetProcAddress("glSpecializeShaderARB");
@endcode ```
In general, you should avoid giving the function pointer variables the (exact) In general, you should avoid giving the function pointer variables the (exact)
same name as the function, as this may confuse your linker. Instead, you can same name as the function, as this may confuse your linker. Instead, you can
@ -308,7 +308,7 @@ use a different prefix, like above, or some other naming scheme.
Now that all the pieces have been introduced, here is what they might look like Now that all the pieces have been introduced, here is what they might look like
when used together. when used together.
@code{.c} ```c
#define GLFW_INCLUDE_GLEXT #define GLFW_INCLUDE_GLEXT
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@ -336,5 +336,5 @@ void some_function(void)
glSpecializeShaderARB(...); glSpecializeShaderARB(...);
} }
} }
@endcode ```

View File

@ -40,18 +40,18 @@ There are three functions for processing pending events. @ref glfwPollEvents,
processes only those events that have already been received and then returns processes only those events that have already been received and then returns
immediately. immediately.
@code{.c} ```c
glfwPollEvents(); glfwPollEvents();
@endcode ```
This is the best choice when rendering continuously, like most games do. This is the best choice when rendering continuously, like most games do.
If you only need to update the contents of the window when you receive new If you only need to update the contents of the window when you receive new
input, @ref glfwWaitEvents is a better choice. input, @ref glfwWaitEvents is a better choice.
@code{.c} ```c
glfwWaitEvents(); glfwWaitEvents();
@endcode ```
It puts the thread to sleep until at least one event has been received and then It puts the thread to sleep until at least one event has been received and then
processes all received events. This saves a great deal of CPU cycles and is processes all received events. This saves a great deal of CPU cycles and is
@ -60,9 +60,9 @@ useful for, for example, editing tools.
If you want to wait for events but have UI elements or other tasks that need If you want to wait for events but have UI elements or other tasks that need
periodic updates, @ref glfwWaitEventsTimeout lets you specify a timeout. periodic updates, @ref glfwWaitEventsTimeout lets you specify a timeout.
@code{.c} ```c
glfwWaitEventsTimeout(0.7); glfwWaitEventsTimeout(0.7);
@endcode ```
It puts the thread to sleep until at least one event has been received, or until It puts the thread to sleep until at least one event has been received, or until
the specified number of seconds have elapsed. It then processes any received the specified number of seconds have elapsed. It then processes any received
@ -72,9 +72,9 @@ If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from
another thread by posting an empty event to the event queue with @ref another thread by posting an empty event to the event queue with @ref
glfwPostEmptyEvent. glfwPostEmptyEvent.
@code{.c} ```c
glfwPostEmptyEvent(); glfwPostEmptyEvent();
@endcode ```
Do not assume that callbacks will _only_ be called in response to the above Do not assume that callbacks will _only_ be called in response to the above
functions. While it is necessary to process events in one or more of the ways functions. While it is necessary to process events in one or more of the ways
@ -106,20 +106,20 @@ same keyboard layout, input method or even operating system as you.
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.
@code{.c} ```c
glfwSetKeyCallback(window, key_callback); glfwSetKeyCallback(window, key_callback);
@endcode ```
The callback function receives the [keyboard key](@ref keys), platform-specific The callback function receives the [keyboard key](@ref keys), platform-specific
scancode, key action and [modifier bits](@ref mods). scancode, key action and [modifier bits](@ref mods).
@code{.c} ```c
void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
{ {
if (key == GLFW_KEY_E && action == GLFW_PRESS) if (key == GLFW_KEY_E && action == GLFW_PRESS)
activate_airship(); activate_airship();
} }
@endcode ```
The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. Events with The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. Events with
`GLFW_PRESS` and `GLFW_RELEASE` actions are emitted for every key press. Most `GLFW_PRESS` and `GLFW_RELEASE` actions are emitted for every key press. Most
@ -147,21 +147,21 @@ different scancodes depending on the platform but they are safe to save to disk.
You can query the scancode for any [key token](@ref keys) supported on the You can query the scancode for any [key token](@ref keys) supported on the
current platform with @ref glfwGetKeyScancode. current platform with @ref glfwGetKeyScancode.
@code{.c} ```c
const int scancode = glfwGetKeyScancode(GLFW_KEY_X); const int scancode = glfwGetKeyScancode(GLFW_KEY_X);
set_key_mapping(scancode, swap_weapons); set_key_mapping(scancode, swap_weapons);
@endcode ```
The last reported state for every physical key with a [key token](@ref keys) is The last reported state for every physical key with a [key token](@ref keys) is
also saved in per-window state arrays that can be polled with @ref glfwGetKey. also saved in per-window state arrays that can be polled with @ref glfwGetKey.
@code{.c} ```c
int state = glfwGetKey(window, GLFW_KEY_E); int state = glfwGetKey(window, GLFW_KEY_E);
if (state == GLFW_PRESS) if (state == GLFW_PRESS)
{ {
activate_airship(); activate_airship();
} }
@endcode ```
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
@ -175,9 +175,9 @@ If a pressed key is released again before you poll its state, you will have
missed the key press. The recommended solution for this is to use a missed the key press. The recommended solution for this is to use a
key callback, but there is also the `GLFW_STICKY_KEYS` input mode. key callback, but there is also the `GLFW_STICKY_KEYS` input mode.
@code{.c} ```c
glfwSetInputMode(window, GLFW_STICKY_KEYS, GLFW_TRUE); glfwSetInputMode(window, GLFW_STICKY_KEYS, GLFW_TRUE);
@endcode ```
When sticky keys mode is enabled, the pollable state of a key will remain When sticky keys mode is enabled, the pollable state of a key will remain
`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey. Once `GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey. Once
@ -188,9 +188,9 @@ the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`.
If you wish to know what the state of the Caps Lock and Num Lock keys was when If you wish to know what the state of the Caps Lock and Num Lock keys was when
input events were generated, set the `GLFW_LOCK_KEY_MODS` input mode. input events were generated, set the `GLFW_LOCK_KEY_MODS` input mode.
@code{.c} ```c
glfwSetInputMode(window, GLFW_LOCK_KEY_MODS, GLFW_TRUE); glfwSetInputMode(window, GLFW_LOCK_KEY_MODS, GLFW_TRUE);
@endcode ```
When this input mode is enabled, any callback that receives When this input mode is enabled, any callback that receives
[modifier bits](@ref mods) will have the @ref GLFW_MOD_CAPS_LOCK bit set if Caps [modifier bits](@ref mods) will have the @ref GLFW_MOD_CAPS_LOCK bit set if Caps
@ -215,19 +215,19 @@ you can treat the code point argument as native endian UTF-32.
If you wish to offer regular text input, set a character callback. If you wish to offer regular text input, set a character callback.
@code{.c} ```c
glfwSetCharCallback(window, character_callback); glfwSetCharCallback(window, character_callback);
@endcode ```
The callback function receives Unicode code points for key events that would The callback function receives Unicode code points for key events that would
have led to regular text input and generally behaves as a standard text field on have led to regular text input and generally behaves as a standard text field on
that platform. that platform.
@code{.c} ```c
void character_callback(GLFWwindow* window, unsigned int codepoint) void character_callback(GLFWwindow* window, unsigned int codepoint)
{ {
} }
@endcode ```
### Key names {#input_key_name} ### Key names {#input_key_name}
@ -235,10 +235,10 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
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.
@code{.c} ```c
const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0); const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0);
show_tutorial_hint("Press %s to move forward", key_name); show_tutorial_hint("Press %s to move forward", key_name);
@endcode ```
This function can handle both [keys and scancodes](@ref input_key). If the This function can handle both [keys and scancodes](@ref input_key). If the
specified key is `GLFW_KEY_UNKNOWN` then the scancode is used, otherwise it is specified key is `GLFW_KEY_UNKNOWN` then the scancode is used, otherwise it is
@ -258,27 +258,27 @@ a custom image or a standard cursor shape from the system theme.
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.
@code{.c} ```c
glfwSetCursorPosCallback(window, cursor_position_callback); glfwSetCursorPosCallback(window, cursor_position_callback);
@endcode ```
The callback functions receives the cursor position, measured in screen The callback functions receives the cursor position, measured in screen
coordinates but relative to the top-left corner of the window content area. On coordinates but relative to the top-left corner of the window content area. On
platforms that provide it, the full sub-pixel cursor position is passed on. platforms that provide it, the full sub-pixel cursor position is passed on.
@code{.c} ```c
static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos) static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos)
{ {
} }
@endcode ```
The cursor position is also saved per-window and can be polled with @ref The cursor position is also saved per-window and can be polled with @ref
glfwGetCursorPos. glfwGetCursorPos.
@code{.c} ```c
double xpos, ypos; double xpos, ypos;
glfwGetCursorPos(window, &xpos, &ypos); glfwGetCursorPos(window, &xpos, &ypos);
@endcode ```
### Cursor mode {#cursor_mode} ### Cursor mode {#cursor_mode}
@ -293,9 +293,9 @@ If you wish to implement mouse motion based camera controls or other input
schemes that require unlimited mouse movement, set the cursor mode to schemes that require unlimited mouse movement, set the cursor mode to
`GLFW_CURSOR_DISABLED`. `GLFW_CURSOR_DISABLED`.
@code{.c} ```c
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED); glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED);
@endcode ```
This will hide the cursor and lock it to the specified window. GLFW will then This will hide the cursor and lock it to the specified window. GLFW will then
take care of all the details of cursor re-centering and offset calculation and take care of all the details of cursor re-centering and offset calculation and
@ -309,18 +309,18 @@ other features of GLFW. It is not supported and will not work as robustly as
If you only wish the cursor to become hidden when it is over a window but still If you only wish the cursor to become hidden when it is over a window but still
want it to behave normally, set the cursor mode to `GLFW_CURSOR_HIDDEN`. want it to behave normally, set the cursor mode to `GLFW_CURSOR_HIDDEN`.
@code{.c} ```c
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN); glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN);
@endcode ```
This mode puts no limit on the motion of the cursor. This mode puts no limit on the motion of the cursor.
If you wish the cursor to be visible but confined to the content area of the If you wish the cursor to be visible but confined to the content area of the
window, set the cursor mode to `GLFW_CURSOR_CAPTURED`. window, set the cursor mode to `GLFW_CURSOR_CAPTURED`.
@code{.c} ```c
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_CAPTURED); glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_CAPTURED);
@endcode ```
The cursor will behave normally inside the content area but will not be able to The cursor will behave normally inside the content area but will not be able to
leave unless the window loses focus. leave unless the window loses focus.
@ -328,9 +328,9 @@ leave unless the window loses focus.
To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL` To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL`
cursor mode. cursor mode.
@code{.c} ```c
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL); glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL);
@endcode ```
If the cursor was disabled, this will move it back to its last visible position. If the cursor was disabled, this will move it back to its last visible position.
@ -351,10 +351,10 @@ Call @ref glfwRawMouseMotionSupported to check if the current machine provides
raw motion and set the `GLFW_RAW_MOUSE_MOTION` input mode to enable it. It is raw motion and set the `GLFW_RAW_MOUSE_MOTION` input mode to enable it. It is
disabled by default. disabled by default.
@code{.c} ```c
if (glfwRawMouseMotionSupported()) if (glfwRawMouseMotionSupported())
glfwSetInputMode(window, GLFW_RAW_MOUSE_MOTION, GLFW_TRUE); glfwSetInputMode(window, GLFW_RAW_MOUSE_MOTION, GLFW_TRUE);
@endcode ```
If supported, raw mouse motion can be enabled or disabled per-window and at any 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.
@ -374,7 +374,7 @@ 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
cursor with the hot-spot in the upper-left corner: cursor with the hot-spot in the upper-left corner:
@code{.c} ```c
unsigned char pixels[16 * 16 * 4]; unsigned char pixels[16 * 16 * 4];
memset(pixels, 0xff, sizeof(pixels)); memset(pixels, 0xff, sizeof(pixels));
@ -384,7 +384,7 @@ image.height = 16;
image.pixels = pixels; image.pixels = pixels;
GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0); GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
@endcode ```
If cursor creation fails, `NULL` will be returned, so it is necessary to check If cursor creation fails, `NULL` will be returned, so it is necessary to check
the return value. the return value.
@ -399,9 +399,9 @@ sequential rows, starting from the top-left corner.
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.
@code{.c} ```c
GLFWcursor* url_cursor = glfwCreateStandardCursor(GLFW_POINTING_HAND_CURSOR); GLFWcursor* url_cursor = glfwCreateStandardCursor(GLFW_POINTING_HAND_CURSOR);
@endcode ```
These cursor objects behave in the exact same way as those created with @ref These cursor objects behave in the exact same way as those created with @ref
glfwCreateCursor except that the system cursor theme provides the actual image. glfwCreateCursor except that the system cursor theme provides the actual image.
@ -414,9 +414,9 @@ A few of these shapes are not available everywhere. If a shape is unavailable,
When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor. When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
@code{.c} ```c
glfwDestroyCursor(cursor); glfwDestroyCursor(cursor);
@endcode ```
Cursor destruction always succeeds. If the cursor is current for any window, Cursor destruction always succeeds. If the cursor is current for any window,
that window will revert to the default cursor. This does not affect the cursor that window will revert to the default cursor. This does not affect the cursor
@ -427,9 +427,9 @@ mode. All remaining cursors are destroyed when @ref glfwTerminate is called.
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.
@code{.c} ```c
glfwSetCursor(window, cursor); glfwSetCursor(window, cursor);
@endcode ```
Once set, the cursor image will be used as long as the system cursor is over the Once set, the cursor image will be used as long as the system cursor is over the
content area of the window and the [cursor mode](@ref cursor_mode) is set content area of the window and the [cursor mode](@ref cursor_mode) is set
@ -439,9 +439,9 @@ A single cursor may be set for any number of windows.
To revert to the default cursor, set the cursor of that window to `NULL`. To revert to the default cursor, set the cursor of that window to `NULL`.
@code{.c} ```c
glfwSetCursor(window, NULL); glfwSetCursor(window, NULL);
@endcode ```
When a cursor is destroyed, any window that has it set will revert to the 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.
@ -452,13 +452,13 @@ default cursor. This does not affect the cursor mode.
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.
@code{.c} ```c
glfwSetCursorEnterCallback(window, cursor_enter_callback); glfwSetCursorEnterCallback(window, cursor_enter_callback);
@endcode ```
The callback function receives the new classification of the cursor. The callback function receives the new classification of the cursor.
@code{.c} ```c
void cursor_enter_callback(GLFWwindow* window, int entered) void cursor_enter_callback(GLFWwindow* window, int entered)
{ {
if (entered) if (entered)
@ -470,17 +470,17 @@ void cursor_enter_callback(GLFWwindow* window, int entered)
// The cursor left the content area of the window // The cursor left the content area of the window
} }
} }
@endcode ```
You can query whether the cursor is currently inside the content area of the You can query whether the cursor is currently inside the content area of the
window with the [GLFW_HOVERED](@ref GLFW_HOVERED_attrib) window attribute. window with the [GLFW_HOVERED](@ref GLFW_HOVERED_attrib) window attribute.
@code{.c} ```c
if (glfwGetWindowAttrib(window, GLFW_HOVERED)) if (glfwGetWindowAttrib(window, GLFW_HOVERED))
{ {
highlight_interface(); highlight_interface();
} }
@endcode ```
### Mouse button input {#input_mouse_button} ### Mouse button input {#input_mouse_button}
@ -488,20 +488,20 @@ if (glfwGetWindowAttrib(window, GLFW_HOVERED))
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.
@code{.c} ```c
glfwSetMouseButtonCallback(window, mouse_button_callback); glfwSetMouseButtonCallback(window, mouse_button_callback);
@endcode ```
The callback function receives the [mouse button](@ref buttons), button action The callback function receives the [mouse button](@ref buttons), button action
and [modifier bits](@ref mods). and [modifier bits](@ref mods).
@code{.c} ```c
void mouse_button_callback(GLFWwindow* window, int button, int action, int mods) void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
{ {
if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS) if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)
popup_menu(); popup_menu();
} }
@endcode ```
The action is one of `GLFW_PRESS` or `GLFW_RELEASE`. The action is one of `GLFW_PRESS` or `GLFW_RELEASE`.
@ -509,13 +509,13 @@ The last reported state for every [supported mouse button](@ref buttons) is also
saved in per-window state arrays that can be polled with @ref saved in per-window state arrays that can be polled with @ref
glfwGetMouseButton. glfwGetMouseButton.
@code{.c} ```c
int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT); int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
if (state == GLFW_PRESS) if (state == GLFW_PRESS)
{ {
upgrade_cow(); upgrade_cow();
} }
@endcode ```
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`. The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
@ -529,9 +529,9 @@ missed the button press. The recommended solution for this is to use a
mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS` mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS`
input mode. input mode.
@code{.c} ```c
glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, GLFW_TRUE); glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, GLFW_TRUE);
@endcode ```
When sticky mouse buttons mode is enabled, the pollable state of a mouse button When sticky mouse buttons mode is enabled, the pollable state of a mouse button
will remain `GLFW_PRESS` until the state of that button is polled with @ref will remain `GLFW_PRESS` until the state of that button is polled with @ref
@ -548,17 +548,17 @@ The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
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.
@code{.c} ```c
glfwSetScrollCallback(window, scroll_callback); glfwSetScrollCallback(window, scroll_callback);
@endcode ```
The callback function receives two-dimensional scroll offsets. The callback function receives two-dimensional scroll offsets.
@code{.c} ```c
void scroll_callback(GLFWwindow* window, double xoffset, double yoffset) void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
{ {
} }
@endcode ```
A normal mouse wheel, being vertical, provides offsets along the Y-axis. A normal mouse wheel, being vertical, provides offsets along the Y-axis.
@ -571,9 +571,9 @@ referred to as joysticks. It supports up to sixteen joysticks, ranging from
`GLFW_JOYSTICK_LAST`. You can test whether a [joystick](@ref joysticks) is `GLFW_JOYSTICK_LAST`. You can test whether a [joystick](@ref joysticks) is
present with @ref glfwJoystickPresent. present with @ref glfwJoystickPresent.
@code{.c} ```c
int present = glfwJoystickPresent(GLFW_JOYSTICK_1); int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
@endcode ```
Each joystick has zero or more axes, zero or more buttons, zero or more hats, Each joystick has zero or more axes, zero or more buttons, zero or more hats,
a human-readable name, a user pointer and an SDL compatible GUID. a human-readable name, a user pointer and an SDL compatible GUID.
@ -599,10 +599,10 @@ 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
returned array. returned array.
@code{.c} ```c
int count; int count;
const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_5, &count); const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_5, &count);
@endcode ```
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.
@ -613,10 +613,10 @@ 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
returned array. returned array.
@code{.c} ```c
int count; int count;
const unsigned char* buttons = glfwGetJoystickButtons(GLFW_JOYSTICK_3, &count); const unsigned char* buttons = glfwGetJoystickButtons(GLFW_JOYSTICK_3, &count);
@endcode ```
Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`. Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`.
@ -630,10 +630,10 @@ the reference documentation for @ref glfwGetJoystickButtons for details.
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.
@code{.c} ```c
int count; int count;
const unsigned char* hats = glfwGetJoystickHats(GLFW_JOYSTICK_7, &count); const unsigned char* hats = glfwGetJoystickHats(GLFW_JOYSTICK_7, &count);
@endcode ```
Each element in the returned array is one of the following: Each element in the returned array is one of the following:
@ -653,12 +653,12 @@ The diagonal directions are bitwise combinations of the primary (up, right, down
and left) directions and you can test for these individually by ANDing it with and left) directions and you can test for these individually by ANDing it with
the corresponding direction. the corresponding direction.
@code{.c} ```c
if (hats[2] & GLFW_HAT_RIGHT) if (hats[2] & GLFW_HAT_RIGHT)
{ {
// State of hat 2 could be right-up, right or right-down // State of hat 2 could be right-up, right or right-down
} }
@endcode ```
For backward compatibility with earlier versions that did not have @ref For backward compatibility with earlier versions that did not have @ref
glfwGetJoystickHats, all hats are by default also included in the button array. glfwGetJoystickHats, all hats are by default also included in the button array.
@ -671,9 +671,9 @@ 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
returned string. returned string.
@code{.c} ```c
const char* name = glfwGetJoystickName(GLFW_JOYSTICK_4); const char* name = glfwGetJoystickName(GLFW_JOYSTICK_4);
@endcode ```
Joystick names are not guaranteed to be unique. Two joysticks of the same model Joystick names are not guaranteed to be unique. Two joysticks of the same model
and make may have the same name. Only the [joystick ID](@ref joysticks) is and make may have the same name. Only the [joystick ID](@ref joysticks) is
@ -696,14 +696,14 @@ The initial value of the pointer is `NULL`.
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.
@code{.c} ```c
glfwSetJoystickCallback(joystick_callback); glfwSetJoystickCallback(joystick_callback);
@endcode ```
The callback function receives the ID of the joystick that has been connected The callback function receives the ID of the joystick that has been connected
and disconnected and the event that occurred. and disconnected and the event that occurred.
@code{.c} ```c
void joystick_callback(int jid, int event) void joystick_callback(int jid, int event)
{ {
if (event == GLFW_CONNECTED) if (event == GLFW_CONNECTED)
@ -715,7 +715,7 @@ void joystick_callback(int jid, int event)
// The joystick was disconnected // The joystick was disconnected
} }
} }
@endcode ```
For joystick connection and disconnection events to be delivered on all For joystick connection and disconnection events to be delivered on all
platforms, you need to call one of the [event processing](@ref events) platforms, you need to call one of the [event processing](@ref events)
@ -746,12 +746,12 @@ a joystick is connected or the mappings are updated.
You can check whether a joystick is both present and has a gamepad mapping with You can check whether a joystick is both present and has a gamepad mapping with
@ref glfwJoystickIsGamepad. @ref glfwJoystickIsGamepad.
@code{.c} ```c
if (glfwJoystickIsGamepad(GLFW_JOYSTICK_2)) if (glfwJoystickIsGamepad(GLFW_JOYSTICK_2))
{ {
// Use as gamepad // Use as gamepad
} }
@endcode ```
If you are only interested in gamepad input you can use this function instead of If you are only interested in gamepad input you can use this function instead of
@ref glfwJoystickPresent. @ref glfwJoystickPresent.
@ -760,13 +760,13 @@ You can query the human-readable name provided by the gamepad mapping with @ref
glfwGetGamepadName. This may or may not be the same as the glfwGetGamepadName. This may or may not be the same as the
[joystick name](@ref joystick_name). [joystick name](@ref joystick_name).
@code{.c} ```c
const char* name = glfwGetGamepadName(GLFW_JOYSTICK_7); const char* name = glfwGetGamepadName(GLFW_JOYSTICK_7);
@endcode ```
To retrieve the gamepad state of a joystick, call @ref glfwGetGamepadState. To retrieve the gamepad state of a joystick, call @ref glfwGetGamepadState.
@code{.c} ```c
GLFWgamepadstate state; GLFWgamepadstate state;
if (glfwGetGamepadState(GLFW_JOYSTICK_3, &state)) if (glfwGetGamepadState(GLFW_JOYSTICK_3, &state))
@ -778,7 +778,7 @@ if (glfwGetGamepadState(GLFW_JOYSTICK_3, &state))
input_speed(state.axes[GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER]); input_speed(state.axes[GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER]);
} }
@endcode ```
The @ref GLFWgamepadstate struct has two arrays; one for button states and one The @ref GLFWgamepadstate struct has two arrays; one for button states and one
for axis states. The values for each button and axis are the same as for the for axis states. The values for each button and axis are the same as for the
@ -816,11 +816,11 @@ GLFW contains a copy of the mappings available in
time of release. Newer ones can be added at runtime with @ref time of release. Newer ones can be added at runtime with @ref
glfwUpdateGamepadMappings. glfwUpdateGamepadMappings.
@code{.c} ```c
const char* mappings = load_file_contents("game/data/gamecontrollerdb.txt"); const char* mappings = load_file_contents("game/data/gamecontrollerdb.txt");
glfwUpdateGamepadMappings(mappings); glfwUpdateGamepadMappings(mappings);
@endcode ```
This function supports everything from single lines up to and including the This function supports everything from single lines up to and including the
unmodified contents of the whole `gamecontrollerdb.txt` file. unmodified contents of the whole `gamecontrollerdb.txt` file.
@ -880,12 +880,12 @@ one built into GLFW for Xbox controllers accessed via the XInput API on Windows.
This example has been broken into several lines to fit on the page, but real This example has been broken into several lines to fit on the page, but real
gamepad mappings must be a single line. gamepad mappings must be a single line.
@code{.unparsed} ```
78696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0, 78696e70757401000000000000000000,XInput Gamepad (GLFW),platform:Windows,a:b0,
b:b1,x:b2,y:b3,leftshoulder:b4,rightshoulder:b5,back:b6,start:b7,leftstick:b8, b:b1,x:b2,y:b3,leftshoulder:b4,rightshoulder:b5,back:b6,start:b7,leftstick:b8,
rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4, rightstick:b9,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:a4,
righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8, righttrigger:a5,dpup:h0.1,dpright:h0.2,dpdown:h0.4,dpleft:h0.8,
@endcode ```
@note GLFW does not yet support the output range and modifiers `+` and `-` that @note GLFW does not yet support the output range and modifiers `+` and `-` that
were recently added to SDL. The input modifiers `+`, `-` and `~` are supported were recently added to SDL. The input modifiers `+`, `-` and `~` are supported
@ -896,9 +896,9 @@ and described above.
GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime. GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
@code{.c} ```c
double seconds = glfwGetTime(); double seconds = glfwGetTime();
@endcode ```
It returns the number of seconds since the library was initialized with @ref It returns the number of seconds since the library was initialized with @ref
glfwInit. The platform-specific time sources used typically have micro- or glfwInit. The platform-specific time sources used typically have micro- or
@ -906,9 +906,9 @@ nanosecond resolution.
You can modify the base time with @ref glfwSetTime. You can modify the base time with @ref glfwSetTime.
@code{.c} ```c
glfwSetTime(4.0); glfwSetTime(4.0);
@endcode ```
This sets the time to the specified time, in seconds, and it continues to count This sets the time to the specified time, in seconds, and it continues to count
from there. from there.
@ -916,17 +916,17 @@ from there.
You can also access the raw timer used to implement the functions above, You can also access the raw timer used to implement the functions above,
with @ref glfwGetTimerValue. with @ref glfwGetTimerValue.
@code{.c} ```c
uint64_t value = glfwGetTimerValue(); uint64_t value = glfwGetTimerValue();
@endcode ```
This value is in 1&nbsp;/&nbsp;frequency seconds. The frequency of the raw This value is in 1&nbsp;/&nbsp;frequency seconds. The frequency of the raw
timer varies depending on the operating system and hardware. You can query the timer varies depending on the operating system and hardware. You can query the
frequency, in Hz, with @ref glfwGetTimerFrequency. frequency, in Hz, with @ref glfwGetTimerFrequency.
@code{.c} ```c
uint64_t frequency = glfwGetTimerFrequency(); uint64_t frequency = glfwGetTimerFrequency();
@endcode ```
## Clipboard input and output {#clipboard} ## Clipboard input and output {#clipboard}
@ -935,13 +935,13 @@ 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
reference documentation for the lifetime of the returned string. reference documentation for the lifetime of the returned string.
@code{.c} ```c
const char* text = glfwGetClipboardString(NULL); const char* text = glfwGetClipboardString(NULL);
if (text) if (text)
{ {
insert_text(text); insert_text(text);
} }
@endcode ```
If the clipboard is empty or if its contents could not be converted, `NULL` is If the clipboard is empty or if its contents could not be converted, `NULL` is
returned. returned.
@ -949,9 +949,9 @@ returned.
The contents of the system clipboard can be set to a UTF-8 encoded string with The contents of the system clipboard can be set to a UTF-8 encoded string with
@ref glfwSetClipboardString. @ref glfwSetClipboardString.
@code{.c} ```c
glfwSetClipboardString(NULL, "A string with words in it"); glfwSetClipboardString(NULL, "A string with words in it");
@endcode ```
## Path drop input {#path_drop} ## Path drop input {#path_drop}
@ -959,20 +959,20 @@ glfwSetClipboardString(NULL, "A string with words in it");
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.
@code{.c} ```c
glfwSetDropCallback(window, drop_callback); glfwSetDropCallback(window, drop_callback);
@endcode ```
The callback function receives an array of paths encoded as UTF-8. The callback function receives an array of paths encoded as UTF-8.
@code{.c} ```c
void drop_callback(GLFWwindow* window, int count, const char** paths) void drop_callback(GLFWwindow* window, int count, const char** paths)
{ {
int i; int i;
for (i = 0; i < count; i++) for (i = 0; i < count; i++)
handle_dropped_file(paths[i]); handle_dropped_file(paths[i]);
} }
@endcode ```
The path array and its strings are only valid until the file drop callback The path array and its strings are only valid until the file drop callback
returns, as they may have been generated specifically for that event. You need returns, as they may have been generated specifically for that event. You need

View File

@ -46,12 +46,12 @@ GLFW_NOT_INITIALIZED error.
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.
@code{.c} ```c
if (!glfwInit()) if (!glfwInit())
{ {
// Handle initialization failure // Handle initialization failure
} }
@endcode ```
If any part of initialization fails, any parts that succeeded are terminated as If any part of initialization fails, any parts that succeeded are terminated as
if @ref glfwTerminate had been called. The library only needs to be initialized if @ref glfwTerminate had been called. The library only needs to be initialized
@ -74,9 +74,9 @@ hint.
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.
@code{.c} ```c
glfwInitHint(GLFW_JOYSTICK_HAT_BUTTONS, GLFW_FALSE); glfwInitHint(GLFW_JOYSTICK_HAT_BUTTONS, GLFW_FALSE);
@endcode ```
The values you set hints to are never reset by GLFW, but they only take effect The values you set hints to are never reset by GLFW, but they only take effect
during initialization. Once GLFW has been initialized, any values you set will during initialization. Once GLFW has been initialized, any values you set will
@ -174,32 +174,32 @@ default, this is set to @ref GLFW_ANY_PLATFORM, which will look for supported wi
systems in order of priority and select the first one it finds. It can also be set to any systems in order of priority and select the first one it finds. It can also be set to any
specific platform to have GLFW only look for that one. specific platform to have GLFW only look for that one.
@code{.c} ```c
glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_X11); glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_X11);
@endcode ```
This mechanism also provides the Null platform, which is always supported but needs to be This mechanism also provides the Null platform, which is always supported but needs to be
explicitly requested. This platform is effectively a stub, emulating a window system on explicitly requested. This platform is effectively a stub, emulating a window system on
a single 1080p monitor, but will not interact with any actual window system. a single 1080p monitor, but will not interact with any actual window system.
@code{.c} ```c
glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_NULL); glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_NULL);
@endcode ```
You can test whether a library binary was compiled with support for a specific platform You can test whether a library binary was compiled with support for a specific platform
with @ref glfwPlatformSupported. with @ref glfwPlatformSupported.
@code{.c} ```c
if (glfwPlatformSupported(GLFW_PLATFORM_WAYLAND)) if (glfwPlatformSupported(GLFW_PLATFORM_WAYLAND))
glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_WAYLAND); glfwInitHint(GLFW_PLATFORM, GLFW_PLATFORM_WAYLAND);
@endcode ```
Once GLFW has been initialized, you can query which platform was selected with @ref Once GLFW has been initialized, you can query which platform was selected with @ref
glfwGetPlatform. glfwGetPlatform.
@code{.c} ```c
int platform = glfwGetPlatform(); int platform = glfwGetPlatform();
@endcode ```
If you are using any [native access functions](@ref native), especially on Linux and other If you are using any [native access functions](@ref native), especially on Linux and other
Unix-like systems, then you may need to check that you are calling the ones matching the Unix-like systems, then you may need to check that you are calling the ones matching the
@ -211,7 +211,7 @@ selected platform.
The heap memory allocator can be customized before initialization with @ref The heap memory allocator can be customized before initialization with @ref
glfwInitAllocator. glfwInitAllocator.
@code{.c} ```c
GLFWallocator allocator; GLFWallocator allocator;
allocator.allocate = my_malloc; allocator.allocate = my_malloc;
allocator.reallocate = my_realloc; allocator.reallocate = my_realloc;
@ -219,7 +219,7 @@ allocator.deallocate = my_free;
allocator.user = NULL; allocator.user = NULL;
glfwInitAllocator(&allocator); glfwInitAllocator(&allocator);
@endcode ```
The allocator will be made active at the beginning of initialization and will be used by The allocator will be made active at the beginning of initialization and will be used by
GLFW until the library has been fully terminated. Any allocator set after initialization GLFW until the library has been fully terminated. Any allocator set after initialization
@ -233,12 +233,12 @@ The allocation function must have a signature matching @ref GLFWallocatefun. It
the desired size, in bytes, and the user pointer passed to @ref glfwInitAllocator and the desired size, in bytes, and the user pointer passed to @ref glfwInitAllocator and
returns the address to the allocated memory block. returns the address to the allocated memory block.
@code{.c} ```c
void* my_malloc(size_t size, void* user) void* my_malloc(size_t size, void* user)
{ {
... ...
} }
@endcode ```
The documentation for @ref GLFWallocatefun also lists the requirements and limitations for The documentation for @ref GLFWallocatefun also lists the requirements and limitations for
an allocation function. If the active one does not meet all of these, GLFW may fail. an allocation function. If the active one does not meet all of these, GLFW may fail.
@ -248,12 +248,12 @@ It receives the memory block to be reallocated, the new desired size, in bytes,
pointer passed to @ref glfwInitAllocator and returns the address to the resized memory pointer passed to @ref glfwInitAllocator and returns the address to the resized memory
block. block.
@code{.c} ```c
void* my_realloc(void* block, size_t size, void* user) void* my_realloc(void* block, size_t size, void* user)
{ {
... ...
} }
@endcode ```
The documentation for @ref GLFWreallocatefun also lists the requirements and limitations The documentation for @ref GLFWreallocatefun also lists the requirements and limitations
for a reallocation function. If the active one does not meet all of these, GLFW may fail. for a reallocation function. If the active one does not meet all of these, GLFW may fail.
@ -262,12 +262,12 @@ The deallocation function must have a function signature matching @ref GLFWdeall
It receives the memory block to be deallocated and the user pointer passed to @ref It receives the memory block to be deallocated and the user pointer passed to @ref
glfwInitAllocator. glfwInitAllocator.
@code{.c} ```c
void my_free(void* block, void* user) void my_free(void* block, void* user)
{ {
... ...
} }
@endcode ```
The documentation for @ref GLFWdeallocatefun also lists the requirements and limitations The documentation for @ref GLFWdeallocatefun also lists the requirements and limitations
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.
@ -278,9 +278,9 @@ for a deallocation function. If the active one does not meet all of these, GLFW
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.
@code{.c} ```c
glfwTerminate(); glfwTerminate();
@endcode ```
This will destroy any remaining window, monitor and cursor objects, restore any This will destroy any remaining window, monitor and cursor objects, restore any
modified gamma ramps, re-enable the screensaver if it had been disabled and free modified gamma ramps, re-enable the screensaver if it had been disabled and free
@ -303,12 +303,12 @@ values.
The last [error code](@ref errors) for the calling thread can be queried at any The last [error code](@ref errors) for the calling thread can be queried at any
time with @ref glfwGetError. time with @ref glfwGetError.
@code{.c} ```c
int code = glfwGetError(NULL); int code = glfwGetError(NULL);
if (code != GLFW_NO_ERROR) if (code != GLFW_NO_ERROR)
handle_error(code); handle_error(code);
@endcode ```
If no error has occurred since the last call, @ref GLFW_NO_ERROR (zero) is If no error has occurred since the last call, @ref GLFW_NO_ERROR (zero) is
returned. The error is cleared before the function returns. returned. The error is cleared before the function returns.
@ -322,13 +322,13 @@ can retrieve a UTF-8 encoded human-readable description along with the error
code. If no error has occurred since the last call, the description is set to code. If no error has occurred since the last call, the description is set to
`NULL`. `NULL`.
@code{.c} ```c
const char* description; const char* description;
int code = glfwGetError(&description); int code = glfwGetError(&description);
if (description) if (description)
display_error_message(code, description); display_error_message(code, description);
@endcode ```
The retrieved description string is only valid until the next error occurs. The retrieved description string is only valid until the next error occurs.
This means you must make a copy of it if you want to keep it. This means you must make a copy of it if you want to keep it.
@ -336,19 +336,19 @@ This means you must make a copy of it if you want to keep it.
You can also set an error callback, which will be called each time an error You can also set an error callback, which will be called each time an error
occurs. It is set with @ref glfwSetErrorCallback. occurs. It is set with @ref glfwSetErrorCallback.
@code{.c} ```c
glfwSetErrorCallback(error_callback); glfwSetErrorCallback(error_callback);
@endcode ```
The error callback receives the same error code and human-readable description The error callback receives the same error code and human-readable description
returned by @ref glfwGetError. returned by @ref glfwGetError.
@code{.c} ```c
void error_callback(int code, const char* description) void error_callback(int code, const char* description)
{ {
display_error_message(code, description); display_error_message(code, description);
} }
@endcode ```
The error callback is called after the error is stored, so calling @ref The error callback is called after the error is stored, so calling @ref
glfwGetError from within the error callback returns the same values as the glfwGetError from within the error callback returns the same values as the
@ -570,12 +570,12 @@ this to verify that the library binary is compatible with your application.
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.
@code{.c} ```c
printf("Compiled against GLFW %i.%i.%i\n", printf("Compiled against GLFW %i.%i.%i\n",
GLFW_VERSION_MAJOR, GLFW_VERSION_MAJOR,
GLFW_VERSION_MINOR, GLFW_VERSION_MINOR,
GLFW_VERSION_REVISION); GLFW_VERSION_REVISION);
@endcode ```
### Run-time version {#intro_version_runtime} ### Run-time version {#intro_version_runtime}
@ -583,12 +583,12 @@ printf("Compiled against GLFW %i.%i.%i\n",
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.
@code{.c} ```c
int major, minor, revision; int major, minor, revision;
glfwGetVersion(&major, &minor, &revision); glfwGetVersion(&major, &minor, &revision);
printf("Running against GLFW %i.%i.%i\n", major, minor, revision); printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
@endcode ```
### Version string {#intro_version_string} ### Version string {#intro_version_string}
@ -622,14 +622,14 @@ The format of the string is as follows:
For example, compiling GLFW 3.4 with MinGW as a DLL for Windows, may result in a version string For example, compiling GLFW 3.4 with MinGW as a DLL for Windows, may result in a version string
like this: like this:
@code{.c} ```c
3.4.0 Win32 WGL Null EGL OSMesa MinGW DLL 3.4.0 Win32 WGL Null EGL OSMesa MinGW DLL
@endcode ```
Compiling GLFW as a static library for Linux, with both Wayland and X11 enabled, may Compiling GLFW as a static library for Linux, with both Wayland and X11 enabled, may
result in a version string like this: result in a version string like this:
@code{.c} ```c
3.4.0 Wayland X11 GLX Null EGL OSMesa monotonic 3.4.0 Wayland X11 GLX Null EGL OSMesa monotonic
@endcode ```

View File

@ -40,17 +40,17 @@ 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
or menu bar. or menu bar.
@code{.c} ```c
GLFWmonitor* primary = glfwGetPrimaryMonitor(); GLFWmonitor* primary = glfwGetPrimaryMonitor();
@endcode ```
You can retrieve all currently connected monitors with @ref glfwGetMonitors. You can retrieve all currently connected monitors with @ref glfwGetMonitors.
See the reference documentation for the lifetime of the returned array. See the reference documentation for the lifetime of the returned array.
@code{.c} ```c
int count; int count;
GLFWmonitor** monitors = glfwGetMonitors(&count); GLFWmonitor** monitors = glfwGetMonitors(&count);
@endcode ```
The primary monitor is always the first monitor in the returned array, but other The primary monitor is always the first monitor in the returned array, but other
monitors may be moved to a different index when a monitor is connected or monitors may be moved to a different index when a monitor is connected or
@ -62,14 +62,14 @@ disconnected.
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.
@code{.c} ```c
glfwSetMonitorCallback(monitor_callback); glfwSetMonitorCallback(monitor_callback);
@endcode ```
The callback function receives the handle for the monitor that has been The callback function receives the handle for the monitor that has been
connected or disconnected and the event that occurred. connected or disconnected and the event that occurred.
@code{.c} ```c
void monitor_callback(GLFWmonitor* monitor, int event) void monitor_callback(GLFWmonitor* monitor, int event)
{ {
if (event == GLFW_CONNECTED) if (event == GLFW_CONNECTED)
@ -81,7 +81,7 @@ void monitor_callback(GLFWmonitor* monitor, int event)
// The monitor was disconnected // The monitor was disconnected
} }
} }
@endcode ```
If a monitor is disconnected, all windows that are full screen on it will be If a monitor is disconnected, all windows that are full screen on it will be
switched to windowed mode before the callback is called. Only @ref switched to windowed mode before the callback is called. Only @ref
@ -107,17 +107,17 @@ Video modes are represented as @ref GLFWvidmode structures. You can get an
array of the video modes supported by a monitor with @ref glfwGetVideoModes. array of the video modes supported by a monitor with @ref glfwGetVideoModes.
See the reference documentation for the lifetime of the returned array. See the reference documentation for the lifetime of the returned array.
@code{.c} ```c
int count; int count;
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count); GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
@endcode ```
To get the current video mode of a monitor call @ref glfwGetVideoMode. See the To get the current video mode of a monitor call @ref glfwGetVideoMode. See the
reference documentation for the lifetime of the returned pointer. reference documentation for the lifetime of the returned pointer.
@code{.c} ```c
const GLFWvidmode* mode = glfwGetVideoMode(monitor); const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@endcode ```
The resolution of a video mode is specified in The resolution of a video mode is specified in
[screen coordinates](@ref coordinate_systems), not pixels. [screen coordinates](@ref coordinate_systems), not pixels.
@ -130,10 +130,10 @@ retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its
current _resolution_, i.e. the width and height of its current current _resolution_, i.e. the width and height of its current
[video mode](@ref monitor_modes). [video mode](@ref monitor_modes).
@code{.c} ```c
int width_mm, height_mm; int width_mm, height_mm;
glfwGetMonitorPhysicalSize(monitor, &width_mm, &height_mm); glfwGetMonitorPhysicalSize(monitor, &width_mm, &height_mm);
@endcode ```
While this can be used to calculate the raw DPI of a monitor, this is often not While this can be used to calculate the raw DPI of a monitor, this is often not
useful. Instead, use the [monitor content scale](@ref monitor_scale) and useful. Instead, use the [monitor content scale](@ref monitor_scale) and
@ -145,10 +145,10 @@ useful. Instead, use the [monitor content scale](@ref monitor_scale) and
The content scale for a monitor can be retrieved with @ref The content scale for a monitor can be retrieved with @ref
glfwGetMonitorContentScale. glfwGetMonitorContentScale.
@code{.c} ```c
float xscale, yscale; float xscale, yscale;
glfwGetMonitorContentScale(monitor, &xscale, &yscale); glfwGetMonitorContentScale(monitor, &xscale, &yscale);
@endcode ```
The content scale is the ratio between the current DPI and the platform's The content scale is the ratio between the current DPI and the platform's
default DPI. This is especially important for text and any UI elements. If the default DPI. This is especially important for text and any UI elements. If the
@ -168,10 +168,10 @@ 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
glfwGetMonitorPos. glfwGetMonitorPos.
@code{.c} ```c
int xpos, ypos; int xpos, ypos;
glfwGetMonitorPos(monitor, &xpos, &ypos); glfwGetMonitorPos(monitor, &xpos, &ypos);
@endcode ```
### Work area {#monitor_workarea} ### Work area {#monitor_workarea}
@ -180,10 +180,10 @@ 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
can be retrieved with @ref glfwGetMonitorWorkarea. can be retrieved with @ref glfwGetMonitorWorkarea.
@code{.c} ```c
int xpos, ypos, width, height; int xpos, ypos, width, height;
glfwGetMonitorWorkarea(monitor, &xpos, &ypos, &width, &height); glfwGetMonitorWorkarea(monitor, &xpos, &ypos, &width, &height);
@endcode ```
### Human-readable name {#monitor_name} ### Human-readable name {#monitor_name}
@ -192,9 +192,9 @@ 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
returned string. returned string.
@code{.c} ```c
const char* name = glfwGetMonitorName(monitor); const char* name = glfwGetMonitorName(monitor);
@endcode ```
Monitor names are not guaranteed to be unique. Two monitors of the same model Monitor names are not guaranteed to be unique. Two monitors of the same model
and make may have the same name. Only the monitor handle is guaranteed to be and make may have the same name. Only the monitor handle is guaranteed to be
@ -217,7 +217,7 @@ The initial value of the pointer is `NULL`.
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.
@code{.c} ```c
GLFWgammaramp ramp; GLFWgammaramp ramp;
unsigned short red[256], green[256], blue[256]; unsigned short red[256], green[256], blue[256];
@ -232,7 +232,7 @@ for (i = 0; i < ramp.size; i++)
} }
glfwSetGammaRamp(monitor, &ramp); glfwSetGammaRamp(monitor, &ramp);
@endcode ```
The gamma ramp data is copied before the function returns, so there is no need The gamma ramp data is copied before the function returns, so there is no need
to keep it around once the ramp has been set. to keep it around once the ramp has been set.
@ -243,17 +243,17 @@ ramp for that monitor.
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. See The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. See
the reference documentation for the lifetime of the returned structure. the reference documentation for the lifetime of the returned structure.
@code{.c} ```c
const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor); const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);
@endcode ```
If you wish to set a regular gamma ramp, you can have GLFW calculate it for you If you wish to set a regular gamma ramp, you can have GLFW calculate it for you
from the desired exponent with @ref glfwSetGamma, which in turn calls @ref from the desired exponent with @ref glfwSetGamma, which in turn calls @ref
glfwSetGammaRamp with the resulting ramp. glfwSetGammaRamp with the resulting ramp.
@code{.c} ```c
glfwSetGamma(monitor, 1.0); glfwSetGamma(monitor, 1.0);
@endcode ```
To experiment with gamma correction via the @ref glfwSetGamma function, run the To experiment with gamma correction via the @ref glfwSetGamma function, run the
`gamma` test program. `gamma` test program.

View File

@ -20,14 +20,14 @@ Unix-like systems, where it uses the
[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`. [soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.
@par Old syntax @par Old syntax
@code{.c} ```c
#include <GL/glfw.h> #include <GL/glfw.h>
@endcode ```
@par New syntax @par New syntax
@code{.c} ```c
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
### Removal of threading functions {#moving_threads} ### Removal of threading functions {#moving_threads}
@ -93,14 +93,14 @@ the creation of DLLs and DLL link libraries, as there's no need to explicitly
disable `@n` entry point suffixes. disable `@n` entry point suffixes.
@par Old syntax @par Old syntax
@code{.c} ```c
void GLFWCALL callback_function(...); void GLFWCALL callback_function(...);
@endcode ```
@par New syntax @par New syntax
@code{.c} ```c
void callback_function(...); void callback_function(...);
@endcode ```
### Window handle parameters {#moving_window_handles} ### Window handle parameters {#moving_window_handles}
@ -112,14 +112,14 @@ a newly created window is returned by @ref glfwCreateWindow (formerly
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWwindow. [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWwindow.
@par Old syntax @par Old syntax
@code{.c} ```c
glfwSetWindowTitle("New Window Title"); glfwSetWindowTitle("New Window Title");
@endcode ```
@par New syntax @par New syntax
@code{.c} ```c
glfwSetWindowTitle(window, "New Window Title"); glfwSetWindowTitle(window, "New Window Title");
@endcode ```
### Explicit monitor selection {#moving_monitor} ### Explicit monitor selection {#moving_monitor}
@ -132,14 +132,14 @@ GLFW 2 would have selected, but there are many other
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor. [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor.
@par Old basic full screen @par Old basic full screen
@code{.c} ```c
glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN); glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN);
@endcode ```
@par New basic full screen @par New basic full screen
@code{.c} ```c
window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL); window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL);
@endcode ```
@note The framebuffer bit depth parameters of `glfwOpenWindow` have been turned @note The framebuffer bit depth parameters of `glfwOpenWindow` have been turned
into [window hints](@ref window_hints), but as they have been given into [window hints](@ref window_hints), but as they have been given
@ -154,17 +154,17 @@ buffer swap, which acts on a single window, the event processing functions act
on all windows at once. on all windows at once.
@par Old basic main loop @par Old basic main loop
@code{.c} ```c
while (...) while (...)
{ {
// Process input // Process input
// Render output // Render output
glfwSwapBuffers(); glfwSwapBuffers();
} }
@endcode ```
@par New basic main loop @par New basic main loop
@code{.c} ```c
while (...) while (...)
{ {
// Process input // Process input
@ -172,7 +172,7 @@ while (...)
glfwSwapBuffers(window); glfwSwapBuffers(window);
glfwPollEvents(); glfwPollEvents();
} }
@endcode ```
### Explicit context management {#moving_context} ### Explicit context management {#moving_context}
@ -196,16 +196,16 @@ glfwGetFramebufferSize function. A framebuffer size callback has also been
added, which can be set with @ref glfwSetFramebufferSizeCallback. added, which can be set with @ref glfwSetFramebufferSizeCallback.
@par Old basic viewport setup @par Old basic viewport setup
@code{.c} ```c
glfwGetWindowSize(&width, &height); glfwGetWindowSize(&width, &height);
glViewport(0, 0, width, height); glViewport(0, 0, width, height);
@endcode ```
@par New basic viewport setup @par New basic viewport setup
@code{.c} ```c
glfwGetFramebufferSize(window, &width, &height); glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height); glViewport(0, 0, width, height);
@endcode ```
### Window closing changes {#moving_window_close} ### Window closing changes {#moving_window_close}
@ -225,20 +225,20 @@ You can query the close flag at any time with @ref glfwWindowShouldClose and set
it at any time with @ref glfwSetWindowShouldClose. it at any time with @ref glfwSetWindowShouldClose.
@par Old basic main loop @par Old basic main loop
@code{.c} ```c
while (glfwGetWindowParam(GLFW_OPENED)) while (glfwGetWindowParam(GLFW_OPENED))
{ {
... ...
} }
@endcode ```
@par New basic main loop @par New basic main loop
@code{.c} ```c
while (!glfwWindowShouldClose(window)) while (!glfwWindowShouldClose(window))
{ {
... ...
} }
@endcode ```
The close callback no longer returns a value. Instead, it is called after the The close callback no longer returns a value. Instead, it is called after the
close flag has been set, so it can optionally override its value, before close flag has been set, so it can optionally override its value, before
@ -246,14 +246,14 @@ event processing completes. You may however not call @ref glfwDestroyWindow
from the close callback (or any other window related callback). from the close callback (or any other window related callback).
@par Old syntax @par Old syntax
@code{.c} ```c
int GLFWCALL window_close_callback(void); int GLFWCALL window_close_callback(void);
@endcode ```
@par New syntax @par New syntax
@code{.c} ```c
void window_close_callback(GLFWwindow* window); void window_close_callback(GLFWwindow* window);
@endcode ```
@note GLFW never clears the close flag to `GLFW_FALSE`, meaning you can use it @note GLFW never clears the close flag to `GLFW_FALSE`, meaning you can use it
for other reasons to close the window as well, for example the user choosing for other reasons to close the window as well, for example the user choosing
@ -287,14 +287,14 @@ produce characters with diacritical marks. Even the Swedish keyboard layout
requires this for uncommon cases like ü. requires this for uncommon cases like ü.
@par Old syntax @par Old syntax
@code{.c} ```c
void GLFWCALL character_callback(int character, int action); void GLFWCALL character_callback(int character, int action);
@endcode ```
@par New syntax @par New syntax
@code{.c} ```c
void character_callback(GLFWwindow* window, int character); void character_callback(GLFWwindow* window, int character);
@endcode ```
### Cursor position changes {#moving_cursorpos} ### Cursor position changes {#moving_cursorpos}
@ -322,14 +322,14 @@ two-dimensional floating point scroll offsets. This allows you to receive
precise scroll data from for example modern touchpads. precise scroll data from for example modern touchpads.
@par Old syntax @par Old syntax
@code{.c} ```c
void GLFWCALL mouse_wheel_callback(int position); void GLFWCALL mouse_wheel_callback(int position);
@endcode ```
@par New syntax @par New syntax
@code{.c} ```c
void scroll_callback(GLFWwindow* window, double xoffset, double yoffset); void scroll_callback(GLFWwindow* window, double xoffset, double yoffset);
@endcode ```
@par Removed functions @par Removed functions
`glfwGetMouseWheel` `glfwGetMouseWheel`
@ -435,15 +435,15 @@ has been moved to GLFW 3, you can request that the GLFW header includes it by
defining @ref GLFW_INCLUDE_GLU before the inclusion of the GLFW header. defining @ref GLFW_INCLUDE_GLU before the inclusion of the GLFW header.
@par Old syntax @par Old syntax
@code{.c} ```c
#include <GL/glfw.h> #include <GL/glfw.h>
@endcode ```
@par New syntax @par New syntax
@code{.c} ```c
#define GLFW_INCLUDE_GLU #define GLFW_INCLUDE_GLU
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
There are many libraries that offer replacements for the functionality offered There are many libraries that offer replacements for the functionality offered
by GLU. For the matrix helper functions, see math libraries like by GLU. For the matrix helper functions, see math libraries like

View File

@ -161,11 +161,11 @@ a subdirectory of another CMake project. To enable these, set the @ref
GLFW_BUILD_TESTS and @ref GLFW_BUILD_EXAMPLES cache variables before adding the GLFW_BUILD_TESTS and @ref GLFW_BUILD_EXAMPLES cache variables before adding the
GLFW subdirectory. GLFW subdirectory.
@code{.cmake} ```cmake
set(GLFW_BUILD_EXAMPLES ON CACHE BOOL "" FORCE) set(GLFW_BUILD_EXAMPLES ON CACHE BOOL "" FORCE)
set(GLFW_BUILD_TESTS ON CACHE BOOL "" FORCE) set(GLFW_BUILD_TESTS ON CACHE BOOL "" FORCE)
add_subdirectory(path/to/glfw) add_subdirectory(path/to/glfw)
@endcode ```
#### macOS main menu now created at initialization {#initmenu_34} #### macOS main menu now created at initialization {#initmenu_34}

View File

@ -19,9 +19,9 @@ behave differently in GLFW 3.
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.
@code{.c} ```c
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
This header provides all the constants, types and function prototypes of the This header provides all the constants, types and function prototypes of the
GLFW API. GLFW API.
@ -36,21 +36,21 @@ This example uses files generated by [glad](https://gen.glad.sh/). The GLFW
header can detect most such headers if they are included first and will then not header can detect most such headers if they are included first and will then not
include the one from your development environment. include the one from your development environment.
@code{.c} ```c
#include <glad/gl.h> #include <glad/gl.h>
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
To make sure there will be no header conflicts, you can define @ref To make sure there will be no header conflicts, you can define @ref
GLFW_INCLUDE_NONE before the GLFW header to explicitly disable inclusion of the GLFW_INCLUDE_NONE before the GLFW header to explicitly disable inclusion of the
development environment header. This also allows the two headers to be included development environment header. This also allows the two headers to be included
in any order. in any order.
@code{.c} ```c
#define GLFW_INCLUDE_NONE #define GLFW_INCLUDE_NONE
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
#include <glad/gl.h> #include <glad/gl.h>
@endcode ```
### Initializing and terminating GLFW {#quick_init_term} ### Initializing and terminating GLFW {#quick_init_term}
@ -59,21 +59,21 @@ 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,
`GLFW_FALSE` is returned. `GLFW_FALSE` is returned.
@code{.c} ```c
if (!glfwInit()) if (!glfwInit())
{ {
// Initialization failed // Initialization failed
} }
@endcode ```
Note that `GLFW_TRUE` and `GLFW_FALSE` are and will always be one and zero. Note that `GLFW_TRUE` and `GLFW_FALSE` are and will always be one and zero.
When you are done using GLFW, typically just before the application exits, you When you are done using GLFW, typically just before the application exits, you
need to terminate GLFW. need to terminate GLFW.
@code{.c} ```c
glfwTerminate(); glfwTerminate();
@endcode ```
This destroys any remaining windows and releases any other resources allocated by This destroys any remaining windows and releases any other resources allocated by
GLFW. After this call, you must initialize GLFW again before using any GLFW GLFW. After this call, you must initialize GLFW again before using any GLFW
@ -90,21 +90,21 @@ In case a GLFW function fails, an error is reported to the GLFW error callback.
You can receive these reports with an error callback. This function must have You can receive these reports with an error callback. This function must have
the signature below but may do anything permitted in other callbacks. the signature below but may do anything permitted in other callbacks.
@code{.c} ```c
void error_callback(int error, const char* description) void error_callback(int error, const char* description)
{ {
fprintf(stderr, "Error: %s\n", description); fprintf(stderr, "Error: %s\n", description);
} }
@endcode ```
Callback functions must be set, so GLFW knows to call them. The function to set Callback functions must be set, so GLFW knows to call them. The function to set
the error callback is one of the few GLFW functions that may be called before the error callback is one of the few GLFW functions that may be called before
initialization, which lets you be notified of errors both during and after initialization, which lets you be notified of errors both during and after
initialization. initialization.
@code{.c} ```c
glfwSetErrorCallback(error_callback); glfwSetErrorCallback(error_callback);
@endcode ```
### Creating a window and context {#quick_create_window} ### Creating a window and context {#quick_create_window}
@ -113,13 +113,13 @@ 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
context object context object
@code{.c} ```c
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
if (!window) if (!window)
{ {
// Window or OpenGL context creation failed // Window or OpenGL context creation failed
} }
@endcode ```
This creates a 640 by 480 windowed mode window with an OpenGL context. If This creates a 640 by 480 windowed mode window with an OpenGL context. If
window or OpenGL context creation fails, `NULL` will be returned. You should window or OpenGL context creation fails, `NULL` will be returned. You should
@ -136,7 +136,7 @@ You can select the OpenGL profile by setting the `GLFW_OPENGL_PROFILE` hint.
This program uses the core profile as that is the only profile macOS supports This program uses the core profile as that is the only profile macOS supports
for OpenGL 3.x and 4.x. for OpenGL 3.x and 4.x.
@code{.c} ```c
glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3); glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 3); glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 3);
glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE); glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE);
@ -145,13 +145,13 @@ if (!window)
{ {
// Window or context creation failed // Window or context creation failed
} }
@endcode ```
When a window and context is no longer needed, destroy it. When a window and context is no longer needed, destroy it.
@code{.c} ```c
glfwDestroyWindow(window); glfwDestroyWindow(window);
@endcode ```
Once this function is called, no more events will be delivered for that window Once this function is called, no more events will be delivered for that window
and its handle becomes invalid. and its handle becomes invalid.
@ -161,9 +161,9 @@ and its handle becomes invalid.
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.
@code{.c} ```c
glfwMakeContextCurrent(window); glfwMakeContextCurrent(window);
@endcode ```
The context will remain current until you make another context current or until The context will remain current until you make another context current or until
the window owning the current context is destroyed. the window owning the current context is destroyed.
@ -174,9 +174,9 @@ a current context to load from. This example uses
[glad](https://github.com/Dav1dde/glad), but the same rule applies to all such [glad](https://github.com/Dav1dde/glad), but the same rule applies to all such
libraries. libraries.
@code{.c} ```c
gladLoadGL(glfwGetProcAddress); gladLoadGL(glfwGetProcAddress);
@endcode ```
### Checking the window close flag {#quick_window_close} ### Checking the window close flag {#quick_window_close}
@ -189,12 +189,12 @@ Note that __the window isn't actually closed__, so you are expected to monitor
this flag and either destroy the window or give some kind of feedback to the this flag and either destroy the window or give some kind of feedback to the
user. user.
@code{.c} ```c
while (!glfwWindowShouldClose(window)) while (!glfwWindowShouldClose(window))
{ {
// Keep running // Keep running
} }
@endcode ```
You can be notified when the user is attempting to close the window by setting You can be notified when the user is attempting to close the window by setting
a close callback with @ref glfwSetWindowCloseCallback. The callback will be a close callback with @ref glfwSetWindowCloseCallback. The callback will be
@ -211,19 +211,19 @@ 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
callback function. callback function.
@code{.c} ```c
static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
{ {
if (key == GLFW_KEY_ESCAPE && action == GLFW_PRESS) if (key == GLFW_KEY_ESCAPE && action == GLFW_PRESS)
glfwSetWindowShouldClose(window, GLFW_TRUE); glfwSetWindowShouldClose(window, GLFW_TRUE);
} }
@endcode ```
The key callback, like other window related callbacks, are set per-window. The key callback, like other window related callbacks, are set per-window.
@code{.c} ```c
glfwSetKeyCallback(window, key_callback); glfwSetKeyCallback(window, key_callback);
@endcode ```
In order for event callbacks to be called when events occur, you need to process In order for event callbacks to be called when events occur, you need to process
events as described below. events as described below.
@ -235,11 +235,11 @@ 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
size needs to be retrieved for `glViewport`. size needs to be retrieved for `glViewport`.
@code{.c} ```c
int width, height; int width, height;
glfwGetFramebufferSize(window, &width, &height); glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height); glViewport(0, 0, width, height);
@endcode ```
You can also set a framebuffer size callback using @ref You can also set a framebuffer size callback using @ref
glfwSetFramebufferSizeCallback and be notified when the size changes. glfwSetFramebufferSizeCallback and be notified when the size changes.
@ -263,9 +263,9 @@ returns the number of seconds since initialization. The time source used is the
most accurate on each platform and generally has micro- or nanosecond most accurate on each platform and generally has micro- or nanosecond
resolution. resolution.
@code{.c} ```c
double time = glfwGetTime(); double time = glfwGetTime();
@endcode ```
### Swapping buffers {#quick_swap_buffers} ### Swapping buffers {#quick_swap_buffers}
@ -277,9 +277,9 @@ the one being displayed and the back buffer the one you render to.
When the entire frame has been rendered, the buffers need to be swapped with one When the entire frame has been rendered, the buffers need to be swapped with one
another, so the back buffer becomes the front buffer and vice versa. another, so the back buffer becomes the front buffer and vice versa.
@code{.c} ```c
glfwSwapBuffers(window); glfwSwapBuffers(window);
@endcode ```
The swap interval indicates how many frames to wait until swapping the buffers, The swap interval indicates how many frames to wait until swapping the buffers,
commonly known as _vsync_. By default, the swap interval is zero, meaning commonly known as _vsync_. By default, the swap interval is zero, meaning
@ -294,9 +294,9 @@ For these reasons, applications will typically want to set the swap interval to
one. It can be set to higher values, but this is usually not recommended, one. It can be set to higher values, but this is usually not recommended,
because of the input latency it leads to. because of the input latency it leads to.
@code{.c} ```c
glfwSwapInterval(1); glfwSwapInterval(1);
@endcode ```
This function acts on the current context and will fail unless a context is This function acts on the current context and will fail unless a context is
current. current.
@ -313,9 +313,9 @@ There are two methods for processing pending events; polling and waiting. This
example will use event polling, which processes only those events that have example will use event polling, which processes only those events that have
already been received and then returns immediately. already been received and then returns immediately.
@code{.c} ```c
glfwPollEvents(); glfwPollEvents();
@endcode ```
This is the best choice when rendering continually, like most games do. If This is the best choice when rendering continually, like most games do. If
instead you only need to update your rendering once you have received new input, instead you only need to update your rendering once you have received new input,

View File

@ -43,9 +43,9 @@ you will need to direct GLFW to it. Pass your version of `vkGetInstanceProcAddr
glfwInitVulkanLoader before initializing GLFW and it will use that function for all Vulkan glfwInitVulkanLoader before initializing GLFW and it will use that function for all Vulkan
entry point retrieval. This prevents GLFW from dynamically loading the Vulkan loader. entry point retrieval. This prevents GLFW from dynamically loading the Vulkan loader.
@code{.c} ```c
glfwInitVulkanLoader(vkGetInstanceProcAddr); glfwInitVulkanLoader(vkGetInstanceProcAddr);
@endcode ```
@macos To make your application be redistributable you will need to set up the application @macos To make your application be redistributable you will need to set up the application
bundle according to the LunarG SDK documentation. This is explained in more detail in the bundle according to the LunarG SDK documentation. This is explained in more detail in the
@ -57,18 +57,18 @@ bundle according to the LunarG SDK documentation. This is explained in more det
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.
@code{.c} ```c
#define GLFW_INCLUDE_VULKAN #define GLFW_INCLUDE_VULKAN
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
If you instead want to include the Vulkan header from a custom location or use If you instead want to include the Vulkan header from a custom location or use
your own custom Vulkan header then do this before the GLFW header. your own custom Vulkan header then do this before the GLFW header.
@code{.c} ```c
#include <path/to/vulkan.h> #include <path/to/vulkan.h>
#include <GLFW/glfw3.h> #include <GLFW/glfw3.h>
@endcode ```
Unless a Vulkan header is included, either by the GLFW header or above it, the following Unless a Vulkan header is included, either by the GLFW header or above it, the following
GLFW functions will not be declared, as depend on Vulkan types. GLFW functions will not be declared, as depend on Vulkan types.
@ -92,12 +92,12 @@ If you are loading the Vulkan loader dynamically instead of linking directly
against it, you can check for the availability of a loader and ICD with @ref against it, you can check for the availability of a loader and ICD with @ref
glfwVulkanSupported. glfwVulkanSupported.
@code{.c} ```c
if (glfwVulkanSupported()) if (glfwVulkanSupported())
{ {
// Vulkan is available, at least for compute // Vulkan is available, at least for compute
} }
@endcode ```
This function returns `GLFW_TRUE` if the Vulkan loader and any minimally This function returns `GLFW_TRUE` if the Vulkan loader and any minimally
functional ICD was found. functional ICD was found.
@ -112,18 +112,18 @@ 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,
pass `NULL` as the instance. pass `NULL` as the instance.
@code{.c} ```c
PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance) PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance)
glfwGetInstanceProcAddress(NULL, "vkCreateInstance"); glfwGetInstanceProcAddress(NULL, "vkCreateInstance");
@endcode ```
Once you have created an instance, you can load from it all other Vulkan core Once you have created an instance, you can load from it all other Vulkan core
functions and functions from any instance extensions you enabled. functions and functions from any instance extensions you enabled.
@code{.c} ```c
PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice) PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice)
glfwGetInstanceProcAddress(instance, "vkCreateDevice"); glfwGetInstanceProcAddress(instance, "vkCreateDevice");
@endcode ```
This function in turn calls `vkGetInstanceProcAddr`. If that fails, the This function in turn calls `vkGetInstanceProcAddr`. If that fails, the
function falls back to a platform-specific query of the Vulkan loader (i.e. function falls back to a platform-specific query of the Vulkan loader (i.e.
@ -135,10 +135,10 @@ Vulkan also provides `vkGetDeviceProcAddr` for loading device-specific versions
of Vulkan function. This function can be retrieved from an instance with @ref of Vulkan function. This function can be retrieved from an instance with @ref
glfwGetInstanceProcAddress. glfwGetInstanceProcAddress.
@code{.c} ```c
PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr) PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr)
glfwGetInstanceProcAddress(instance, "vkGetDeviceProcAddr"); glfwGetInstanceProcAddress(instance, "vkGetDeviceProcAddr");
@endcode ```
Device-specific functions may execute a little faster, due to not having to Device-specific functions may execute a little faster, due to not having to
dispatch internally based on the device passed to them. For more information dispatch internally based on the device passed to them. For more information
@ -154,10 +154,10 @@ GLFW requires to create Vulkan surfaces.
To query the instance extensions required, call @ref To query the instance extensions required, call @ref
glfwGetRequiredInstanceExtensions. glfwGetRequiredInstanceExtensions.
@code{.c} ```c
uint32_t count; uint32_t count;
const char** extensions = glfwGetRequiredInstanceExtensions(&count); const char** extensions = glfwGetRequiredInstanceExtensions(&count);
@endcode ```
These extensions must all be enabled when creating instances that are going to These extensions must all be enabled when creating instances that are going to
be passed to @ref glfwGetPhysicalDevicePresentationSupport and @ref be passed to @ref glfwGetPhysicalDevicePresentationSupport and @ref
@ -172,14 +172,14 @@ If successful the returned array will always include `VK_KHR_surface`, so if
you don't require any additional extensions you can pass this list directly to you don't require any additional extensions you can pass this list directly to
the `VkInstanceCreateInfo` struct. the `VkInstanceCreateInfo` struct.
@code{.c} ```c
VkInstanceCreateInfo ici; VkInstanceCreateInfo ici;
memset(&ici, 0, sizeof(ici)); memset(&ici, 0, sizeof(ici));
ici.enabledExtensionCount = count; ici.enabledExtensionCount = count;
ici.ppEnabledExtensionNames = extensions; ici.ppEnabledExtensionNames = extensions;
... ...
@endcode ```
Additional extensions may be required by future versions of GLFW. You should Additional extensions may be required by future versions of GLFW. You should
check whether any extensions you wish to enable are already in the returned check whether any extensions you wish to enable are already in the returned
@ -201,12 +201,12 @@ To check whether a specific queue family of a physical device supports image
presentation without first having to create a window and surface, call @ref presentation without first having to create a window and surface, call @ref
glfwGetPhysicalDevicePresentationSupport. glfwGetPhysicalDevicePresentationSupport.
@code{.c} ```c
if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index)) if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index))
{ {
// Queue family supports image presentation // Queue family supports image presentation
} }
@endcode ```
The `VK_KHR_surface` extension additionally provides the The `VK_KHR_surface` extension additionally provides the
`vkGetPhysicalDeviceSurfaceSupportKHR` function, which performs the same test on `vkGetPhysicalDeviceSurfaceSupportKHR` function, which performs the same test on
@ -219,10 +219,10 @@ 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
[GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint. [GLFW_CLIENT_API](@ref GLFW_CLIENT_API_hint) hint.
@code{.c} ```c
glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API); glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
GLFWwindow* window = glfwCreateWindow(640, 480, "Window Title", NULL, NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "Window Title", NULL, NULL);
@endcode ```
See @ref context_less for more information. See @ref context_less for more information.
@ -232,14 +232,14 @@ See @ref context_less for more information.
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.
@code{.c} ```c
VkSurfaceKHR surface; VkSurfaceKHR surface;
VkResult err = glfwCreateWindowSurface(instance, window, NULL, &surface); VkResult err = glfwCreateWindowSurface(instance, window, NULL, &surface);
if (err) if (err)
{ {
// Window surface creation failed // Window surface creation failed
} }
@endcode ```
If an OpenGL or OpenGL ES context was created on the window, the context has If an OpenGL or OpenGL ES context was created on the window, the context has
ownership of the presentation on the window and a Vulkan surface cannot be ownership of the presentation on the window and a Vulkan surface cannot be

View File

@ -30,9 +30,9 @@ 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
example, this creates a 640 by 480 windowed mode window: example, this creates a 640 by 480 windowed mode window:
@code{.c} ```c
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
@endcode ```
If window creation fails, `NULL` will be returned, so it is necessary to check If window creation fails, `NULL` will be returned, so it is necessary to check
the return value. the return value.
@ -48,9 +48,9 @@ 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.
For more information about retrieving monitors, see @ref monitor_monitors. For more information about retrieving monitors, see @ref monitor_monitors.
@code{.c} ```c
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
@endcode ```
Full screen windows cover the entire display area of a monitor, have no border Full screen windows cover the entire display area of a monitor, have no border
or decorations. or decorations.
@ -99,7 +99,7 @@ switching much smoother. This is sometimes called _windowed full screen_ or
_borderless full screen_ window and counts as a full screen window. To create _borderless full screen_ window and counts as a full screen window. To create
such a window, request the current video mode. such a window, request the current video mode.
@code{.c} ```c
const GLFWvidmode* mode = glfwGetVideoMode(monitor); const GLFWvidmode* mode = glfwGetVideoMode(monitor);
glfwWindowHint(GLFW_RED_BITS, mode->redBits); glfwWindowHint(GLFW_RED_BITS, mode->redBits);
@ -108,15 +108,15 @@ glfwWindowHint(GLFW_BLUE_BITS, mode->blueBits);
glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate); glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate);
GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL); GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL);
@endcode ```
This also works for windowed mode windows that are made full screen. This also works for windowed mode windows that are made full screen.
@code{.c} ```c
const GLFWvidmode* mode = glfwGetVideoMode(monitor); const GLFWvidmode* mode = glfwGetVideoMode(monitor);
glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate); glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
@endcode ```
Note that @ref glfwGetVideoMode returns the _current_ video mode of a monitor, Note that @ref glfwGetVideoMode returns the _current_ video mode of a monitor,
so if you already have a full screen window on that monitor that you want to so if you already have a full screen window on that monitor that you want to
@ -127,9 +127,9 @@ make windowed full screen, you need to have saved the desktop resolution before.
When a window is no longer needed, destroy it with @ref glfwDestroyWindow. When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
@code{.c} ```c
glfwDestroyWindow(window); glfwDestroyWindow(window);
@endcode ```
Window destruction always succeeds. Before the actual destruction, all Window destruction always succeeds. Before the actual destruction, all
callbacks are removed so no further events will be delivered for the window. callbacks are removed so no further events will be delivered for the window.
@ -596,7 +596,7 @@ The current state of the close flag is returned by @ref glfwWindowShouldClose
and can be set or cleared directly with @ref glfwSetWindowShouldClose. A common and can be set or cleared directly with @ref glfwSetWindowShouldClose. A common
pattern is to use the close flag as a main loop condition. pattern is to use the close flag as a main loop condition.
@code{.c} ```c
while (!glfwWindowShouldClose(window)) while (!glfwWindowShouldClose(window))
{ {
render(window); render(window);
@ -604,26 +604,26 @@ while (!glfwWindowShouldClose(window))
glfwSwapBuffers(window); glfwSwapBuffers(window);
glfwPollEvents(); glfwPollEvents();
} }
@endcode ```
If you wish to be notified when the user attempts to close a window, set a close If you wish to be notified when the user attempts to close a window, set a close
callback. callback.
@code{.c} ```c
glfwSetWindowCloseCallback(window, window_close_callback); glfwSetWindowCloseCallback(window, window_close_callback);
@endcode ```
The callback function is called directly _after_ the close flag has been set. The callback function is called directly _after_ the close flag has been set.
It can be used for example to filter close requests and clear the close flag It can be used for example to filter close requests and clear the close flag
again unless certain conditions are met. again unless certain conditions are met.
@code{.c} ```c
void window_close_callback(GLFWwindow* window) void window_close_callback(GLFWwindow* window)
{ {
if (!time_to_close) if (!time_to_close)
glfwSetWindowShouldClose(window, GLFW_FALSE); glfwSetWindowShouldClose(window, GLFW_FALSE);
} }
@endcode ```
### Window size {#window_size} ### Window size {#window_size}
@ -633,9 +633,9 @@ mode windows, this sets the size, in
[screen coordinates](@ref coordinate_systems) of the _content area_ or _content [screen coordinates](@ref coordinate_systems) of the _content area_ or _content
area_ of the window. The window system may impose limits on window size. area_ of the window. The window system may impose limits on window size.
@code{.c} ```c
glfwSetWindowSize(window, 640, 480); glfwSetWindowSize(window, 640, 480);
@endcode ```
For full screen windows, the specified size becomes the new resolution of the For full screen windows, the specified size becomes the new resolution of the
window's desired video mode. The video mode most closely matching the new window's desired video mode. The video mode most closely matching the new
@ -645,26 +645,26 @@ resolution of the set video mode.
If you wish to be notified when a window is resized, whether by the user, the If you wish to be notified when a window is resized, whether by the user, the
system or your own code, set a size callback. system or your own code, set a size callback.
@code{.c} ```c
glfwSetWindowSizeCallback(window, window_size_callback); glfwSetWindowSizeCallback(window, window_size_callback);
@endcode ```
The callback function receives the new size, in screen coordinates, of the The callback function receives the new size, in screen coordinates, of the
content area of the window when the window is resized. content area of the window when the window is resized.
@code{.c} ```c
void window_size_callback(GLFWwindow* window, int width, int height) void window_size_callback(GLFWwindow* window, int width, int height)
{ {
} }
@endcode ```
There is also @ref glfwGetWindowSize for directly retrieving the current size of There is also @ref glfwGetWindowSize for directly retrieving the current size of
a window. a window.
@code{.c} ```c
int width, height; int width, height;
glfwGetWindowSize(window, &width, &height); glfwGetWindowSize(window, &width, &height);
@endcode ```
@note Do not pass the window size to `glViewport` or other pixel-based OpenGL @note Do not pass the window size to `glViewport` or other pixel-based OpenGL
calls. The window size is in screen coordinates, not pixels. Use the calls. The window size is in screen coordinates, not pixels. Use the
@ -675,10 +675,10 @@ The above functions work with the size of the content area, but decorated
windows typically have title bars and window frames around this rectangle. You windows typically have title bars and window frames around this rectangle. You
can retrieve the extents of these with @ref glfwGetWindowFrameSize. can retrieve the extents of these with @ref glfwGetWindowFrameSize.
@code{.c} ```c
int left, top, right, bottom; int left, top, right, bottom;
glfwGetWindowFrameSize(window, &left, &top, &right, &bottom); glfwGetWindowFrameSize(window, &left, &top, &right, &bottom);
@endcode ```
The returned values are the distances, in screen coordinates, from the edges of The returned values are the distances, in screen coordinates, from the edges of
the content area to the corresponding edges of the full window. As they are the content area to the corresponding edges of the full window. As they are
@ -696,28 +696,28 @@ pixels, of the framebuffer of a window.
If you wish to be notified when the framebuffer of a window is resized, whether If you wish to be notified when the framebuffer of a window is resized, whether
by the user or the system, set a size callback. by the user or the system, set a size callback.
@code{.c} ```c
glfwSetFramebufferSizeCallback(window, framebuffer_size_callback); glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
@endcode ```
The callback function receives the new size of the framebuffer when it is The callback function receives the new size of the framebuffer when it is
resized, which can for example be used to update the OpenGL viewport. resized, which can for example be used to update the OpenGL viewport.
@code{.c} ```c
void framebuffer_size_callback(GLFWwindow* window, int width, int height) void framebuffer_size_callback(GLFWwindow* window, int width, int height)
{ {
glViewport(0, 0, width, height); glViewport(0, 0, width, height);
} }
@endcode ```
There is also @ref glfwGetFramebufferSize for directly retrieving the current There is also @ref glfwGetFramebufferSize for directly retrieving the current
size of the framebuffer of a window. size of the framebuffer of a window.
@code{.c} ```c
int width, height; int width, height;
glfwGetFramebufferSize(window, &width, &height); glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height); glViewport(0, 0, width, height);
@endcode ```
The size of a framebuffer may change independently of the size of a window, for 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.
@ -728,10 +728,10 @@ example if the window is dragged between a regular monitor and a high-DPI one.
The content scale for a window can be retrieved with @ref The content scale for a window can be retrieved with @ref
glfwGetWindowContentScale. glfwGetWindowContentScale.
@code{.c} ```c
float xscale, yscale; float xscale, yscale;
glfwGetWindowContentScale(window, &xscale, &yscale); glfwGetWindowContentScale(window, &xscale, &yscale);
@endcode ```
The content scale is the ratio between the current DPI and the platform's The content scale is the ratio between the current DPI and the platform's
default DPI. This is especially important for text and any UI elements. If the default DPI. This is especially important for text and any UI elements. If the
@ -748,18 +748,18 @@ If you wish to be notified when the content scale of a window changes, whether
because of a system setting change or because it was moved to a monitor with because of a system setting change or because it was moved to a monitor with
a different scale, set a content scale callback. a different scale, set a content scale callback.
@code{.c} ```c
glfwSetWindowContentScaleCallback(window, window_content_scale_callback); glfwSetWindowContentScaleCallback(window, window_content_scale_callback);
@endcode ```
The callback function receives the new content scale of the window. The callback function receives the new content scale of the window.
@code{.c} ```c
void window_content_scale_callback(GLFWwindow* window, float xscale, float yscale) void window_content_scale_callback(GLFWwindow* window, float xscale, float yscale)
{ {
set_interface_scale(xscale, yscale); set_interface_scale(xscale, yscale);
} }
@endcode ```
On platforms where pixels and screen coordinates always map 1:1, the window On platforms where pixels and screen coordinates always map 1:1, the window
will need to be resized to appear the same size when it is moved to a monitor will need to be resized to appear the same size when it is moved to a monitor
@ -775,16 +775,16 @@ be enforced with @ref glfwSetWindowSizeLimits. The user may resize the window
to any size and aspect ratio within the specified limits, unless the aspect to any size and aspect ratio within the specified limits, unless the aspect
ratio is also set. ratio is also set.
@code{.c} ```c
glfwSetWindowSizeLimits(window, 200, 200, 400, 400); glfwSetWindowSizeLimits(window, 200, 200, 400, 400);
@endcode ```
To specify only a minimum size or only a maximum one, set the other pair to To specify only a minimum size or only a maximum one, set the other pair to
`GLFW_DONT_CARE`. `GLFW_DONT_CARE`.
@code{.c} ```c
glfwSetWindowSizeLimits(window, 640, 480, GLFW_DONT_CARE, GLFW_DONT_CARE); glfwSetWindowSizeLimits(window, 640, 480, GLFW_DONT_CARE, GLFW_DONT_CARE);
@endcode ```
To disable size limits for a window, set them all to `GLFW_DONT_CARE`. To disable size limits for a window, set them all to `GLFW_DONT_CARE`.
@ -793,19 +793,19 @@ with @ref glfwSetWindowAspectRatio. The user may resize the window freely
unless size limits are also set, but the size will be constrained to maintain unless size limits are also set, but the size will be constrained to maintain
the aspect ratio. the aspect ratio.
@code{.c} ```c
glfwSetWindowAspectRatio(window, 16, 9); glfwSetWindowAspectRatio(window, 16, 9);
@endcode ```
The aspect ratio is specified as a numerator and denominator, corresponding to The aspect ratio is specified as a numerator and denominator, corresponding to
the width and height, respectively. If you want a window to maintain its the width and height, respectively. If you want a window to maintain its
current aspect ratio, use its current size as the ratio. current aspect ratio, use its current size as the ratio.
@code{.c} ```c
int width, height; int width, height;
glfwGetWindowSize(window, &width, &height); glfwGetWindowSize(window, &width, &height);
glfwSetWindowAspectRatio(window, width, height); glfwSetWindowAspectRatio(window, width, height);
@endcode ```
To disable the aspect ratio limit for a window, set both terms to To disable the aspect ratio limit for a window, set both terms to
`GLFW_DONT_CARE`. `GLFW_DONT_CARE`.
@ -822,10 +822,10 @@ This is most often the right choice. If you need to create a window at
a specific position, you can set the desired position with the @ref a specific position, you can set the desired position with the @ref
GLFW_POSITION_X and @ref GLFW_POSITION_Y window hints. GLFW_POSITION_X and @ref GLFW_POSITION_Y window hints.
@code{.c} ```c
glfwWindowHint(GLFW_POSITION_X, 70); glfwWindowHint(GLFW_POSITION_X, 70);
glfwWindowHint(GLFW_POSITION_Y, 83); glfwWindowHint(GLFW_POSITION_Y, 83);
@endcode ```
To restore the previous behavior, set these hints to `GLFW_ANY_POSITION`. To restore the previous behavior, set these hints to `GLFW_ANY_POSITION`.
@ -834,33 +834,33 @@ glfwSetWindowPos. This moves the window so that the upper-left corner of its
content area has the specified [screen coordinates](@ref coordinate_systems). content area has the specified [screen coordinates](@ref coordinate_systems).
The window system may put limitations on window placement. The window system may put limitations on window placement.
@code{.c} ```c
glfwSetWindowPos(window, 100, 100); glfwSetWindowPos(window, 100, 100);
@endcode ```
If you wish to be notified when a window is moved, whether by the user, the If you wish to be notified when a window is moved, whether by the user, the
system or your own code, set a position callback. system or your own code, set a position callback.
@code{.c} ```c
glfwSetWindowPosCallback(window, window_pos_callback); glfwSetWindowPosCallback(window, window_pos_callback);
@endcode ```
The callback function receives the new position, in screen coordinates, of the The callback function receives the new position, in screen coordinates, of the
upper-left corner of the content area when the window is moved. upper-left corner of the content area when the window is moved.
@code{.c} ```c
void window_pos_callback(GLFWwindow* window, int xpos, int ypos) void window_pos_callback(GLFWwindow* window, int xpos, int ypos)
{ {
} }
@endcode ```
There is also @ref glfwGetWindowPos for directly retrieving the current position There is also @ref glfwGetWindowPos for directly retrieving the current position
of the content area of the window. of the content area of the window.
@code{.c} ```c
int xpos, ypos; int xpos, ypos;
glfwGetWindowPos(window, &xpos, &ypos); glfwGetWindowPos(window, &xpos, &ypos);
@endcode ```
### Window title {#window_title} ### Window title {#window_title}
@ -869,9 +869,9 @@ 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
set a UTF-8 encoded window title with @ref glfwSetWindowTitle. set a UTF-8 encoded window title with @ref glfwSetWindowTitle.
@code{.c} ```c
glfwSetWindowTitle(window, "My Window"); glfwSetWindowTitle(window, "My Window");
@endcode ```
The specified string is copied before the function returns, so there is no need The specified string is copied before the function returns, so there is no need
to keep it around. to keep it around.
@ -879,15 +879,15 @@ to keep it around.
As long as your source file is encoded as UTF-8, you can use any Unicode As long as your source file is encoded as UTF-8, you can use any Unicode
characters directly in the source. characters directly in the source.
@code{.c} ```c
glfwSetWindowTitle(window, "ラストエグザイル"); glfwSetWindowTitle(window, "ラストエグザイル");
@endcode ```
If you are using C++11 or C11, you can use a UTF-8 string literal. If you are using C++11 or C11, you can use a UTF-8 string literal.
@code{.c} ```c
glfwSetWindowTitle(window, u8"This is always a UTF-8 string"); glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
@endcode ```
### Window icon {#window_icon} ### Window icon {#window_icon}
@ -895,13 +895,13 @@ glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
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.
@code{.c} ```c
GLFWimage images[2]; GLFWimage images[2];
images[0] = load_icon("my_icon.png"); images[0] = load_icon("my_icon.png");
images[1] = load_icon("my_icon_small.png"); images[1] = load_icon("my_icon_small.png");
glfwSetWindowIcon(window, 2, images); glfwSetWindowIcon(window, 2, images);
@endcode ```
The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits
per channel with the red channel first. The pixels are arranged canonically as per channel with the red channel first. The pixels are arranged canonically as
@ -909,9 +909,9 @@ sequential rows, starting from the top-left corner.
To revert to the default window icon, pass in an empty image array. To revert to the default window icon, pass in an empty image array.
@code{.c} ```c
glfwSetWindowIcon(window, 0, NULL); glfwSetWindowIcon(window, 0, NULL);
@endcode ```
### Window monitor {#window_monitor} ### Window monitor {#window_monitor}
@ -919,9 +919,9 @@ glfwSetWindowIcon(window, 0, NULL);
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.
@code{.c} ```c
GLFWmonitor* monitor = glfwGetWindowMonitor(window); GLFWmonitor* monitor = glfwGetWindowMonitor(window);
@endcode ```
This monitor handle is one of those returned by @ref glfwGetMonitors. This monitor handle is one of those returned by @ref glfwGetMonitors.
@ -933,18 +933,18 @@ with @ref glfwSetWindowMonitor. When making a window full screen on the same or
on a different monitor, specify the desired monitor, resolution and refresh on a different monitor, specify the desired monitor, resolution and refresh
rate. The position arguments are ignored. rate. The position arguments are ignored.
@code{.c} ```c
const GLFWvidmode* mode = glfwGetVideoMode(monitor); const GLFWvidmode* mode = glfwGetVideoMode(monitor);
glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate); glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
@endcode ```
When making the window windowed, specify the desired position and size. The When making the window windowed, specify the desired position and size. The
refresh rate argument is ignored. refresh rate argument is ignored.
@code{.c} ```c
glfwSetWindowMonitor(window, NULL, xpos, ypos, width, height, 0); glfwSetWindowMonitor(window, NULL, xpos, ypos, width, height, 0);
@endcode ```
This restores any previous window settings such as whether it is decorated, This restores any previous window settings such as whether it is decorated,
floating, resizable, has size or aspect ratio limits, etc.. To restore a window floating, resizable, has size or aspect ratio limits, etc.. To restore a window
@ -956,9 +956,9 @@ before making it full screen and then pass them in as above.
Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow. Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
@code{.c} ```c
glfwIconifyWindow(window); glfwIconifyWindow(window);
@endcode ```
When a full screen window is iconified, the original video mode of its monitor When a full screen window is iconified, the original video mode of its monitor
is restored until the user or application restores the window. is restored until the user or application restores the window.
@ -966,9 +966,9 @@ is restored until the user or application restores the window.
Iconified windows can be restored with @ref glfwRestoreWindow. This function Iconified windows can be restored with @ref glfwRestoreWindow. This function
also restores windows from maximization. also restores windows from maximization.
@code{.c} ```c
glfwRestoreWindow(window); glfwRestoreWindow(window);
@endcode ```
When a full screen window is restored, the desired video mode is restored to its When a full screen window is restored, the desired video mode is restored to its
monitor as well. monitor as well.
@ -976,13 +976,13 @@ monitor as well.
If you wish to be notified when a window is iconified or restored, whether by If you wish to be notified when a window is iconified or restored, whether by
the user, system or your own code, set an iconify callback. the user, system or your own code, set an iconify callback.
@code{.c} ```c
glfwSetWindowIconifyCallback(window, window_iconify_callback); glfwSetWindowIconifyCallback(window, window_iconify_callback);
@endcode ```
The callback function receives changes in the iconification state of the window. The callback function receives changes in the iconification state of the window.
@code{.c} ```c
void window_iconify_callback(GLFWwindow* window, int iconified) void window_iconify_callback(GLFWwindow* window, int iconified)
{ {
if (iconified) if (iconified)
@ -994,22 +994,22 @@ void window_iconify_callback(GLFWwindow* window, int iconified)
// The window was restored // The window was restored
} }
} }
@endcode ```
You can also get the current iconification state with @ref glfwGetWindowAttrib. You can also get the current iconification state with @ref glfwGetWindowAttrib.
@code{.c} ```c
int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED); int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
@endcode ```
### Window maximization {#window_maximize} ### Window maximization {#window_maximize}
Windows can be maximized (i.e. zoomed) with @ref glfwMaximizeWindow. Windows can be maximized (i.e. zoomed) with @ref glfwMaximizeWindow.
@code{.c} ```c
glfwMaximizeWindow(window); glfwMaximizeWindow(window);
@endcode ```
Full screen windows cannot be maximized and passing a full screen window to this Full screen windows cannot be maximized and passing a full screen window to this
function does nothing. function does nothing.
@ -1017,20 +1017,20 @@ function does nothing.
Maximized windows can be restored with @ref glfwRestoreWindow. This function Maximized windows can be restored with @ref glfwRestoreWindow. This function
also restores windows from iconification. also restores windows from iconification.
@code{.c} ```c
glfwRestoreWindow(window); glfwRestoreWindow(window);
@endcode ```
If you wish to be notified when a window is maximized or restored, whether by If you wish to be notified when a window is maximized or restored, whether by
the user, system or your own code, set a maximize callback. the user, system or your own code, set a maximize callback.
@code{.c} ```c
glfwSetWindowMaximizeCallback(window, window_maximize_callback); glfwSetWindowMaximizeCallback(window, window_maximize_callback);
@endcode ```
The callback function receives changes in the maximization state of the window. The callback function receives changes in the maximization state of the window.
@code{.c} ```c
void window_maximize_callback(GLFWwindow* window, int maximized) void window_maximize_callback(GLFWwindow* window, int maximized)
{ {
if (maximized) if (maximized)
@ -1042,30 +1042,30 @@ void window_maximize_callback(GLFWwindow* window, int maximized)
// The window was restored // The window was restored
} }
} }
@endcode ```
You can also get the current maximization state with @ref glfwGetWindowAttrib. You can also get the current maximization state with @ref glfwGetWindowAttrib.
@code{.c} ```c
int maximized = glfwGetWindowAttrib(window, GLFW_MAXIMIZED); int maximized = glfwGetWindowAttrib(window, GLFW_MAXIMIZED);
@endcode ```
By default, newly created windows are not maximized. You can change this By default, newly created windows are not maximized. You can change this
behavior by setting the [GLFW_MAXIMIZED](@ref GLFW_MAXIMIZED_hint) window hint behavior by setting the [GLFW_MAXIMIZED](@ref GLFW_MAXIMIZED_hint) window hint
before creating the window. before creating the window.
@code{.c} ```c
glfwWindowHint(GLFW_MAXIMIZED, GLFW_TRUE); glfwWindowHint(GLFW_MAXIMIZED, GLFW_TRUE);
@endcode ```
### Window visibility {#window_hide} ### Window visibility {#window_hide}
Windowed mode windows can be hidden with @ref glfwHideWindow. Windowed mode windows can be hidden with @ref glfwHideWindow.
@code{.c} ```c
glfwHideWindow(window); glfwHideWindow(window);
@endcode ```
This makes the window completely invisible to the user, including removing it This makes the window completely invisible to the user, including removing it
from the task bar, dock or window list. Full screen windows cannot be hidden from the task bar, dock or window list. Full screen windows cannot be hidden
@ -1073,9 +1073,9 @@ and calling @ref glfwHideWindow on a full screen window does nothing.
Hidden windows can be shown with @ref glfwShowWindow. Hidden windows can be shown with @ref glfwShowWindow.
@code{.c} ```c
glfwShowWindow(window); glfwShowWindow(window);
@endcode ```
By default, this function will also set the input focus to that window. Set By default, this function will also set the input focus to that window. Set
the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint to change the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint to change
@ -1084,17 +1084,17 @@ existing window with @ref glfwSetWindowAttrib.
You can also get the current visibility state with @ref glfwGetWindowAttrib. You can also get the current visibility state with @ref glfwGetWindowAttrib.
@code{.c} ```c
int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE); int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
@endcode ```
By default, newly created windows are visible. You can change this behavior by By default, newly created windows are visible. You can change this behavior by
setting the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint before creating setting the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window hint before creating
the window. the window.
@code{.c} ```c
glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE); glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);
@endcode ```
Windows created hidden are completely invisible to the user until shown. This Windows created hidden are completely invisible to the user until shown. This
can be useful if you need to set up your window further before showing it, for can be useful if you need to set up your window further before showing it, for
@ -1106,9 +1106,9 @@ example moving it to a specific location.
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.
@code{.c} ```c
glfwFocusWindow(window); glfwFocusWindow(window);
@endcode ```
Keep in mind that it can be very disruptive to the user when a window is forced Keep in mind that it can be very disruptive to the user when a window is forced
to the top. For a less disruptive way of getting the user's attention, see to the top. For a less disruptive way of getting the user's attention, see
@ -1117,13 +1117,13 @@ to the top. For a less disruptive way of getting the user's attention, see
If you wish to be notified when a window gains or loses input focus, whether by If you wish to be notified when a window gains or loses input focus, whether by
the user, system or your own code, set a focus callback. the user, system or your own code, set a focus callback.
@code{.c} ```c
glfwSetWindowFocusCallback(window, window_focus_callback); glfwSetWindowFocusCallback(window, window_focus_callback);
@endcode ```
The callback function receives changes in the input focus state of the window. The callback function receives changes in the input focus state of the window.
@code{.c} ```c
void window_focus_callback(GLFWwindow* window, int focused) void window_focus_callback(GLFWwindow* window, int focused)
{ {
if (focused) if (focused)
@ -1135,21 +1135,21 @@ void window_focus_callback(GLFWwindow* window, int focused)
// The window lost input focus // The window lost input focus
} }
} }
@endcode ```
You can also get the current input focus state with @ref glfwGetWindowAttrib. You can also get the current input focus state with @ref glfwGetWindowAttrib.
@code{.c} ```c
int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED); int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
@endcode ```
By default, newly created windows are given input focus. You can change this By default, newly created windows are given input focus. You can change this
behavior by setting the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) window hint behavior by setting the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) window hint
before creating the window. before creating the window.
@code{.c} ```c
glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE); glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE);
@endcode ```
### Window attention request {#window_attention} ### Window attention request {#window_attention}
@ -1157,9 +1157,9 @@ glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE);
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.
@code{.c} ```c
glfwRequestWindowAttention(window); glfwRequestWindowAttention(window);
@endcode ```
The system will highlight the specified window, or on platforms where this is The system will highlight the specified window, or on platforms where this is
not supported, the application as a whole. Once the user has given it not supported, the application as a whole. Once the user has given it
@ -1171,20 +1171,20 @@ attention, the system will automatically end the request.
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.
@code{.c} ```c
glfwSetWindowRefreshCallback(m_handle, window_refresh_callback); glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
@endcode ```
The callback function is called when the contents of the window needs to be The callback function is called when the contents of the window needs to be
refreshed. refreshed.
@code{.c} ```c
void window_refresh_callback(GLFWwindow* window) void window_refresh_callback(GLFWwindow* window)
{ {
draw_editor_ui(window); draw_editor_ui(window);
glfwSwapBuffers(window); glfwSwapBuffers(window);
} }
@endcode ```
@note On compositing window systems such as Aero, Compiz or Aqua, where the @note On compositing window systems such as Aero, Compiz or Aqua, where the
window contents are saved off-screen, this callback might only be called when window contents are saved off-screen, this callback might only be called when
@ -1205,9 +1205,9 @@ Window framebuffers can be made transparent on a per-pixel per-frame basis with
the [GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) the [GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint)
window hint. window hint.
@code{.c} ```c
glfwWindowHint(GLFW_TRANSPARENT_FRAMEBUFFER, GLFW_TRUE); glfwWindowHint(GLFW_TRANSPARENT_FRAMEBUFFER, GLFW_TRUE);
@endcode ```
If supported by the system, the window content area will be composited with the If supported by the system, the window content area will be composited with the
background using the framebuffer per-pixel alpha channel. This requires desktop background using the framebuffer per-pixel alpha channel. This requires desktop
@ -1218,21 +1218,21 @@ with the
[GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_attrib) [GLFW_TRANSPARENT_FRAMEBUFFER](@ref GLFW_TRANSPARENT_FRAMEBUFFER_attrib)
window attribute. window attribute.
@code{.c} ```c
if (glfwGetWindowAttrib(window, GLFW_TRANSPARENT_FRAMEBUFFER)) if (glfwGetWindowAttrib(window, GLFW_TRANSPARENT_FRAMEBUFFER))
{ {
// window framebuffer is currently transparent // window framebuffer is currently transparent
} }
@endcode ```
GLFW comes with an example that enabled framebuffer transparency called `gears`. GLFW comes with an example that enabled framebuffer transparency called `gears`.
The opacity of the whole window, including any decorations, can be set with @ref The opacity of the whole window, including any decorations, can be set with @ref
glfwSetWindowOpacity. glfwSetWindowOpacity.
@code{.c} ```c
glfwSetWindowOpacity(window, 0.5f); glfwSetWindowOpacity(window, 0.5f);
@endcode ```
The opacity (or alpha) value is a positive finite number between zero and one, The opacity (or alpha) value is a positive finite number between zero and one,
where 0 (zero) is fully transparent and 1 (one) is fully opaque. The initial where 0 (zero) is fully transparent and 1 (one) is fully opaque. The initial
@ -1240,9 +1240,9 @@ opacity value for newly created windows is 1.
The current opacity of a window can be queried with @ref glfwGetWindowOpacity. The current opacity of a window can be queried with @ref glfwGetWindowOpacity.
@code{.c} ```c
float opacity = glfwGetWindowOpacity(window); float opacity = glfwGetWindowOpacity(window);
@endcode ```
If the system does not support whole window transparency, this function always If the system does not support whole window transparency, this function always
returns one. returns one.
@ -1263,12 +1263,12 @@ interaction, (e.g. whether it has input focus), while others reflect inherent
properties of the window (e.g. what kind of border it has). Some are related to properties of the window (e.g. what kind of border it has). Some are related to
the window and others to its OpenGL or OpenGL ES context. the window and others to its OpenGL or OpenGL ES context.
@code{.c} ```c
if (glfwGetWindowAttrib(window, GLFW_FOCUSED)) if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
{ {
// window has input focus // window has input focus
} }
@endcode ```
The [GLFW_DECORATED](@ref GLFW_DECORATED_attrib), The [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
[GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib), [GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib),
@ -1277,9 +1277,9 @@ The [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
[GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib) window attributes can be [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib) window attributes can be
changed with @ref glfwSetWindowAttrib. changed with @ref glfwSetWindowAttrib.
@code{.c} ```c
glfwSetWindowAttrib(window, GLFW_RESIZABLE, GLFW_FALSE); glfwSetWindowAttrib(window, GLFW_RESIZABLE, GLFW_FALSE);
@endcode ```
@ -1463,18 +1463,18 @@ When the entire frame has been rendered, it is time to swap the back and the
front buffers in order to display what has been rendered and begin rendering front buffers in order to display what has been rendered and begin rendering
a new frame. This is done with @ref glfwSwapBuffers. a new frame. This is done with @ref glfwSwapBuffers.
@code{.c} ```c
glfwSwapBuffers(window); glfwSwapBuffers(window);
@endcode ```
Sometimes it can be useful to select when the buffer swap will occur. With the Sometimes it can be useful to select when the buffer swap will occur. With the
function @ref glfwSwapInterval it is possible to select the minimum number of function @ref glfwSwapInterval it is possible to select the minimum number of
monitor refreshes the driver should wait from the time @ref glfwSwapBuffers was monitor refreshes the driver should wait from the time @ref glfwSwapBuffers was
called before swapping the buffers: called before swapping the buffers:
@code{.c} ```c
glfwSwapInterval(1); glfwSwapInterval(1);
@endcode ```
If the interval is zero, the swap will take place immediately when @ref If the interval is zero, the swap will take place immediately when @ref
glfwSwapBuffers is called without waiting for a refresh. Otherwise at least glfwSwapBuffers is called without waiting for a refresh. Otherwise at least