mirror/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2024-11-22 13:04:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clarify documentation for hints

Browse Source 
(cherry picked from commit bbbbd3e870)
This commit is contained in:
Camilla Löwy 2021-05-12 18:53:06 +02:00
parent 2a5038e4e9
commit a149810df9
2 changed files with 37 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/intro.dox
View File

@ -86,7 +86,7 @@ Setting these hints requires no platform specific headers or functions.
@anchor GLFW_JOYSTICK_HAT_BUTTONS @anchor GLFW_JOYSTICK_HAT_BUTTONS
__GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as __GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as
buttons, for compatibility with earlier versions of GLFW that did not have @ref buttons, for compatibility with earlier versions of GLFW that did not have @ref
glfwGetJoystickHats. Set this with @ref glfwInitHint. glfwGetJoystickHats. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
@subsubsection init_hints_osx macOS specific init hints @subsubsection init_hints_osx macOS specific init hints

88
docs/window.dox
View File

@ -236,7 +236,8 @@ does not affect window decorations. Possible values are `GLFW_TRUE` and
@anchor GLFW_FOCUS_ON_SHOW_hint @anchor GLFW_FOCUS_ON_SHOW_hint
__GLFW_FOCUS_ON_SHOW__ specifies whether the window will be given input __GLFW_FOCUS_ON_SHOW__ specifies whether the window will be given input
focus when @ref glfwShowWindow is called. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. focus when @ref glfwShowWindow is called. Possible values are `GLFW_TRUE` and
`GLFW_FALSE`.
@anchor GLFW_SCALE_TO_MONITOR @anchor GLFW_SCALE_TO_MONITOR
__GLFW_SCALE_TO_MONITOR__ specified whether the window content area should be __GLFW_SCALE_TO_MONITOR__ specified whether the window content area should be
@ -271,7 +272,6 @@ __GLFW_ACCUM_ALPHA_BITS__ specify the desired bit depths of the various
components of the accumulation buffer. A value of `GLFW_DONT_CARE` means the components of the accumulation buffer. A value of `GLFW_DONT_CARE` means the
application has no preference. application has no preference.
@par
Accumulation buffers are a legacy OpenGL feature and should not be used in new Accumulation buffers are a legacy OpenGL feature and should not be used in new
code. code.
@ -279,7 +279,6 @@ code.
__GLFW_AUX_BUFFERS__ specifies the desired number of auxiliary buffers. A value __GLFW_AUX_BUFFERS__ specifies the desired number of auxiliary buffers. A value
of `GLFW_DONT_CARE` means the application has no preference. of `GLFW_DONT_CARE` means the application has no preference.
@par
Auxiliary buffers are a legacy OpenGL feature and should not be used in new Auxiliary buffers are a legacy OpenGL feature and should not be used in new
code. code.
@ -296,14 +295,12 @@ the application has no preference.
__GLFW_SRGB_CAPABLE__ specifies whether the framebuffer should be sRGB capable. __GLFW_SRGB_CAPABLE__ specifies whether the framebuffer should be sRGB capable.
Possible values are `GLFW_TRUE` and `GLFW_FALSE`. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
@par @note __OpenGL:__ If enabled and supported by the system, the
__OpenGL:__ If enabled and supported by the system, the `GL_FRAMEBUFFER_SRGB` `GL_FRAMEBUFFER_SRGB` enable will control sRGB rendering. By default, sRGB
enable will control sRGB rendering. By default, sRGB rendering will be rendering will be disabled.
disabled.
@par @note __OpenGL ES:__ If enabled and supported by the system, the context will
__OpenGL ES:__ If enabled and supported by the system, the context will always always have sRGB rendering enabled.
have sRGB rendering enabled.
@anchor GLFW_DOUBLEBUFFER @anchor GLFW_DOUBLEBUFFER
__GLFW_DOUBLEBUFFER__ specifies whether the framebuffer should be double __GLFW_DOUBLEBUFFER__ specifies whether the framebuffer should be double
@ -332,28 +329,25 @@ create the context. Possible values are `GLFW_NATIVE_CONTEXT_API`,
`GLFW_EGL_CONTEXT_API` and `GLFW_OSMESA_CONTEXT_API`. This is a hard `GLFW_EGL_CONTEXT_API` and `GLFW_OSMESA_CONTEXT_API`. This is a hard
constraint. If no client API is requested, this hint is ignored. constraint. If no client API is requested, this hint is ignored.
@par An [extension loader library](@ref context_glext_auto) that assumes it knows
@macos The EGL API is not available on this platform and requests to use it which API was used to create the current context may fail if you change this
will fail. hint. This can be resolved by having it load functions via @ref
glfwGetProcAddress.
@par @note @macos The EGL API is not available on this platform and requests to use
__Wayland:__ The EGL API _is_ the native context creation API, so this hint it will fail.
@note @wayland The EGL API _is_ the native context creation API, so this hint
will have no effect. will have no effect.
@par @note @x11 On some Linux systems, creating contexts via both the native and EGL
__OSMesa:__ As its name implies, an OpenGL context created with OSMesa does not APIs in a single process will cause the application to segfault. Stick to one
update the window contents when its buffers are swapped. Use OpenGL functions API or the other on Linux for now.
or the OSMesa native access functions @ref glfwGetOSMesaColorBuffer and @ref
glfwGetOSMesaDepthBuffer to retrieve the framebuffer contents.
@note An OpenGL extension loader library that assumes it knows which context @note __OSMesa:__ As its name implies, an OpenGL context created with OSMesa
creation API is used on a given platform may fail if you change this hint. This does not update the window contents when its buffers are swapped. Use OpenGL
can be resolved by having it load via @ref glfwGetProcAddress, which always uses functions or the OSMesa native access functions @ref glfwGetOSMesaColorBuffer
the selected API. and @ref glfwGetOSMesaDepthBuffer to retrieve the framebuffer contents.
@bug On some Linux systems, creating contexts via both the native and EGL APIs
in a single process will cause the application to segfault. Stick to one API or
the other on Linux for now.
@anchor GLFW_CONTEXT_VERSION_MAJOR_hint @anchor GLFW_CONTEXT_VERSION_MAJOR_hint
@anchor GLFW_CONTEXT_VERSION_MINOR_hint @anchor GLFW_CONTEXT_VERSION_MINOR_hint
@ -361,27 +355,24 @@ __GLFW_CONTEXT_VERSION_MAJOR__ and __GLFW_CONTEXT_VERSION_MINOR__ specify the
client API version that the created context must be compatible with. The exact client API version that the created context must be compatible with. The exact
behavior of these hints depend on the requested client API. behavior of these hints depend on the requested client API.
@note Do not confuse these hints with `GLFW_VERSION_MAJOR` and
`GLFW_VERSION_MINOR`, which provide the API version of the GLFW header.
@par
__OpenGL:__ These hints are not hard constraints, but creation will fail if the
OpenGL version of the created context is less than the one requested. It is
therefore perfectly safe to use the default of version 1.0 for legacy code and
you will still get backwards-compatible contexts of version 3.0 and above when
available.
@par
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, GLFW will attempt to provide this when you ask for a version 1.0 version, GLFW will attempt to provide this when you ask for a version 1.0
context, which is the default for these hints. context, which is the default for these hints.
@par Do not confuse these hints with @ref GLFW_VERSION_MAJOR and @ref
__OpenGL ES:__ These hints are not hard constraints, but creation will fail if GLFW_VERSION_MINOR, which provide the API version of the GLFW header.
the OpenGL ES version of the created context is less than the one requested.
Additionally, OpenGL ES 1.x cannot be returned if 2.0 or later was requested, @note __OpenGL:__ These hints are not hard constraints, but creation will fail
and vice versa. This is because OpenGL ES 3.x is backward compatible with 2.0, if the OpenGL version of the created context is less than the one requested. It
but OpenGL ES 2.0 is not backward compatible with 1.x. is therefore perfectly safe to use the default of version 1.0 for legacy code
and you will still get backwards-compatible contexts of version 3.0 and above
when available.
@note __OpenGL ES:__ These hints are not hard constraints, but creation will
fail if the OpenGL ES version of the created context is less than the one
requested. Additionally, OpenGL ES 1.x cannot be returned if 2.0 or later was
requested, and vice versa. This is because OpenGL ES 3.x is backward compatible
with 2.0, but OpenGL ES 2.0 is not backward compatible with 1.x.
@note @macos The OS only supports forward-compatible core profile contexts for @note @macos The OS only supports forward-compatible core profile contexts for
OpenGL versions 3.2 and later. Before creating an OpenGL context of version OpenGL versions 3.2 and later. Before creating an OpenGL context of version
@ -396,7 +387,6 @@ forward-compatible, i.e. one where all functionality deprecated in the requested
version of OpenGL is removed. This must only be used if the requested OpenGL version of OpenGL is removed. This must only be used if the requested OpenGL
version is 3.0 or above. If OpenGL ES is requested, this hint is ignored. version is 3.0 or above. If OpenGL ES is requested, this hint is ignored.
@par
Forward-compatibility is described in detail in the Forward-compatibility is described in detail in the
[OpenGL Reference Manual](https://www.opengl.org/registry/). [OpenGL Reference Manual](https://www.opengl.org/registry/).
@ -405,7 +395,6 @@ __GLFW_OPENGL_DEBUG_CONTEXT__ specifies whether the context should be created
in debug mode, which may provide additional error and diagnostic reporting in debug mode, which may provide additional error and diagnostic reporting
functionality. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. functionality. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
@par
Debug contexts for OpenGL and OpenGL ES are described in detail by the Debug contexts for OpenGL and OpenGL ES are described in detail by the
[GL_KHR_debug](https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt) [GL_KHR_debug](https://www.khronos.org/registry/OpenGL/extensions/KHR/KHR_debug.txt)
extension. extension.
@ -418,7 +407,6 @@ a specific profile. If requesting an OpenGL version below 3.2,
`GLFW_OPENGL_ANY_PROFILE` must be used. If OpenGL ES is requested, this hint `GLFW_OPENGL_ANY_PROFILE` must be used. If OpenGL ES is requested, this hint
is ignored. is ignored.
@par
OpenGL profiles are described in detail in the OpenGL profiles are described in detail in the
[OpenGL Reference Manual](https://www.opengl.org/registry/). [OpenGL Reference Manual](https://www.opengl.org/registry/).
@ -438,7 +426,6 @@ the pipeline will be flushed whenever the context is released from being the
current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
not be flushed on release. not be flushed on release.
@par
Context release behaviors are described in detail by the Context release behaviors are described in detail by the
[GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt) [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
extension. extension.
@ -448,7 +435,6 @@ __GLFW_CONTEXT_NO_ERROR__ specifies whether errors should be generated by the
context. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. If enabled, context. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. If enabled,
situations that would have generated errors instead cause undefined behavior. situations that would have generated errors instead cause undefined behavior.
@par
The no error mode for OpenGL and OpenGL ES is described in detail by the The no error mode for OpenGL and OpenGL ES is described in detail by the
[GL_KHR_no_error](https://www.opengl.org/registry/specs/KHR/no_error.txt) [GL_KHR_no_error](https://www.opengl.org/registry/specs/KHR/no_error.txt)
extension. extension.
@ -474,12 +460,10 @@ run on the discrete GPU. This only affects systems with both integrated and
discrete GPUs. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This is discrete GPUs. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This is
ignored on other platforms. ignored on other platforms.
@par
Simpler programs and tools may want to enable this to save power, while games Simpler programs and tools may want to enable this to save power, while games
and other applications performing advanced rendering will want to leave it and other applications performing advanced rendering will want to leave it
disabled. disabled.
@par
A bundled application that wishes to participate in Automatic Graphics Switching A bundled application that wishes to participate in Automatic Graphics Switching
should also declare this in its `Info.plist` by setting the should also declare this in its `Info.plist` by setting the
`NSSupportsAutomaticGraphicsSwitching` key to `true`. `NSSupportsAutomaticGraphicsSwitching` key to `true`.