text:
/*!

@page moving_guide Moving from GLFW 2 to 3

@tableofcontents

This is a transition guide for moving from GLFW 2 to 3.  It describes what has
changed or been removed, but does _not_ include
[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
required to create full screen windows with GLFW 3.

@section moving_removed Changed and removed features

@subsection moving_renamed_files Renamed library and header file

The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
avoid collisions with the headers of other major versions.  Similarly, the GLFW
3 library is named `glfw3,` except when it's installed as a shared library on
Unix-like systems, where it uses the
[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.

@par Old syntax
@code
#include <GL/glfw.h>
@endcode

@par New syntax
@code
#include <GLFW/glfw3.h>
@endcode

@subsection moving_threads Removal of threading functions

The threading functions have been removed, including the per-thread sleep
function.  They were fairly primitive, under-used, poorly integrated and took
time away from the focus of GLFW (i.e.  context, input and window).  There are
better threading libraries available and native threading support is available
in both [C++11](http://en.cppreference.com/w/cpp/thread) and
[C11](http://en.cppreference.com/w/c/thread), both of which are gaining
traction.

If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
support them, see the
[TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and
[TinyCThread](https://github.com/tinycthread/tinycthread) projects created by
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
TinyCThread.

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
thread at a time, and the documentation explicitly states which functions may be
used from any thread and which must only be used from the main thread.

@par Removed functions
`glfwSleep`, `glfwCreateThread`, `glfwDestroyThread`, `glfwWaitThread`,
`glfwGetThreadID`, `glfwCreateMutex`, `glfwDestroyMutex`, `glfwLockMutex`,
`glfwUnlockMutex`, `glfwCreateCond`, `glfwDestroyCond`, `glfwWaitCond`,
`glfwSignalCond`, `glfwBroadcastCond` and `glfwGetNumberOfProcessors`.

@par Removed types
`GLFWthreadfun`

@subsection moving_image Removal of image and texture loading

The image and texture loading functions have been removed.  They only supported
the Targa image format, making them mostly useful for beginner level examples.
To become of sufficiently high quality to warrant keeping them in GLFW 3, they
would need not only to support other formats, but also modern extensions to
OpenGL texturing.  This would either add a number of external
dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
of these libraries.

As there already are libraries doing this, it is unnecessary both to duplicate
the work and to tie the duplicate to GLFW.  The resulting library would also be
platform-independent, as both OpenGL and stdio are available wherever GLFW is.

@par Removed functions
`glfwReadImage`, `glfwReadMemoryImage`, `glfwFreeImage`, `glfwLoadTexture2D`,
`glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`.

@subsection moving_stdcall Removal of GLFWCALL macro

The `GLFWCALL` macro, which made callback functions use
[__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
has been removed.  GLFW is written in C, not Pascal.  Removing this macro means
there's one less thing for application programmers to remember, i.e. the
requirement to mark all callback functions with `GLFWCALL`.  It also simplifies
the creation of DLLs and DLL link libraries, as there's no need to explicitly
disable `@n` entry point suffixes.

@par Old syntax
@code
void GLFWCALL callback_function(...);
@endcode

@par New syntax
@code
void callback_function(...);
@endcode

@subsection moving_window_handles Window handle parameters

Because GLFW 3 supports multiple windows, window handle parameters have been
added to all window-related GLFW functions and callbacks.  The handle of
a newly created window is returned by @ref glfwCreateWindow (formerly
`glfwOpenWindow`).  Window handles are pointers to the
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWwindow.

@par Old syntax
@code
glfwSetWindowTitle("New Window Title");
@endcode

@par New syntax
@code
glfwSetWindowTitle(window, "New Window Title");
@endcode

@subsection moving_monitor Explicit monitor selection

GLFW 3 provides support for multiple monitors.  To request a full screen mode window,
instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
window to use.  The @ref glfwGetPrimaryMonitor function returns the monitor that
GLFW 2 would have selected, but there are many other
[monitor functions](@ref monitor_guide).  Monitor handles are pointers to the
[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor.

@par Old basic full screen
@code
glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN);
@endcode

@par New basic full screen
@code
window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL);
@endcode

@note The framebuffer bit depth parameters of `glfwOpenWindow` have been turned
into [window hints](@ref window_hints), but as they have been given
[sane defaults](@ref window_hints_values) you rarely need to set these hints.

@subsection moving_autopoll Removal of automatic event polling

GLFW 3 does not automatically poll for events in @ref glfwSwapBuffers, meaning
you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.  Unlike
buffer swap, which acts on a single window, the event processing functions act
on all windows at once.

@par Old basic main loop
@code
while (...)
{
    // Process input
    // Render output
    glfwSwapBuffers();
}
@endcode

@par New basic main loop
@code
while (...)
{
    // Process input
    // Render output
    glfwSwapBuffers(window);
    glfwPollEvents();
}
@endcode

@subsection moving_context Explicit context management

Each GLFW 3 window has its own OpenGL context and only you, the application
programmer, can know which context should be current on which thread at any
given time.  Therefore, GLFW 3 leaves that decision to you.

This means that you need to call @ref glfwMakeContextCurrent after creating
a window before you can call any OpenGL functions.

@subsection moving_hidpi Separation of window and framebuffer sizes

Window positions and sizes now use screen coordinates, which may not be the same
as pixels on machines with high-DPI monitors.  This is important as OpenGL uses
pixels, not screen coordinates.  For example, the rectangle specified with
`glViewport` needs to use pixels.  Therefore, framebuffer size functions have
been added.  You can retrieve the size of the framebuffer of a window with @ref
glfwGetFramebufferSize function.  A framebuffer size callback has also been
added, which can be set with @ref glfwSetFramebufferSizeCallback.

@par Old basic viewport setup
@code
glfwGetWindowSize(&width, &height);
glViewport(0, 0, width, height);
@endcode

@par New basic viewport setup
@code
glfwGetFramebufferSize(window, &width, &height);
glViewport(0, 0, width, height);
@endcode

@subsection moving_window_close Window closing changes

The `GLFW_OPENED` window parameter has been removed.  As long as the window has
not been destroyed, whether through @ref glfwDestroyWindow or @ref
glfwTerminate, the window is "open".

A user attempting to close a window is now just an event like any other.  Unlike
GLFW 2, windows and contexts created with GLFW 3 will never be destroyed unless
you choose them to be.  Each window now has a close flag that is set to
`GLFW_TRUE` when the user attempts to close that window.  By default, nothing else
happens and the window stays visible.  It is then up to you to either destroy
the window, take some other action or simply ignore the request.

You can query the close flag at any time with @ref glfwWindowShouldClose and set
it at any time with @ref glfwSetWindowShouldClose.

@par Old basic main loop
@code
while (glfwGetWindowParam(GLFW_OPENED))
{
    ...
}
@endcode

@par New basic main loop
@code
while (!glfwWindowShouldClose(window))
{
    ...
}
@endcode

The close callback no longer returns a value.  Instead, it is called after the
close flag has been set so it can override its value, if it chooses to, before
event processing completes.  You may however not call @ref glfwDestroyWindow
from the close callback (or any other window related callback).

@par Old syntax
@code
int GLFWCALL window_close_callback(void);
@endcode

@par New syntax
@code
void window_close_callback(GLFWwindow* window);
@endcode

@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
Quit from an in-game menu.

@subsection moving_hints Persistent window hints

The `glfwOpenWindowHint` function has been renamed to @ref glfwWindowHint.

Window hints are no longer reset to their default values on window creation, but
instead retain their values until modified by @ref glfwWindowHint or @ref
glfwDefaultWindowHints, or until the library is terminated and re-initialized.

@subsection moving_video_modes Video mode enumeration

Video mode enumeration is now per-monitor.  The @ref glfwGetVideoModes function
now returns all available modes for a specific monitor instead of requiring you
to guess how large an array you need.  The `glfwGetDesktopMode` function, which
had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
returns the current mode of a monitor.

@subsection moving_char_up Removal of character actions

The action parameter of the [character callback](@ref GLFWcharfun) has been
removed.  This was an artefact of the origin of GLFW, i.e. being developed in
English by a Swede.  However, many keyboard layouts require more than one key to
produce characters with diacritical marks. Even the Swedish keyboard layout
requires this for uncommon cases like ü.

@par Old syntax
@code
void GLFWCALL character_callback(int character, int action);
@endcode

@par New syntax
@code
void character_callback(GLFWwindow* window, int character);
@endcode

@subsection moving_cursorpos Cursor position changes

The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos,
`glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref
glfwSetCursorPosCallback.

The cursor position is now `double` instead of `int`, both for the direct
functions and for the callback.  Some platforms can provide sub-pixel cursor
movement and this data is now passed on to the application where available.  On
platforms where this is not provided, the decimal part is zero.

GLFW 3 only allows you to position the cursor within a window using @ref
glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
Unless the window is active, the function fails silently.

@subsection moving_wheel Wheel position replaced by scroll offsets

The `glfwGetMouseWheel` function has been removed.  Scrolling is the input of
offsets and has no absolute position.  The mouse wheel callback has been
replaced by a [scroll callback](@ref GLFWscrollfun) that receives
two-dimensional floating point scroll offsets.  This allows you to receive
precise scroll data from for example modern touchpads.

@par Old syntax
@code
void GLFWCALL mouse_wheel_callback(int position);
@endcode

@par New syntax
@code
void scroll_callback(GLFWwindow* window, double xoffset, double yoffset);
@endcode

@par Removed functions
`glfwGetMouseWheel`

@subsection moving_repeat Key repeat action

The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
for both keys and characters.  A new key action, `GLFW_REPEAT`, has been added
to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press
from a repeat.  Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
`GLFW_RELEASE`.

@subsection moving_keys Physical key input

GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
the values generated by the current keyboard layout.  The tokens are named
according to the values they would have using the standard US layout, but this
is only a convenience, as most programmers are assumed to know that layout.
This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
is the same key in the same place regardless of what keyboard layouts the users
of your program has.

The key input facility was never meant for text input, although using it that
way worked slightly better in GLFW 2.  If you were using it to input text, you
should be using the character callback instead, on both GLFW 2 and 3.  This will
give you the characters being input, as opposed to the keys being pressed.

GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
having to remember whether to check for `'a'` or `'A'`, you now check for
`GLFW_KEY_A`.

@subsection moving_joystick Joystick function changes

The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.

The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and
`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent
function as well as axis and button counts returned by the @ref
glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.

@subsection moving_mbcs Win32 MBCS support

The Win32 port of GLFW 3 will not compile in
[MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
However, because the use of the Unicode version of the Win32 API doesn't affect
the process as a whole, but only those windows created using it, it's perfectly
possible to call MBCS functions from other parts of the same application.
Therefore, even if an application using GLFW has MBCS mode code, there's no need
for GLFW itself to support it.

@subsection moving_windows Support for versions of Windows older than XP

All explicit support for version of Windows older than XP has been removed.
There is no code that actively prevents GLFW 3 from running on these earlier
versions, but it uses Win32 functions that those versions lack.

Windows XP was released in 2001, and by now (January 2015) it has not only
replaced almost all earlier versions of Windows, but is itself rapidly being
replaced by Windows 7 and 8.  The MSDN library doesn't even provide
documentation for version older than Windows 2000, making it difficult to
maintain compatibility with these versions even if it was deemed worth the
effort.

The Win32 API has also not stood still, and GLFW 3 uses many functions only
present on Windows XP or later.  Even supporting an OS as new as XP (new
from the perspective of GLFW 2, which still supports Windows 95) requires
runtime checking for a number of functions that are present only on modern
version of Windows.

@subsection moving_syskeys Capture of system-wide hotkeys

The ability to disable and capture system-wide hotkeys like Alt+Tab has been
removed.  Modern applications, whether they're games, scientific visualisations
or something else, are nowadays expected to be good desktop citizens and allow
these hotkeys to function even when running in full screen mode.

@subsection moving_terminate Automatic termination

GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization,
because `exit` calls registered functions from the calling thread and while it
is permitted to call `exit` from any thread, @ref glfwTerminate must only be
called from the main thread.

To release all resources allocated by GLFW, you should call @ref glfwTerminate
yourself, from the main thread, before the program terminates.  Note that this
destroys all windows not already destroyed with @ref glfwDestroyWindow,
invalidating any window handles you may still have.

@subsection moving_glu GLU header inclusion

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
projects should not use GLU__, but if you need it for legacy code that
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.

@par Old syntax
@code
#include <GL/glfw.h>
@endcode

@par New syntax
@code
#define GLFW_INCLUDE_GLU
#include <GLFW/glfw3.h>
@endcode

@section moving_tables Name change tables

@subsection moving_renamed_functions Renamed functions

| GLFW 2                      | GLFW 3                        | Notes |
| --------------------------- | ----------------------------- | ----- |
| `glfwOpenWindow`            | @ref glfwCreateWindow         | All channel bit depths are now hints
| `glfwCloseWindow`           | @ref glfwDestroyWindow        |       |
| `glfwOpenWindowHint`        | @ref glfwWindowHint           | Now accepts all `GLFW_*_BITS` tokens |
| `glfwEnable`                | @ref glfwSetInputMode         |       |
| `glfwDisable`               | @ref glfwSetInputMode         |       |
| `glfwGetMousePos`           | @ref glfwGetCursorPos         |       |
| `glfwSetMousePos`           | @ref glfwSetCursorPos         |       |
| `glfwSetMousePosCallback`   | @ref glfwSetCursorPosCallback |       |
| `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback    | Accepts two-dimensional scroll offsets as doubles |
| `glfwGetJoystickPos`        | @ref glfwGetJoystickAxes      |       |
| `glfwGetWindowParam`        | @ref glfwGetWindowAttrib      |       |
| `glfwGetGLVersion`          | @ref glfwGetWindowAttrib      | Use `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and `GLFW_CONTEXT_REVISION` |
| `glfwGetDesktopMode`        | @ref glfwGetVideoMode         | Returns the current mode of a monitor |
| `glfwGetJoystickParam`      | @ref glfwJoystickPresent      | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons |

@subsection moving_renamed_types Renamed types

| GLFW 2              | GLFW 3                | Notes |
| ------------------- | --------------------- |       |
| `GLFWmousewheelfun` | @ref GLFWscrollfun    |       |
| `GLFWmouseposfun`   | @ref GLFWcursorposfun |       |

@subsection moving_renamed_tokens Renamed tokens

| GLFW 2                      | GLFW 3                       | Notes |
| --------------------------- | ---------------------------- | ----- |
| `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well |
| `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well |
| `GLFW_FSAA_SAMPLES`         | `GLFW_SAMPLES`               | Renamed to match the OpenGL API |
| `GLFW_ACTIVE`               | `GLFW_FOCUSED`               | Renamed to match the window focus callback |
| `GLFW_WINDOW_NO_RESIZE`     | `GLFW_RESIZABLE`             | The default has been inverted |
| `GLFW_MOUSE_CURSOR`         | `GLFW_CURSOR`                | Used with @ref glfwSetInputMode |
| `GLFW_KEY_ESC`              | `GLFW_KEY_ESCAPE`            |       |
| `GLFW_KEY_DEL`              | `GLFW_KEY_DELETE`            |       |
| `GLFW_KEY_PAGEUP`           | `GLFW_KEY_PAGE_UP`           |       |
| `GLFW_KEY_PAGEDOWN`         | `GLFW_KEY_PAGE_DOWN`         |       |
| `GLFW_KEY_KP_NUM_LOCK`      | `GLFW_KEY_NUM_LOCK`          |       |
| `GLFW_KEY_LCTRL`            | `GLFW_KEY_LEFT_CONTROL`      |       |
| `GLFW_KEY_LSHIFT`           | `GLFW_KEY_LEFT_SHIFT`        |       |
| `GLFW_KEY_LALT`             | `GLFW_KEY_LEFT_ALT`          |       |
| `GLFW_KEY_LSUPER`           | `GLFW_KEY_LEFT_SUPER`        |       |
| `GLFW_KEY_RCTRL`            | `GLFW_KEY_RIGHT_CONTROL`     |       |
| `GLFW_KEY_RSHIFT`           | `GLFW_KEY_RIGHT_SHIFT`       |       |
| `GLFW_KEY_RALT`             | `GLFW_KEY_RIGHT_ALT`         |       |
| `GLFW_KEY_RSUPER`           | `GLFW_KEY_RIGHT_SUPER`       |       |

*/


