281013002d
This changes the behavior of framebuffer hints set to zero. Before, zero meant that any value was acceptable. This changes zero to be an explicit preference and adds GLFW_DONT_CARE to mean that any value is equally acceptable. Fixes #70.
505 lines
20 KiB
Plaintext
505 lines
20 KiB
Plaintext
/*!
|
|
|
|
@page window Window handling guide
|
|
|
|
@tableofcontents
|
|
|
|
The primary purpose of GLFW is to provide a simple interface to window
|
|
management and OpenGL and OpenGL ES context creation. GLFW supports multiple
|
|
windows, which can be either a normal desktop window or a full screen window.
|
|
|
|
|
|
@section window_object Window handles
|
|
|
|
The @ref GLFWwindow object encapsulates both a window and a context. They are
|
|
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
|
|
@ref glfwTerminate, if any remain). As the window and context are inseparably
|
|
linked, the object pointer is used as both a context and window handle.
|
|
|
|
|
|
@section window_creation Window creation
|
|
|
|
The window and its context are created with @ref glfwCreateWindow, which
|
|
returns a handle to the created window object. For example, this creates a 640
|
|
by 480 windowed mode window:
|
|
|
|
@code
|
|
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
|
|
@endcode
|
|
|
|
If window creation fails, `NULL` will be returned, so you need to check whether
|
|
it did.
|
|
|
|
This handle is then passed to all window related functions, and is provided to
|
|
you along with input events, so you know which window received the input.
|
|
|
|
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. For
|
|
more information about monitors, see the @ref monitor.
|
|
|
|
@code
|
|
GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
|
|
@endcode
|
|
|
|
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
|
|
matching the requested window size.
|
|
|
|
For more control over how the window and its context are created, see @ref
|
|
window_hints below.
|
|
|
|
|
|
@section window_destruction Window destruction
|
|
|
|
When you are done with the window, destroy it with the @ref glfwDestroyWindow
|
|
function.
|
|
|
|
@code
|
|
glfwDestroyWindow(window);
|
|
@endcode
|
|
|
|
Once this function is called, no more events will be delivered for that window
|
|
and its handle becomes invalid.
|
|
|
|
|
|
@section window_userptr Window user pointer
|
|
|
|
Each window has a user pointer that can be set with @ref
|
|
glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer. This
|
|
can be used for any purpose you need and will not be modified by GLFW throughout
|
|
the life-time of the window.
|
|
|
|
|
|
@section window_hints Window creation hints
|
|
|
|
There are a number of hints that can be set before the creation of a window and
|
|
context. Some affect the window itself, others affect the framebuffer or
|
|
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
|
|
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
|
|
you wish to have the specified attributes.
|
|
|
|
|
|
@subsection window_hints_hard Hard and soft constraints
|
|
|
|
Some window hints are hard constraints. These must match the available
|
|
capabilities *exactly* for window and context creation to succeed. Hints
|
|
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
|
|
find out the actual attributes of the created window and context, use the
|
|
@ref glfwGetWindowAttrib function.
|
|
|
|
The following hints are hard constraints:
|
|
- `GLFW_STEREO`
|
|
- `GLFW_CLIENT_API`
|
|
|
|
The following additional hints are hard constraints if requesting an OpenGL
|
|
context:
|
|
- `GLFW_OPENGL_FORWARD_COMPAT`
|
|
- `GLFW_OPENGL_PROFILE`
|
|
|
|
Hints that do not apply to a given type of window or context are ignored.
|
|
|
|
|
|
@subsection window_hints_wnd Window related hints
|
|
|
|
The `GLFW_RESIZABLE` hint specifies whether the (windowed mode) window will be
|
|
resizable *by the user*. The window will still be resizable using the @ref
|
|
glfwSetWindowSize function. This hint is ignored for full screen windows.
|
|
|
|
The `GLFW_VISIBLE` hint specifies whether the (windowed mode) window will be
|
|
initially visible. This hint is ignored for full screen windows.
|
|
|
|
The `GLFW_DECORATED` hint specifies whether the (windowed mode) window will have
|
|
window decorations such as a border, a close widget, etc. This hint is ignored
|
|
for full screen windows. Note that even though a window may lack a close
|
|
widget, it is usually still possible for the user to generate close events.
|
|
|
|
The `GLFW_AUTO_ICONIFY` hint specifies whether the (full screen) window
|
|
will automatically iconify and restore the previous video mode on focus loss.
|
|
This hint is ignored for windowed mode windows.
|
|
|
|
|
|
@subsection window_hints_fb Framebuffer related hints
|
|
|
|
The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
|
|
`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit
|
|
depths of the various components of the default framebuffer. `GLFW_DONT_CARE`
|
|
means the application has no preference.
|
|
|
|
The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS`
|
|
and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the
|
|
various components of the accumulation buffer. `GLFW_DONT_CARE` means the
|
|
application has no preference.
|
|
|
|
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary
|
|
buffers. `GLFW_DONT_CARE` means the application has no preference.
|
|
|
|
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering.
|
|
|
|
The `GLFW_SAMPLES` hint specifies the desired number of samples to use for
|
|
multisampling. Zero disables multisampling. `GLFW_DONT_CARE` means the
|
|
application has no preference.
|
|
|
|
The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be
|
|
sRGB capable.
|
|
|
|
The `GLFW_REFRESH_RATE` hint specifies the desired refresh rate for full screen
|
|
windows. If set to zero, the highest available refresh rate will be used. This
|
|
hint is ignored for windowed mode windows.
|
|
|
|
|
|
@subsection window_hints_ctx Context related hints
|
|
|
|
The `GLFW_CLIENT_API` hint specifies which client API to create the context
|
|
for. Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`.
|
|
|
|
The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints
|
|
specify the client API version that the created context must be compatible
|
|
with.
|
|
|
|
For OpenGL, these hints are *not* hard constraints, as they don't have to
|
|
match exactly, but @ref glfwCreateWindow will still fail if the resulting
|
|
OpenGL version is less than the one requested. It is therefore perfectly
|
|
safe to use the default of version 1.0 for legacy code and you may still
|
|
get backwards-compatible contexts of version 3.0 and above when available.
|
|
|
|
While there is no way to ask the driver for a context of the highest supported
|
|
version, most drivers provide this when you ask GLFW for a version
|
|
1.0 context.
|
|
|
|
For OpenGL ES, these hints are hard constraints.
|
|
|
|
If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint
|
|
specifies whether the OpenGL context should be forward-compatible, i.e. one
|
|
where all functionality deprecated in the requested version of OpenGL is
|
|
removed. This may only be used if the requested OpenGL version is 3.0 or
|
|
above. If another client API is requested, this hint is ignored.
|
|
|
|
If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
|
|
specifies whether to create a debug OpenGL context, which may have
|
|
additional error and performance issue reporting functionality. If another
|
|
client API is requested, this hint is ignored.
|
|
|
|
If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies
|
|
which OpenGL profile to create the context for. Possible values are one of
|
|
`GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or
|
|
`GLFW_OPENGL_ANY_PROFILE` to not request a specific profile. If requesting
|
|
an OpenGL version below 3.2, `GLFW_OPENGL_ANY_PROFILE` must be used. If
|
|
another client API is requested, this hint is ignored.
|
|
|
|
The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be
|
|
used by the context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or
|
|
`GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
|
|
a robustness strategy.
|
|
|
|
|
|
@subsection window_hints_values Supported and default values
|
|
|
|
| Name | Default value | Supported values |
|
|
| ---------------------------- | ------------------------- | ----------------------- |
|
|
| `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_VISIBLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_DECORATED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_AUTO_ICONIFY` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_REFRESH_RATE` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE` |
|
|
| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_SRGB_CAPABLE` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API` |
|
|
| `GLFW_CONTEXT_VERSION_MAJOR` | 1 | Any valid major version number of the chosen client API |
|
|
| `GLFW_CONTEXT_VERSION_MINOR` | 0 | Any valid minor version number of the chosen client API |
|
|
| `GLFW_CONTEXT_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` |
|
|
| `GLFW_OPENGL_FORWARD_COMPAT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_OPENGL_DEBUG_CONTEXT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` |
|
|
| `GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |
|
|
|
|
|
|
@section window_close Window close flag
|
|
|
|
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.
|
|
The window is however not actually destroyed and, unless you watch for this
|
|
state change, nothing further happens.
|
|
|
|
The current state of the close flag is returned by @ref glfwWindowShouldClose
|
|
and can be set or cleared directly with @ref glfwSetWindowShouldClose. A common
|
|
pattern is to use the close flag as a main loop condition.
|
|
|
|
@code
|
|
while (!glfwWindowShouldClose(window))
|
|
{
|
|
render(window);
|
|
|
|
glfwSwapBuffers(window);
|
|
glfwPollEvents();
|
|
}
|
|
@endcode
|
|
|
|
If you wish to be notified when the user attempts to close a window, you can set
|
|
the close callback with @ref glfwSetWindowCloseCallback. This callback is
|
|
called directly *after* the close flag has been set.
|
|
|
|
@code
|
|
glfwSetWindowCloseCallback(window, window_close_callback);
|
|
@endcode
|
|
|
|
The callback function can be used for example to filter close requests and clear
|
|
the close flag again unless certain conditions are met.
|
|
|
|
@code
|
|
void window_close_callback(GLFWwindow* window)
|
|
{
|
|
if (!time_to_close)
|
|
glfwSetWindowShouldClose(window, GL_FALSE);
|
|
}
|
|
@endcode
|
|
|
|
|
|
@section window_size Window size
|
|
|
|
The size of a window can be changed with @ref glfwSetWindowSize. For windowed
|
|
mode windows, this resizes the specified window so that its *client area* has
|
|
the specified size. Note that the window system may put limitations on size.
|
|
For full screen windows, it selects and sets the video mode most closely
|
|
matching the specified size.
|
|
|
|
@code
|
|
void glfwSetWindowSize(window, 640, 480);
|
|
@endcode
|
|
|
|
If you wish to be notified when a window is resized, whether by the user or
|
|
the system, you can set the size callback with @ref glfwSetWindowSizeCallback.
|
|
|
|
@code
|
|
glfwSetWindowSizeCallback(window, window_size_callback);
|
|
@endcode
|
|
|
|
The callback function receives the new size of the client area of the window.
|
|
|
|
@code
|
|
void window_size_callback(GLFWwindow* window, int width, int height)
|
|
{
|
|
}
|
|
@endcode
|
|
|
|
There is also @ref glfwGetWindowSize for directly retrieving the current size of
|
|
a window.
|
|
|
|
@code
|
|
int width, height;
|
|
glfwGetWindowSize(window, &width, &height);
|
|
@endcode
|
|
|
|
|
|
@section window_fbsize Window framebuffer size
|
|
|
|
While the size of a window is measured in screen coordinates, OpenGL works with
|
|
pixels. The size you pass into `glViewport`, for example, should be in pixels
|
|
and not screen coordinates. On some platforms screen coordinates and pixels are
|
|
the same, but this is not the case on all platforms supported by GLFW. There is
|
|
a second set of functions to retrieve the size in pixels of the framebuffer of
|
|
a window.
|
|
|
|
If you wish to be notified when the framebuffer of a window is resized, whether
|
|
by the user or the system, you can set the size callback with @ref
|
|
glfwSetFramebufferSizeCallback.
|
|
|
|
@code
|
|
glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
|
|
@endcode
|
|
|
|
The callback function receives the new size of the client area of the window,
|
|
which can for example be used to update the OpenGL viewport.
|
|
|
|
@code
|
|
void framebuffer_size_callback(GLFWwindow* window, int width, int height)
|
|
{
|
|
glViewport(0, 0, width, height);
|
|
}
|
|
@endcode
|
|
|
|
There is also @ref glfwGetFramebufferSize for directly retrieving the current
|
|
size of the framebuffer of a window.
|
|
|
|
@code
|
|
int width, height;
|
|
glfwGetFramebufferSize(window, &width, &height);
|
|
glViewport(0, 0, width, height);
|
|
@endcode
|
|
|
|
Note that the size of a framebuffer may change independently of the size of
|
|
a window, for example if the window is dragged between a regular monitor and
|
|
a high-DPI one.
|
|
|
|
|
|
@section window_pos Window position
|
|
|
|
The position of a windowed-mode window can be changed with @ref
|
|
glfwSetWindowPos. This moves the window so that the upper-left corner of its
|
|
client area has the specified screen coordinates. Note that the window system
|
|
may put limitations on placement.
|
|
|
|
@code
|
|
glfwSetWindowPos(window, 100, 100);
|
|
@endcode
|
|
|
|
If you wish to be notified when a window is moved, whether by the user or
|
|
the system, you can set the position callback with @ref glfwSetWindowPosCallback.
|
|
|
|
@code
|
|
glfwSetWindowPosCallback(window, window_pos_callback);
|
|
@endcode
|
|
|
|
The callback function receives the new position of the upper-left corner of its
|
|
client area.
|
|
|
|
@code
|
|
void window_pos_callback(GLFWwindow* window, int xpos, int ypos)
|
|
{
|
|
}
|
|
@endcode
|
|
|
|
There is also @ref glfwGetWindowPos for directly retrieving the current position
|
|
of the client area of the window.
|
|
|
|
@code
|
|
int xpos, ypos;
|
|
glfwGetWindowPos(window, &xpos, &ypos);
|
|
@endcode
|
|
|
|
|
|
@section window_title Window title
|
|
|
|
All GLFW windows have a title, although undecorated or full screen windows may
|
|
not display it or only display it in a task bar or similar interface. To change
|
|
the title of a window, use @ref glfwSetWindowTitle.
|
|
|
|
@code
|
|
glfwSetWindowTitle(window, "My Window");
|
|
@endcode
|
|
|
|
The window title is a regular C string using the UTF-8 encoding. This means
|
|
for example that, as long as your source file is encoded as UTF-8, you can use
|
|
any Unicode characters.
|
|
|
|
@code
|
|
glfwSetWindowTitle(window, "さよなら絶望先生");
|
|
@endcode
|
|
|
|
|
|
@section window_attribs Window attributes
|
|
|
|
Windows have a number of attributes that can be returned using @ref
|
|
glfwGetWindowAttrib. Some reflect state that may change during the lifetime of
|
|
the window, while others reflect the corresponding hints and are fixed at the
|
|
time of creation.
|
|
|
|
@code
|
|
if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
|
|
{
|
|
// window has input focus
|
|
}
|
|
@endcode
|
|
|
|
|
|
@subsection window_attribs_window Window attributes
|
|
|
|
The `GLFW_FOCUSED` attribute indicates whether the specified window currently
|
|
has input focus.
|
|
|
|
The `GLFW_ICONIFIED` attribute indicates whether the specified window is
|
|
currently iconified, whether by the user or with @ref glfwIconifyWindow.
|
|
|
|
The `GLFW_VISIBLE` attribute indicates whether the specified window is currently
|
|
visible. Window visibility can be controlled with @ref glfwShowWindow and @ref
|
|
glfwHideWindow and initial visibility is controlled by the
|
|
[window hint](@ref window_hints) with the same name.
|
|
|
|
The `GLFW_RESIZABLE` attribute indicates whether the specified window is
|
|
resizable *by the user*. This is controlled by the
|
|
[window hint](@ref window_hints) with the same name.
|
|
|
|
The `GLFW_DECORATED` attribute indicates whether the specified window has
|
|
decorations such as a border, a close widget, etc. This is controlled by the
|
|
[window hint](@ref window_hints) with the same name.
|
|
|
|
|
|
@subsection window_attribs_context Context attributes
|
|
|
|
The `GLFW_CLIENT_API` attribute indicates the client API provided by the
|
|
window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`.
|
|
|
|
The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
|
|
`GLFW_CONTEXT_REVISION` attributes indicate the client API version of the
|
|
window's context.
|
|
|
|
The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's
|
|
context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise.
|
|
|
|
The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's
|
|
context is an OpenGL debug context, or `GL_FALSE` otherwise.
|
|
|
|
The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the
|
|
context. This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`
|
|
if the context uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the
|
|
OpenGL profile is unknown or the context is for another client API. Note that
|
|
the returned profile may not match the profile bits of the context flags, as
|
|
GLFW will try other means of detecting the profile when no bits are set.
|
|
|
|
The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy
|
|
used by the context. This is `GLFW_LOSE_CONTEXT_ON_RESET` or
|
|
`GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or
|
|
`GLFW_NO_ROBUSTNESS` otherwise.
|
|
|
|
|
|
@section window_swap Swapping buffers
|
|
|
|
GLFW windows are always double buffered. That means that you have two
|
|
rendering buffers; a front buffer and a back buffer. The front buffer is
|
|
the one being displayed and the back buffer the one you render to.
|
|
|
|
When the entire frame has been rendered, it is time to swap the back and the
|
|
front buffers in order to display what has been rendered and begin rendering
|
|
a new frame. This is done with @ref glfwSwapBuffers.
|
|
|
|
@code
|
|
glfwSwapBuffers(window);
|
|
@endcode
|
|
|
|
Sometimes it can be useful to select when the buffer swap will occur. With the
|
|
function @ref glfwSwapInterval it is possible to select the minimum number of
|
|
monitor refreshes the driver should wait before swapping the buffers:
|
|
|
|
@code
|
|
glfwSwapInterval(1);
|
|
@endcode
|
|
|
|
If the interval is zero, the swap will take place immediately when @ref
|
|
glfwSwapBuffers is called without waiting for a refresh. Otherwise at least
|
|
interval retraces will pass between each buffer swap. Using a swap interval of
|
|
zero can be useful for benchmarking purposes, when it is not desirable to
|
|
measure the time it takes to wait for the vertical retrace. However, a swap
|
|
interval of one lets you avoid tearing.
|
|
|
|
Note that this may not work on all machines, as some drivers have
|
|
user-controlled settings that override any swap interval the application
|
|
requests. It is also by default disabled on Windows Vista and later when using
|
|
DWM (Aero), as using it there sometimes leads to severe jitter. You can
|
|
forcibly enable it for machines using DWM using @ref compile_options_win32.
|
|
|
|
*/
|