Camilla Berglund
ago%!(EXTRA string=12 years)
parent
159f9b9526
commit
fa0cbd9a44
2 changed files with 185 additions and 185 deletions
@ -1,181 +1,180 @@ |
|||||||
/*! @page window Window handling |
/*! @page window Window handling |
||||||
|
|
||||||
@tableofcontents |
@tableofcontents |
||||||
|
|
||||||
The primary purpose of GLFW is to provide a simple interface to window |
The primary purpose of GLFW is to provide a simple interface to window |
||||||
management and OpenGL and OpenGL ES context creation. GLFW supports |
management and OpenGL and OpenGL ES context creation. GLFW supports |
||||||
multiple windows, which can be either a normal desktop window or |
multiple windows, which can be either a normal desktop window or |
||||||
a fullscreen window. |
a fullscreen window. |
||||||
|
|
||||||
@section window_object Window objects |
@section window_object Window objects |
||||||
|
|
||||||
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 |
||||||
@ref glfwTerminate, if any remain). As the window and context are inseparably |
@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 |
linked, the window handle (i.e. window object pointer) is used as a context |
||||||
handle as well, for example when calling @ref glfwMakeContextCurrent. |
handle as well, for example when calling @ref glfwMakeContextCurrent. |
||||||
|
|
||||||
|
|
||||||
@section window_hints Window hints |
@section window_hints Window hints |
||||||
|
|
||||||
There are a number of hints that can be set before the creation of a window. |
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 |
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 |
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 |
glfwInit, can be individually set with @ref glfwWindowHint and reset all at once |
||||||
to their defaults with @ref glfwDefaultWindowHints. |
to their defaults with @ref glfwDefaultWindowHints. |
||||||
|
|
||||||
Note again that they need to be set *before* the creation of the window you wish |
Note again that they need to be set *before* the creation of the window you wish |
||||||
to have the specified properties. |
to have the specified properties. |
||||||
|
|
||||||
|
|
||||||
@subsection window_hints_hard Hard and soft constraints |
@subsection window_hints_hard Hard and soft constraints |
||||||
|
|
||||||
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 |
||||||
that are not hard constraints are matched as closely as possible, but the |
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 |
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 |
find out the actual parameters of the created window and context, use the |
||||||
@ref glfwGetWindowParam function. |
@ref glfwGetWindowParam function. |
||||||
|
|
||||||
The following hints are hard constraints: |
The following hints are hard constraints: |
||||||
- `GLFW_STEREO` |
- `GLFW_STEREO` |
||||||
- `GLFW_CLIENT_API` |
- `GLFW_CLIENT_API` |
||||||
|
|
||||||
The following additional hints are hard constraints if requesting an OpenGL |
The following additional hints are hard constraints if requesting an OpenGL |
||||||
context: |
context: |
||||||
- `GLFW_OPENGL_FORWARD_COMPAT` |
- `GLFW_OPENGL_FORWARD_COMPAT` |
||||||
- `GLFW_OPENGL_PROFILE` |
- `GLFW_OPENGL_PROFILE` |
||||||
|
|
||||||
Hints that do not apply to a given type of window or context are ignored. |
Hints that do not apply to a given type of window or context are ignored. |
||||||
|
|
||||||
|
|
||||||
@subsection window_hints_fb Framebuffer related hints |
@subsection window_hints_fb Framebuffer related hints |
||||||
|
|
||||||
The `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`, |
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 |
`GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` hints specify the desired bit |
||||||
depths of the various components of the default framebuffer. |
depths of the various components of the default framebuffer. |
||||||
|
|
||||||
The `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` |
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 |
and `GLFW_ACCUM_ALPHA_BITS` hints specify the desired bit depths of the |
||||||
various components of the accumulation buffer. |
various components of the accumulation buffer. |
||||||
|
|
||||||
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary |
The `GLFW_AUX_BUFFERS` hint specifies the desired number of auxiliary |
||||||
buffers. |
buffers. |
||||||
|
|
||||||
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. |
The `GLFW_STEREO` hint specifies whether to use stereoscopic rendering. |
||||||
|
|
||||||
The `GLFW_SAMPLES` hint specifies the desired number of samples to use for |
The `GLFW_SAMPLES` hint specifies the desired number of samples to use for |
||||||
multisampling. |
multisampling. Zero disables multisampling. |
||||||
|
|
||||||
The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be |
The `GLFW_SRGB_CAPABLE` hint specifies whether the framebuffer should be |
||||||
sRGB capable. |
sRGB capable. |
||||||
|
|
||||||
|
|
||||||
@subsection window_hints_ctx Context related hints |
@subsection window_hints_ctx Context related hints |
||||||
|
|
||||||
The `GLFW_CLIENT_API` hint specifies which client API to create the context |
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`. |
for. Possible values are `GLFW_OPENGL_API` and `GLFW_OPENGL_ES_API`. |
||||||
|
|
||||||
The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints |
The `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` hints |
||||||
specify the client API version that the created context must be compatible |
specify the client API version that the created context must be compatible |
||||||
with. |
with. |
||||||
|
|
||||||
For OpenGL, these hints are *not* hard constraints, as they don't have to |
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 |
match exactly, but @ref glfwCreateWindow will still fail if the resulting |
||||||
OpenGL version is less than the one requested. It is therefore perfectly |
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 |
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. |
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 |
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 |
version, most drivers provide this when you ask GLFW for a version |
||||||
1.0 context. |
1.0 context. |
||||||
|
|
||||||
For OpenGL ES, these hints are hard constraints, as there is no backward |
For OpenGL ES, these hints are hard constraints. |
||||||
compatibility between OpenGL ES versions. |
|
||||||
|
If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint |
||||||
If an OpenGL context is requested, the `GLFW_OPENGL_FORWARD_COMPAT` hint |
specifies whether the OpenGL context should be forward-compatible, i.e. one |
||||||
specifies whether the OpenGL context should be forward-compatible, i.e. one |
where all functionality deprecated in the requested version of OpenGL is |
||||||
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 |
||||||
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. |
||||||
above. If another client API is requested, this hint is ignored. |
|
||||||
|
If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint |
||||||
If an OpenGL context is requested, the `GLFW_OPENGL_DEBUG_CONTEXT` hint |
specifies whether to create a debug OpenGL context, which may have |
||||||
specifies whether to create a debug OpenGL context, which may have |
additional error and performance issue reporting functionality. If another |
||||||
additional error and performance issue reporting functionality. If another |
client API is requested, this hint is ignored. |
||||||
client API is requested, this hint is ignored. |
|
||||||
|
If an OpenGL context is requested, the `GLFW_OPENGL_PROFILE` hint specifies |
||||||
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 |
||||||
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_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE`, or |
`GLFW_OPENGL_NO_PROFILE` to not request a specific profile. If requesting |
||||||
`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 |
||||||
an OpenGL version below 3.2, `GLFW_OPENGL_NO_PROFILE` must be used. If |
another client API is requested, this hint is ignored. |
||||||
another client API is requested, this hint is ignored. |
|
||||||
|
The `GLFW_CONTEXT_ROBUSTNESS` hint specifies the robustness strategy to be |
||||||
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 |
||||||
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 |
||||||
`GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request |
a robustness strategy. |
||||||
a robustness strategy. |
|
||||||
|
|
||||||
|
@subsection window_hints_wnd Window related hints |
||||||
@subsection window_hints_wnd Window related hints |
|
||||||
|
The `GLFW_RESIZABLE` hint specifies whether the window will be resizable *by the |
||||||
The `GLFW_RESIZABLE` hint specifies whether the window will be resizable by |
user*. The window will still be resizable using the @ref glfwSetWindowSize |
||||||
the user. The window will still be resizable using the @ref |
function. This hint is ignored for fullscreen windows. |
||||||
glfwSetWindowSize function. This hint is ignored for fullscreen windows. |
|
||||||
|
The `GLFW_VISIBLE` hint specifies whether the window will be initially |
||||||
The `GLFW_VISIBLE` hint specifies whether the window will be initially |
visible. This hint is ignored for fullscreen windows. |
||||||
visible. This hint is ignored for fullscreen windows. |
|
||||||
|
The `GLFW_DECORATED` hint specifies whether the window will have window |
||||||
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 |
||||||
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 |
||||||
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. |
||||||
is usually still possible for the user to generate close events. |
|
||||||
|
|
||||||
|
@subsection window_hints_values Supported and default values |
||||||
@subsection window_hints_values Supported and default values |
|
||||||
|
| Name | Default value | Supported values | |
||||||
| Name | Default value | Supported values | |
| ---------------------------- | ------------------------ | ----------------------- | |
||||||
| ---------------------------- | ------------------------ | ----------------------- | |
| `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | |
||||||
| `GLFW_RESIZABLE` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | |
| `GLFW_VISIBLE` | `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_DECORATED` | `GL_TRUE` | `GL_TRUE` or `GL_FALSE` | |
| `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` | |
||||||
| `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` | |
| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` | |
||||||
| `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` | |
| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` | |
||||||
| `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` | |
| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` | |
||||||
| `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` | |
| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` | |
||||||
| `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` | |
| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` | |
||||||
| `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` | |
| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` | |
||||||
| `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` | |
| `GLFW_ACCUM_GREEN_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_BLUE_BITS` | 0 | 0 to `INT_MAX` | |
| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` | |
||||||
| `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` | |
| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` | |
||||||
| `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` | |
| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` | |
||||||
| `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` | |
| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | |
||||||
| `GLFW_STEREO` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | |
| `GLFW_SRGB_CAPABLE` | `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_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_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_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_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_FORWARD_COMPAT` | `GL_FALSE` | `GL_TRUE` or `GL_FALSE` | |
| `GLFW_OPENGL_DEBUG_CONTEXT` | `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` | |
||||||
| `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 |
||||||
@section window_closing Window closing |
|
||||||
|
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 window's close flag is set and then |
||||||
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 |
||||||
its close callback is called. The window is not actually destroyed and, unless |
you are monitoring the close flag, nothing further happens. |
||||||
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 |
||||||
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 |
||||||
close callback (or from any other point in your program) with @ref |
glfwSetWindowShouldClose. |
||||||
glfwSetWindowShouldClose. |
|
||||||
|
|
||||||
|
@section window_dims Window dimensions |
||||||
@section window_dims Window dimensions |
|
||||||
|
Text here. |
||||||
Text here. |
|
||||||
|
*/ |
||||||
*/ |
|
||||||
|
|||||||
Loading…
Reference in New Issue