text:
/*!

@page input_guide Input guide

@tableofcontents

This guide introduces the input related functions of GLFW.  For details on
a specific function in this category, see the @ref input.  There are also guides
for the other areas of GLFW.

 - @ref intro_guide
 - @ref window_guide
 - @ref context_guide
 - @ref vulkan_guide
 - @ref monitor_guide

GLFW provides many kinds of input.  While some can only be polled, like time, or
only received via callbacks, like scrolling, there are those that provide both
callbacks and polling.  Where a callback is provided, that is the recommended
way to receive that kind of input.  The more you can use callbacks the less time
your users' machines will need to spend polling.

All input callbacks receive a window handle.  By using the
[window user pointer](@ref window_userptr), you can access non-global structures
or objects from your callbacks.

To get a better feel for how the various events callbacks behave, run the
`events` test program.  It register every callback supported by GLFW and prints
out all arguments provided for every event, along with time and sequence
information.

@section events Event processing

GLFW needs to communicate regularly with the window system both in order to
receive events and to show that the application hasn't locked up.  Event
processing must be done regularly while you have any windows and is normally
done each frame after [buffer swapping](@ref buffer_swap).  Even when you have
no windows, event polling needs to be done in order to receive monitor
connection events.

There are two functions for processing pending events.  @ref glfwPollEvents,
processes only those events that have already been received and then returns
immediately.

@code
glfwPollEvents();
@endcode

This is the best choice when rendering continually, like most games do.

If you only need to update the contents of the window when you receive new
input, @ref glfwWaitEvents is a better choice.

@code
glfwWaitEvents();
@endcode

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
useful for, for example, editing tools.  There must be at least one GLFW window
for this function to sleep.

If you want to wait for events but have UI elements that need periodic updates,
call @ref glfwWaitEventsTimeout.

@code
glfwWaitEventsTimeout(0.7);
@endcode

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
events.

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
glfwPostEmptyEvent.

@code
glfwPostEmptyEvent();
@endcode

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
window systems will send some events directly to the application, which in turn
causes callbacks to be called outside of regular event processing.

@section input_keyboard Keyboard input

GLFW divides keyboard input into two categories; key events and character
events.  Key events relate to actual physical keyboard keys, whereas character
events relate to the Unicode code points generated by pressing some of them.

Keys and characters do not map 1:1.  A single key press may produce several
characters, and a single character may require several keys to produce.  This
may not be the case on your machine, but your users are likely not all using the
same keyboard layout, input method or even operating system as you.

@subsection input_key Key input

If you wish to be notified when a physical key is pressed or released or when it
repeats, set a key callback.

@code
glfwSetKeyCallback(window, key_callback);
@endcode

The callback function receives the [keyboard key](@ref keys), platform-specific
scancode, key action and [modifier bits](@ref mods).

@code
void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
{
    if (key == GLFW_KEY_E && action == GLFW_PRESS)
        activate_airship();
}
@endcode

The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`.  The key
will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it, for example
_E-mail_ and _Play_ keys.

The scancode is unique for every key, regardless of whether it has a key token.
Scancodes are platform-specific but consistent over time, so keys will have
different scancodes depending on the platform but they are safe to save to disk.

Key states for [named keys](@ref keys) are also saved in per-window state arrays
that can be polled with @ref glfwGetKey.

@code
int state = glfwGetKey(window, GLFW_KEY_E);
if (state == GLFW_PRESS)
    activate_airship();
@endcode

The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.

This function only returns cached key event state.  It does not poll the
system for the current state of the key.

Whenever you poll state, you risk missing the state change you are looking for.
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
key callback, but there is also the `GLFW_STICKY_KEYS` input mode.

@code
glfwSetInputMode(window, GLFW_STICKY_KEYS, 1);
@endcode

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
it has been polled, if a key release event had been processed in the meantime,
the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`.

The `GLFW_KEY_LAST` constant holds the highest value of any
[named key](@ref keys).

@subsection input_char Text input

GLFW supports text input in the form of a stream of
[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
operating system text input system.  Unlike key input, text input obeys keyboard
layouts and modifier keys and supports composing characters using
[dead keys](https://en.wikipedia.org/wiki/Dead_key).  Once received, you can
encode the code points into
[UTF-8](https://en.wikipedia.org/wiki/UTF-8) or any other encoding you prefer.

Because an `unsigned int` is 32 bits long on all platforms supported by GLFW,
you can treat the code point argument as native endian
[UTF-32](https://en.wikipedia.org/wiki/UTF-32).

There are two callbacks for receiving Unicode code points.  If you wish to
offer regular text input, set a character callback.

@code
glfwSetCharCallback(window, character_callback);
@endcode

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
that platform.

@code
void character_callback(GLFWwindow* window, unsigned int codepoint)
{
}
@endcode

If you wish to receive even those Unicode code points generated with modifier
key combinations that a plain text field would ignore, or just want to know
exactly what modifier keys were used, set a character with modifiers callback.

@code
glfwSetCharModsCallback(window, charmods_callback);
@endcode

The callback function receives Unicode code points and
[modifier bits](@ref mods).

@code
void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods)
{
}
@endcode

@subsection input_key_name Key names

If you wish to refer to keys by name, you can query the keyboard layout
dependent name of printable keys with @ref glfwGetKeyName.

@code
const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0);
show_tutorial_hint("Press %s to move forward", key_name);
@endcode

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
ignored.  This matches the behavior of the key callback, meaning the callback
arguments can always be passed unmodified to this function.

@section input_mouse Mouse input

Mouse input comes in many forms, including cursor motion, button presses and
scrolling offsets.  The cursor appearance can also be changed, either to
a custom image or a standard cursor shape from the system theme.

@subsection cursor_pos Cursor position

If you wish to be notified when the cursor moves over the window, set a cursor
position callback.

@code
glfwSetCursorPosCallback(window, cursor_pos_callback);
@endcode

The callback functions receives the cursor position, measured in screen
coordinates but relative to the top-left corner of the window client area.  On
platforms that provide it, the full sub-pixel cursor position is passed on.

@code
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
glfwGetCursorPos.

@code
double xpos, ypos;
glfwGetCursorPos(window, &xpos, &ypos);
@endcode

@subsection cursor_mode Cursor modes

The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
mouse motion input.  By default, the cursor mode is `GLFW_CURSOR_NORMAL`,
meaning the regular arrow cursor (or another cursor set with @ref glfwSetCursor)
is used and cursor motion is not limited.

If you wish to implement mouse motion based camera controls or other input
schemes that require unlimited mouse movement, set the cursor mode to
`GLFW_CURSOR_DISABLED`.

@code
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED);
@endcode

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
providing the application with a virtual cursor position.  This virtual position
is provided normally via both the cursor position callback and through polling.

@note You should not implement your own version of this functionality using
other features of GLFW.  It is not supported and will not work as robustly as
`GLFW_CURSOR_DISABLED`.

If you just wish the cursor to become hidden when it is over a window, set
the cursor mode to `GLFW_CURSOR_HIDDEN`.

@code
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN);
@endcode

This mode puts no limit on the motion of the cursor.

To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL`
cursor mode.

@code
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL);
@endcode

@subsection cursor_object Cursor objects

GLFW supports creating both custom and system theme cursor images, encapsulated
as @ref GLFWcursor objects.  They are created with @ref glfwCreateCursor or @ref
glfwCreateStandardCursor and destroyed with @ref glfwDestroyCursor, or @ref
glfwTerminate, if any remain.

@subsubsection cursor_custom Custom cursor creation

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
cursor with the hot-spot in the upper-left corner:

@code
unsigned char pixels[16 * 16 * 4];
memset(pixels, 0xff, sizeof(pixels));

GLFWimage image;
image.width = 16;
image.height = 16;
image.pixels = pixels;

GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
@endcode

If cursor creation fails, `NULL` will be returned, so it is necessary to check
the return value.

The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits
per channel.  The pixels are arranged canonically as sequential rows, starting
from the top-left corner.

@subsubsection cursor_standard Standard cursor creation

A cursor with a [standard shape](@ref shapes) from the current system cursor
theme can be can be created with @ref glfwCreateStandardCursor.

@code
GLFWcursor* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_CURSOR);
@endcode

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.

@subsubsection cursor_destruction Cursor destruction

When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.

@code
glfwDestroyCursor(cursor);
@endcode

Cursor destruction always succeeds.  All cursors remaining when @ref
glfwTerminate is called are destroyed as well.

@subsubsection cursor_set Cursor setting

A cursor can be set as current for a window with @ref glfwSetCursor.

@code
glfwSetCursor(window, cursor);
@endcode

Once set, the cursor image will be used as long as the system cursor is over the
client area of the window and the [cursor mode](@ref cursor_mode) is set
to `GLFW_CURSOR_NORMAL`.

A single cursor may be set for any number of windows.

To remove a cursor from a window, set the cursor of that window to `NULL`.

@code
glfwSetCursor(window, NULL);
@endcode

When a cursor is destroyed, it is removed from any window where it is set.  This
does not affect the cursor modes of those windows.

@subsection cursor_enter Cursor enter/leave events

If you wish to be notified when the cursor enters or leaves the client area of
a window, set a cursor enter/leave callback.

@code
glfwSetCursorEnterCallback(window, cursor_enter_callback);
@endcode

The callback function receives the new classification of the cursor.

@code
void cursor_enter_callback(GLFWwindow* window, int entered)
{
    if (entered)
    {
        // The cursor entered the client area of the window
    }
    else
    {
        // The cursor left the client area of the window
    }
}
@endcode

@subsection input_mouse_button Mouse button input

If you wish to be notified when a mouse button is pressed or released, set
a mouse button callback.

@code
glfwSetMouseButtonCallback(window, mouse_button_callback);
@endcode

The callback function receives the [mouse button](@ref buttons), button action
and [modifier bits](@ref mods).

@code
void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
{
    if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)
        popup_menu();
}
@endcode

The action is one of `GLFW_PRESS` or `GLFW_RELEASE`.

Mouse button states for [named buttons](@ref buttons) are also saved in
per-window state arrays that can be polled with @ref glfwGetMouseButton.

@code
int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
if (state == GLFW_PRESS)
    upgrade_cow();
@endcode

The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.

This function only returns cached mouse button event state.  It does not poll
the system for the current state of the mouse button.

Whenever you poll state, you risk missing the state change you are looking for.
If a pressed mouse button is released again before you poll its state, you will have
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`
input mode.

@code
glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, 1);
@endcode

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
glfwGetMouseButton.  Once it has been polled, if a mouse button release event
had been processed in the meantime, the state will reset to `GLFW_RELEASE`,
otherwise it will remain `GLFW_PRESS`.

The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
[named button](@ref buttons).

@subsection scrolling Scroll input

If you wish to be notified when the user scrolls, whether with a mouse wheel or
touchpad gesture, set a scroll callback.

@code
glfwSetScrollCallback(window, scroll_callback);
@endcode

The callback function receives two-dimensional scroll offsets.

@code
void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
{
}
@endcode

A simple mouse wheel, being vertical, provides offsets along the Y-axis.

@section joystick Joystick input

The joystick functions expose connected joysticks and controllers, with both
referred to as joysticks.  It supports up to sixteen joysticks, ranging from
`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to `GLFW_JOYSTICK_LAST`.  You can test
whether a [joystick](@ref joysticks) is present with @ref glfwJoystickPresent.

@code
int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
@endcode

When GLFW is initialized, detected joysticks are added to to the beginning of
the array, starting with `GLFW_JOYSTICK_1`.  Once a joystick is detected, it
keeps its assigned index until it is disconnected, so as joysticks are connected
and disconnected, they will become spread out.

Joystick state is updated as needed when a joystick function is called and does
not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents
to be called.

@subsection joystick_axis Joystick axis states

The positions of all axes of a joystick are returned by @ref
glfwGetJoystickAxes.  See the reference documentation for the lifetime of the
returned array.

@code
int count;
const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count);
@endcode

Each element in the returned array is a value between -1.0 and 1.0.

@subsection joystick_button Joystick button states

The states of all buttons of a joystick are returned by @ref
glfwGetJoystickButtons.  See the reference documentation for the lifetime of the
returned array.

@code
int count;
const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count);
@endcode

Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`.

@subsection joystick_name Joystick name

The human-readable, UTF-8 encoded name of a joystick is returned by @ref
glfwGetJoystickName.  See the reference documentation for the lifetime of the
returned string.

@code
const char* name = glfwGetJoystickName(GLFW_JOYSTICK_1);
@endcode

Joystick names are not guaranteed to be unique.  Two joysticks of the same model
and make may have the same name.  Only the [joystick token](@ref joysticks) is
guaranteed to be unique, and only until that joystick is disconnected.

@subsection joystick_event Joystick configuration changes

If you wish to be notified when a joystick is connected or disconnected, set
a joystick callback.

@code
glfwSetJoystickCallback(joystick_callback);
@endcode

The callback function receives the ID of the joystick that has been connected
and disconnected and the event that occurred.

@code
void joystick_callback(int joy, int event)
{
    if (event == GLFW_CONNECTED)
    {
        // The joystick was connected
    }
    else if (event == GLFW_DISCONNECTED)
    {
        // The joystick was disconnected
    }
}
@endcode

@section time Time input

GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.

@code
double seconds = glfwGetTime();
@endcode

It returns the number of seconds since the timer was started when the library
was initialized with @ref glfwInit.  The platform-specific time sources used
usually have micro- or nanosecond resolution.

You can modify the reference time with @ref glfwSetTime.

@code
glfwSetTime(4.0);
@endcode

This sets the timer to the specified time, in seconds.

You can also access the raw timer value, measured in 1 / frequency
seconds, with @ref glfwGetTimerValue.

@code
uint64_t value = glfwGetTimerValue();
@endcode

The frequency of the raw timer varies depending on what time sources are
available on the machine.  You can query its frequency, in Hz, with @ref
glfwGetTimerFrequency.

@code
uint64_t freqency = glfwGetTimerFrequency();
@endcode

@section clipboard Clipboard input and output

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
reference documentation for the lifetime of the returned string.

@code
const char* text = glfwGetClipboardString(window);
if (text)
    insert_text(text);
@endcode

If the clipboard is empty or if its contents could not be converted, `NULL` is
returned.

The contents of the system clipboard can be set to a UTF-8 encoded string with
@ref glfwSetClipboardString.

@code
glfwSetClipboardString(window, "A string with words in it");
@endcode

The clipboard functions take a window handle argument because some window
systems require a window to communicate with the system clipboard.  Any valid
window may be used.

@section path_drop Path drop input

If you wish to receive the paths of files and/or directories dropped on
a window, set a file drop callback.

@code
glfwSetDropCallback(window, drop_callback);
@endcode

The callback function receives an array of paths encoded as UTF-8.

@code
void drop_callback(GLFWwindow* window, int count, const char** paths)
{
    int i;
    for (i = 0;  i < count;  i++)
        handle_dropped_file(paths[i]);
}
@endcode

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
to make a deep copy of the array if you want to keep the paths.

*/

