@ -1,4 +1,4 @@
@page window_guide Window guide# Window guide {#window_guide}
@tableofcontents @tableofcontents
@ -13,7 +13,7 @@ guides for the other areas of GLFW.
- @ref input_guide - @ref input_guide
@section window_object Window objects## Window objects {#window_object}
The @ref GLFWwindow object encapsulates both a window and a context. They are The @ref GLFWwindow object encapsulates both a window and a context. They are
created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or
@ -24,7 +24,7 @@ To see the event stream provided to the various window related callbacks, run
the `events` test program. the `events` test program.
@subsection window_creation Window creation### Window creation {#window_creation}
A window and its OpenGL or OpenGL ES context are created with @ref A window and its OpenGL or OpenGL ES context are created with @ref
glfwCreateWindow, which returns a handle to the created window object. For glfwCreateWindow, which returns a handle to the created window object. For
@ -42,7 +42,7 @@ along with all input events, so event handlers can tell which window received
the event. the event.
@subsubsection window_full_screen Full screen windows#### Full screen windows {#window_full_screen}
To create a full screen window, you need to specify which monitor the window To create a full screen window, you need to specify which monitor the window
should use. In most cases, the user's primary monitor is a good choice. should use. In most cases, the user's primary monitor is a good choice.
@ -91,7 +91,7 @@ If a monitor is disconnected, all windows that are full screen on that monitor
will be switched to windowed mode. See @ref monitor_event for more information. will be switched to windowed mode. See @ref monitor_event for more information.
@subsubsection window_windowed_full_screen "Windowed full screen" windows#### "Windowed full screen" windows {#window_windowed_full_screen}
If the closest match for the desired video mode is the current one, the video 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 mode will not be changed, making window creation faster and application
@ -123,7 +123,7 @@ 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. make windowed full screen, you need to have saved the desktop resolution before.
@subsection window_destruction Window destruction### Window destruction {#window_destruction}
When a window is no longer needed, destroy it with @ref glfwDestroyWindow. When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
@ -139,7 +139,7 @@ When a full screen window is destroyed, the original video mode of its monitor
is restored, but the gamma ramp is left untouched. is restored, but the gamma ramp is left untouched.
@subsection window_hints Window creation hints### Window creation hints {#window_hints}
There are a number of hints that can be set before the creation of a window and 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. Some affect the window itself, others affect the framebuffer or
@ -158,7 +158,7 @@ you wish to have the specified attributes. They function as additional
arguments to @ref glfwCreateWindow. arguments to @ref glfwCreateWindow.
@subsubsection window_hints_hard Hard and soft constraints#### Hard and soft constraints {#window_hints_hard}
Some window hints are hard constraints. These must match the available Some window hints are hard constraints. These must match the available
capabilities _exactly_ for window and context creation to succeed. Hints capabilities _exactly_ for window and context creation to succeed. Hints
@ -177,7 +177,7 @@ context, but are ignored when requesting an OpenGL ES context:
- [GLFW_OPENGL_PROFILE ](@ref GLFW_OPENGL_PROFILE_hint ) - [GLFW_OPENGL_PROFILE ](@ref GLFW_OPENGL_PROFILE_hint )
@subsubsection window_hints_wnd Window related hints#### Window related hints {#window_hints_wnd}
@anchor GLFW_RESIZABLE_hint@anchor GLFW_RESIZABLE_hint
__GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable __GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable
@ -263,7 +263,7 @@ manager will position the window where it thinks the user will prefer it.
Possible values are any valid screen coordinates and `GLFW_ANY_POSITION` . Possible values are any valid screen coordinates and `GLFW_ANY_POSITION` .
@subsubsection window_hints_fb Framebuffer related hints#### Framebuffer related hints {#window_hints_fb}
@anchor GLFW_RED_BITS@anchor GLFW_RED_BITS
@anchor GLFW_GREEN_BITS@anchor GLFW_GREEN_BITS
@ -322,7 +322,7 @@ buffered. You nearly always want to use double buffering. This is a hard
constraint. Possible values are `GLFW_TRUE` and `GLFW_FALSE` . constraint. Possible values are `GLFW_TRUE` and `GLFW_FALSE` .
@subsubsection window_hints_mtr Monitor related hints#### Monitor related hints {#window_hints_mtr}
@anchor GLFW_REFRESH_RATE@anchor GLFW_REFRESH_RATE
__GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen __GLFW_REFRESH_RATE__ specifies the desired refresh rate for full screen
@ -330,7 +330,7 @@ windows. A value of `GLFW_DONT_CARE` means the highest available refresh rate
will be used. This hint is ignored for windowed mode windows. will be used. This hint is ignored for windowed mode windows.
@subsubsection window_hints_ctx Context related hints#### Context related hints {#window_hints_ctx}
@anchor GLFW_CLIENT_API_hint@anchor GLFW_CLIENT_API_hint
__GLFW_CLIENT_API__ specifies which client API to create the context for. __GLFW_CLIENT_API__ specifies which client API to create the context for.
@ -453,7 +453,7 @@ The no error mode for OpenGL and OpenGL ES is described in detail by the
extension. extension.
@subsubsection window_hints_win32 Win32 specific hints#### Win32 specific hints {#window_hints_win32}
@anchor GLFW_WIN32_KEYBOARD_MENU_hint@anchor GLFW_WIN32_KEYBOARD_MENU_hint
__GLFW_WIN32_KEYBOARD_MENU__ specifies whether to allow access to the window __GLFW_WIN32_KEYBOARD_MENU__ specifies whether to allow access to the window
@ -469,7 +469,7 @@ GLFW behaves as if this hint was set to `GLFW_FALSE`. Possible values are
`GLFW_TRUE` and `GLFW_FALSE` . This is ignored on other platforms.`GLFW_TRUE` and `GLFW_FALSE` . This is ignored on other platforms.
@subsubsection window_hints_osx macOS specific hints#### macOS specific hints {#window_hints_osx}
@anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint@anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint
__GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution __GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution
@ -498,7 +498,7 @@ should also declare this in its `Info.plist` by setting the
`NSSupportsAutomaticGraphicsSwitching` key to `true` .`NSSupportsAutomaticGraphicsSwitching` key to `true` .
@subsubsection window_hints_x11 X11 specific window hints#### X11 specific window hints {#window_hints_x11}
@anchor GLFW_X11_CLASS_NAME_hint@anchor GLFW_X11_CLASS_NAME_hint
@anchor GLFW_X11_INSTANCE_NAME_hint@anchor GLFW_X11_INSTANCE_NAME_hint
@ -507,7 +507,7 @@ ASCII encoded class and instance parts of the ICCCM `WM_CLASS` window property.
hints need to be set to something other than an empty string for them to take effect. hints need to be set to something other than an empty string for them to take effect.
These are set with @ref glfwWindowHintString. These are set with @ref glfwWindowHintString.
@subsubsection window_hints_wayland Wayland specific window hints#### Wayland specific window hints {#window_hints_wayland}
@anchor GLFW_WAYLAND_APP_ID_hint@anchor GLFW_WAYLAND_APP_ID_hint
__GLFW_WAYLAND_APP_ID__ specifies the Wayland app_id for a window, used __GLFW_WAYLAND_APP_ID__ specifies the Wayland app_id for a window, used
@ -515,7 +515,7 @@ by window managers to identify types of windows. This is set with
@ref glfwWindowHintString.@ref glfwWindowHintString.
@subsubsection window_hints_values Supported and default values#### Supported and default values {#window_hints_values}
Window hint | Default value | Supported values Window hint | Default value | Supported values
----------------------------- | --------------------------- | ---------------- ----------------------------- | --------------------------- | ----------------
@ -568,14 +568,14 @@ GLFW_X11_INSTANCE_NAME | `""` | An ASCII encoded `
GLFW_WAYLAND_APP_ID | `""` | An ASCII encoded Wayland `app_id` name GLFW_WAYLAND_APP_ID | `""` | An ASCII encoded Wayland `app_id` name
@section window_events Window event processing## Window event processing {#window_events}
See @ref events. See @ref events.
@section window_properties Window properties and events## Window properties and events {#window_properties}
@subsection window_userptr User pointer### User pointer {#window_userptr}
Each window has a user pointer that can be set with @ref Each window has a user pointer that can be set with @ref
glfwSetWindowUserPointer and queried with @ref glfwGetWindowUserPointer. This glfwSetWindowUserPointer and queried with @ref glfwGetWindowUserPointer. This
@ -585,7 +585,7 @@ the life-time of the window.
The initial value of the pointer is `NULL` . The initial value of the pointer is `NULL` .
@subsection window_close Window closing and close flag### Window closing and close flag {#window_close}
When the user attempts to close the window, for example by clicking the close When the user attempts to close the window, for example by clicking the close
widget or using a key chord like Alt+F4, the _close flag_ of the window is set. widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
@ -626,7 +626,7 @@ void window_close_callback(GLFWwindow* window)
@endcode @endcode
@subsection window_size Window size### Window size {#window_size}
The size of a window can be changed with @ref glfwSetWindowSize. For windowed The size of a window can be changed with @ref glfwSetWindowSize. For windowed
mode windows, this sets the size, in mode windows, this sets the size, in
@ -685,7 +685,7 @@ the content area to the corresponding edges of the full window. As they are
distances and not coordinates, they are always zero or positive. distances and not coordinates, they are always zero or positive.
@subsection window_fbsize Framebuffer size### Framebuffer size {#window_fbsize}
While the size of a window is measured in screen coordinates, OpenGL works with 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. pixels. The size you pass into `glViewport` , for example, should be in pixels.
@ -723,7 +723,7 @@ 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. example if the window is dragged between a regular monitor and a high-DPI one.
@subsection window_scale Window content scale### Window content scale {#window_scale}
The content scale for a window can be retrieved with @ref The content scale for a window can be retrieved with @ref
glfwGetWindowContentScale. glfwGetWindowContentScale.
@ -768,7 +768,7 @@ window is created and when its content scale later changes, set the @ref
GLFW_SCALE_TO_MONITOR window hint. GLFW_SCALE_TO_MONITOR window hint.
@subsection window_sizelimits Window size limits### Window size limits {#window_sizelimits}
The minimum and maximum size of the content area of a windowed mode window can The minimum and maximum size of the content area of a windowed mode window can
be enforced with @ref glfwSetWindowSizeLimits. The user may resize the window be enforced with @ref glfwSetWindowSizeLimits. The user may resize the window
@ -814,7 +814,7 @@ You can have both size limits and aspect ratio set for a window, but the results
are undefined if they conflict. are undefined if they conflict.
@subsection window_pos Window position### Window position {#window_pos}
By default, the window manager chooses the position of new windowed mode By default, the window manager chooses the position of new windowed mode
windows, based on its size and which monitor the user appears to be working on. windows, based on its size and which monitor the user appears to be working on.
@ -863,7 +863,7 @@ glfwGetWindowPos(window, &xpos, &ypos);
@endcode @endcode
@subsection window_title Window title### Window title {#window_title}
All GLFW windows have a title, although undecorated or full screen windows may 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 not display it or only display it in a task bar or similar interface. You can
@ -890,7 +890,7 @@ glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
@endcode @endcode
@subsection window_icon Window icon### Window icon {#window_icon}
Decorated windows have icons on some platforms. You can set this icon by Decorated windows have icons on some platforms. You can set this icon by
specifying a list of candidate images with @ref glfwSetWindowIcon. specifying a list of candidate images with @ref glfwSetWindowIcon.
@ -914,7 +914,7 @@ glfwSetWindowIcon(window, 0, NULL);
@endcode @endcode
@subsection window_monitor Window monitor### Window monitor {#window_monitor}
Full screen windows are associated with a specific monitor. You can get the Full screen windows are associated with a specific monitor. You can get the
handle for this monitor with @ref glfwGetWindowMonitor. handle for this monitor with @ref glfwGetWindowMonitor.
@ -952,7 +952,7 @@ that was originally windowed to its original size and position, save these
before making it full screen and then pass them in as above. before making it full screen and then pass them in as above.
@subsection window_iconify Window iconification### Window iconification {#window_iconify}
Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow. Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
@ -1003,7 +1003,7 @@ int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
@endcode @endcode
@subsection window_maximize Window maximization### Window maximization {#window_maximize}
Windows can be maximized (i.e. zoomed) with @ref glfwMaximizeWindow. Windows can be maximized (i.e. zoomed) with @ref glfwMaximizeWindow.
@ -1059,7 +1059,7 @@ glfwWindowHint(GLFW_MAXIMIZED, GLFW_TRUE);
@endcode @endcode
@subsection window_hide Window visibility### Window visibility {#window_hide}
Windowed mode windows can be hidden with @ref glfwHideWindow. Windowed mode windows can be hidden with @ref glfwHideWindow.
@ -1101,7 +1101,7 @@ can be useful if you need to set up your window further before showing it, for
example moving it to a specific location. example moving it to a specific location.
@subsection window_focus Window input focus### Window input focus {#window_focus}
Windows can be given input focus and brought to the front with @ref Windows can be given input focus and brought to the front with @ref
glfwFocusWindow. glfwFocusWindow.
@ -1152,7 +1152,7 @@ glfwWindowHint(GLFW_FOCUSED, GLFW_FALSE);
@endcode @endcode
@subsection window_attention Window attention request### Window attention request {#window_attention}
If you wish to notify the user of an event without interrupting, you can request If you wish to notify the user of an event without interrupting, you can request
attention with @ref glfwRequestWindowAttention. attention with @ref glfwRequestWindowAttention.
@ -1166,7 +1166,7 @@ not supported, the application as a whole. Once the user has given it
attention, the system will automatically end the request. attention, the system will automatically end the request.
@subsection window_refresh Window damage and refresh### Window damage and refresh {#window_refresh}
If you wish to be notified when the contents of a window is damaged and needs If you wish to be notified when the contents of a window is damaged and needs
to be refreshed, set a window refresh callback. to be refreshed, set a window refresh callback.
@ -1191,7 +1191,7 @@ window contents are saved off-screen, this callback might only be called when
the window or framebuffer is resized. the window or framebuffer is resized.
@subsection window_transparency Window transparency### Window transparency {#window_transparency}
GLFW supports two kinds of transparency for windows; framebuffer transparency GLFW supports two kinds of transparency for windows; framebuffer transparency
and whole window transparency. A single window may not use both methods. The and whole window transparency. A single window may not use both methods. The
@ -1255,7 +1255,7 @@ overlay like for example a notification, the @ref GLFW_FLOATING and @ref
GLFW_MOUSE_PASSTHROUGH window hints and attributes may be useful. GLFW_MOUSE_PASSTHROUGH window hints and attributes may be useful.
@subsection window_attribs Window attributes### Window attributes {#window_attribs}
Windows have a number of attributes that can be returned using @ref Windows have a number of attributes that can be returned using @ref
glfwGetWindowAttrib. Some reflect state that may change as a result of user glfwGetWindowAttrib. Some reflect state that may change as a result of user
@ -1283,7 +1283,7 @@ glfwSetWindowAttrib(window, GLFW_RESIZABLE, GLFW_FALSE);
@subsubsection window_attribs_wnd Window related attributes#### Window related attributes {#window_attribs_wnd}
@anchor GLFW_FOCUSED_attrib@anchor GLFW_FOCUSED_attrib
__GLFW_FOCUSED__ indicates whether the specified window has input focus. See __GLFW_FOCUSED__ indicates whether the specified window has input focus. See
@ -1351,7 +1351,7 @@ with @ref glfwSetWindowAttrib. This is only supported for undecorated windows.
Decorated windows with this enabled will behave differently between platforms. Decorated windows with this enabled will behave differently between platforms.
@subsubsection window_attribs_ctx Context related attributes#### Context related attributes {#window_attribs_ctx}
@anchor GLFW_CLIENT_API_attrib@anchor GLFW_CLIENT_API_attrib
__GLFW_CLIENT_API__ indicates the client API provided by the window's context; __GLFW_CLIENT_API__ indicates the client API provided by the window's context;
@ -1415,7 +1415,7 @@ 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. if the window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
@subsubsection window_attribs_fb Framebuffer related attributes#### Framebuffer related attributes {#window_attribs_fb}
GLFW does not expose most attributes of the default framebuffer (i.e. the GLFW does not expose most attributes of the default framebuffer (i.e. the
framebuffer attached to the window) as these can be queried directly with either framebuffer attached to the window) as these can be queried directly with either
@ -1453,7 +1453,7 @@ when rendering with OpenGL or OpenGL ES. This can be set before creation with
the [GLFW_DOUBLEBUFFER ](@ref GLFW_DOUBLEBUFFER_hint ) window hint. the [GLFW_DOUBLEBUFFER ](@ref GLFW_DOUBLEBUFFER_hint ) window hint.
@section buffer_swap Buffer swapping## Buffer swapping {#buffer_swap}
GLFW windows are by default double buffered. That means that you have two 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 rendering buffers; a front buffer and a back buffer. The front buffer is
Camilla Löwy
ago%!(EXTRA string=2 years)