Documentation work

[ci skip]
This commit is contained in:
Camilla Löwy 2017-02-13 15:36:06 +01:00
parent c3fd757b03
commit f69829f7b4
3 changed files with 45 additions and 24 deletions

View File

@ -145,7 +145,9 @@ per-window state arrays that can be polled with @ref glfwGetKey.
@code
int state = glfwGetKey(window, GLFW_KEY_E);
if (state == GLFW_PRESS)
{
activate_airship();
}
@endcode
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
@ -449,7 +451,9 @@ per-window state arrays that can be polled with @ref glfwGetMouseButton.
@code
int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
if (state == GLFW_PRESS)
{
upgrade_cow();
}
@endcode
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
@ -642,7 +646,9 @@ reference documentation for the lifetime of the returned string.
@code
const char* text = glfwGetClipboardString(window);
if (text)
{
insert_text(text);
}
@endcode
If the clipboard is empty or if its contents could not be converted, `NULL` is

View File

@ -83,9 +83,9 @@ immediately.
@section error_handling Error handling
Some GLFW functions have return values that indicate an error, but this is often
not very helpful when trying to figure out _why_ the error occurred. Some
functions also return otherwise valid values on error. Finally, far from all
GLFW functions have return values.
not very helpful when trying to figure out _why_ the error occurred. Other
functions have no return value reserved for errors, so error notification needs
a separate channel. Finally, far from all GLFW functions have return values.
This is where the error callback comes in. This callback is called whenever an
error occurs. It is set with @ref glfwSetErrorCallback, a function that may be
@ -110,6 +110,12 @@ The error code indicates the general category of the error. Some error codes,
such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
@ref GLFW_PLATFORM_ERROR are used for many different errors.
Reported errors are never fatal. As long as GLFW was successfully initialized,
it will remain initialized and in a safe state until terminated regardless of
how many errors occur. If an error occurs during initialization that causes
@ref glfwInit to fail, any part of the library that was initialized will be
safely terminated.
The description string is only valid until the error callback returns, as it may
have been generated specifically for that error. This lets GLFW provide much
more specific error descriptions but means you must make a copy if you want to

View File