repo_language: C

mime_type: text/x-c


text:
/*!

@page monitor_guide Monitor guide

@tableofcontents

This guide introduces the monitor related functions of GLFW.  For details on
a specific function in this category, see the @ref monitor.  There are also
guides for the other areas of GLFW.

 - @ref intro_guide
 - @ref window_guide
 - @ref context_guide
 - @ref vulkan_guide
 - @ref input_guide

@section monitor_object Monitor objects

A monitor object represents a currently connected monitor and is represented as
a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
@ref GLFWmonitor.  Monitor objects cannot be created or destroyed by the
application and retain their addresses until the monitors they represent are
disconnected or until the library is [terminated](@ref intro_init_terminate).

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.  One of the monitors is the primary monitor.

The virtual position of a monitor is in
[screen coordinates](@ref coordinate_systems) and, together with the current
video mode, describes the viewports that the connected monitors provide into the
virtual desktop that spans them.

To see how GLFW views your monitor setup and its available video modes, run the
`monitors` test program.

@subsection monitor_monitors Retrieving monitors

The primary monitor is returned by @ref glfwGetPrimaryMonitor.  It is the user's
preferred monitor and is usually the one with global UI elements like task bar
or menu bar.

@code
GLFWmonitor* primary = glfwGetPrimaryMonitor();
@endcode

You can retrieve all currently connected monitors with @ref glfwGetMonitors.
See the reference documentation for the lifetime of the returned array.

@code
int count;
GLFWmonitor** monitors = glfwGetMonitors(&count);
@endcode

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
disconnected.

@subsection monitor_event Monitor configuration changes

If you wish to be notified when a monitor is connected or disconnected, set
a monitor callback.

@code
glfwSetMonitorCallback(monitor_callback);
@endcode

The callback function receives the handle for the monitor that has been
connected or disconnected and the event that occurred.

@code
void monitor_callback(GLFWmonitor* monitor, int event)
{
    if (event == GLFW_CONNECTED)
    {
        // The monitor was connected
    }
    else if (event == GLFW_DISCONNECTED)
    {
        // The monitor was disconnected
    }
}
@endcode

If a monitor is disconnected, any windows that are full screen on it get forced
into windowed mode.

@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

GLFW generally does a good job selecting a suitable video mode when you create
a full screen window, change its video mode or or make a windowed one full
screen, but it is sometimes useful to know exactly which video modes are
supported.

Video modes are represented as @ref GLFWvidmode structures.  You can get an
array of the video modes supported by a monitor with @ref glfwGetVideoModes.
See the reference documentation for the lifetime of the returned array.

@code
int count;
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
@endcode

To get the current video mode of a monitor call @ref glfwGetVideoMode.  See the
reference documentation for the lifetime of the returned pointer.

@code
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@endcode

The resolution of a video mode is specified in
[screen coordinates](@ref coordinate_systems), not pixels.

@subsection monitor_size Physical size

The physical size of a monitor in millimetres, or an estimation of it, can be
retrieved with @ref glfwGetMonitorPhysicalSize.  This has no relation to its
current _resolution_, i.e. the width and height of its current
[video mode](@ref monitor_modes).

@code
int widthMM, heightMM;
glfwGetMonitorPhysicalSize(monitor, &widthMM, &heightMM);
@endcode

This can, for example, be used together with the current video mode to calculate
the DPI of a monitor.

@code
const double dpi = mode->width / (widthMM / 25.4);
@endcode

@subsection monitor_pos Virtual position

The position of the monitor on the virtual desktop, in
[screen coordinates](@ref coordinate_systems), can be retrieved with @ref
glfwGetMonitorPos.

@code
int xpos, ypos;
glfwGetMonitorPos(monitor, &xpos, &ypos);
@endcode

@subsection monitor_name Human-readable name

The human-readable, UTF-8 encoded name of a monitor is returned by @ref
glfwGetMonitorName.  See the reference documentation for the lifetime of the
returned string.

@code
const char* name = glfwGetMonitorName(monitor);
@endcode

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
unique, and only until that monitor is disconnected.

@subsection monitor_gamma Gamma ramp

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.

@code
GLFWgammaramp ramp;
unsigned short red[256], green[256], blue[256];

ramp.size = 256;
ramp.red = red;
ramp.green = green;
ramp.blue = blue;

for (i = 0;  i < ramp.size;  i++)
{
    // Fill out gamma ramp arrays as desired
}

glfwSetGammaRamp(monitor, &ramp);
@endcode

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.

@note It is recommended to use gamma ramps of size 256, as that is the size
supported by all graphics cards on all platforms.

The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp.  See
the reference documentation for the lifetime of the returned structure.

@code
const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);
@endcode

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
glfwSetGammaRamp with the resulting ramp.

@code
glfwSetGamma(monitor, 1.0);
@endcode

*/


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen $doxygenversion"/>
<title>$projectname: $title</title>
<title>$title</title>
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>

