glfw/docs/window.dox

/*! @page window Window handling
 
@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 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 window handle (i.e. window object pointer) is used as a context
handle as well, for example when calling @ref glfwMakeContextCurrent.


@section window_hints Window hints

There are a number of hints that can be set before the creation of a window.
Some affect the window itself, others its framebuffer or context.  These hints
are set to their default values each time the library is initialized with @ref
glfwInit, can be individually set with @ref glfwWindowHint and reset all at once
to their defaults with @ref glfwDefaultWindowHints.

Note again that they need to be set *before* the creation of the window you wish
to have the specified properties.


@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 parameters of the created window and context, use the
@ref glfwGetWindowParam 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_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.


@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_NO_PROFILE` to not request a specific profile.  If requesting
an OpenGL version below 3.2, `GLFW_OPENGL_NO_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_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_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_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_NO_PROFILE` | `GLFW_OPENGL_NO_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE` |


@section window_closing Window closing

When the user attempts to close the window, for example by clicking the close
widget or using a key chord like Alt+F4, the window's close flag is set and then
its close callback is called.  The window is not actually destroyed and, unless
you are monitoring the close flag, nothing further happens.

If you do not want the close flag to be set, it can be cleared again from the
close callback (or from any other point in your program) with @ref
glfwSetWindowShouldClose.


@section window_dims Window dimensions

Text here.

*/