caio/glfw
1
0
Fork 0
mirror of https://github.com/glfw/glfw.git synced 2026-08-27 19:05:54 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation work.

Browse Source
This commit is contained in:
Camilla Berglund
2014-09-18 15:03:29 +02:00
parent c769061a8a
commit 4591ad2d64
21 changed files with 3186 additions and 882 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
docs/intro.dox
View File

@@ -1,12 +1,13 @@
/*!
@page intro Introduction to the GLFW API
@page intro Introduction to the API
@tableofcontents
This guide will introduce the basic concepts of GLFW and describes
initialization, error handling and version management. There are other guides
for the various areas of the GLFW API.
This guide introduces the basic concepts of GLFW and describes initialization,
error handling and API guarantees and limitations. For a broad but shallow
tutorial, see @ref quick instead. There are also guides for the other areas of
GLFW.
- @ref window
- @ref context
@@ -22,7 +23,7 @@ enumerates monitors and joysticks, initializes the timer and performs any
required platform-specific initialization.
Only the following functions may be called before the library has been
successfully initialized.
successfully initialized, and only from the main thread.
- @ref glfwGetVersion
- @ref glfwGetVersionString
@@ -36,8 +37,8 @@ error.
@subsection intro_init_init Initializing GLFW
The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
error occurred.
The library is initialized with @ref glfwInit, which returns zero if an error
occurred.
@code
if (!glfwInit())
@@ -49,7 +50,7 @@ if (!glfwInit())
If any part of initialization fails, all remaining bits are terminated as if
@ref glfwTerminate was called. The library only needs to be initialized once
and additional calls to an already initialized library will simply return
`GL_TRUE` immediately.
non-zero immediately.
Once the library has been successfully initialized, it should be terminated
before the application exits.
@@ -74,23 +75,24 @@ library had not been successfully initialized or had already been terminated,
additional calls return immediately.
@section intro_error Error handling
@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. Also, far
from all GLFW functions have such return values.
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.
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
called before @ref glfwInit and after @ref glfwTerminate.
called regardless of whether GLFW is initialized.
@code
glfwSetErrorCallback(error_callback);
@endcode
The error callback receives a human-readable description of the error and (when
possible) its cause. The description is a regular C string using the UTF-8
encoding. The callback is also provided with an [error code](@ref errors).
possible) its cause. The description encoded as UTF-8. The callback is also
provided with an [error code](@ref errors).
@code
void error_callback(int error, const char* description)
@@ -100,25 +102,177 @@ void error_callback(int error, const char* description)
@endcode
The error code indicates the general category of the error. Some error codes,
such as `GLFW_NOT_INITIALIZED` has only a single meaning, whereas others like
`GLFW_PLATFORM_ERROR` are used for many different errors.
such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
@ref GLFW_PLATFORM_ERROR are used for many different errors.
@note 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 keep the description string.
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
keep the description string.
@section coordinate_systems Coordinate systems
GLFW has two primary coordinate systems: the _virtual screen_ and the window
_client area_. Both use the same unit: _virtual screen coordinates_, or just
_screen coordinates_, which don't necessarily correspond to pixels.
<img src="spaces.svg" width="90%" />
Window and monitor positions are specified relative to the upper-left corners of
their content areas, while cursor positions are specified relative to the window
client area.
The origin of the window client area coordinate system is also the position of
the window, meaning you can translate client area coordinates to the virtual
screen by adding the window position. The window frame, when present, extend
out from the client area but does not affect the window position.
Almost all positions and sizes in GLFW are measured in screen coordinates
relative to one of the two origins above. This includes cursor positions,
window positions and sizes, window frame sizes, monitor positions and video mode
resolutions.
Two exceptions are the [monitor physical size](@ref monitor_size), which is
measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
measured in pixels.
Pixels and screen coordinates may map 1:1 on your machine, but they won't on
every other machine, for example on a Mac with a Retina display. The ratio
between screen coordinates and pixels may also change at run-time depending on
which monitor the window is currently 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.
@subsection lifetime Pointer lifetimes
GLFW will never free any pointer you provide to it and you must never free any
pointer it provides to you.
Many GLFW functions return pointers to dynamically allocated structures, strings
or arrays, and some callbacks are provided with strings or arrays. These are
always managed by GLFW and should never be freed by the application. The
lifetime of these pointers is documented for each GLFW function and callback.
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.
Pointer lifetimes are guaranteed not to be shortened in future minor releases.
@subsection reentrancy Reentrancy
GLFW event processing and object creation and destruction are not reentrant.
This means that the following functions may not be called from any callback
function:
- @ref glfwCreateWindow
- @ref glfwDestroyWindow
- @ref glfwCreateCursor
- @ref glfwDestroyCursor
- @ref glfwPollEvents
- @ref glfwWaitEvents
@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.
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:
- Initialization and termination
- Event processing
- Creation and destruction of window, context and cursor objects
Because event processing must be performed on the main thread, all callbacks
except for the error callback will only be called on that thread. The error
callback may be called on any thread, as any GLFW function may generate errors.
The posting of empty events may be done from any thread. The window user
pointer and close flag may also be accessed and modified from any thread, but
this is not synchronized by GLFW. The following window related functions may
be called from any thread:
- @ref glfwPostEmptyEvent
- @ref glfwGetWindowUserPointer
- @ref glfwSetWindowUserPointer
- @ref glfwWindowShouldClose
- @ref glfwSetWindowShouldClose
Rendering may be done on any thread. The following context related functions
may be called from any thread:
- @ref glfwMakeContextCurrent
- @ref glfwGetCurrentContext
- @ref glfwSwapBuffers
- @ref glfwSwapInterval
- @ref glfwExtensionSupported
- @ref glfwGetProcAddress
The timer may be accessed from any thread, but this is not synchronized by GLFW.
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.
GLFW uses no synchronization objects internally except for thread-local storage
to keep track of the current context for each thread. Synchronization is left
to the application.
Functions that may currently be called from any thread will always remain so,
but functions that are currently limited to the main may be updated to allow
calls from any thread in future releases.
@subsection compatibility Version compatibility
GLFW guarantees binary backward compatibility with earlier minor versions of the
API. This means that you can drop in a newer version of the GLFW DLL / shared
library / dynamic library and existing applications will continue to run.
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.
If the reference documentation and the implementation differ, the reference
documentation is correct and the implementation will be fixed in the next
release.
@subsection event_order Event order
The order of arrival of related events is not guaranteed to be consistent
across platforms. The exception is synthetic key and mouse button release
events, which are always delivered after the window defocus event.
@section intro_version Version management
GLFW provides mechanisms for identifying what version of GLFW your application
was compiled against as well as what version it is currently using. The GLFW
API is binary-compatible with later minor versions, i.e. an executable using the
3.0 API will be able to use a version 3.2 DLL.
As long as an executable does not use any newer functions, it can also use an
older minor version DLL, although any window hints or other tokens added since
that older version will cause errors to be reported.
was compiled against as well as what version it is currently running against.
If you are loading GLFW dynamically (not just linking dynamically), you can use
this to verify that the library binary is compatible with your application.
@subsection intro_version_compile Compile-time version
@@ -126,15 +280,24 @@ that older version will cause errors to be reported.
The compile-time version of GLFW is provided by the GLFW header with the
`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
@code
printf("Compiled against GLFW %i.%i.%i\n",
GLFW_VERSION_MAJOR,
GLFW_VERSION_MINOR,
GLFW_VERSION_REVISION);
@endcode
@subsection intro_version_runtime Run-time version
The run-time version can be retrieved with @ref glfwGetVersion, a function that
may be called before @ref glfwInit and after @ref glfwTerminate
may be called regardless of whether GLFW is initialized.
@code
int major, minor, revision;
glfwGetVersion(&major, &minor, &revision);
printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
@endcode
@@ -146,7 +309,7 @@ This is primarily intended for submitting bug reports, to allow developers to
see which code paths are enabled in a binary.
The version string is returned by @ref glfwGetVersionString, a function that may
be called before @ref glfwInit and after @ref glfwTerminate.
be called regardless of whether GLFW is initialized.
The format of the string is as follows:
- The version of GLFW
@@ -157,7 +320,9 @@ The format of the string is as follows:
For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
back ends, the version string may look something like this:
3.0.0 Win32 WGL MinGW
@code
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