$treeview
$search
$mathjax
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
$extrastylesheet

		GLFW

Documentation

Download

Media

Community


text:
/*!

@page internals_guide Internal structure

@tableofcontents

There are several interfaces inside GLFW.  Each interface has its own area of
responsibility and its own naming conventions.

@section internals_public Public interface

The most well-known is the public interface, described in the glfw3.h header
file.  This is implemented in source files shared by all platforms and these
files contain no platform-specific code.  This code usually ends up calling the
platform and internal interfaces to do the actual work.

The public interface uses the OpenGL naming conventions except with GLFW and
glfw instead of GL and gl.  For struct members, where OpenGL sets no precedent,
it use headless camel case.

Examples: @ref glfwCreateWindow, @ref GLFWwindow, @ref GLFWvidmode.redBits,
`GLFW_RED_BITS`

@section internals_native Native interface

The [native interface](@ref native) is a small set of publicly available
but platform-specific functions, described in the glfw3native.h header file and
used to gain access to the underlying window, context and (on some platforms)
display handles used by the platform interface.

The function names of the native interface are similar to those of the public
interface, but embeds the name of the interface that the returned handle is
from.

Examples: @ref glfwGetX11Window, @ref glfwGetWGLContext

@section internals_internal Internal interface

The internal interface consists of utility functions used by all other
interfaces.  It is shared code implemented in the same shared source files as
the public and event interfaces.  The internal interface is described in the
internal.h header file.

The internal interface is in charge of GLFW's global data, which it stores in
a `_GLFWlibrary` struct named `_glfw`.

The internal interface uses the same style as the public interface, except all
global names have a leading underscore.

Examples: @ref _glfwIsValidContextConfig, @ref _GLFWwindow, `_glfw.currentRamp`

@section internals_platform Platform interface

The platform interface implements all platform-specific operations as a service
to the public interface.  This includes event processing.  The platform
interface is never directly called by application code and never directly calls
application-provided callbacks.  It is also prohibited from modifying the
platform-independent part of the internal structs.  Instead, it calls the event
interface when events interesting to GLFW are received.

The platform interface mirrors those parts of the public interface that needs to
perform platform-specific operations on some or all platforms.  The are also
named the same except that the glfw function prefix is replaced by
_glfwPlatform.

Examples: @ref _glfwPlatformCreateWindow

The platform interface also defines structs that contain platform-specific
global and per-object state.  Their names mirror those of the internal
interface, except that an interface-specific suffix is added.

Examples: `_GLFWwindowX11`, `_GLFWcontextWGL`

These structs are incorporated as members into the internal interface structs
using special macros that name them after the specific interface used.  This
prevents shared code from accidentally using these members.

Examples: `window.win32.handle`, `_glfw.x11.display`

@section internals_event Event interface

The event interface is implemented in the same shared source files as the public
interface and is responsible for delivering the events it receives to the
application, either via callbacks, via window state changes or both.

The function names of the event interface use a `_glfwInput` prefix and the
ObjectEvent pattern.

Examples: @ref _glfwInputWindowFocus, @ref _glfwInputCursorMotion

@section internals_static Static functions

Static functions may be used by any interface and have no prefixes or suffixes.
These use headless camel case.

Examples: `clearScrollOffsets`

@section internals_config Configuration macros

GLFW uses a number of configuration macros to select at compile time which
interfaces and code paths to use.  They are defined in the glfw_config.h header file,
which is generated from the `glfw_config.h.in` file by CMake.

Configuration macros the same style as tokens in the public interface, except
with a leading underscore.

Examples: `_GLFW_HAS_XF86VM`

*/


