Documentation work.

This commit is contained in:
Camilla Berglund 2015-01-11 18:25:54 +01:00
parent 500f5ebf04
commit 4e375d0e74
6 changed files with 47 additions and 40 deletions

View File

@ -91,7 +91,7 @@ formats. If GLX 1.3 is not supported, @ref glfwInit will fail.
GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
`GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
(or "vsync"), in that order of preference. Where none of these extension are
(or _vsync_), in that order of preference. Where none of these extension are
available, calling @ref glfwSwapInterval will have no effect.
GLFW uses the `GLX_ARB_multisample` extension to create contexts with
@ -128,7 +128,7 @@ neither is available, no other extensions are used and many GLFW features
related to context creation will have no effect or cause errors when used.
GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
synchronization (or 'vsync'). Where this extension is unavailable, calling @ref
synchronization (or _vsync_). Where this extension is unavailable, calling @ref
glfwSwapInterval will have no effect.
GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to

View File

@ -4,12 +4,8 @@
@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, with each window having its own context.
This guide introduces the functions related to managing OpenGL and OpenGL ES
contexts. There are also guides for the other areas of the GLFW API.
This guide introduces the OpenGL and OpenGL ES context related functions of
GLFW. There are also guides for the other areas of the GLFW API.
- @ref intro
- @ref window
@ -27,6 +23,10 @@ information.
As the window and context are inseparably linked, the window object also serves
as the context handle.
To test the creation of various kinds of contexts and see their properties, run
the `glfwinfo` test program.
@subsection context_hints Context creation hints
There are a number of hints, specified using @ref glfwWindowHint, related to

View File

@ -151,10 +151,10 @@ which monitor the window is currently considered to be on.
@section guarantees_limitations Guarantees and limitations
This section describes the conditions under which GLFW can be expected to
function, barring any bugs in GLFW, the operating system or drivers. Use of
GLFW outside of these limits may work on some platforms, or on some machines, or
some of the time, or on some versions of GLFW, but it may break at any time and
will not be considered a bug.
function, barring bugs in the operating system or drivers. Use of GLFW outside
of these limits may work on some platforms, or on some machines, or some of the
time, or on some versions of GLFW, but it may break at any time and this will
not be considered a bug.
@subsection lifetime Pointer lifetimes
@ -171,9 +171,10 @@ If you need to keep this data, you must copy it before its lifetime expires.
Many GLFW functions accept pointers to structures or strings allocated by the
application. These are never freed by GLFW and are always the responsibility of
the application. If GLFW needs to keep the data in these structures or strings,
they are copied before the function returns.
it is copied before the function returns.
Pointer lifetimes are guaranteed not to be shortened in future minor releases.
Pointer lifetimes are guaranteed not to be shortened in future minor or patch
releases.
@subsection reentrancy Reentrancy
@ -191,16 +192,22 @@ function:
- @ref glfwWaitEvents
- @ref glfwTerminate
These functions may be made reentrant in future minor or patch releases, but
functions not on this list will not be made non-reentrant.
@subsection thread_safety Thread safety
Most GLFW functions may only be called from the main thread. The reference
documentation for every GLFW function states whether it is limited to the main
thread.
Most GLFW functions may only be called from the main thread, but some may be
called from any thread. However, no GLFW function may be called from any other
thread until GLFW has been successfully initialized on the main thread,
including functions that may called before initialization.
There are some general rules that make it easier to remember which functions are
limited to the main thread. The following tasks may only be performed on the
main thread:
The reference documentation for every GLFW function states whether it is limited
to the main thread.
The following categories of functions are and will remain limited to the main
thread due to the limitations of one or several platforms:
- Initialization and termination
- Event processing
@ -236,9 +243,11 @@ The following timer related functions may be called from any thread:
- @ref glfwGetTime
No GLFW function may be called from any other thread until GLFW has been
successfully initialized on the main thread, including functions that may called
before initialization.
Library version information may be queried from any thread. The following
version related functions may be called from any thread:
- @ref glfwGetVersion
- @ref glfwGetVersionString
GLFW uses no synchronization objects internally except for thread-local storage
to keep track of the current context for each thread. Synchronization is left
@ -259,8 +268,8 @@ Once a function or constant has been added, the signature of that function or
value of that constant will remain unchanged until the next major version of
GLFW. No compatibility of any kind is guaranteed between major versions.
Undefined behavior, i.e. behavior that is not described in reference
documentation, may change at any time until it is documented.
Undocumented behavior, i.e. behavior that is not described in the documentation,
may change at any time until it is documented.
If the reference documentation and the implementation differ, the reference
documentation is correct and the implementation will be fixed in the next
@ -318,6 +327,10 @@ see which code paths are enabled in a binary.
The version string is returned by @ref glfwGetVersionString, a function that may
be called regardless of whether GLFW is initialized.
__Do not use the version string__ to find the GLFW library version. The @ref
glfwGetVersion function already provides the version of the running library
binary.
The format of the string is as follows:
- The version of GLFW
- The name of the window system API
@ -331,8 +344,4 @@ back ends, the version string may look something like this:
3.0.0 Win32 WGL MinGW
@endcode
@note Do not parse the version string to find the GLFW library version. The
@ref glfwGetVersion function provides the version of the library binary in
numeric form.
*/

View File

@ -12,9 +12,6 @@ guides for the other areas of GLFW.
- @ref context
- @ref input
To see how GLFW views your monitor setup and its available video modes, run the
`modes` test program.
@section monitor_objects Monitor objects
@ -33,6 +30,9 @@ The virtual position of a monitor is in
video mode, describes the viewports that the connected monitors provide into the
virtual desktop that spans them.
To see how GLFW views your monitor setup and its available video modes, run the
`modes` test program.
@subsection monitor_monitors Retrieving monitors

View File

@ -145,15 +145,14 @@ and its handle becomes invalid.
@subsection quick_context_current Making the OpenGL context current
Before you can use the OpenGL API, it must have a current OpenGL context. You
make a window's context current.
Before you can use the OpenGL API, you must have a current OpenGL context.
@code
glfwMakeContextCurrent(window);
@endcode
The context will then remain as current until you make another context current
or until the window owning the current context is destroyed.
The context will remain current until you make another context current or until
the window owning the current context is destroyed.
@subsection quick_window_close Checking the window close flag

View File

@ -4,10 +4,6 @@
@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 full screen window.
This guide introduces the window related functions of GLFW. There are also
guides for the other areas of GLFW.
@ -24,6 +20,9 @@ created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow (or
@ref glfwTerminate, if any remain). As the window and context are inseparably
linked, the object pointer is used as both a context and window handle.
To see the event stream provided to the various window related callbacks, run
the `events` test program.
@subsection window_creation Window creation