mirror of
https://github.com/glfw/glfw.git
synced 2024-11-29 05:22:00 +00:00
Clarify documentation for hints
This commit is contained in:
parent
e17ffcd0db
commit
bbbbd3e870
@ -103,7 +103,6 @@ one of `GLFW_ANGLE_PLATFORM_TYPE_NONE`, `GLFW_ANGLE_PLATFORM_TYPE_OPENGL`,
|
|||||||
`GLFW_ANGLE_PLATFORM_TYPE_D3D11`, `GLFW_ANGLE_PLATFORM_TYPE_VULKAN` and
|
`GLFW_ANGLE_PLATFORM_TYPE_D3D11`, `GLFW_ANGLE_PLATFORM_TYPE_VULKAN` and
|
||||||
`GLFW_ANGLE_PLATFORM_TYPE_METAL`.
|
`GLFW_ANGLE_PLATFORM_TYPE_METAL`.
|
||||||
|
|
||||||
@par
|
|
||||||
The ANGLE platform type is specified via the `EGL_ANGLE_platform_angle`
|
The ANGLE platform type is specified via the `EGL_ANGLE_platform_angle`
|
||||||
extension. This extension is not used if this hint is
|
extension. This extension is not used if this hint is
|
||||||
`GLFW_ANGLE_PLATFORM_TYPE_NONE`, which is the default value.
|
`GLFW_ANGLE_PLATFORM_TYPE_NONE`, which is the default value.
|
||||||
|
@ -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
|
||||||
@ -278,7 +279,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.
|
||||||
|
|
||||||
@ -286,7 +286,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.
|
||||||
|
|
||||||
@ -303,14 +302,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
|
||||||
@ -339,28 +336,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
|
||||||
@ -368,27 +362,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 core profile contexts for OpenGL versions 3.2
|
@note @macos The OS only supports core profile contexts for OpenGL versions 3.2
|
||||||
and later. Before creating an OpenGL context of version 3.2 or later you must
|
and later. Before creating an OpenGL context of version 3.2 or later you must
|
||||||
@ -401,7 +392,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/).
|
||||||
|
|
||||||
@ -411,13 +401,11 @@ __GLFW_CONTEXT_DEBUG__ specifies whether the context should be created in debug
|
|||||||
mode, which may provide additional error and diagnostic reporting functionality.
|
mode, which may provide additional error and diagnostic reporting functionality.
|
||||||
Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
|
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.
|
||||||
|
|
||||||
@par
|
@note `GLFW_CONTEXT_DEBUG` is the new name introduced in GLFW 3.4. The older
|
||||||
This is the new name, introduced in GLFW 3.4. The older
|
|
||||||
`GLFW_OPENGL_DEBUG_CONTEXT` name is also available for compatibility.
|
`GLFW_OPENGL_DEBUG_CONTEXT` name is also available for compatibility.
|
||||||
|
|
||||||
@anchor GLFW_OPENGL_PROFILE_hint
|
@anchor GLFW_OPENGL_PROFILE_hint
|
||||||
@ -428,7 +416,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/).
|
||||||
|
|
||||||
@ -448,7 +435,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.
|
||||||
@ -458,7 +444,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.
|
||||||
@ -492,12 +477,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`.
|
||||||
|
Loading…
Reference in New Issue
Block a user