text:
/*!

@page news New features

@section news_32 New features in 3.2

@subsection news_32_vulkan Support for Vulkan

GLFW now supports basic integration with Vulkan with @ref glfwVulkanSupported,
@ref glfwGetRequiredInstanceExtensions, @ref glfwGetInstanceProcAddress, @ref
glfwGetPhysicalDevicePresentationSupport and @ref glfwCreateWindowSurface.
Vulkan header inclusion can be selected with
[GLFW_INCLUDE_VULKAN](@ref build_macros).

@subsection news_32_setwindowmonitor Window mode switching

GLFW now supports switching between windowed and full screen modes and updating
the monitor and desired resolution and refresh rate of full screen windows with
@ref glfwSetWindowMonitor.

@subsection news_32_maximize Window maxmimization support

GLFW now supports window maximization with @ref glfwMaximizeWindow and the
[GLFW_MAXIMIZED](@ref window_attribs_wnd) window hint and attribute.

@subsection news_32_focus Window input focus control

GLFW now supports giving windows input focus with @ref glfwFocusWindow.

@subsection news_32_sizelimits Window size limit support

GLFW now supports setting both absolute and relative window size limits with
@ref glfwSetWindowSizeLimits and @ref glfwSetWindowAspectRatio.

@subsection news_32_keyname Localized key names

GLFW now supports querying the localized name of printable keys with @ref
glfwGetKeyName, either by key token or by scancode.

@subsection news_32_waittimeout Wait for events with timeout

GLFW now supports waiting for events for a set amount of time with @ref
glfwWaitEventsTimeout.

@subsection news_32_icon Window icon support

GLFW now supports setting the icon of windows with @ref glfwSetWindowIcon.

@subsection news_32_timer Raw timer access

GLFW now supports raw timer values with @ref glfwGetTimerValue and @ref
glfwGetTimerFrequency.

@subsection news_32_joystick Joystick connection callback

GLFW now supports notifying when a joystick has been connected or disconnected
with @ref glfwSetJoystickCallback.

@subsection news_32_noapi Context-less windows

GLFW now supports creating windows without a OpenGL or OpenGL ES context with
[GLFW_NO_API](@ref window_hints_ctx).

@subsection news_32_contextapi Run-time context creation API selection

GLFW now supports selecting the context creation API at run-time with the
[GLFW_CONTEXT_CREATION_API](@ref window_hints_ctx) window hint value.

@subsection news_32_noerror Error-free context creation

GLFW now supports creating OpenGL and OpenGL ES contexts that do not emit errors
with the [GLFW_CONTEXT_NO_ERROR](@ref window_hints_ctx) window hint, provided
the machine supports the `GL_KHR_no_error` extension.

@subsection news_32_cmake CMake config-file package support

GLFW now supports being used as a
[config-file package](@ref build_link_cmake_package) from other projects for
easy linking with the library and its dependencies.

@section news_31 New features in 3.1

These are the release highlights.  For a full list of changes see the
[version history](http://www.glfw.org/changelog.html).

@subsection news_31_cursor Custom mouse cursor images

GLFW now supports creating and setting both custom cursor images and standard
cursor shapes.  They are created with @ref glfwCreateCursor or @ref
glfwCreateStandardCursor, set with @ref glfwSetCursor and destroyed with @ref
glfwDestroyCursor.

@see @ref cursor_object

@subsection news_31_drop Path drop event

GLFW now provides a callback for receiving the paths of files and directories
dropped onto GLFW windows.  The callback is set with @ref glfwSetDropCallback.

@see @ref path_drop

@subsection news_31_emptyevent Main thread wake-up

GLFW now provides the @ref glfwPostEmptyEvent function for posting an empty
event from another thread to the main thread event queue, causing @ref
glfwWaitEvents to return.

@see @ref events

@subsection news_31_framesize Window frame size query

GLFW now supports querying the size, on each side, of the frame around the
client area of a window, with @ref glfwGetWindowFrameSize.

@see [Window size](@ref window_size)

@subsection news_31_autoiconify Simultaneous multi-monitor rendering

GLFW now supports disabling auto-iconification of full screen windows with
the [GLFW_AUTO_ICONIFY](@ref window_hints_wnd) window hint.  This is intended
for people building multi-monitor installations, where you need windows to stay
in full screen despite losing input focus.

@subsection news_31_floating Floating windows

GLFW now supports floating windows, also called topmost or always on top, for
easier debugging with the [GLFW_FLOATING](@ref window_hints_wnd) window hint.

@subsection news_31_focused Initially unfocused windows

GLFW now supports preventing a windowed mode window from gaining input focus on
creation, with the [GLFW_FOCUSED](@ref window_hints_wnd) window hint.

@subsection news_31_direct Direct access for window attributes and cursor position

GLFW now queries the window input focus, visibility and iconification attributes
and the cursor position directly instead of returning cached data.

@subsection news_31_charmods Character with modifiers callback

GLFW now provides a callback for character events with modifier key bits.  The
callback is set with @ref glfwSetCharModsCallback.  Unlike the regular character
callback, this will report character events that will not result in a character
being input, for example if the Control key is held down.

@see @ref input_char

@subsection news_31_single Single buffered framebuffers

GLFW now supports the creation of single buffered windows, with the
[GLFW_DOUBLEBUFFER](@ref window_hints_fb) window hint.

@subsection news_31_glext Macro for including extension header

GLFW now includes the extension header appropriate for the chosen OpenGL or
OpenGL ES header when [GLFW_INCLUDE_GLEXT](@ref build_macros) is defined.  GLFW
does not provide these headers.  They must be provided by your development
environment or your OpenGL or OpenGL ES SDK.

@subsection news_31_release Context release behaviors

GLFW now supports controlling whether the pipeline is flushed when a context is
made non-current, with the
[GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint, provided the
machine supports the `GL_KHR_context_flush_control` extension.

@subsection news_31_wayland (Experimental) Wayland support

GLFW now has an _experimental_ Wayland display protocol backend that can be
selected on Linux with a CMake option.

@subsection news_31_mir (Experimental) Mir support

GLFW now has an _experimental_ Mir display server backend that can be selected
on Linux with a CMake option.

@section news_30 New features in 3.0

These are the release highlights.  For a full list of changes see the
[version history](http://www.glfw.org/changelog.html).

@subsection news_30_cmake CMake build system

GLFW now uses the CMake build system instead of the various makefiles and
project files used by earlier versions.  CMake is available for all platforms
supported by GLFW, is present in most package systems and can generate
makefiles and/or project files for most popular development environments.

For more information on how to use CMake, see the
[CMake manual](http://cmake.org/cmake/help/documentation.html).

@subsection news_30_multiwnd Multi-window support

GLFW now supports the creation of multiple windows, each with their own OpenGL
or OpenGL ES context, and all window functions now take a window handle.  Event
callbacks are now per-window and are provided with the handle of the window that
received the event.  The @ref glfwMakeContextCurrent function has been added to
select which context is current on a given thread.

@subsection news_30_multimon Multi-monitor support

GLFW now explicitly supports multiple monitors.  They can be enumerated with
@ref glfwGetMonitors, queried with @ref glfwGetVideoModes, @ref
glfwGetMonitorPos, @ref glfwGetMonitorName and @ref glfwGetMonitorPhysicalSize,
and specified at window creation to make the newly created window full screen on
that specific monitor.

@subsection news_30_unicode Unicode support

All string arguments to GLFW functions and all strings returned by GLFW now use
the UTF-8 encoding.  This includes the window title, error string, clipboard
text, monitor and joystick names as well as the extension function arguments (as
ASCII is a subset of UTF-8).

@subsection news_30_clipboard Clipboard text I/O

GLFW now supports reading and writing plain text to and from the system
clipboard, with the @ref glfwGetClipboardString and @ref glfwSetClipboardString
functions.

@subsection news_30_gamma Gamma ramp support

GLFW now supports setting and reading back the gamma ramp of monitors, with the
@ref glfwGetGammaRamp and @ref glfwSetGammaRamp functions.  There is also @ref
glfwSetGamma, which generates a ramp from a gamma value and then sets it.

@subsection news_30_gles OpenGL ES support

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
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
drivers support creation of OpenGL ES context using the GLX and WGL APIs, while
AMD provides an EGL implementation instead.

@subsection news_30_egl (Experimental) EGL support

GLFW now has an experimental EGL context creation back end that can be selected
through CMake options.

@subsection news_30_hidpi High-DPI support

GLFW now supports high-DPI monitors on both Windows and OS X, giving windows full
resolution framebuffers where other UI elements are scaled up.  To achieve this,
@ref glfwGetFramebufferSize and @ref glfwSetFramebufferSizeCallback have been
added.  These work with pixels, while the rest of the GLFW API works with screen
coordinates.  This is important as OpenGL uses pixels, not screen coordinates.

@subsection news_30_error Error callback

GLFW now has an error callback, which can provide your application with much
more detailed diagnostics than was previously possible.  The callback is passed
an error code and a description string.

@subsection news_30_wndptr Per-window user pointer

Each window now has a user-defined pointer, retrieved with @ref
glfwGetWindowUserPointer and set with @ref glfwSetWindowUserPointer, to make it
easier to integrate GLFW into C++ code.

@subsection news_30_iconifyfun Window iconification callback

Each window now has a callback for iconification and restoration events,
which is set with @ref glfwSetWindowIconifyCallback.

@subsection news_30_wndposfun Window position callback

Each window now has a callback for position events, which is set with @ref
glfwSetWindowPosCallback.

@subsection news_30_wndpos Window position query

The position of a window can now be retrieved using @ref glfwGetWindowPos.

@subsection news_30_focusfun Window focus callback

Each windows now has a callback for focus events, which is set with @ref
glfwSetWindowFocusCallback.

@subsection news_30_enterleave Cursor enter/leave callback

Each window now has a callback for when the mouse cursor enters or leaves its
client area, which is set with @ref glfwSetCursorEnterCallback.

@subsection news_30_wndtitle Initial window title

The title of a window is now specified at creation time, as one of the arguments
to @ref glfwCreateWindow.

@subsection news_30_hidden Hidden windows

Windows can now be hidden with @ref glfwHideWindow, shown using @ref
glfwShowWindow and created initially hidden with the `GLFW_VISIBLE` window hint.
This allows for off-screen rendering in a way compatible with most drivers, as
well as moving a window to a specific position before showing it.

@subsection news_30_undecorated Undecorated windows

Windowed mode windows can now be created without decorations, e.g. things like
a frame, a title bar, with the `GLFW_DECORATED` window hint.  This allows for
the creation of things like splash screens.

@subsection news_30_keymods Modifier key bit masks

[Modifier key bit mask](@ref mods) parameters have been added to the
[mouse button](@ref GLFWmousebuttonfun) and [key](@ref GLFWkeyfun) callbacks.

@subsection news_30_scancode Platform-specific scancodes

A scancode parameter has been added to the [key callback](@ref GLFWkeyfun). Keys
that don't have a [key token](@ref keys) still get passed on with the key
parameter set to `GLFW_KEY_UNKNOWN`.  These scancodes will vary between machines
and are intended to be used for key bindings.

@subsection news_30_jsname Joystick names

The name of a joystick can now be retrieved using @ref glfwGetJoystickName.

@subsection news_30_doxygen Doxygen documentation

You are reading it.

*/


