mirror of
https://github.com/glfw/glfw.git
synced 2024-11-11 04:53:50 +00:00
Documentation work.
This commit is contained in:
Camilla Berglund
parent
500f5ebf04
commit
4e375d0e74
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
*/
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user