Documentation work.

This commit is contained in:
Camilla Berglund 2014-10-02 17:35:10 +02:00
parent 4dd669661b
commit 95654cfada
13 changed files with 207 additions and 153 deletions

View File

@ -35,21 +35,21 @@ with the entire Win32 API.
Instead, the GLFW header takes care of this for you, not by including Instead, the GLFW header takes care of this for you, not by including
`windows.h`, but by duplicating only the very few necessary parts of it. It `windows.h`, but by duplicating only the very few necessary parts of it. It
does this only when needed, so if `windows.h` *is* included, the GLFW header does this only when needed, so if `windows.h` _is_ included, the GLFW header
does not try to redefine those symbols. The reverse is not true, i.e. does not try to redefine those symbols. The reverse is not true, i.e.
`windows.h` cannot cope if any of its symbols have already been defined. `windows.h` cannot cope if any of its symbols have already been defined.
In other words: In other words:
- Do *not* include the OpenGL headers yourself, as GLFW does this for you - Do _not_ include the OpenGL headers yourself, as GLFW does this for you
- Do *not* include `windows.h` or other platform-specific headers unless you - Do _not_ include `windows.h` or other platform-specific headers unless you
plan on using those APIs directly plan on using those APIs directly
- If you *do* need to include such headers, do it *before* including - If you _do_ need to include such headers, do it _before_ including
the GLFW header and it will handle this the GLFW header and it will handle this
If you are using an OpenGL extension loading library such as If you are using an OpenGL extension loading library such as
[glad](https://github.com/Dav1dde/glad), the extension loader header should [glad](https://github.com/Dav1dde/glad), the extension loader header should
either be included *before* the GLFW one, or the `GLFW_INCLUDE_NONE` macro either be included _before_ the GLFW one, or the `GLFW_INCLUDE_NONE` macro
(described below) should be defined. (described below) should be defined.
@ -85,7 +85,7 @@ header. This is useful in combination with an extension loading library.
If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h` If none of the above inclusion macros are defined, the standard OpenGL `GL/gl.h`
header (`OpenGL/gl.h` on OS X) is included. header (`OpenGL/gl.h` on OS X) is included.
`GLFW_INCLUDE_GLU` makes the header include the GLU header *in addition to* the `GLFW_INCLUDE_GLU` makes the header include the GLU header _in addition to_ the
header selected above. This should only be used with legacy code. GLU has been header selected above. This should only be used with legacy code. GLU has been
deprecated and should not be used in new code. deprecated and should not be used in new code.
@ -124,7 +124,7 @@ set of default libraries along with other dependencies like `user32` and
The link library for the GLFW DLL is named `glfw3dll`. When compiling an The link library for the GLFW DLL is named `glfw3dll`. When compiling an
application that uses the DLL version of GLFW, you need to define the `GLFW_DLL` application that uses the DLL version of GLFW, you need to define the `GLFW_DLL`
macro *before* any inclusion of the GLFW header. This can be done either with macro _before_ any inclusion of the GLFW header. This can be done either with
a compiler switch or by defining it in your source code. a compiler switch or by defining it in your source code.
An application using the GLFW DLL does not need to link against any of its An application using the GLFW DLL does not need to link against any of its
@ -293,6 +293,6 @@ against it from the command-line.
The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
special to do when using GLU. Also note that even though your machine may have special to do when using GLU. Also note that even though your machine may have
`libGL`-style OpenGL libraries, they are for use with the X Window System and `libGL`-style OpenGL libraries, they are for use with the X Window System and
will *not* work with the OS X native version of GLFW. will _not_ work with the OS X native version of GLFW.
*/ */

View File

@ -9,7 +9,7 @@ It lists what are essentially implementation details, but which are nonetheless
vital knowledge for developers intending to deploy their applications on a wide vital knowledge for developers intending to deploy their applications on a wide
range of machines. range of machines.
@note The information in this guide is not a part of GLFW API, but merely The information in this guide is not a part of GLFW API, but merely
preconditions for some parts of the library to function on a given machine. Any preconditions for some parts of the library to function on a given machine. Any
part of this information may change in future versions of GLFW and that will not part of this information may change in future versions of GLFW and that will not
be considered a breaking API change. be considered a breaking API change.

View File

@ -92,8 +92,8 @@ example, on Ubuntu and other distributions based on Debian GNU/Linux, you need
to install the `xorg-dev` and `libglu1-mesa-dev` packages. The former pulls in to install the `xorg-dev` and `libglu1-mesa-dev` packages. The former pulls in
all X.org header packages and the latter pulls in the Mesa OpenGL and GLU all X.org header packages and the latter pulls in the Mesa OpenGL and GLU
packages. GLFW itself doesn't need or use GLU, but some of the examples do. packages. GLFW itself doesn't need or use GLU, but some of the examples do.
Note that using header files and libraries from Mesa during compilation *will Note that using header files and libraries from Mesa during compilation
not* tie your binaries to the Mesa implementation of OpenGL. _will not_ tie your binaries to the Mesa implementation of OpenGL.
Once you have installed the necessary packages, move on to @ref Once you have installed the necessary packages, move on to @ref
compile_generate. compile_generate.
@ -103,8 +103,8 @@ compile_generate.
Once you have all necessary dependencies it is time to generate the project Once you have all necessary dependencies it is time to generate the project
files or makefiles for your development environment. CMake needs to know two files or makefiles for your development environment. CMake needs to know two
paths for this: the path to the *root* directory of the GLFW source tree (i.e. paths for this: the path to the _root_ directory of the GLFW source tree (i.e.
*not* the `src` subdirectory) and the target path for the generated files and _not_ the `src` subdirectory) and the target path for the generated files and
compiled binaries. If these are the same, it is called an in-tree build, compiled binaries. If these are the same, it is called an in-tree build,
otherwise it is called an out-of-tree build. otherwise it is called an out-of-tree build.
@ -117,8 +117,8 @@ to compile the GLFW library, not about compiling the actual library.
@subsubsection compile_generate_cli Generating files with the CMake command-line tool @subsubsection compile_generate_cli Generating files with the CMake command-line tool
To make an in-tree build, enter the *root* directory of the GLFW source tree To make an in-tree build, enter the _root_ directory of the GLFW source tree
(i.e. *not* the `src` subdirectory) and run CMake. The current directory is (i.e. _not_ the `src` subdirectory) and run CMake. The current directory is
used as target path, while the path provided as an argument is used to find the used as target path, while the path provided as an argument is used to find the
source tree. source tree.
@ -146,8 +146,8 @@ development environment, move on to @ref compile_compile.
If you are using the GUI version, choose the root of the GLFW source tree as If you are using the GUI version, choose the root of the GLFW source tree as
source location and the same directory or another, empty directory as the source location and the same directory or another, empty directory as the
destination for binaries. Choose *Configure*, change any options you wish to, destination for binaries. Choose _Configure_, change any options you wish to,
*Configure* again to let the changes take effect and then *Generate*. _Configure_ again to let the changes take effect and then _Generate_.
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.
@ -252,7 +252,7 @@ defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
`internal.h`. Without this macro, GLFW will expect the necessary configuration `internal.h`. Without this macro, GLFW will expect the necessary configuration
macros to be defined on the command-line. macros to be defined on the command-line.
Three macros *must* be defined when compiling GLFW: one for selecting the window Three macros _must_ be defined when compiling GLFW: one for selecting the window
creation API, one selecting the context creation API and one client library. creation API, one selecting the context creation API and one client library.
Exactly one of each kind must be defined for GLFW to compile and link. Exactly one of each kind must be defined for GLFW to compile and link.
@ -289,7 +289,7 @@ libraries.
If you are building GLFW as a shared library / dynamic library / DLL then you If you are building GLFW as a shared library / dynamic library / DLL then you
must also define `_GLFW_BUILD_DLL`. Otherwise, you may not define it. must also define `_GLFW_BUILD_DLL`. Otherwise, you may not define it.
If you are using the X11 window creation API then you *must* also select an entry If you are using the X11 window creation API then you _must_ also select an entry
point retrieval mechanism. point retrieval mechanism.
- `_GLFW_HAS_GLXGETPROCADDRESS` to use `glXGetProcAddress` (recommended) - `_GLFW_HAS_GLXGETPROCADDRESS` to use `glXGetProcAddress` (recommended)

View File

@ -50,8 +50,8 @@ requests that all types are shared.
See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or See the relevant chapter of the [OpenGL](https://www.opengl.org/registry/) or
[OpenGL ES](http://www.khronos.org/opengles/) reference documents for more [OpenGL ES](http://www.khronos.org/opengles/) reference documents for more
information. The name and number of this chapter unfortunately varies between information. The name and number of this chapter unfortunately varies between
versions and APIs, but has at times been named *Shared Objects and Multiple versions and APIs, but has at times been named _Shared Objects and Multiple
Contexts*. Contexts_.
GLFW comes with a simple object sharing test program called `sharing`. GLFW comes with a simple object sharing test program called `sharing`.

View File

@ -65,7 +65,7 @@ glfwPostEmptyEvent.
glfwPostEmptyEvent(); glfwPostEmptyEvent();
@endcode @endcode
Do not assume that callbacks will *only* be called through either of the above Do not assume that callbacks will _only_ be called through either of the above
functions. While it is necessary to process events in the event queue, some functions. While it is necessary to process events in the event queue, some
window systems will send some events directly to the application, which in turn window systems will send some events directly to the application, which in turn
causes callbacks to be called outside of regular event processing. causes callbacks to be called outside of regular event processing.
@ -86,7 +86,7 @@ same keyboard layout, input method or even operating system as you.
@subsection input_key Key input @subsection input_key Key input
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 with @ref glfwSetKeyCallback. repeats, set a key callback.
@code @code
glfwSetKeyCallback(window, key_callback); glfwSetKeyCallback(window, key_callback);
@ -110,7 +110,7 @@ have unique, if platform-specific scancodes.
The scancode is unique for every key but is platform-specific, so a scancode The scancode is unique for every key but is platform-specific, so a scancode
will map to different keys on different platforms. will map to different keys on different platforms.
The key will be `GLFW_KEY_UNKNOWN` for special keys like *E-mail* or *Play* that The key will be `GLFW_KEY_UNKNOWN` for special keys like _E-mail_ or _Play_ that
don't have a key token. Those keys will still have unique, if platform-specific don't have a key token. Those keys will still have unique, if platform-specific
scancodes. scancodes.
@ -148,8 +148,7 @@ The `GLFW_KEY_LAST` constant holds the highest value of any
@subsection input_char Unicode character input @subsection input_char Unicode character input
If you wish to receive Unicode code point input, set a character callback with If you wish to receive Unicode code point input, set a character callback.
@ref glfwSetCharCallback.
@code @code
glfwSetCharCallback(window, character_callback); glfwSetCharCallback(window, character_callback);
@ -166,7 +165,7 @@ void character_callback(GLFWwindow* window, unsigned int codepoint)
If you wish to receive all Unicode code point events generated by the system, or If you wish to receive all Unicode code point events generated by the system, or
just want to know exactly what modifier keys were used, set a character with just want to know exactly what modifier keys were used, set a character with
modifiers callback with @ref glfwSetCharModsCallback. modifiers callback.
@code @code
glfwSetCharCallback(window, charmods_callback); glfwSetCharCallback(window, charmods_callback);
@ -192,7 +191,7 @@ these are supported by GLFW.
@subsection input_cursor_pos Cursor position @subsection input_cursor_pos Cursor position
If you wish to be notified when the system cursor moves over the window, set If you wish to be notified when the system cursor moves over the window, set
a cursor position callback with @ref glfwSetCursorPosCallback. a cursor position callback.
@code @code
glfwSetCursorPosCallback(window, cursor_pos_callback); glfwSetCursorPosCallback(window, cursor_pos_callback);
@ -287,6 +286,9 @@ image.pixels = pixels;
GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0); GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
@endcode @endcode
If cursor creation fails, `NULL` will be returned, so it is necessary to check
the return value.
The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are
arranged canonically as sequental rows, starting from the top-left corner. arranged canonically as sequental rows, starting from the top-left corner.
@ -299,7 +301,7 @@ When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
glfwDestroyCursor(cursor); glfwDestroyCursor(cursor);
@endcode @endcode
Cursor destruction always succeeds. All cursors remaining at the time of @ref Cursor destruction always succeeds. All cursors remaining when @ref
glfwTerminate is called are destroyed as well. glfwTerminate is called are destroyed as well.
@ -330,7 +332,7 @@ does not affect the cursor modes of those windows.
@subsection input_cursor_enter Cursor enter/leave events @subsection input_cursor_enter Cursor enter/leave events
If you wish to be notified when the cursor enters or leaves the client area of If you wish to be notified when the cursor enters or leaves the client area of
a window, set a cursor enter/leave callback with @ref glfwSetCursorEnterCallback. a window, set a cursor enter/leave callback.
@code @code
glfwSetCursorEnterCallback(window, cursor_enter_callback); glfwSetCursorEnterCallback(window, cursor_enter_callback);
@ -356,7 +358,7 @@ void cursor_enter_callback(GLFWwindow* window, int entered)
@subsection input_mouse_button Mouse button input @subsection input_mouse_button Mouse button input
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 with @ref glfwSetMouseButtonCallback. a mouse button callback.
@code @code
glfwSetMouseButtonCallback(window, mouse_button_callback); glfwSetMouseButtonCallback(window, mouse_button_callback);
@ -412,7 +414,7 @@ The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
@subsection input_scroll Scroll input @subsection input_scroll Scroll input
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 with @ref glfwSetScrollCallback. touchpad gesture, set a scroll callback.
@code @code
glfwSetScrollCallback(window, scroll_callback); glfwSetScrollCallback(window, scroll_callback);
@ -539,7 +541,7 @@ window may be used.
@section input_drop Path drop input @section input_drop Path drop input
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 with @ref glfwSetDropCallback. a window, set a file drop callback.
@code @code
glfwSetDropCallback(window, drop_callback); glfwSetDropCallback(window, drop_callback);

View File

@ -78,7 +78,7 @@ additional calls return immediately.
@section error_handling Error handling @section error_handling Error handling
Some GLFW functions have return values that indicate an error, but this is often Some GLFW functions have return values that indicate an error, but this is often
not very helpful when trying to figure out *why* the error occurred. Some not very helpful when trying to figure out _why_ the error occurred. Some
functions also return otherwise valid values on error. Finally, far from all functions also return otherwise valid values on error. Finally, far from all
GLFW functions have return values. GLFW functions have return values.

View File

@ -18,11 +18,11 @@ API.
There are guides for each of the various areas of the API. There are guides for each of the various areas of the API.
- @ref intro - @ref intro initialization, error handling and high-level design
- @ref window - @ref window creating and working with windows and framebuffers
- @ref context - @ref context working with OpenGL and OpenGL ES contexts
- @ref monitor - @ref monitor enumerating and working with monitors and video modes
- @ref input - @ref input receiving events, polling and processing input
The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the The [FAQ](http://www.glfw.org/faq.html) answers many common questions about the
design, implementation and use of GLFW. design, implementation and use of GLFW.

View File

@ -24,9 +24,9 @@ a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
application and retain their addresses until the monitors they represent are application and retain their addresses until the monitors they represent are
disconnected or until the library is [terminated](@ref intro_init_terminate). disconnected or until the library is [terminated](@ref intro_init_terminate).
Each monitor has a human-readable name, a current video mode, a list of Each monitor has a current video mode, a list of supported video modes,
supported video modes, a virtual position, an estimated physical size and a virtual position, a human-readable name, an estimated physical size and
a gamma ramp. a gamma ramp. One of the monitors is the primary monitor.
The virtual position of a monitor is in screen coordinates and, together with The virtual position of a monitor is in screen coordinates and, together with
the current video mode, describes the viewports that the connected monitors the current video mode, describes the viewports that the connected monitors
@ -37,7 +37,7 @@ provide into the virtual desktop that spans them.
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's
preferred monitor and is usually the one with global UI elements like task bar preferred monitor and is usually the one with global UI elements like task bar
or menu bar. The returned structure is allocated and freed by GLFW. or menu bar.
@code @code
GLFWmonitor* primary = glfwGetPrimaryMonitor(); GLFWmonitor* primary = glfwGetPrimaryMonitor();
@ -59,7 +59,7 @@ disconnected.
@subsection monitor_event Monitor configuration changes @subsection monitor_event Monitor configuration changes
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 with @ref glfwSetMonitorCallback. a monitor callback.
@code @code
glfwSetMonitorCallback(monitor_callback); glfwSetMonitorCallback(monitor_callback);
@ -79,6 +79,11 @@ The action is one of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
@section monitor_properties Monitor properties @section monitor_properties Monitor properties
Each monitor has a current video mode, a list of supported video modes,
a virtual position, a human-readable name, an estimated physical size and
a gamma ramp.
@subsection monitor_modes Video modes @subsection monitor_modes Video modes
Although GLFW generally does a good job at selecting a suitable video Although GLFW generally does a good job at selecting a suitable video
@ -87,7 +92,7 @@ know exactly which modes are available on a certain system. For example,
you may want to present the user with a list of video modes to select you may want to present the user with a list of video modes to select
from. from.
To get a list of available video modes, you can use the function @ref To get a list of supported video modes, you can use the function @ref
glfwGetVideoModes. See the reference documentation for the lifetime of the glfwGetVideoModes. See the reference documentation for the lifetime of the
returned array. returned array.

View File

@ -5,7 +5,7 @@
@tableofcontents @tableofcontents
This is a transition guide for moving from GLFW 2 to 3. It describes what has This is a transition guide for moving from GLFW 2 to 3. It describes what has
changed or been removed, but does *not* include changed or been removed, but does _not_ include
[new features](@ref news) unless they are required when moving an existing code [new features](@ref news) unless they are required when moving an existing code
base onto the new API. For example, the new multi-monitor functions are base onto the new API. For example, the new multi-monitor functions are
required to create full screen windows with GLFW 3. required to create full screen windows with GLFW 3.
@ -50,7 +50,7 @@ the original author of GLFW. These libraries implement a usable subset of the
threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
TinyCThread. TinyCThread.
However, GLFW 3 has better support for *use from multiple threads* than GLFW However, GLFW 3 has better support for _use from multiple threads_ than GLFW
2 had. Contexts can be made current on any thread, although only a single 2 had. Contexts can be made current on any thread, although only a single
thread at a time, and the documentation explicitly states which functions may be thread at a time, and the documentation explicitly states which functions may be
used from any thread and which may only be used from the main thread. used from any thread and which may only be used from the main thread.
@ -149,7 +149,7 @@ into [window hints](@ref window_hints), but as they have been given
GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
Unlike buffer swap, which acts on a single window, **glfwPollEvents** and Unlike buffer swap, which acts on a single window, __glfwPollEvents__ and
__glfwWaitEvents__ process events for all windows at once. __glfwWaitEvents__ process events for all windows at once.
@par Old basic main loop @par Old basic main loop
@ -428,8 +428,8 @@ invalidating any window handles you may still have.
@subsection moving_glu GLU header inclusion @subsection moving_glu GLU header inclusion
GLFW 3 does not by default include the GLU header and GLU itself has been GLFW 3 does not by default include the GLU header and GLU itself has been
deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). **New deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New
projects should avoid using GLU**, but if you need to compile legacy code that projects should avoid using GLU__, but if you need to compile legacy code that
has been moved to GLFW 3, you can request that the GLFW header includes it by has been moved to GLFW 3, you can request that the GLFW header includes it by
defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW header. defining `GLFW_INCLUDE_GLU` before the inclusion of the GLFW header.

View File

@ -139,7 +139,7 @@ glfwSetGamma, which generates a ramp from a gamma value and then sets it.
GLFW now supports the creation of OpenGL ES contexts, by setting the GLFW now supports the creation of OpenGL ES contexts, by setting the
`GLFW_CLIENT_API` window hint to `GLFW_OPENGL_ES_API`, where creation of such `GLFW_CLIENT_API` window hint to `GLFW_OPENGL_ES_API`, where creation of such
contexts are supported. Note that GLFW *does not implement* OpenGL ES, so your contexts are supported. Note that GLFW _does not implement_ OpenGL ES, so your
driver must provide support in a way usable by GLFW. Modern nVidia and Intel driver must provide support in a way usable by GLFW. Modern nVidia and Intel
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
AMD provides an EGL implementation instead. AMD provides an EGL implementation instead.

View File

@ -35,15 +35,15 @@ and pollute your code's namespace with the whole Win32 API.
Instead, the GLFW header takes care of this for you, not by including Instead, the GLFW header takes care of this for you, not by including
`windows.h`, but rather by itself duplicating only the necessary parts of it. `windows.h`, but rather by itself duplicating only the necessary parts of it.
It does this only where needed, so if `windows.h` *is* included, the GLFW header It does this only where needed, so if `windows.h` _is_ included, the GLFW header
does not try to redefine those symbols. does not try to redefine those symbols.
In other words: In other words:
- Do *not* include the OpenGL headers yourself, as GLFW does this for you - Do _not_ include the OpenGL headers yourself, as GLFW does this for you
- Do *not* include `windows.h` or other platform-specific headers unless - Do _not_ include `windows.h` or other platform-specific headers unless
you plan on using those APIs directly you plan on using those APIs directly
- If you *do* need to include such headers, do it *before* including the - If you _do_ need to include such headers, do it _before_ including the
GLFW one and it will detect this GLFW one and it will detect this
Starting with version 3.0, the GLU header `glu.h` is no longer included by Starting with version 3.0, the GLU header `glu.h` is no longer included by
@ -162,7 +162,7 @@ Each window has a flag indicating whether the window should be closed.
When the user attempts to close the window, either by pressing the close widget When the user attempts to close the window, either by pressing the close widget
in the title bar or using a key combination like Alt+F4, this flag is set to 1. in the title bar or using a key combination like Alt+F4, this flag is set to 1.
Note that **the window isn't actually closed**, so you are expected to monitor 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.
@ -248,7 +248,7 @@ glfwSwapBuffers(window);
@endcode @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
buffer swapping will occur immediately. On fast machines, many of those frames buffer swapping will occur immediately. On fast machines, many of those frames
will never be seen, as the screen is still only updated typically 60-75 times will never be seen, as the screen is still only updated typically 60-75 times
per second, so this wastes a lot of CPU and GPU cycles. per second, so this wastes a lot of CPU and GPU cycles.

View File

@ -38,32 +38,65 @@ GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
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.
@code
if (!window)
{
// Handle window creation failure
}
@endcode
The window handle is passed to all window related functions and is provided to The window handle is passed to all window related functions and is provided to
along with all input events, so event handlers can tell which window received along with all input events, so event handlers can tell which window received
the event. the event.
@subsubsection window_full_screen Full screen windows
To create a full screen window, you need to specify which monitor the window To create a full screen window, you need to specify which monitor the window
should use. In most cases, the user's primary monitor is a good choice. You should use. In most cases, the user's primary monitor is a good choice.
can get this with @ref glfwGetPrimaryMonitor. For more information about For more information about retrieving monitors, see @ref monitor_monitors.
monitors, see the @ref monitor.
@code @code
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL); GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
@endcode @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, and change the monitor's resolution to the one most closely or decorations.
matching the requested window size.
For more control over how the window and its context are created, see @ref The requested window size combined with the window hints below form the _desired
window_hints below. video mode_. The supported video mode most closely matching the desired video
mode will be set for the chosen monitor as long as the window is focused. For
more information about video modes supported by a monitor, see @ref
monitor_modes.
Video mode field | Corresponds to
----------------------- | ------------------------
GLFWvidmode.width | `width` parameter
GLFWvidmode.height | `height` parameter
GLFWvidmode.redBits | `GLFW_RED_BITS` hint
GLFWvidmode.greenBits | `GLFW_GREEN_BITS` hint
GLFWvidmode.blueBits | `GLFW_BLUE_BITS` hint
GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint
Once you have a full screen window, you can change its resolution with @ref
glfwSetWindowSize. The new video mode will be selected and set the same way as
the video mode chosen by @ref glfwCreateWindow.
By default, the original video mode of the monitor will be restored and the
window iconified if it loses input focus, to allow the user to switch back to
the desktop. This can be disabled with the `GLFW_AUTO_ICONIFY` window hint, for
example if you wish to simultaneously cover multiple windows with full screen
windows.
To create a so called _windowed full screen_ or _borderless full screen_ window,
i.e. a full screen window that doesn't change the video mode of the monitor, you
need to request the current video mode of the chosen monitor.
@code
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
glfwWindowHint(GLFW_RED_BITS, mode->redBits);
glfwWindowHint(GLFW_GREEN_BITS, mode->greenBits);
glfwWindowHint(GLFW_BLUE_BITS, mode->blueBits);
glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate);
GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL);
@endcode
GLFW will detect this and will not perform any mode setting for that window.
@subsection window_destruction Window destruction @subsection window_destruction Window destruction
@ -80,8 +113,7 @@ callbacks are removed so no further events will be delivered for the window.
When a full screen window is destroyed, the original video mode of its monitor When a full screen window is destroyed, the original video mode of its monitor
is restored, but the gamma ramp is left untouched. is restored, but the gamma ramp is left untouched.
All windows remaining at the time @ref glfwTerminate is called are destroyed as All windows remaining when @ref glfwTerminate is called are destroyed as well.
well.
@subsection window_hints Window creation hints @subsection window_hints Window creation hints
@ -92,14 +124,14 @@ context. These hints are set to their default values each time the library is
initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
and reset all at once to their defaults with @ref glfwDefaultWindowHints. and reset all at once to their defaults with @ref glfwDefaultWindowHints.
Note that hints need to be set *before* the creation of the window and context Note that hints need to be set _before_ the creation of the window and context
you wish to have the specified attributes. you wish to have the specified attributes.
@subsubsection window_hints_hard Hard and soft constraints @subsubsection window_hints_hard Hard and soft constraints
Some window hints are hard constraints. These must match the available Some window hints are hard constraints. These must match the available
capabilities *exactly* for window and context creation to succeed. Hints capabilities _exactly_ for window and context creation to succeed. Hints
that are not hard constraints are matched as closely as possible, but the that are not hard constraints are matched as closely as possible, but the
resulting window and context may differ from what these hints requested. To resulting window and context may differ from what these hints requested. To
find out the actual attributes of the created window and context, use the find out the actual attributes of the created window and context, use the
@ -119,7 +151,7 @@ context, but are ignored when requesting an OpenGL ES context:
@subsubsection window_hints_wnd Window related hints @subsubsection window_hints_wnd Window related hints
`GLFW_RESIZABLE` specifies whether the (windowed mode) window will be resizable `GLFW_RESIZABLE` specifies whether the (windowed mode) window will be resizable
*by the user*. The window will still be resizable using the @ref _by the user_. The window will still be resizable using the @ref
glfwSetWindowSize function. This hint is ignored for full screen windows. glfwSetWindowSize function. This hint is ignored for full screen windows.
`GLFW_VISIBLE` specifies whether the (windowed mode) window will be initially `GLFW_VISIBLE` specifies whether the (windowed mode) window will be initially
@ -306,7 +338,7 @@ The initial value of the pointer is `NULL`.
@subsection window_close Closing and close flag @subsection window_close Closing and close flag
When the user attempts to close the window, for example by clicking the close When the user attempts to close the window, for example by clicking the close
widget or using a key chord like Alt+F4, the *close flag* of the window is set. widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
The window is however not actually destroyed and, unless you watch for this The window is however not actually destroyed and, unless you watch for this
state change, nothing further happens. state change, nothing further happens.
@ -325,13 +357,13 @@ while (!glfwWindowShouldClose(window))
@endcode @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 with @ref glfwSetWindowCloseCallback. callback.
@code @code
glfwSetWindowCloseCallback(window, window_close_callback); glfwSetWindowCloseCallback(window, window_close_callback);
@endcode @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.
@ -344,20 +376,23 @@ void window_close_callback(GLFWwindow* window)
@endcode @endcode
@subsection window_size Client area size @subsection window_size Size
The size of a window can be changed with @ref glfwSetWindowSize. For windowed The size of a window can be changed with @ref glfwSetWindowSize. For windowed
mode windows, this resizes the window so that its *client area* has the mode windows, this sets the size of the _client area_ or _content area_ of the
specified size. The window system may impose limits on window size. For full window. The window system may impose limits on window size.
screen windows, it selects and sets the video mode most closely matching the
specified size and the color bit depth and refresh rate hints set at creation.
@code @code
void glfwSetWindowSize(window, 640, 480); glfwSetWindowSize(window, 640, 480);
@endcode @endcode
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
desired video mode is set immediately. The window is resized to fit the
resolution of the set video mode.
If you wish to be notified when a window is resized, whether by the user or If you wish to be notified when a window is resized, whether by the user or
the system, set a size callback with @ref glfwSetWindowSizeCallback. the system, set a size callback.
@code @code
glfwSetWindowSizeCallback(window, window_size_callback); glfwSetWindowSizeCallback(window, window_size_callback);
@ -409,8 +444,7 @@ a second set of functions to retrieve the size in pixels of the framebuffer of
a window. 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 with @ref by the user or the system, set a size callback.
glfwSetFramebufferSizeCallback.
@code @code
glfwSetFramebufferSizeCallback(window, framebuffer_size_callback); glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
@ -452,7 +486,7 @@ glfwSetWindowPos(window, 100, 100);
@endcode @endcode
If you wish to be notified when a window is moved, whether by the user, system If you wish to be notified when a window is moved, whether by the user, system
or your own code, set a position callback with @ref glfwSetWindowPosCallback. or your own code, set a position callback.
@code @code
glfwSetWindowPosCallback(window, window_pos_callback); glfwSetWindowPosCallback(window, window_pos_callback);
@ -533,8 +567,7 @@ When a full screen window is restored, the desired video mode is restored to its
monitor as well. 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 a iconify callback with @ref the user, system or your own code, set a iconify callback.
glfwSetWindowIconifyCallback.
@code @code
glfwSetWindowIconifyCallback(window, window_iconify_callback); glfwSetWindowIconifyCallback(window, window_iconify_callback);
@ -597,8 +630,7 @@ int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
@subsection window_focus Input focus @subsection window_focus Input focus
If you wish to be notified when a window gains or loses focus, whether by If you wish to be notified when a window gains or loses focus, whether by
the user, system or your own code, set a focus callback with @ref the user, system or your own code, set a focus callback.
glfwSetWindowFocusCallback.
@code @code
glfwSetWindowFocusCallback(window, window_focus_callback); glfwSetWindowFocusCallback(window, window_focus_callback);
@ -630,8 +662,7 @@ int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
@subsection window_refresh Damage and refresh @subsection window_refresh Damage and refresh
If you wish to be notified when the contents of a window is damaged and needs If you wish to be notified when the contents of a window is damaged and needs
to be refreshed, set a window refresh callback with @ref to be refreshed, set a window refresh callback.
glfwSetWindowRefreshCallback.
@code @code
glfwSetWindowRefreshCallback(m_handle, window_refresh_callback); glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
@ -681,8 +712,8 @@ visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
and initial visibility is controlled by the [window hint](@ref window_hints) and initial visibility is controlled by the [window hint](@ref window_hints)
with the same name. with the same name.
`GLFW_RESIZABLE` indicates whether the specified window is resizable *by the `GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
user*. This is controlled by the [window hint](@ref window_hints) with the same user_. This is controlled by the [window hint](@ref window_hints) with the same
name. name.
`GLFW_DECORATED` indicates whether the specified window has decorations such as `GLFW_DECORATED` indicates whether the specified window has decorations such as

View File

@ -263,7 +263,7 @@ extern "C" {
/*! @defgroup keys Keyboard keys /*! @defgroup keys Keyboard keys
* *
* These key codes are inspired by the *USB HID Usage Tables v1.12* (p. 53-60), * These key codes are inspired by the _USB HID Usage Tables v1.12_ (p. 53-60),
* but re-arranged to map to 7-bit ASCII for printable keys (function keys are * but re-arranged to map to 7-bit ASCII for printable keys (function keys are
* put in the 256+ range). * put in the 256+ range).
* *
@ -839,7 +839,7 @@ typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
* @param[in] window The window that received the event. * @param[in] window The window that received the event.
* @param[in] key The [keyboard key](@ref keys) that was pressed or released. * @param[in] key The [keyboard key](@ref keys) that was pressed or released.
* @param[in] scancode The system-specific scancode of the key. * @param[in] scancode The system-specific scancode of the key.
* @param[in] action @ref GLFW_PRESS, @ref GLFW_RELEASE or @ref GLFW_REPEAT. * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`.
* @param[in] mods Bit field describing which [modifier keys](@ref mods) were * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
* held down. * held down.
* *
@ -997,7 +997,7 @@ typedef struct GLFWimage
* @return `GL_TRUE` if successful, or `GL_FALSE` if an * @return `GL_TRUE` if successful, or `GL_FALSE` if an
* [error](@ref error_handling) occurred. * [error](@ref error_handling) occurred.
* *
* @remarks **OS X:** This function will change the current directory of the * @remarks __OS X:__ This function will change the current directory of the
* application to the `Contents/Resources` subdirectory of the application's * application to the `Contents/Resources` subdirectory of the application's
* bundle, if present. This can be disabled with a * bundle, if present. This can be disabled with a
* [compile-time option](@ref compile_options_osx). * [compile-time option](@ref compile_options_osx).
@ -1012,7 +1012,7 @@ typedef struct GLFWimage
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** This function no longer registers @ref glfwTerminate with `atexit`. * __GLFW 3:__ This function no longer registers @ref glfwTerminate with `atexit`.
* *
* @ingroup init * @ingroup init
*/ */
@ -1277,7 +1277,7 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
* @return The previously set callback, or `NULL` if no callback was set or the * @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init). * library had not been [initialized](@ref intro_init).
* *
* @bug **X11:** This callback is not yet called on monitor configuration * @bug __X11:__ This callback is not yet called on monitor configuration
* changes. * changes.
* *
* @par Thread Safety * @par Thread Safety
@ -1320,7 +1320,7 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Changed to return a dynamic array of video modes for a specific * __GLFW 3:__ Changed to return a dynamic array of video modes for a specific
* monitor. * monitor.
* *
* @ingroup monitor * @ingroup monitor
@ -1463,7 +1463,7 @@ GLFWAPI void glfwDefaultWindowHints(void);
* Added in GLFW 2.2. * Added in GLFW 2.2.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwOpenWindowHint`. Hints are no longer reset to * __GLFW 3:__ Renamed from `glfwOpenWindowHint`. Hints are no longer reset to
* default values on window creation. * default values on window creation.
* *
* @ingroup window * @ingroup window
@ -1494,17 +1494,24 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* that you pick the primary monitor. For more information on how to query * that you pick the primary monitor. For more information on how to query
* connected monitors, see @ref monitor_monitors. * connected monitors, see @ref monitor_monitors.
* *
* For full screen windows, the specified size becomes the resolution of the
* window's _desired video mode_. As long as a full screen window has input
* focus, the supported video mode most closely matching the desired video mode
* is set for the specified monitor. For more information about full screen
* windows, including the creation of so called _windowed full screen_ or
* _borderless full screen_ windows, see @ref window_full_screen.
*
* By default, newly created windows use the placement recommended by the * By default, newly created windows use the placement recommended by the
* window system. To create the window at a specific position, make it * window system. To create the window at a specific position, make it
* initially invisible using the `GLFW_VISIBLE` window hint, set its position * initially invisible using the `GLFW_VISIBLE` window hint, set its
* and then show it. * [position](@ref window_pos) and then [show](@ref window_hide) it.
* *
* If a full screen window is active, the screensaver is prohibited from * If a full screen window is focused, the screensaver is prohibited from
* starting. * starting.
* *
* Window systems put limits on window sizes. Very large or very small window * Window systems put limits on window sizes. Very large or very small window
* dimensions may be overridden by the window system on creation. Check the * dimensions may be overridden by the window system on creation. Check the
* actual [window size](@ref window_size) after creation. * actual [size](@ref window_size) after creation.
* *
* The [swap interval](@ref window_swap) is not set during window creation and * The [swap interval](@ref window_swap) is not set during window creation and
* the initial value may vary depending on driver settings and defaults. * the initial value may vary depending on driver settings and defaults.
@ -1521,27 +1528,27 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* @return The handle of the created window, or `NULL` if an * @return The handle of the created window, or `NULL` if an
* [error](@ref error_handling) occurred. * [error](@ref error_handling) occurred.
* *
* @remarks **Windows:** Window creation will fail if the Microsoft GDI * @remarks __Windows:__ Window creation will fail if the Microsoft GDI
* software OpenGL implementation is the only one available. * software OpenGL implementation is the only one available.
* *
* @remarks **Windows:** If the executable has an icon resource named * @remarks __Windows:__ If the executable has an icon resource named
* `GLFW_ICON,` it will be set as the icon for the window. If no such icon is * `GLFW_ICON,` it will be set as the icon for the window. If no such icon is
* present, the `IDI_WINLOGO` icon will be used instead. * present, the `IDI_WINLOGO` icon will be used instead.
* *
* @remarks **OS X:** The GLFW window has no icon, as it is not a document * @remarks __OS X:__ The GLFW window has no icon, as it is not a document
* window, but the dock icon will be the same as the application bundle's icon. * window, but the dock icon will be the same as the application bundle's icon.
* For more information on bundles, see the * For more information on bundles, see the
* [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/) * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
* in the Mac Developer Library. * in the Mac Developer Library.
* *
* @remarks **OS X:** The first time a window is opened the menu bar is populated with * @remarks __OS X:__ The first time a window is opened the menu bar is populated with
* common commands like Hide, Quit and About. The About entry opens a minimal * common commands like Hide, Quit and About. The About entry opens a minimal
* about dialog with information from the application's bundle. The menu bar can be * about dialog with information from the application's bundle. The menu bar can be
* disabled with a [compile-time option](@ref compile_options_osx). * disabled with a [compile-time option](@ref compile_options_osx).
* *
* @remarks **X11:** There is no mechanism for setting the window icon yet. * @remarks __X11:__ There is no mechanism for setting the window icon yet.
* *
* @remarks **X11:** Some window managers will not respect the placement of * @remarks __X11:__ Some window managers will not respect the placement of
* initially hidden windows. * initially hidden windows.
* *
* @note This function may not be called from a callback. * @note This function may not be called from a callback.
@ -1556,7 +1563,7 @@ GLFWAPI void glfwWindowHint(int target, int hint);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwOpenWindow`. Complete signature overhaul. * __GLFW 3:__ Renamed from `glfwOpenWindow`. Complete signature overhaul.
* *
* @ingroup window * @ingroup window
*/ */
@ -1587,7 +1594,7 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwCloseWindow`. Added window handle parameter. * __GLFW 3:__ Renamed from `glfwCloseWindow`. Added window handle parameter.
* *
* @ingroup window * @ingroup window
*/ */
@ -1650,7 +1657,7 @@ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup window * @ingroup window
*/ */
@ -1708,7 +1715,7 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup window * @ingroup window
*/ */
@ -1739,7 +1746,7 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup window * @ingroup window
*/ */
@ -1771,7 +1778,7 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup window * @ingroup window
*/ */
@ -1862,7 +1869,7 @@ GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int
* Added in GLFW 2.1. * Added in GLFW 2.1.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup window * @ingroup window
*/ */
@ -1888,7 +1895,7 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
* Added in GLFW 2.1. * Added in GLFW 2.1.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup window * @ingroup window
*/ */
@ -1977,7 +1984,7 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwGetWindowParam`. Added window handle * __GLFW 3:__ Renamed from `glfwGetWindowParam`. Added window handle
* parameter. * parameter.
* *
* @ingroup window * @ingroup window
@ -2047,7 +2054,7 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
* Added in GLFW 3.0. * Added in GLFW 3.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Updated callback signature. * __GLFW 3:__ Added window handle parameter. Updated callback signature.
* *
* @ingroup window * @ingroup window
*/ */
@ -2074,7 +2081,7 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Updated callback signature. * __GLFW 3:__ Added window handle parameter. Updated callback signature.
* *
* @ingroup window * @ingroup window
*/ */
@ -2097,7 +2104,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
* @return The previously set callback, or `NULL` if no callback was set or the * @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init). * library had not been [initialized](@ref intro_init).
* *
* @remarks **OS X:** Selecting Quit from the application menu will * @remarks __OS X:__ Selecting Quit from the application menu will
* trigger the close callback for all windows. * trigger the close callback for all windows.
* *
* @par Thread Safety * @par Thread Safety
@ -2109,7 +2116,7 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
* Added in GLFW 2.5. * Added in GLFW 2.5.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Updated callback signature. * __GLFW 3:__ Added window handle parameter. Updated callback signature.
* *
* @ingroup window * @ingroup window
*/ */
@ -2140,7 +2147,7 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
* Added in GLFW 2.5. * Added in GLFW 2.5.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Updated callback signature. * __GLFW 3:__ Added window handle parameter. Updated callback signature.
* *
* @ingroup window * @ingroup window
*/ */
@ -2250,7 +2257,7 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** This function is no longer called by @ref glfwSwapBuffers. * __GLFW 3:__ This function is no longer called by @ref glfwSwapBuffers.
* *
* @ingroup window * @ingroup window
*/ */
@ -2322,6 +2329,10 @@ GLFWAPI void glfwWaitEvents(void);
GLFWAPI void glfwPostEmptyEvent(void); GLFWAPI void glfwPostEmptyEvent(void);
/*! @brief Returns the value of an input option for the specified window. /*! @brief Returns the value of an input option for the specified window.
*
* This function returns the value of an input option for the specified window.
* The mode must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
* `GLFW_STICKY_MOUSE_BUTTONS`.
* *
* @param[in] window The window to query. * @param[in] window The window to query.
* @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
@ -2340,10 +2351,10 @@ GLFWAPI void glfwPostEmptyEvent(void);
GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode); GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
/*! @brief Sets an input option for the specified window. /*! @brief Sets an input option for the specified window.
* @param[in] window The window whose input mode to set. *
* @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or * This function sets an input mode option for the specified window. The mode
* must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
* `GLFW_STICKY_MOUSE_BUTTONS`. * `GLFW_STICKY_MOUSE_BUTTONS`.
* @param[in] value The new value of the specified input mode.
* *
* If the mode is `GLFW_CURSOR`, the value must be one of the following cursor * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor
* modes: * modes:
@ -2358,18 +2369,23 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
* *
* If the mode is `GLFW_STICKY_KEYS`, the value must be either `GL_TRUE` to * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GL_TRUE` to
* enable sticky keys, or `GL_FALSE` to disable it. If sticky keys are * enable sticky keys, or `GL_FALSE` to disable it. If sticky keys are
* enabled, a key press will ensure that @ref glfwGetKey returns @ref * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS`
* GLFW_PRESS the next time it is called even if the key had been released * the next time it is called even if the key had been released before the
* before the call. This is useful when you are only interested in whether * call. This is useful when you are only interested in whether keys have been
* keys have been pressed but not when or in which order. * pressed but not when or in which order.
* *
* If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either
* `GL_TRUE` to enable sticky mouse buttons, or `GL_FALSE` to disable it. If * `GL_TRUE` to enable sticky mouse buttons, or `GL_FALSE` to disable it. If
* sticky mouse buttons are enabled, a mouse button press will ensure that @ref * sticky mouse buttons are enabled, a mouse button press will ensure that @ref
* glfwGetMouseButton returns @ref GLFW_PRESS the next time it is called even * glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even if
* if the mouse button had been released before the call. This is useful when * the mouse button had been released before the call. This is useful when you
* you are only interested in whether mouse buttons have been pressed but not * are only interested in whether mouse buttons have been pressed but not when
* when or in which order. * or in which order.
*
* @param[in] window The window whose input mode to set.
* @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
* `GLFW_STICKY_MOUSE_BUTTONS`.
* @param[in] value The new value of the specified input mode.
* *
* @par Thread Safety * @par Thread Safety
* This function may only be called from the main thread. * This function may only be called from the main thread.
@ -2416,7 +2432,7 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup input * @ingroup input
*/ */
@ -2447,7 +2463,7 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. * __GLFW 3:__ Added window handle parameter.
* *
* @ingroup input * @ingroup input
*/ */
@ -2487,7 +2503,7 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwGetMousePos`. Added window handle parameter. * __GLFW 3:__ Renamed from `glfwGetMousePos`. Added window handle parameter.
* Moved to floating-point coordinates. * Moved to floating-point coordinates.
* *
* @ingroup input * @ingroup input
@ -2512,7 +2528,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
* @param[in] ypos The desired y-coordinate, relative to the top edge of the * @param[in] ypos The desired y-coordinate, relative to the top edge of the
* client area. * client area.
* *
* @remarks **X11:** Due to the asynchronous nature of a modern X desktop, it * @remarks __X11:__ Due to the asynchronous nature of a modern X desktop, it
* may take a moment for the window focus event to arrive. This means you will * may take a moment for the window focus event to arrive. This means you will
* not be able to set the cursor position directly after window creation. * not be able to set the cursor position directly after window creation.
* *
@ -2526,7 +2542,7 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwSetMousePos`. Added window handle parameter. * __GLFW 3:__ Renamed from `glfwSetMousePos`. Added window handle parameter.
* Moved to floating-point coordinates. * Moved to floating-point coordinates.
* *
* @ingroup input * @ingroup input
@ -2650,7 +2666,7 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Updated callback signature. * __GLFW 3:__ Added window handle parameter. Updated callback signature.
* *
* @ingroup input * @ingroup input
*/ */
@ -2690,7 +2706,7 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
* Added in GLFW 2.4. * Added in GLFW 2.4.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Updated callback signature. * __GLFW 3:__ Added window handle parameter. Updated callback signature.
* *
* @ingroup input * @ingroup input
*/ */
@ -2755,7 +2771,7 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Updated callback signature. * __GLFW 3:__ Added window handle parameter. Updated callback signature.
* *
* @ingroup input * @ingroup input
*/ */
@ -2783,7 +2799,7 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwSetMousePosCallback`. Added window handle * __GLFW 3:__ Renamed from `glfwSetMousePosCallback`. Added window handle
* parameter. Updated callback signature. * parameter. Updated callback signature.
* *
* @ingroup input * @ingroup input
@ -2838,7 +2854,7 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
* Added in GLFW 2.1. * Added in GLFW 2.1.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwSetMouseWheelCallback`. Added window handle. * __GLFW 3:__ Renamed from `glfwSetMouseWheelCallback`. Added window handle.
* Updated callback signature. * Updated callback signature.
* *
* @ingroup input * @ingroup input
@ -2916,7 +2932,7 @@ GLFWAPI int glfwJoystickPresent(int joy);
* Added in GLFW 2.2. * Added in GLFW 2.2.
* *
* @par * @par
* **GLFW 3:** Renamed from `glfwGetJoystickPos`. Changed to return a dynamic * __GLFW 3:__ Renamed from `glfwGetJoystickPos`. Changed to return a dynamic
* array. * array.
* *
* @ingroup input * @ingroup input
@ -2947,7 +2963,7 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count);
* Added in GLFW 2.2. * Added in GLFW 2.2.
* *
* @par * @par
* **GLFW 3:** Changed to return a dynamic array. * __GLFW 3:__ Changed to return a dynamic array.
* *
* @ingroup input * @ingroup input
*/ */
@ -3143,7 +3159,7 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
* Added in GLFW 1.0. * Added in GLFW 1.0.
* *
* @par * @par
* **GLFW 3:** Added window handle parameter. Removed call to @ref * __GLFW 3:__ Added window handle parameter. Removed call to @ref
* glfwPollEvents. * glfwPollEvents.
* *
* @ingroup window * @ingroup window