text:
/*!

@page compile_guide Compiling GLFW

@tableofcontents

This is about compiling the GLFW library itself.  For information on how to
build applications that use GLFW, see @ref build_guide.

@section compile_cmake Using CMake

GLFW uses [CMake](http://www.cmake.org/) to generate project files or makefiles
for a particular development environment.  If you are on a Unix-like system such
as Linux or FreeBSD or have a package system like Fink, MacPorts, Cygwin or
Homebrew, you can simply install its CMake package.  If not, you can download
installers for Windows and OS X from the [CMake website](http://www.cmake.org/).

@note CMake only generates project files or makefiles.  It does not compile the
actual GLFW library.  To compile GLFW, first generate these files for your
chosen development environment and then use them to compile the actual GLFW
library.

@subsection compile_deps Dependencies

Once you have installed CMake, make sure that all other dependencies are
available.  On some platforms, GLFW needs a few additional packages to be
installed.  See the section for your chosen platform and development environment
below.

@subsubsection compile_deps_msvc Dependencies for Visual C++ on Windows

The Microsoft Platform SDK that is installed along with Visual C++ already
contains all the necessary headers, link libraries and tools except for CMake.
Move on to @ref compile_generate.

@subsubsection compile_deps_mingw Dependencies for MinGW or MinGW-w64 on Windows

Both the MinGW and the MinGW-w64 packages already contain all the necessary
headers, link libraries and tools except for CMake.  Move on to @ref
compile_generate.

@subsubsection compile_deps_mingw_cross Dependencies for MinGW or MinGW-w64 cross-compilation

Both Cygwin and many Linux distributions have MinGW or MinGW-w64 packages.  For
example, Cygwin has the `mingw64-i686-gcc` and `mingw64-x86_64-gcc` packages
for 32- and 64-bit version of MinGW-w64, while Debian GNU/Linux and derivatives
like Ubuntu have the `mingw-w64` package for both.

GLFW has CMake toolchain files in the `CMake/` directory that allow for easy
cross-compilation of Windows binaries.  To use these files you need to add a
special parameter when generating the project files or makefiles:

@code{.sh}
cmake -DCMAKE_TOOLCHAIN_FILE=<toolchain-file> .
@endcode

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
directory.  For example, both the Debian/Ubuntu and Cygwin MinGW-w64 packages
have `/usr/x86_64-w64-mingw32` for the 64-bit compilers, so the correct
invocation would be:

@code{.sh}
cmake -DCMAKE_TOOLCHAIN_FILE=CMake/x86_64-w64-mingw32.cmake .
@endcode

For more details see the article
[CMake Cross Compiling](http://www.paraview.org/Wiki/CMake_Cross_Compiling) on
the CMake wiki.

Once you have this set up, move on to @ref compile_generate.

@subsubsection compile_deps_xcode Dependencies for Xcode on OS X

Xcode comes with all necessary tools except for CMake.  The required headers
and libraries are included in the core OS X frameworks.  Xcode can be downloaded
from the Mac App Store or from the ADC Member Center.

Once you have Xcode installed, move on to @ref compile_generate.

@subsubsection compile_deps_x11 Dependencies for Linux and X11

To compile GLFW for X11, you need to have the X11 packages installed, as well as
the basic development tools like GCC and make.  For example, on Ubuntu and other
distributions based on Debian GNU/Linux, you need to install the `xorg-dev`
package, which pulls in all X.org header packages.

Once you have installed the necessary packages, move on to @ref
compile_generate.

@subsection compile_generate Generating build files with CMake

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
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
compiled binaries.  If these are the same, it is called an in-tree build,
otherwise it is called an out-of-tree build.

One of several advantages of out-of-tree builds is that you can generate files
and compile for different development environments using a single source tree.

@note This section is about generating the project files or makefiles necessary
to compile the GLFW library, not about compiling the actual library.

@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
(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
source tree.

@code{.sh}
cd <glfw-root-dir>
cmake .
@endcode

To make an out-of-tree build, make a directory outside of the source tree, enter
it and run CMake with the (relative or absolute) path to the root of the source
tree as an argument.

@code{.sh}
mkdir glfw-build
cd glfw-build
cmake <glfw-root-dir>
@endcode

Once you have generated the project files or makefiles for your chosen
development environment, move on to @ref compile_compile.

@subsubsection compile_generate_gui Generating files with the CMake GUI

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
destination for binaries.  Choose _Configure_, change any options you wish to,
_Configure_ again to let the changes take effect and then _Generate_.

Once you have generated the project files or makefiles for your chosen
development environment, move on to @ref compile_compile.

@subsection compile_compile Compiling the library

You should now have all required dependencies and the project files or makefiles
necessary to compile GLFW.  Go ahead and compile the actual GLFW library with
these files, as you would with any other project.

Once the GLFW library is compiled, you are ready to build your applications,
linking it to the GLFW library.  See @ref build_guide for more information.

@subsection compile_options CMake options

The CMake files for GLFW provide a number of options, although not all are
available on all supported platforms.  Some of these are de facto standards
among projects using CMake and so have no `GLFW_` prefix.

If you are using the GUI version of CMake, these are listed and can be changed
from there.  If you are using the command-line version of CMake you can use the
`ccmake` ncurses GUI to set options.  Some package systems like Ubuntu and other
distributions based on Debian GNU/Linux have this tool in a separate
`cmake-curses-gui` package.

Finally, if you don't want to use any GUI, you can set options from the `cmake`
command-line with the `-D` flag.

@code{.sh}
cmake -DBUILD_SHARED_LIBS=ON .
@endcode

@subsubsection compile_options_shared Shared CMake options

`BUILD_SHARED_LIBS` determines whether GLFW is built as a static
library or as a DLL / shared library / dynamic library.

`LIB_SUFFIX` affects where the GLFW shared /dynamic library is installed.  If it
is empty, it is installed to `${CMAKE_INSTALL_PREFIX}/lib`.  If it is set to
`64`, it is installed to `${CMAKE_INSTALL_PREFIX}/lib64`.

`GLFW_BUILD_EXAMPLES` determines whether the GLFW examples are built
along with the library.

`GLFW_BUILD_TESTS` determines whether the GLFW test programs are
built along with the library.

`GLFW_BUILD_DOCS` determines whether the GLFW documentation is built along with
the library.

`GLFW_VULKAN_STATIC` determines whether to use the Vulkan loader linked
statically into the application.

@subsubsection compile_options_osx OS X specific CMake options

`GLFW_USE_CHDIR` determines whether `glfwInit` changes the current
directory of bundled applications to the `Contents/Resources` directory.

`GLFW_USE_MENUBAR` determines whether the first call to
`glfwCreateWindow` sets up a minimal menu bar.

`GLFW_USE_RETINA` determines whether windows will use the full resolution of
Retina displays.

@subsubsection compile_options_win32 Windows specific CMake options

`USE_MSVC_RUNTIME_LIBRARY_DLL` determines whether to use the DLL version or the
static library version of the Visual C++ runtime library.  If set to `ON`, the
DLL version of the Visual C++ library is used.

`GLFW_USE_HYBRID_HPG` determines whether to export the `NvOptimusEnablement` and
`AmdPowerXpressRequestHighPerformance` symbols, which force the use of the
high-performance GPU on Nvidia Optimus and AMD PowerXpress systems.  These symbols
need to be exported by the EXE to be detected by the driver, so the override
will not work if GLFW is built as a DLL.

@section compile_manual Compiling GLFW manually

If you wish to compile GLFW without its CMake build environment then you will
have to do at least some of the platform detection yourself.  GLFW needs
a configuration macro to be defined in order to know what window system it's
being compiled for and also has optional, platform-specific ones for various
features.

When building with CMake, the `glfw_config.h` configuration header is generated
based on the current platform and CMake options.  The GLFW CMake environment
defines `_GLFW_USE_CONFIG_H`, which causes this header to be included by
`internal.h`.  Without this macro, GLFW will expect the necessary configuration
macros to be defined on the command-line.

The window creation API is used to create windows, handle input, monitors, gamma
ramps and clipboard.  The options are:

 - `_GLFW_COCOA` to use the Cocoa frameworks
 - `_GLFW_WIN32` to use the Win32 API
 - `_GLFW_X11` to use the X Window System
 - `_GLFW_WAYLAND` to use the Wayland API (experimental and incomplete)
 - `_GLFW_MIR` to use the Mir API (experimental and incomplete)

If you are building GLFW as a shared library / dynamic library / DLL then you
must also define `_GLFW_BUILD_DLL`.  Otherwise, you must not define it.

If you are linking the Vulkan loader statically into your application then you
must also define `_GLFW_VULKAN_STATIC`.  Otherwise, GLFW will attempt to use the
external version.

For the EGL context creation API, the following options are available:

 - `_GLFW_USE_EGLPLATFORM_H` to use `EGL/eglplatform.h` for native handle
   definitions (fallback)

If you are using the X11 window creation API, support for the following X11
extensions can be enabled:

 - `_GLFW_HAS_XF86VM` to use Xxf86vm as a fallback when RandR gamma is broken
 (recommended)

If you are using the Cocoa window creation API, the following options are
available:

 - `_GLFW_USE_CHDIR` to `chdir` to the `Resources` subdirectory of the
   application bundle during @ref glfwInit (recommended)
 - `_GLFW_USE_MENUBAR` to create and populate the menu bar when the first window
   is created (recommended)
 - `_GLFW_USE_RETINA` to have windows use the full resolution of Retina displays
   (recommended)

@note None of the @ref build_macros may be defined during the compilation of
GLFW.  If you define any of these in your build files, make sure they are not
applied to the GLFW sources.

*/


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

