352 lines
13 KiB
Plaintext
352 lines
13 KiB
Plaintext
/*!
|
|
|
|
@page intro Introduction to the API
|
|
|
|
@tableofcontents
|
|
|
|
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
|
|
- @ref monitor
|
|
- @ref input
|
|
|
|
|
|
@section intro_init Initialization and termination
|
|
|
|
Before most GLFW functions may be called, the library must be initialized.
|
|
This initialization checks what features are available on the machine,
|
|
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, and only from the main thread.
|
|
|
|
- @ref glfwGetVersion
|
|
- @ref glfwGetVersionString
|
|
- @ref glfwSetErrorCallback
|
|
- @ref glfwInit
|
|
- @ref glfwTerminate
|
|
|
|
Calling any other function before that time will cause a @ref
|
|
GLFW_NOT_INITIALIZED error.
|
|
|
|
|
|
@subsection intro_init_init Initializing GLFW
|
|
|
|
The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
|
|
error occurred.
|
|
|
|
@code
|
|
if (!glfwInit())
|
|
{
|
|
// Handle initialization failure
|
|
}
|
|
@endcode
|
|
|
|
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.
|
|
|
|
Once the library has been successfully initialized, it should be terminated
|
|
before the application exits.
|
|
|
|
|
|
@subsection intro_init_terminate Terminating GLFW
|
|
|
|
Before your application exits, you should terminate the GLFW library if it has
|
|
been initialized. This is done with @ref glfwTerminate.
|
|
|
|
@code
|
|
glfwTerminate();
|
|
@endcode
|
|
|
|
This will destroy any remaining window, monitor and cursor objects, restore any
|
|
modified gamma ramps, re-enable the screensaver if it had been disabled and free
|
|
any resources allocated by GLFW.
|
|
|
|
Once the library is terminated, it is as if it had never been initialized and
|
|
you will need to initialize it again before being able to use GLFW. If the
|
|
library was not initialized or had already been terminated, it return
|
|
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.
|
|
|
|
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 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 encoded as UTF-8. The callback is also
|
|
provided with an [error code](@ref errors).
|
|
|
|
@code
|
|
void error_callback(int error, const char* description)
|
|
{
|
|
puts(description);
|
|
}
|
|
@endcode
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
@note Relying on erroneous behavior is not forward compatible. In other words,
|
|
do not rely on a currently invalid call to generate a specific error, as that
|
|
same call may in future versions generate a different error or become valid.
|
|
|
|
|
|
@section coordinate_systems Coordinate systems
|
|
|
|
GLFW has two primary coordinate systems: the _virtual screen_ and the window
|
|
_client area_ or _content 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%" />
|
|
|
|
Both the virtual screen and the client area coordinate systems have the X-axis
|
|
pointing to the right and the Y-axis pointing down.
|
|
|
|
Window and monitor positions are specified as the position of the upper-left
|
|
corners of their content areas relative to the virtual screen, while cursor
|
|
positions are specified relative to a window's client area.
|
|
|
|
Because the origin of the window's client area coordinate system is also the
|
|
point from which the window position is specified, you can translate client area
|
|
coordinates to the virtual screen by adding the window position. The window
|
|
frame, when present, extends 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 considered to be on.
|
|
|
|
|
|
@section guarantees_limitations Guarantees and limitations
|
|
|
|
This section describes the conditions under which GLFW can be expected to
|
|
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
|
|
|
|
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,
|
|
it is copied before the function returns.
|
|
|
|
Pointer lifetimes are guaranteed not to be shortened in future minor or patch
|
|
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 glfwCreateStandardCursor
|
|
- @ref glfwDestroyCursor
|
|
- @ref glfwPollEvents
|
|
- @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, 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.
|
|
|
|
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
|
|
- 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
|
|
|
|
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
|
|
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.
|
|
|
|
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
|
|
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 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
|
|
|
|
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 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
|
|
|
|
|
|
@subsection intro_version_string Version string
|
|
|
|
GLFW 3 also provides a compile-time generated version string that describes the
|
|
version, platform, compiler and any platform-specific compile-time options.
|
|
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 regardless of whether GLFW is initialized.
|
|
|
|
__Do not use the version string__ to parse 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
|
|
- The name of the context creation API
|
|
- Any additional options or APIs
|
|
|
|
For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
|
|
back ends, the version string may look something like this:
|
|
|
|
@code
|
|
3.0.0 Win32 WGL MinGW
|
|
@endcode
|
|
|
|
*/
|