docs/intro.dox - third_party/glfw - Git at Google

 /*!

 @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.


 @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

 */
	/*!

	@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.


	@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

	*/