- s -

GLFW_SAMPLES
: glfw3.h

GLFW_SRGB_CAPABLE
: glfw3.h

GLFW_STENCIL_BITS
: glfw3.h

GLFW_STEREO
: glfw3.h

GLFW_STICKY_KEYS
: glfw3.h

GLFW_STICKY_MOUSE_BUTTONS
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: compile.dox File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

compile.dox File Reference

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Bug List</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Bug List

Page Window guide

On some Linux systems, creating contexts via both the native and EGL APIs in a single process will cause the application to segfault. Stick to one API or the other on Linux for now.

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Standards conformance</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Standards conformance

Table of Contents

X11 extensions, protocols and IPC standards

GLX extensions

WGL extensions

OpenGL 3.2 and later on OS X

Vulkan loader and API

Vulkan WSI extensions

This guide describes the various API extensions used by this version of GLFW. It lists what are essentially implementation details, but which are nonetheless vital knowledge for developers intending to deploy their applications on a wide range of machines.

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 part of this information may change in future versions of GLFW and that will not be considered a breaking API change.

X11 extensions, protocols and IPC standards

As GLFW uses Xlib directly, without any intervening toolkit library, it has sole responsibility for interacting well with the many and varied window managers in use on Unix-like systems. In order for applications and window managers to work well together, a number of standards and conventions have been developed that regulate behavior outside the scope of the X11 API; most importantly the Inter-Client Communication Conventions Manual (ICCCM) and Extended Window Manager Hints (EWMH) standards.

