You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1008 lines
38 KiB
1008 lines
38 KiB
/*!
|
|
|
|
@page window_guide Window guide
|
|
|
|
@tableofcontents
|
|
|
|
This guide introduces the window related functions of GLFW. For details on
|
|
a specific function in this category, see the @ref window. There are also
|
|
guides for the other areas of GLFW.
|
|
|
|
- @ref intro_guide
|
|
- @ref context_guide
|
|
- @ref vulkan_guide
|
|
- @ref monitor_guide
|
|
- @ref input_guide
|
|
|
|
|
|
@section window_object Window objects
|
|
|
|
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.
|
|
|
|
To see the event stream provided to the various window related callbacks, run
|
|
the `events` test program.
|
|
|
|
|
|
@subsection window_creation Window creation
|
|
|
|
A window and its OpenGL or OpenGL ES context are created with @ref
|
|
glfwCreateWindow, which returns a handle to the created window object. For
|
|
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 it is necessary to check
|
|
the return value.
|
|
|
|
The window handle is passed to all window related functions and is provided to
|
|
along with all input events, so event handlers can tell which window received
|
|
the event.
|
|
|
|
|
|
@subsubsection window_full_screen Full screen windows
|
|
|
|
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 retrieving monitors, see @ref monitor_monitors.
|
|
|
|
@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.
|
|
|
|
Windowed mode windows can be made full screen by setting a monitor with @ref
|
|
glfwSetWindowMonitor, and full screen ones can be made windowed by unsetting it
|
|
with the same function.
|
|
|
|
Each field of the @ref GLFWvidmode structure corresponds to a function parameter
|
|
or window hint and combine to form the _desired video mode_ for that window.
|
|
The supported video mode most closely matching the desired video mode will be
|
|
set for the chosen monitor as long as the window has input focus. For more
|
|
information about retrieving video modes, see @ref monitor_modes.
|
|
|
|
Video mode field | Corresponds to
|
|
----------------------- | ------------------------
|
|
GLFWvidmode.width | `width` parameter
|
|
GLFWvidmode.height | `height` parameter
|
|
GLFWvidmode.redBits | `GLFW_RED_BITS` hint
|
|
GLFWvidmode.greenBits | `GLFW_GREEN_BITS` hint
|
|
GLFWvidmode.blueBits | `GLFW_BLUE_BITS` hint
|
|
GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint
|
|
|
|
Once you have a full screen window, you can change its resolution, refresh rate
|
|
and monitor with @ref glfwSetWindowMonitor. If you just need change its
|
|
resolution you can also call @ref glfwSetWindowSize. In all cases, the new
|
|
video mode will be selected the same way as the video mode chosen by @ref
|
|
glfwCreateWindow. If the window has an OpenGL or OpenGL ES context, it will be
|
|
unaffected.
|
|
|
|
By default, the original video mode of the monitor will be restored and the
|
|
window iconified if it loses input focus, to allow the user to switch back to
|
|
the desktop. This behavior can be disabled with the `GLFW_AUTO_ICONIFY` window
|
|
hint, for example if you wish to simultaneously cover multiple windows with full
|
|
screen windows.
|
|
|
|
|
|
@subsubsection window_windowed_full_screen "Windowed full screen" windows
|
|
|
|
If the closest match for the desired video mode is the current one, the video
|
|
mode will not be changed, making window creation faster and application
|
|
switching much smoother. This is sometimes called _windowed full screen_ or
|
|
_borderless full screen_ window and counts as a full screen window. To create
|
|
such a window, simply request the current video mode.
|
|
|
|
@code
|
|
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
|
|
|
|
glfwWindowHint(GLFW_RED_BITS, mode->redBits);
|
|
glfwWindowHint(GLFW_GREEN_BITS, mode->greenBits);
|
|
glfwWindowHint(GLFW_BLUE_BITS, mode->blueBits);
|
|
glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate);
|
|
|
|
GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL);
|
|
@endcode
|
|
|
|
This also works for windowed mode windows that are made full screen.
|
|
|
|
@code
|
|
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
|
|
|
|
glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
|
|
@endcode
|
|
|
|
Note that @ref glfwGetVideoMode returns the _current_ video mode of a monitor,
|
|
so if you already have a full screen window on that monitor that you want to
|
|
make windowed full screen, you need to have saved the desktop resolution before.
|
|
|
|
|
|
@subsection window_destruction Window destruction
|
|
|
|
When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
|
|
|
|
@code
|
|
glfwDestroyWindow(window);
|
|
@endcode
|
|
|
|
Window destruction always succeeds. Before the actual destruction, all
|
|
callbacks are removed so no further events will be delivered for the window.
|
|
All windows remaining when @ref glfwTerminate is called are destroyed as well.
|
|
|
|
When a full screen window is destroyed, the original video mode of its monitor
|
|
is restored, but the gamma ramp is left untouched.
|
|
|
|
|
|
@subsection 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.
|
|
|
|
|
|
@subsubsection 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 context and framebuffer may differ from what these hints requested.
|
|
|
|
The following hints are always hard constraints:
|
|
- `GLFW_STEREO`
|
|
- `GLFW_DOUBLEBUFFER`
|
|
- `GLFW_CLIENT_API`
|
|
- `GLFW_CONTEXT_CREATION_API`
|
|
|
|
The following additional hints are hard constraints when requesting an OpenGL
|
|
context, but are ignored when requesting an OpenGL ES context:
|
|
- `GLFW_OPENGL_FORWARD_COMPAT`
|
|
- `GLFW_OPENGL_PROFILE`
|
|
|
|
|
|
@subsubsection window_hints_wnd Window related hints
|
|
|
|
`GLFW_RESIZABLE` 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.
|
|
|
|
`GLFW_VISIBLE` specifies whether the windowed mode window will be initially
|
|
visible. This hint is ignored for full screen windows.
|
|
|
|
`GLFW_DECORATED` specifies whether the windowed mode window will have window
|
|
decorations such as a border, a close widget, etc. An undecorated window may
|
|
still allow the user to generate close events on some platforms. This hint is
|
|
ignored for full screen windows.
|
|
|
|
`GLFW_FOCUSED` specifies whether the windowed mode window will be given input
|
|
focus when created. This hint is ignored for full screen and initially hidden
|
|
windows.
|
|
|
|
`GLFW_AUTO_ICONIFY` specifies whether the full screen window will
|
|
automatically iconify and restore the previous video mode on input focus loss.
|
|
This hint is ignored for windowed mode windows.
|
|
|
|
`GLFW_FLOATING` specifies whether the windowed mode window will be floating
|
|
above other regular windows, also called topmost or always-on-top. This is
|
|
intended primarily for debugging purposes and cannot be used to implement proper
|
|
full screen windows. This hint is ignored for full screen windows.
|
|
|
|
`GLFW_MAXIMIZED` specifies whether the windowed mode window will be maximized
|
|
when created. This hint is ignored for full screen windows.
|
|
|
|
|
|
@subsubsection window_hints_fb Framebuffer related hints
|
|
|
|
`GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
|
|
`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the
|
|
various components of the default framebuffer. `GLFW_DONT_CARE` means the
|
|
application has no preference.
|
|
|
|
`GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and
|
|
`GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components
|
|
of the accumulation buffer. `GLFW_DONT_CARE` means the application has no
|
|
preference.
|
|
|
|
@par
|
|
Accumulation buffers are a legacy OpenGL feature and should not be used in new
|
|
code.
|
|
|
|
`GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
|
|
`GLFW_DONT_CARE` means the application has no preference.
|
|
|
|
@par
|
|
Auxiliary buffers are a legacy OpenGL feature and should not be used in new
|
|
code.
|
|
|
|
`GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard
|
|
constraint.
|
|
|
|
`GLFW_SAMPLES` specifies the desired number of samples to use for multisampling.
|
|
Zero disables multisampling. `GLFW_DONT_CARE` means the application has no
|
|
preference.
|
|
|
|
`GLFW_SRGB_CAPABLE` specifies whether the framebuffer should be sRGB capable.
|
|
If supported, a created OpenGL context will support the `GL_FRAMEBUFFER_SRGB`
|
|
enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering
|
|
and a created OpenGL ES context will always have sRGB rendering enabled.
|
|
|
|
`GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered.
|
|
You nearly always want to use double buffering. This is a hard constraint.
|
|
|
|
|
|
@subsubsection window_hints_mtr Monitor related hints
|
|
|
|
`GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows.
|
|
If set to `GLFW_DONT_CARE`, the highest available refresh rate will be used.
|
|
This hint is ignored for windowed mode windows.
|
|
|
|
|
|
@subsubsection window_hints_ctx Context related hints
|
|
|
|
`GLFW_CLIENT_API` specifies which client API to create the context for.
|
|
Possible values are `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` and `GLFW_NO_API`.
|
|
This is a hard constraint.
|
|
|
|
`GLFW_CONTEXT_CREATION_API` specifies which context creation API to use to
|
|
create the context. Possible values are `GLFW_NATIVE_CONTEXT_API` and
|
|
`GLFW_EGL_CONTEXT_API`. This is a hard constraint. If no client API is
|
|
requested, this hint is ignored.
|
|
|
|
@par
|
|
__OS X:__ The EGL API is not available on this platform and requests to use it
|
|
will fail.
|
|
|
|
@par
|
|
__Wayland, Mir:__ The EGL API _is_ the native context creation API, so this hint
|
|
will have no effect.
|
|
|
|
@note An OpenGL extension loader library that assumes it knows which context
|
|
creation API is used on a given platform may fail if you change this hint. This
|
|
can be resolved by having it load via @ref glfwGetProcAddress, which always uses
|
|
the selected API.
|
|
|
|
@bug 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.
|
|
|
|
`GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
|
|
API version that the created context must be compatible with. The exact
|
|
behavior of these hints depend on the requested client API.
|
|
|
|
@par
|
|
__OpenGL:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
|
|
not hard constraints, but creation will fail if the OpenGL version of the
|
|
created context is less than the one requested. It is therefore perfectly safe
|
|
to use the default of version 1.0 for legacy code and you will still get
|
|
backwards-compatible contexts of version 3.0 and above when available.
|
|
|
|
@par
|
|
While there is no way to ask the driver for a context of the highest supported
|
|
version, GLFW will attempt to provide this when you ask for a version 1.0
|
|
context, which is the default for these hints.
|
|
|
|
@par
|
|
__OpenGL ES:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
|
|
not hard constraints, but creation will fail if the OpenGL ES version of the
|
|
created context is less than the one requested. Additionally, OpenGL ES 1.x
|
|
cannot be returned if 2.0 or later was requested, and vice versa. This is
|
|
because OpenGL ES 3.x is backward compatible with 2.0, but OpenGL ES 2.0 is not
|
|
backward compatible with 1.x.
|
|
|
|
`GLFW_OPENGL_FORWARD_COMPAT` 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 must only be used if the requested OpenGL
|
|
version is 3.0 or above. If OpenGL ES is requested, this hint is ignored.
|
|
|
|
@par
|
|
Forward-compatibility is described in detail in the
|
|
[OpenGL Reference Manual](https://www.opengl.org/registry/).
|
|
|
|
`GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context,
|
|
which may have additional error and performance issue reporting functionality.
|
|
If OpenGL ES is requested, this hint is ignored.
|
|
|
|
`GLFW_OPENGL_PROFILE` 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 OpenGL ES is requested,
|
|
this hint is ignored.
|
|
|
|
@par
|
|
OpenGL profiles are described in detail in the
|
|
[OpenGL Reference Manual](https://www.opengl.org/registry/).
|
|
|
|
`GLFW_CONTEXT_ROBUSTNESS` 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.
|
|
|
|
`GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be
|
|
used by the context. Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
|
|
`GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the
|
|
behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context
|
|
creation API will be used. If the behavior is `GLFW_RELEASE_BEHAVIOR_FLUSH`,
|
|
the pipeline will be flushed whenever the context is released from being the
|
|
current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
|
|
not be flushed on release.
|
|
|
|
@par
|
|
Context release behaviors are described in detail by the
|
|
[GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
|
|
extension.
|
|
|
|
`GLFW_CONTEXT_NO_ERROR` specifies whether errors should be generated by the
|
|
context. If enabled, situations that would have generated errors instead cause
|
|
undefined behavior.
|
|
|
|
@par
|
|
The no error mode for OpenGL and OpenGL ES is described in detail by the
|
|
[GL_KHR_no_error](https://www.opengl.org/registry/specs/KHR/no_error.txt)
|
|
extension.
|
|
|
|
@note This hint is experimental in its current state. There are currently
|
|
(October 2015) no corresponding WGL or GLX extensions. That makes this hint
|
|
a [hard constraint](@ref window_hints_hard) for those backends, as creation will
|
|
fail if unsupported context flags are requested. Once the extensions are
|
|
available, they will be required and creation of `GL_KHR_no_error` contexts may
|
|
fail on early drivers where this flag is supported without those extensions
|
|
being listed.
|
|
|
|
|
|
@subsubsection window_hints_values Supported and default values
|
|
|
|
Window hint | Default value | Supported values
|
|
------------------------------- | --------------------------- | ----------------
|
|
`GLFW_RESIZABLE` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_VISIBLE` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_DECORATED` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_FOCUSED` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_AUTO_ICONIFY` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_FLOATING` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_MAXIMIZED` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_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` | `GLFW_DONT_CARE` | 0 to `INT_MAX` or `GLFW_DONT_CARE`
|
|
`GLFW_STEREO` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_SRGB_CAPABLE` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_DOUBLEBUFFER` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`
|
|
`GLFW_CONTEXT_CREATION_API` | `GLFW_NATIVE_CONTEXT_API` | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_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_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
|
|
`GLFW_OPENGL_FORWARD_COMPAT` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_OPENGL_DEBUG_CONTEXT` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
|
|
`GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
|
|
|
|
|
|
@section window_events Window event processing
|
|
|
|
See @ref events.
|
|
|
|
|
|
@section window_properties Window properties and events
|
|
|
|
@subsection window_userptr 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.
|
|
|
|
The initial value of the pointer is `NULL`.
|
|
|
|
|
|
@subsection window_close Window closing and 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, set a close
|
|
callback.
|
|
|
|
@code
|
|
glfwSetWindowCloseCallback(window, window_close_callback);
|
|
@endcode
|
|
|
|
The callback function is called directly _after_ the close flag has been set.
|
|
It can be used for example to filter close requests and clear the close flag
|
|
again unless certain conditions are met.
|
|
|
|
@code
|
|
void window_close_callback(GLFWwindow* window)
|
|
{
|
|
if (!time_to_close)
|
|
glfwSetWindowShouldClose(window, GLFW_FALSE);
|
|
}
|
|
@endcode
|
|
|
|
|
|
@subsection window_size Window size
|
|
|
|
The size of a window can be changed with @ref glfwSetWindowSize. For windowed
|
|
mode windows, this sets the size, in
|
|
[screen coordinates](@ref coordinate_systems) of the _client area_ or _content
|
|
area_ of the window. The window system may impose limits on window size.
|
|
|
|
@code
|
|
glfwSetWindowSize(window, 640, 480);
|
|
@endcode
|
|
|
|
For full screen windows, the specified size becomes the new resolution of the
|
|
window's desired video mode. The video mode most closely matching the new
|
|
desired video mode is set immediately. The window is resized to fit the
|
|
resolution of the set video mode.
|
|
|
|
If you wish to be notified when a window is resized, whether by the user or
|
|
the system, set a size callback.
|
|
|
|
@code
|
|
glfwSetWindowSizeCallback(window, window_size_callback);
|
|
@endcode
|
|
|
|
The callback function receives the new size, in screen coordinates, of the
|
|
client area of the window when it is resized.
|
|
|
|
@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
|
|
|
|
@note Do not pass the window size to `glViewport` or other pixel-based OpenGL
|
|
calls. The window size is in screen coordinates, not pixels. Use the
|
|
[framebuffer size](@ref window_fbsize), which is in pixels, for pixel-based
|
|
calls.
|
|
|
|
The above functions work with the size of the client area, but decorated windows
|
|
typically have title bars and window frames around this rectangle. You can
|
|
retrieve the extents of these with @ref glfwGetWindowFrameSize.
|
|
|
|
@code
|
|
int left, top, right, bottom;
|
|
glfwGetWindowFrameSize(window, &left, &top, &right, &bottom);
|
|
@endcode
|
|
|
|
The returned values are the distances, in screen coordinates, from the edges of
|
|
the client area to the corresponding edges of the full window. As they are
|
|
distances and not coordinates, they are always zero or positive.
|
|
|
|
|
|
@subsection window_fbsize 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.
|
|
On some machines screen coordinates and pixels are the same, but on others they
|
|
will not be. 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, set a size callback.
|
|
|
|
@code
|
|
glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
|
|
@endcode
|
|
|
|
The callback function receives the new size of the framebuffer when it is
|
|
resized, which can for example be used to update the OpenGL viewport.
|
|
|
|
@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
|
|
|
|
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.
|
|
|
|
|
|
@subsection window_sizelimits Window size limits
|
|
|
|
The minimum and maximum size of the client area of a windowed mode window can be
|
|
enforced with @ref glfwSetWindowSizeLimits. The user may resize the window to
|
|
any size and aspect ratio within the specified limits, unless the aspect ratio
|
|
is also set.
|
|
|
|
@code
|
|
glfwSetWindowSizeLimits(window, 200, 200, 400, 400);
|
|
@endcode
|
|
|
|
To specify only a minimum size or only a maximum one, set the other pair to
|
|
`GLFW_DONT_CARE`.
|
|
|
|
@code
|
|
glfwSetWindowSizeLimits(window, 640, 480, GLFW_DONT_CARE, GLFW_DONT_CARE);
|
|
@endcode
|
|
|
|
To disable size limits for a window, set them all to `GLFW_DONT_CARE`.
|
|
|
|
The aspect ratio of the client area of a windowed mode window can be enforced
|
|
with @ref glfwSetWindowAspectRatio. The user may resize the window freely
|
|
unless size limits are also set, but the size will be constrained to maintain
|
|
the aspect ratio.
|
|
|
|
@code
|
|
glfwSetWindowAspectRatio(window, 16, 9);
|
|
@endcode
|
|
|
|
The aspect ratio is specified as a numerator and denominator, corresponding to
|
|
the width and height, respectively. If you want a window to maintain its
|
|
current aspect ratio, simply use its current size as the ratio.
|
|
|
|
@code
|
|
int width, height;
|
|
glfwGetWindowSize(window, &width, &height);
|
|
glfwSetWindowAspectRatio(window, width, height);
|
|
@endcode
|
|
|
|
To disable the aspect ratio limit for a window, set both terms to
|
|
`GLFW_DONT_CARE`.
|
|
|
|
You can have both size limits and aspect ratio set for a window, but the results
|
|
are undefined if they conflict.
|
|
|
|
|
|
@subsection 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](@ref coordinate_systems).
|
|
The window system may put limitations on window placement.
|
|
|
|
@code
|
|
glfwSetWindowPos(window, 100, 100);
|
|
@endcode
|
|
|
|
If you wish to be notified when a window is moved, whether by the user, system
|
|
or your own code, set a position callback.
|
|
|
|
@code
|
|
glfwSetWindowPosCallback(window, window_pos_callback);
|
|
@endcode
|
|
|
|
The callback function receives the new position of the upper-left corner of the
|
|
client area when the window is moved.
|
|
|
|
@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
|
|
|
|
|
|
@subsection window_title Window title
|
|
|
|
All GLFW windows have a title, although undecorated or full screen windows may
|
|
not display it or only display it in a task bar or similar interface. You can
|
|
set a UTF-8 encoded window title with @ref glfwSetWindowTitle.
|
|
|
|
@code
|
|
glfwSetWindowTitle(window, "My Window");
|
|
@endcode
|
|
|
|
The specified string is copied before the function returns, so there is no need
|
|
to keep it around.
|
|
|
|
As long as your source file is encoded as UTF-8, you can use any Unicode
|
|
characters directly in the source.
|
|
|
|
@code
|
|
glfwSetWindowTitle(window, "カウボーイビバップ");
|
|
@endcode
|
|
|
|
If you are using C++11 or C11, you can use a UTF-8 string literal.
|
|
|
|
@code
|
|
glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
|
|
@endcode
|
|
|
|
|
|
@subsection window_icon Window icon
|
|
|
|
Decorated windows have icons on some platforms. You can set this icon by
|
|
specifying a list of candidate images with @ref glfwSetWindowIcon.
|
|
|
|
@code
|
|
GLFWimage images[2];
|
|
images[0] = load_icon("my_icon.png");
|
|
images[1] = load_icon("my_icon_small.png");
|
|
|
|
glfwSetWindowIcon(window, 2, images);
|
|
@endcode
|
|
|
|
To revert to the default window icon, pass in an empty image array.
|
|
|
|
@code
|
|
glfwSetWindowIcon(window, 0, NULL);
|
|
@endcode
|
|
|
|
|
|
@subsection window_monitor Window monitor
|
|
|
|
Full screen windows are associated with a specific monitor. You can get the
|
|
handle for this monitor with @ref glfwGetWindowMonitor.
|
|
|
|
@code
|
|
GLFWmonitor* monitor = glfwGetWindowMonitor(window);
|
|
@endcode
|
|
|
|
This monitor handle is one of those returned by @ref glfwGetMonitors.
|
|
|
|
For windowed mode windows, this function returns `NULL`. This is how to tell
|
|
full screen windows from windowed mode windows.
|
|
|
|
You can move windows between monitors or between full screen and windowed mode
|
|
with @ref glfwSetWindowMonitor. When making a window full screen on the same or
|
|
on a different monitor, specify the desired monitor, resolution and refresh
|
|
rate. The position arguments are ignored.
|
|
|
|
@code
|
|
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
|
|
|
|
glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
|
|
@endcode
|
|
|
|
When making the window windowed, specify the desired position and size. The
|
|
refresh rate argument is ignored.
|
|
|
|
@code
|
|
glfwSetWindowMonitor(window, NULL, xpos, ypos, width, height, 0);
|
|
@endcode
|
|
|
|
This restores any previous window settings such as whether it is decorated,
|
|
floating, resizable, has size or aspect ratio limits, etc.. To restore a window
|
|
that was originally windowed to its original size and position, save these
|
|
before making it full screen and then pass them in as above.
|
|
|
|
|
|
@subsection window_iconify Window iconification
|
|
|
|
Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
|
|
|
|
@code
|
|
glfwIconifyWindow(window);
|
|
@endcode
|
|
|
|
When a full screen window is iconified, the original video mode of its monitor
|
|
is restored until the user or application restores the window.
|
|
|
|
Iconified windows can be restored with @ref glfwRestoreWindow.
|
|
|
|
@code
|
|
glfwRestoreWindow(window);
|
|
@endcode
|
|
|
|
When a full screen window is restored, the desired video mode is restored to its
|
|
monitor as well.
|
|
|
|
If you wish to be notified when a window is iconified or restored, whether by
|
|
the user, system or your own code, set a iconify callback.
|
|
|
|
@code
|
|
glfwSetWindowIconifyCallback(window, window_iconify_callback);
|
|
@endcode
|
|
|
|
The callback function receives changes in the iconification state of the window.
|
|
|
|
@code
|
|
void window_iconify_callback(GLFWwindow* window, int iconified)
|
|
{
|
|
if (iconified)
|
|
{
|
|
// The window was iconified
|
|
}
|
|
else
|
|
{
|
|
// The window was restored
|
|
}
|
|
}
|
|
@endcode
|
|
|
|
You can also get the current iconification state with @ref glfwGetWindowAttrib.
|
|
|
|
@code
|
|
int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
|
|
@endcode
|
|
|
|
|
|
@subsection window_hide Window visibility
|
|
|
|
Windowed mode windows can be hidden with @ref glfwHideWindow.
|
|
|
|
@code
|
|
glfwHideWindow(window);
|
|
@endcode
|
|
|
|
This makes the window completely invisible to the user, including removing it
|
|
from the task bar, dock or window list. Full screen windows cannot be hidden
|
|
and calling @ref glfwHideWindow on a full screen window does nothing.
|
|
|
|
Hidden windows can be shown with @ref glfwShowWindow.
|
|
|
|
@code
|
|
glfwShowWindow(window);
|
|
@endcode
|
|
|
|
Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE`
|
|
[window hint](@ref window_hints_wnd). Windows created hidden are completely
|
|
invisible to the user until shown. This can be useful if you need to set up
|
|
your window further before showing it, for example moving it to a specific
|
|
location.
|
|
|
|
You can also get the current visibility state with @ref glfwGetWindowAttrib.
|
|
|
|
@code
|
|
int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
|
|
@endcode
|
|
|
|
|
|
@subsection window_focus Window input focus
|
|
|
|
Windows can be given input focus and brought to the front with @ref
|
|
glfwFocusWindow.
|
|
|
|
@code
|
|
glfwFocusWindow(window);
|
|
@endcode
|
|
|
|
If you wish to be notified when a window gains or loses input focus, whether by
|
|
the user, system or your own code, set a focus callback.
|
|
|
|
@code
|
|
glfwSetWindowFocusCallback(window, window_focus_callback);
|
|
@endcode
|
|
|
|
The callback function receives changes in the input focus state of the window.
|
|
|
|
@code
|
|
void window_focus_callback(GLFWwindow* window, int focused)
|
|
{
|
|
if (focused)
|
|
{
|
|
// The window gained input focus
|
|
}
|
|
else
|
|
{
|
|
// The window lost input focus
|
|
}
|
|
}
|
|
@endcode
|
|
|
|
You can also get the current input focus state with @ref glfwGetWindowAttrib.
|
|
|
|
@code
|
|
int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
|
|
@endcode
|
|
|
|
|
|
@subsection window_refresh Window damage and refresh
|
|
|
|
If you wish to be notified when the contents of a window is damaged and needs
|
|
to be refreshed, set a window refresh callback.
|
|
|
|
@code
|
|
glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
|
|
@endcode
|
|
|
|
The callback function is called when the contents of the window needs to be
|
|
refreshed.
|
|
|
|
@code
|
|
void window_refresh_callback(GLFWwindow* window)
|
|
{
|
|
draw_editor_ui(window);
|
|
glfwSwapBuffers(window);
|
|
}
|
|
@endcode
|
|
|
|
@note On compositing window systems such as Aero, Compiz or Aqua, where the
|
|
window contents are saved off-screen, this callback might only be called when
|
|
the window or framebuffer is resized.
|
|
|
|
|
|
@subsection 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. Some are related to the actual window and others to its
|
|
context.
|
|
|
|
@code
|
|
if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
|
|
{
|
|
// window has input focus
|
|
}
|
|
@endcode
|
|
|
|
|
|
@subsubsection window_attribs_wnd Window related attributes
|
|
|
|
`GLFW_FOCUSED` indicates whether the specified window has input focus. Initial
|
|
input focus is controlled by the [window hint](@ref window_hints_wnd) with the
|
|
same name.
|
|
|
|
`GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by
|
|
the user or with @ref glfwIconifyWindow.
|
|
|
|
`GLFW_MAXIMIZED` indicates whether the specified window is maximized, whether by
|
|
the user or with @ref glfwMaximizeWindow.
|
|
|
|
`GLFW_VISIBLE` indicates whether the specified window is visible. Window
|
|
visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
|
|
and initial visibility is controlled by the [window hint](@ref window_hints_wnd)
|
|
with the same name.
|
|
|
|
`GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
|
|
user_. This is set on creation with the [window hint](@ref window_hints_wnd)
|
|
with the same name.
|
|
|
|
`GLFW_DECORATED` indicates whether the specified window has decorations such as
|
|
a border, a close widget, etc. This is set on creation with the
|
|
[window hint](@ref window_hints_wnd) with the same name.
|
|
|
|
`GLFW_FLOATING` indicates whether the specified window is floating, also called
|
|
topmost or always-on-top. This is controlled by the
|
|
[window hint](@ref window_hints_wnd) with the same name.
|
|
|
|
|
|
@subsubsection window_attribs_ctx Context related attributes
|
|
|
|
`GLFW_CLIENT_API` indicates the client API provided by the window's context;
|
|
either `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`.
|
|
|
|
`GLFW_CONTEXT_CREATION_API` indicates the context creation API used to create
|
|
the window's context; either `GLFW_NATIVE_CONTEXT_API` or
|
|
`GLFW_EGL_CONTEXT_API`.
|
|
|
|
`GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
|
|
`GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.
|
|
|
|
`GLFW_OPENGL_FORWARD_COMPAT` is `GLFW_TRUE` if the window's context is an OpenGL
|
|
forward-compatible one, or `GLFW_FALSE` otherwise.
|
|
|
|
`GLFW_OPENGL_DEBUG_CONTEXT` is `GLFW_TRUE` if the window's context is an OpenGL
|
|
debug context, or `GLFW_FALSE` otherwise.
|
|
|
|
`GLFW_OPENGL_PROFILE` 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 an OpenGL ES context. 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.
|
|
|
|
`GLFW_CONTEXT_ROBUSTNESS` 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.
|
|
|
|
|
|
@subsubsection window_attribs_fb Framebuffer related attributes
|
|
|
|
GLFW does not expose attributes of the default framebuffer (i.e. the framebuffer
|
|
attached to the window) as these can be queried directly with either OpenGL,
|
|
OpenGL ES or Vulkan.
|
|
|
|
If you are using version 3.0 or later of OpenGL or OpenGL ES, the
|
|
`glGetFramebufferAttachmentParameteriv` function can be used to retrieve the
|
|
number of bits for the red, green, blue, alpha, depth and stencil buffer
|
|
channels. Otherwise, the `glGetIntegerv` function can be used.
|
|
|
|
The number of MSAA samples are always retrieved with `glGetIntegerv`. For
|
|
contexts supporting framebuffer objects, the number of samples of the currently
|
|
bound framebuffer is returned.
|
|
|
|
Attribute | glGetIntegerv | glGetFramebufferAttachmentParameteriv
|
|
------------ | ----------------- | -------------------------------------
|
|
Red bits | `GL_RED_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_RED_SIZE`
|
|
Green bits | `GL_GREEN_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_GREEN_SIZE`
|
|
Blue bits | `GL_BLUE_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_BLUE_SIZE`
|
|
Alpha bits | `GL_ALPHA_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE`
|
|
Depth bits | `GL_DEPTH_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE`
|
|
Stencil bits | `GL_STENCIL_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE`
|
|
MSAA samples | `GL_SAMPLES` | _Not provided by this function_
|
|
|
|
When calling `glGetFramebufferAttachmentParameteriv`, the red, green, blue and
|
|
alpha sizes are queried from the `GL_BACK_LEFT`, while the depth and stencil
|
|
sizes are queried from the `GL_DEPTH` and `GL_STENCIL` attachments,
|
|
respectively.
|
|
|
|
|
|
@section buffer_swap Buffer swapping
|
|
|
|
GLFW windows are by default double buffered. That means that you have two
|
|
rendering buffers; a front buffer and a back buffer. The front buffer is
|
|
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 wait should from the time @ref glfwSwapBuffers was
|
|
called 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.
|
|
|
|
*/
|