@ -179,43 +179,48 @@ context, but are ignored when requesting an OpenGL ES context:
@anchor GLFW_RESIZABLE_hint
__GLFW_RESIZABLE__ specifies whether the windowed mode window will be resizable
_by the user_. The window will still be resizable using the @ref
glfwSetWindowSize function. This hint is ignored for full screen and
undecorated windows.
glfwSetWindowSize function. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
This hint is ignored for full screen and undecorated windows.
@anchor GLFW_VISIBLE_hint
__GLFW_VISIBLE__ specifies whether the windowed mode window will be initially
visible. This hint is ignored for full screen windows.
visible. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This hint is
ignored for full screen windows.
@anchor GLFW_DECORATED_hint
__GLFW_DECORATED__ specifies whether the windowed mode window will have window
decorations such as a border, a close widget, etc. An undecorated window will
not be resizable by the user but will still allow the user to generate close
events on some platforms. This hint is ignored for full screen windows.
events on some platforms. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
This hint is ignored for full screen windows.
@anchor GLFW_FOCUSED_hint
__GLFW_FOCUSED__ specifies whether the windowed mode window will be given input
focus when created. This hint is ignored for full screen and initially hidden
windows.
focus when created. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This
hint is ignored for full screen and initially hidden windows.
@anchor GLFW_AUTO_ICONIFY_hint
__GLFW_AUTO_ICONIFY__ specifies whether the full screen window will
automatically iconify and restore the previous video mode on input focus loss.
This hint is ignored for windowed mode windows.
Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This hint is ignored for
windowed mode windows.
@anchor GLFW_FLOATING_hint
__GLFW_FLOATING__ specifies whether the windowed mode window will be floating
above other regular windows, also called topmost or always-on-top. This is
intended primarily for debugging purposes and cannot be used to implement proper
full screen windows. This hint is ignored for full screen windows.
full screen windows. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This
hint is ignored for full screen windows.
@anchor GLFW_MAXIMIZED_hint
__GLFW_MAXIMIZED__ specifies whether the windowed mode window will be maximized
when created. This hint is ignored for full screen windows.
when created. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This hint is
ignored for full screen windows.
@anchor GLFW_CENTER_CURSOR_hint
__GLFW_CENTER_CURSOR__ specifies whether the cursor should be centered over
newly created full screen windows. This hint is ignored for windowed mode
windows.
newly created full screen windows. Possible values are `GLFW_TRUE` and
`GLFW_FALSE`. This hint is ignored for windowed mode windows.
@subsubsection window_hints_fb Framebuffer related hints
@ -253,8 +258,8 @@ Auxiliary buffers are a legacy OpenGL feature and should not be used in new
code.
@anchor GLFW_STEREO
__GLFW_STEREO__ specifies whether to use OpenGL stereoscopic rendering. This is
a hard constraint.
__GLFW_STEREO__ specifies whether to use OpenGL stereoscopic rendering.
Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This is a hard constraint.
@anchor GLFW_SAMPLES
__GLFW_SAMPLES__ specifies the desired number of samples to use for
@ -266,11 +271,12 @@ __GLFW_SRGB_CAPABLE__ specifies whether the framebuffer should be sRGB capable.
If supported, a created OpenGL context will support the `GL_FRAMEBUFFER_SRGB`
enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering
and a created OpenGL ES context will always have sRGB rendering enabled.
Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
@anchor GLFW_DOUBLEBUFFER
__GLFW_DOUBLEBUFFER__ specifies whether the framebuffer should be double
buffered. You nearly always want to use double buffering. This is a hard
constraint.
constraint. Possible values are `GLFW_TRUE` and `GLFW_FALSE`.
@subsubsection window_hints_mtr Monitor related hints
@ -356,7 +362,8 @@ Forward-compatibility is described in detail in the
@anchor GLFW_OPENGL_DEBUG_CONTEXT_hint
__GLFW_OPENGL_DEBUG_CONTEXT__ specifies whether to create a debug OpenGL
context, which may have additional error and performance issue reporting
functionality. If OpenGL ES is requested, this hint is ignored.
functionality. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. If OpenGL ES
is requested, this hint is ignored.
@anchor GLFW_OPENGL_PROFILE_hint
__GLFW_OPENGL_PROFILE__ specifies which OpenGL profile to create the context
@ -393,8 +400,8 @@ extension.
@anchor GLFW_CONTEXT_NO_ERROR_hint
__GLFW_CONTEXT_NO_ERROR__ specifies whether errors should be generated by the
context. If enabled, situations that would have generated errors instead cause
undefined behavior.
context. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. If enabled,
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
@ -414,19 +421,21 @@ being listed.
@anchor GLFW_COCOA_RETINA_FRAMEBUFFER_hint
__GLFW_COCOA_RETINA_FRAMEBUFFER__ specifies whether to use full resolution
framebuffers on Retina displays. This is ignored on other platforms.
framebuffers on Retina displays. Possible values are `GLFW_TRUE` and
`GLFW_FALSE`. This is ignored on other platforms.
@anchor GLFW_COCOA_FRAME_AUTOSAVE_hint
__GLFW_COCOA_FRAME_AUTOSAVE__ specifies whether to activate frame autosaving
using the window title specified at window creation. This is ignored on other
platforms.
using the window title specified at window creation. Possible values are
`GLFW_TRUE` and `GLFW_FALSE`. This is ignored on other platforms.
@anchor GLFW_COCOA_GRAPHICS_SWITCHING_hint
__GLFW_COCOA_GRAPHICS_SWITCHING__ specifies whether to in Automatic Graphics
Switching, i.e. to allow the system to choose the integrated GPU for the OpenGL
context and move it between GPUs if necessary or whether to force it to always
run on the discrete GPU. This only affects systems with both integrated and
discrete GPUs. This is ignored on other platforms.
discrete GPUs. Possible values are `GLFW_TRUE` and `GLFW_FALSE`. This is
ignored on other platforms.
@par
Simpler programs and tools may want to enable this to save power, while games