diff --git a/docs/window.dox b/docs/window.dox index b9928561..079c3787 100644 --- a/docs/window.dox +++ b/docs/window.dox @@ -1,181 +1,180 @@ -/*! @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. - -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, as there is no backward -compatibility between OpenGL ES versions. - -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. - -*/ +/*! @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. + +*/ diff --git a/include/GL/glfw3.h b/include/GL/glfw3.h index 327e1cf4..bf04951f 100644 --- a/include/GL/glfw3.h +++ b/include/GL/glfw3.h @@ -1121,16 +1121,17 @@ GLFWAPI void glfwWindowHint(int target, int hint); * * This function creates a window and its associated context. Most of the * options controlling how the window and its context should be created are - * specified via the @ref glfwWindowHint function. + * specified through @ref glfwWindowHint. * * Successful creation does not change which context is current. Before you * can use the newly created context, you need to make it current using @ref * glfwMakeContextCurrent. * * Note that the created window and context may differ from what you requested, - * as not all parameters and hints are hard constraints. This includes the - * size of the window, especially for full screen windows. To retrieve the - * actual properties of the window and context, use queries like @ref + * as not all parameters and hints are + * [hard constraints](@ref window_hints_hard). This includes the size of the + * window, especially for full screen windows. To retrieve the actual + * properties of the window and context, use queries like @ref * glfwGetWindowParam and @ref glfwGetWindowSize. * * @param[in] width The desired width, in screen coordinates, of the window.