804 lines
30 KiB
Plaintext
804 lines
30 KiB
Plaintext
/*!
|
|
|
|
@page window Window guide
|
|
|
|
@tableofcontents
|
|
|
|
This guide introduces the window related functions of GLFW. There are also
|
|
guides for the other areas of GLFW.
|
|
|
|
- @ref intro
|
|
- @ref context
|
|
- @ref monitor
|
|
- @ref input
|
|
|
|
|
|
@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.
|
|
|
|
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 with @ref
|
|
glfwSetWindowSize. The new video mode will be selected and set the same way as
|
|
the video mode chosen by @ref glfwCreateWindow.
|
|
|
|
By default, the original video mode of the monitor will be restored and the
|
|
window iconified if it loses input focus, to allow the user to switch back to
|
|
the desktop. This 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
|
|
|
|
|
|
@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 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 always hard constraints:
|
|
- `GLFW_STEREO`
|
|
- `GLFW_DOUBLEBUFFER`
|
|
- `GLFW_CLIENT_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. 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.
|
|
|
|
`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 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.
|
|
|
|
|
|
@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.
|
|
|
|
`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` and `GLFW_OPENGL_ES_API`. This is a hard
|
|
constraint.
|
|
|
|
`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 may 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 may 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.
|
|
|
|
|
|
@subsubsection window_hints_values Supported and default values
|
|
|
|
Window hint | 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_FOCUSED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
|
`GLFW_AUTO_ICONIFY` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE`
|
|
`GLFW_FLOATING` | `GL_FALSE` | `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` | `GLFW_DONT_CARE` | 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_DOUBLEBUFFER` | `GL_TRUE` | `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_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
|
|
`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_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, GL_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_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
|
|
|
|
|
|
@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 the
|
|
recommended way to tell full screen windows from windowed mode windows.
|
|
|
|
|
|
@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
|
|
|
|
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_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` or `GLFW_OPENGL_ES_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 `GL_TRUE` if the window's context is an OpenGL
|
|
forward-compatible one, or `GL_FALSE` otherwise.
|
|
|
|
`GLFW_OPENGL_DEBUG_CONTEXT` is `GL_TRUE` if the window's context is an OpenGL
|
|
debug context, or `GL_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.
|
|
|
|
|
|
@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. 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.
|
|
|
|
*/
|