| /*! |
| |
| @page window Window handling guide |
| |
| @tableofcontents |
| |
| The primary purpose of GLFW is to provide a simple interface to window |
| management and OpenGL and OpenGL ES context creation. GLFW supports multiple |
| windows, which can be either a normal desktop window or a fullscreen window. |
| |
| |
| @section window_object Window handles |
| |
| The @ref GLFWwindow object encapsulates both a window and a context. They are |
| created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or |
| @ref glfwTerminate, if any remain). As the window and context are inseparably |
| linked, the object pointer is used as both a context and window handle. |
| |
| |
| @section window_hints Window creation hints |
| |
| There are a number of hints that can be set before the creation of a window and |
| context. Some affect the window itself, others affect the framebuffer or |
| context. These hints are set to their default values each time the library is |
| initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint |
| and reset all at once to their defaults with @ref glfwDefaultWindowHints. |
| |
| Note that hints need to be set *before* the creation of the window and context |
| you wish to have the specified attributes. |
| |
| |
| @subsection window_hints_hard Hard and soft constraints |
| |
| Some window hints are hard constraints. These must match the available |
| capabilities *exactly* for window and context creation to succeed. Hints |
| that are not hard constraints are matched as closely as possible, but the |
| resulting window and context may differ from what these hints requested. To |
| find out the actual attributes of the created window and context, use the |
| @ref glfwGetWindowAttrib function. |
| |
| The following hints are hard constraints: |
| - `GLFW_STEREO` |
| - `GLFW_CLIENT_API` |
| |
| The following additional hints are hard constraints if requesting an OpenGL |
| context: |
| - `GLFW_OPENGL_FORWARD_COMPAT` |
| - `GLFW_OPENGL_PROFILE` |
| |
| Hints that do not apply to a given type of window or context are ignored. |
| |
| |
| @subsection window_hints_wnd Window related hints |
| |
| The `GLFW_RESIZABLE` hint specifies whether the window will be resizable *by the |
| user*. The window will still be resizable using the @ref glfwSetWindowSize |
| function. This hint is ignored for fullscreen windows. |
| |
| The `GLFW_VISIBLE` hint specifies whether the window will be initially |
| visible. This hint is ignored for fullscreen windows. |
| |
| The `GLFW_DECORATED` hint specifies whether the window will have window |
| decorations such as a border, a close widget, etc. This hint is ignored for |
| fullscreen windows. Note that even though a window may lack a close widget, it |
| is usually still possible for the user to generate close events. |
| |
| |
| @subsection window_hints_fb Framebuffer related hints |
| |
| The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`, |
| `GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit |
| depths of the various components of the default framebuffer. |
| |
| The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` |
| and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the |
| various components of the accumulation buffer. |
| |
| The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary |
| buffers. |
| |
| The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. |
| |
| The `GLFW_SAMPLES` hint specifies the desired number of samples to use for |
| multisampling. Zero disables multisampling. |
| |
| The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be |
| sRGB capable. |
| |
| The `GLFW_REFRESH_RATE` hint specifies the desired refresh rate for full screen |
| windows. If set to zero, the highest available refresh rate will be used. This |
| hint is ignored for windowed mode windows. |
| |
| |
| @subsection window_hints_ctx Context related hints |
| |
| The `GLFW_CLIENT_API` hint specifies which client API to create the context |
| for. Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`. |
| |
| The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints |
| specify the client API version that the created context must be compatible |
| with. |
| |
| For OpenGL, these hints are *not* hard constraints, as they don't have to |
| match exactly, but @ref glfwCreateWindow will still fail if the resulting |
| OpenGL version is less than the one requested. It is therefore perfectly |
| safe to use the default of version 1.0 for legacy code and you may still |
| get backwards-compatible contexts of version 3.0 and above when available. |
| |
| While there is no way to ask the driver for a context of the highest supported |
| version, most drivers provide this when you ask GLFW for a version |
| 1.0 context. |
| |
| For OpenGL ES, these hints are hard constraints. |
| |
| If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint |
| specifies whether the OpenGL context should be forward-compatible, i.e. one |
| where all functionality deprecated in the requested version of OpenGL is |
| removed. This may only be used if the requested OpenGL version is 3.0 or |
| above. If another client API is requested, this hint is ignored. |
| |
| If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint |
| specifies whether to create a debug OpenGL context, which may have |
| additional error and performance issue reporting functionality. If another |
| client API is requested, this hint is ignored. |
| |
| If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies |
| which OpenGL profile to create the context for. Possible values are one of |
| `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or |
| `GLFW_OPENGL_ANY_PROFILE` to not request a specific profile. If requesting |
| an OpenGL version below 3.2, `GLFW_OPENGL_ANY_PROFILE` must be used. If |
| another client API is requested, this hint is ignored. |
| |
| The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be |
| used by the context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or |
| `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request |
| a robustness strategy. |
| |
| |
| @subsection window_hints_values Supported and default values |
| |
| | Name | Default value | Supported values | |
| | ---------------------------- | ------------------------- | ----------------------- | |
| | `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | |
| | `GLFW_VISIBLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | |
| | `GLFW_DECORATED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | |
| | `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` | |
| | `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` | |
| | `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` | |
| | `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` | |
| | `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` | |
| | `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` | |
| | `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` | |
| | `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` | |
| | `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` | |
| | `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` | |
| | `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` | |
| | `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` | |
| | `GLFW_REFRESH_RATE` | 0 | 0 to `INT_MAX` | |
| | `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | |
| | `GLFW_SRGB_CAPABLE` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | |
| | `GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API` | |
| | `GLFW_CONTEXT_VERSION_MAJOR` | 1 | Any valid major version number of the chosen client API | |
| | `GLFW_CONTEXT_VERSION_MINOR` | 0 | Any valid minor version number of the chosen client API | |
| | `GLFW_CONTEXT_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET` | |
| | `GLFW_OPENGL_FORWARD_COMPAT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | |
| | `GLFW_OPENGL_DEBUG_CONTEXT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | |
| | `GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` | |
| |
| |
| @section window_close Window close flag |
| |
| When the user attempts to close the window, for example by clicking the close |
| widget or using a key chord like Alt+F4, the *close flag* of the window is set. |
| The window is however not actually destroyed and, unless you watch for this |
| state change, nothing further happens. |
| |
| The current state of the close flag is returned by @ref glfwWindowShouldClose |
| and can be set or cleared directly with @ref glfwSetWindowShouldClose. A common |
| pattern is to use the close flag as a main loop condition. |
| |
| @code |
| while (!glfwWindowShouldClose(window)) |
| { |
| render(window); |
| |
| glfwSwapBuffers(window); |
| glfwPollEvents(); |
| } |
| @endcode |
| |
| If you wish to be notified when the user attempts to close a window, you can set |
| the close callback with @ref glfwSetWindowCloseCallback. This callback is |
| called directly *after* the close flag has been set. |
| |
| @code |
| glfwSetWindowCloseCallback(window, window_close_callback); |
| @endcode |
| |
| The callback function can be used for example to filter close requests and clear |
| the close flag again unless certain conditions are met. |
| |
| @code |
| void window_close_callback(GLFWwindow* window) |
| { |
| if (!time_to_close) |
| glfwSetWindowShouldClose(window, GL_FALSE); |
| } |
| @endcode |
| |
| |
| @section window_size Window size |
| |
| The size of a window can be changed with @ref glfwSetWindowSize. For windowed |
| mode windows, this resizes the specified window so that its *client area* has |
| the specified size. Note that the window system may put limitations on size. |
| For full screen windows, it selects and sets the video mode most closely |
| matching the specified size. |
| |
| @code |
| void glfwSetWindowSize(window, 640, 480); |
| @endcode |
| |
| If you wish to be notified when a window is resized, whether by the user or |
| the system, you can set the size callback with @ref glfwSetWindowSizeCallback. |
| |
| @code |
| glfwSetWindowSizeCallback(window, window_size_callback); |
| @endcode |
| |
| The callback function receives the new size of the client area of the window, |
| which can for example be used to update the viewport. |
| |
| @code |
| void window_size_callback(GLFWwindow* window, int width, int height) |
| { |
| glViewport(0, 0, width, height); |
| } |
| @endcode |
| |
| There is also @ref glfwGetWindowSize for directly retrieving the current size of |
| a window. |
| |
| @code |
| int width, height; |
| glfwGetWindowSize(window, &width, &height); |
| glViewport(0, 0, width, height); |
| @endcode |
| |
| |
| @section window_pos Window position |
| |
| The position of a windowed-mode window can be changed with @ref |
| glfwSetWindowPos. This moves the window so that the upper-left corner of its |
| client area has the specified screen coordinates. Note that the window system |
| may put limitations on placement. |
| |
| @code |
| glfwSetWindowPos(window, 100, 100); |
| @endcode |
| |
| If you wish to be notified when a window is moved, whether by the user or |
| the system, you can set the position callback with @ref glfwSetWindowPosCallback. |
| |
| @code |
| glfwSetWindowPosCallback(window, window_pos_callback); |
| @endcode |
| |
| The callback function receives the new position of the upper-left corner of its |
| client area. |
| |
| @code |
| void window_size_callback(GLFWwindow* window, int xpos, int ypos) |
| { |
| } |
| @endcode |
| |
| There is also @ref glfwGetWindowPos for directly retrieving the current position |
| of the client area of the window. |
| |
| @code |
| int xpos, ypos; |
| glfwGetWindowPos(window, &xpos, &ypos); |
| @endcode |
| |
| |
| @section window_title Window title |
| |
| All GLFW windows have a title, although undecorated or full screen windows may |
| not display it or only display it in a task bar or similar interface. To change |
| the title of a window, use @ref glfwSetWindowTitle. |
| |
| @code |
| glfwSetWindowTitle(window, "My Window"); |
| @endcode |
| |
| The window title is a regular C string using the UTF-8 encoding. This means |
| for example that, as long as your source file is encoded as UTF-8, you can use |
| any Unicode characters. |
| |
| @code |
| glfwSetWindowTitle(window, "さよなら絶望先生"); |
| @endcode |
| |
| |
| @section window_attribs Window attributes |
| |
| Windows have a number of attributes that can be returned using @ref |
| glfwGetWindowAttrib. Some reflect state that may change during the lifetime of |
| the window, while others reflect the corresponding hints and are fixed at the |
| time of creation. |
| |
| @code |
| if (glfwGetWindowAttrib(window, GLFW_FOCUSED)) |
| { |
| // window has input focus |
| } |
| @endcode |
| |
| |
| @subsection window_attribs_window Window attributes |
| |
| The `GLFW_FOCUSED` attribute indicates whether the specified window currently |
| has input focus. |
| |
| The `GLFW_ICONIFIED` attribute indicates whether the specified window is |
| currently iconified, whether by the user or with @ref glfwIconifyWindow. |
| |
| The `GLFW_VISIBLE` attribute indicates whether the specified window is currently |
| visible. Window visibility can be controlled with @ref glfwShowWindow and @ref |
| glfwHideWindow and initial visibility is controlled by the |
| [window hint](@ref window_hints) with the same name. |
| |
| The `GLFW_RESIZABLE` attribute indicates whether the specified window is |
| resizable *by the user*. This is controlled by the |
| [window hint](@ref window_hints) with the same name. |
| |
| The `GLFW_DECORATED` attribute indicates whether the specified window has |
| decorations such as a border, a close widget, etc. This is controlled by the |
| [window hint](@ref window_hints) with the same name. |
| |
| |
| @subsection window_attribs_context Context attributes |
| |
| The `GLFW_CLIENT_API` attribute indicates the client API provided by the |
| window's context; either `GLFW_OPENGL_API` or `GLFW_OPENGL_ES_API`. |
| |
| The `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and |
| `GLFW_CONTEXT_REVISION` attributes indicate the client API version of the |
| window's context. |
| |
| The `GLFW_OPENGL_FORWARD_COMPAT` attribute is `GL_TRUE` if the window's |
| context is an OpenGL forward-compatible one, or `GL_FALSE` otherwise. |
| |
| The `GLFW_OPENGL_DEBUG_CONTEXT` attribute is `GL_TRUE` if the window's |
| context is an OpenGL debug context, or `GL_FALSE` otherwise. |
| |
| The `GLFW_OPENGL_PROFILE` attribute indicates the OpenGL profile used by the |
| context. This is `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` |
| if the context uses a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the |
| OpenGL profile is unknown or the context is for another client API. |
| |
| The `GLFW_CONTEXT_ROBUSTNESS` attribute indicates the robustness strategy |
| used by the context. This is `GLFW_LOSE_CONTEXT_ON_RESET` or |
| `GLFW_NO_RESET_NOTIFICATION` if the window's context supports robustness, or |
| `GLFW_NO_ROBUSTNESS` otherwise. |
| |
| |
| @section window_swap Swapping buffers |
| |
| GLFW windows are always double buffered. That means that you have two |
| rendering buffers; a front buffer and a back buffer. The front buffer is |
| the one being displayed and the back buffer the one you render to. |
| |
| When the entire frame has been rendered, it is time to swap the back and the |
| front buffers in order to display what has been rendered and begin rendering |
| a new frame. This is done with @ref glfwSwapBuffers. |
| |
| @code |
| glfwSwapBuffers(window); |
| @endcode |
| |
| Sometimes it can be useful to select when the buffer swap will occur. With the |
| function @ref glfwSwapInterval it is possible to select the minimum number of |
| monitor refreshes the driver should wait before swapping the buffers: |
| |
| @code |
| glfwSwapInterval(1); |
| @endcode |
| |
| If the interval is zero, the swap will take place immediately when @ref |
| glfwSwapBuffers is called without waiting for a refresh. Otherwise at least |
| interval retraces will pass between each buffer swap. Using a swap interval of |
| zero can be useful for benchmarking purposes, when it is not desirable to |
| measure the time it takes to wait for the vertical retrace. However, a swap |
| interval of one lets you avoid tearing. |
| |
| Note that not all OpenGL implementations properly implement this function, in |
| which case @ref glfwSwapInterval will have no effect. Some drivers also have |
| user settings that override requests by GLFW. |
| |
| */ |