| /*! |
| |
| @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 zero 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 |
| non-zero 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. |
| |
| |
| @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 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. |
| |
| 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 |
| |
| @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. |
| |
| */ |