GLFW uses the _MOTIF_WM_HINTS window property to support borderless windows. If the running window manager does not support this property, the GLFW_DECORATED hint will have no effect.

GLFW uses the ICCCM WM_DELETE_WINDOW protocol to intercept the user attempting to close the GLFW window. If the running window manager does not support this protocol, the close callback will never be called.

GLFW uses the EWMH _NET_WM_PING protocol, allowing the window manager notify the user when the application has stopped responding, i.e. when it has ceased to process events. If the running window manager does not support this protocol, the user will not be notified if the application locks up.

GLFW uses the EWMH _NET_WM_STATE_FULLSCREEN window state to tell the window manager to make the GLFW window full screen. If the running window manager does not support this state, full screen windows may not work properly. GLFW has a fallback code path in case this state is unavailable, but every window manager behaves slightly differently in this regard.

GLFW uses the EWMH _NET_WM_BYPASS_COMPOSITOR window property to tell a compositing window manager to un-redirect full screen GLFW windows. If the running window manager uses compositing but does not support this property then additional copying may be performed for each buffer swap of full screen windows.

GLFW uses the clipboard manager protocol to push a clipboard string (i.e. selection) owned by a GLFW window about to be destroyed to the clipboard manager. If there is no running clipboard manager, the clipboard string will be unavailable once the window has been destroyed.

GLFW uses the X drag-and-drop protocol to provide file drop events. If the application originating the drag does not support this protocol, drag and drop will not work.

GLFW uses the XRandR 1.3 extension to provide multi-monitor support. If the running X server does not support this version of this extension, multi-monitor support will not function and only a single, desktop-spanning monitor will be reported.

GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp support. If the running X server does not support either or both of these extensions, gamma ramp support will not function.

GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard input. If the running X server does not support this extension, a non-Xkb fallback path is used.

GLX extensions

The GLX API is the default API used to create OpenGL contexts on Unix-like systems using the X Window System.

GLFW uses the GLX 1.3 GLXFBConfig functions to enumerate and select framebuffer pixel formats. If GLX 1.3 is not supported, glfwInit will fail.

GLFW uses the GLX_MESA_swap_control, GLX_EXT_swap_control and GLX_SGI_swap_control extensions to provide vertical retrace synchronization (or vsync), in that order of preference. Where none of these extension are available, calling glfwSwapInterval will have no effect.

GLFW uses the GLX_ARB_multisample extension to create contexts with multisampling anti-aliasing. Where this extension is unavailable, the GLFW_SAMPLES hint will have no effect.

GLFW uses the GLX_ARB_create_context extension when available, even when creating OpenGL contexts of version 2.1 and below. Where this extension is unavailable, the GLFW_CONTEXT_VERSION_MAJOR and GLFW_CONTEXT_VERSION_MINOR hints will only be partially supported, the GLFW_OPENGL_DEBUG_CONTEXT hint will have no effect, and setting the GLFW_OPENGL_PROFILE or GLFW_OPENGL_FORWARD_COMPAT hints to GLFW_TRUE will cause glfwCreateWindow to fail.

GLFW uses the GLX_ARB_create_context_profile extension to provide support for context profiles. Where this extension is unavailable, setting the GLFW_OPENGL_PROFILE hint to anything but GLFW_OPENGL_ANY_PROFILE, or setting GLFW_CLIENT_API to anything but GLFW_OPENGL_API or GLFW_NO_API will cause glfwCreateWindow to fail.

GLFW uses the GLX_ARB_context_flush_control extension to provide control over whether a context is flushed when it is released (made non-current). Where this extension is unavailable, the GLFW_CONTEXT_RELEASE_BEHAVIOR hint will have no effect and the context will always be flushed when released.

GLFW uses the GLX_ARB_framebuffer_sRGB and GLX_EXT_framebuffer_sRGB extensions to provide support for sRGB framebuffers. Where both of these extensions are unavailable, the GLFW_SRGB_CAPABLE hint will have no effect.

WGL extensions

The WGL API is used to create OpenGL contexts on Microsoft Windows and other implementations of the Win32 API, such as Wine.

GLFW uses either the WGL_EXT_extension_string or the WGL_ARB_extension_string extension to check for the presence of all other WGL extensions listed below. If both are available, the EXT one is preferred. If neither is available, no other extensions are used and many GLFW features related to context creation will have no effect or cause errors when used.

GLFW uses the WGL_EXT_swap_control extension to provide vertical retrace synchronization (or vsync). Where this extension is unavailable, calling glfwSwapInterval will have no effect.

GLFW uses the WGL_ARB_pixel_format and WGL_ARB_multisample extensions to create contexts with multisampling anti-aliasing. Where these extensions are unavailable, the GLFW_SAMPLES hint will have no effect.

GLFW uses the WGL_ARB_create_context extension when available, even when creating OpenGL contexts of version 2.1 and below. Where this extension is unavailable, the GLFW_CONTEXT_VERSION_MAJOR and GLFW_CONTEXT_VERSION_MINOR hints will only be partially supported, the GLFW_OPENGL_DEBUG_CONTEXT hint will have no effect, and setting the GLFW_OPENGL_PROFILE or GLFW_OPENGL_FORWARD_COMPAT hints to GLFW_TRUE will cause glfwCreateWindow to fail.

GLFW uses the WGL_ARB_create_context_profile extension to provide support for context profiles. Where this extension is unavailable, setting the GLFW_OPENGL_PROFILE hint to anything but GLFW_OPENGL_ANY_PROFILE will cause glfwCreateWindow to fail.

GLFW uses the WGL_ARB_context_flush_control extension to provide control over whether a context is flushed when it is released (made non-current). Where this extension is unavailable, the GLFW_CONTEXT_RELEASE_BEHAVIOR hint will have no effect and the context will always be flushed when released.

GLFW uses the WGL_ARB_framebuffer_sRGB and WGL_EXT_framebuffer_sRGB extensions to provide support for sRGB framebuffers. Where both of these extension are unavailable, the GLFW_SRGB_CAPABLE hint will have no effect.

OpenGL 3.2 and later on OS X

Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then only forward-compatible, core profile contexts are supported. Support for OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible, core profile contexts. There is also still no mechanism for requesting debug contexts. Versions of Mac OS X earlier than 10.7 support at most OpenGL version 2.1.

Because of this, on OS X 10.7 and later, the GLFW_CONTEXT_VERSION_MAJOR and GLFW_CONTEXT_VERSION_MINOR hints will cause glfwCreateWindow to fail if given version 3.0 or 3.1, the GLFW_OPENGL_FORWARD_COMPAT hint must be set to GLFW_TRUE and the GLFW_OPENGL_PROFILE hint must be set to GLFW_OPENGL_CORE_PROFILE when creating OpenGL 3.2 and later contexts and the GLFW_OPENGL_DEBUG_CONTEXT hint is ignored.

Also, on Mac OS X 10.6 and below, the GLFW_CONTEXT_VERSION_MAJOR and GLFW_CONTEXT_VERSION_MINOR hints will fail if given a version above 2.1, setting the GLFW_OPENGL_PROFILE or GLFW_OPENGL_FORWARD_COMPAT hints to a non-default value will cause glfwCreateWindow to fail and the GLFW_OPENGL_DEBUG_CONTEXT hint is ignored.

Vulkan loader and API

GLFW uses the standard system-wide Vulkan loader to access the Vulkan API. This should be installed by graphics drivers and Vulkan SDKs. If this is not available, glfwVulkanSupported will return GLFW_FALSE and all other Vulkan-related functions will fail with an GLFW_API_UNAVAILABLE error.

Vulkan WSI extensions

The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on all supported platforms.

GLFW uses the VK_KHR_surface and VK_KHR_win32_surface extensions to create surfaces on Microsoft Windows. If any of these extensions are not available, glfwGetRequiredInstanceExtensions will return an empty list and window surface creation will fail.

GLFW uses the VK_KHR_surface and either the VK_KHR_xlib_surface or VK_KHR_xcb_surface extensions to create surfaces on X11. If VK_KHR_surface or both VK_KHR_xlib_surface and VK_KHR_xcb_surface are not available, glfwGetRequiredInstanceExtensions will return an empty list and window surface creation will fail.

GLFW uses the VK_KHR_surface and VK_KHR_wayland_surface extensions to create surfaces on Wayland. If any of these extensions are not available, glfwGetRequiredInstanceExtensions will return an empty list and window surface creation will fail.

GLFW uses the VK_KHR_surface and VK_KHR_mir_surface extensions to create surfaces on Mir. If any of these extensions are not available, glfwGetRequiredInstanceExtensions will return an empty list and window surface creation will fail.

GLFW does not support any extensions for window surface creation on OS X, meaningglfwGetRequiredInstanceExtensions will return an empty list and window surface creation will fail.

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>