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

 /*!

 @page moving Moving from GLFW 2 to 3

 @tableofcontents

 This is a transition guide for moving from GLFW 2 to 3.  It describes what has
 changed or been removed, but does *not* include
 [new features](@ref news) unless they are required when moving an existing code
 base onto the new API.  For example, use of the new multi-monitor functions are
 required to create full screen windows with GLFW 3.


 @section moving_removed Removed features

 @subsection moving_threads Threading functions

 The threading functions have been removed, including the sleep function.  They
 were fairly primitive, under-used, poorly integrated and took time away from the
 focus of GLFW (i.e.  context, input and window).  There are better threading
 libraries available and native threading support is available in both C++11 and
 C11, both of which are gaining traction.

 If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
 support them, see the
 [TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and
 [TinyCThread](https://gitorious.org/tinythread/tinycthread) projects created by
 the original author of GLFW.  These libraries implement a usable subset of the
 threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
 TinyCThread.

 However, GLFW 3 has better support for *use from multiple threads* than GLFW
 2 had.  Contexts can be made current on and rendered with from secondary
 threads, and the documentation explicitly states which functions may be used
 from secondary threads and which may only be used from the main thread, i.e. the
 thread that calls main.


 @subsection moving_image Image and texture loading

 The image and texture loading functions have been removed.  They only supported
 the Targa image format, making them mostly useful for beginner level examples.
 To become of sufficiently high quality to warrant keeping them in GLFW 3, they
 would need not only to support other formats, but also modern extensions to the
 OpenGL texturing facilities.  This would either add a number of external
 dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
 of these libraries.

 As there already are libraries doing this, it seems unnecessary both to
 duplicate this work and to tie this duplicate to GLFW.  Projects similar to
 GLFW, such as freeglut, could also gain from such a library.  Also, would be no
 platform-specific part of such a library, as both OpenGL and stdio are available
 wherever GLFW is.


 @subsection moving_char_up Character actions

 The action parameter of the [character callback](@ref GLFWcharfun) has been
 removed.  This was an artefact of the origin of GLFW, i.e. being developed in
 English by a Swede.  However, many keyboard layouts require more than one key to
 produce characters with diacritical marks. Even the Swedish keyboard layout
 requires this for uncommon cases like ü.

 Note that this is only the removal of the *action parameter* of the character
 callback, *not* the removal of the character callback itself.


 @subsection moving_wheel Mouse wheel position

 The `glfwGetMouseWheel` function has been removed.  Scroll events do not
 represent an absolute state, but is instead an interpretation of a relative
 change in state, like character input.  So, like character input, there is no
 sane 'current state' to return.  The mouse wheel callback has been replaced by
 a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll
 offsets.


 @subsection moving_stdcall GLFWCALL macro

 The `GLFWCALL` macro, which made callback functions use
 [__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
 has been removed.  GLFW is written in C, not Pascal.  Removing this macro means
 there's one less thing for users of GLFW to remember, i.e. the requirement to
 mark all callback functions with `GLFWCALL`.  It also simplifies the creation of
 DLLs and DLL link libraries, as there's no need to explicitly disable `@n` entry
 point suffixes.


 @subsection moving_mbcs Win32 MBCS support

 The Win32 port of GLFW 3 will not compile in
 [MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
 However, because the use of the Unicode version of the Win32 API doesn't affect
 the process as a whole, but only those windows created using it, it's perfectly
 possible to call MBCS functions from other parts of the same application.
 Therefore, even if an application using GLFW has MBCS mode code, there's no need
 for GLFW itself to support it.


 @subsection moving_windows Support for versions of Windows older than XP

 All explicit support for version of Windows older than XP has been removed.
 There is no code that actively prevents GLFW 3 from running on these earlier
 versions, but it uses Win32 functions that those versions lack.

 Windows XP was released in 2001, and by now (2013) it has not only
 replaced almost all earlier versions of Windows, but is itself rapidly being
 replaced by Windows 7 and 8.  The MSDN library doesn't even provide
 documentation for version older than Windows 2000, making it difficult to
 maintain compatibility with these versions even if it was deemed worth the
 effort.

 The Win32 API has also not stood still, and GLFW 3 uses many functions only
 present on Windows XP or later.  Even supporting an OS as new as XP (new
 from the perspective of GLFW 2, which still supports Windows 95) requires
 runtime checking for a number of functions that are present only on modern
 version of Windows.


 @subsection moving_syskeys Capture of system-wide hotkeys

 The ability to disable and capture system-wide hotkeys like Alt+Tab has been
 removed.  Modern applications, whether they're games, scientific visualisations
 or something else, are nowadays expected to be good desktop citizens and allow
 these hotkeys to function even when running in full screen mode.


 @subsection moving_opened Window open parameter

 The `GLFW_OPENED` window parameter has been removed.  As long as the
 [window object](@ref window_object) is around, the window is "open".  To detect
 when the user attempts to close the window, see @ref glfwWindowShouldClose and
 the [close callback](@ref GLFWwindowclosefun).


 @subsection moving_autopoll Automatic polling of events

 GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
 means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
 Unlike buffer swap, the event processing functions act on all windows at once.


 @subsection moving_terminate Automatic termination

 GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization.  To
 properly release all resources allocated by GLFW, you should therefore call @ref
 glfwTerminate yourself before exiting.


 @subsection moving_glu GLU header inclusion

 GLFW 3 does not include the GLU header by default and GLU itself has been
 deprecated, but you can request that the GLFW 3 header includes it by defining
 `GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header.


 @section moving_changed Changes to existing features

 @subsection moving_window_handles Window handles

 Because GLFW 3 supports multiple windows, window handle parameters have been
 added to all window-related GLFW functions and callbacks.  The handle of
 a newly created window is returned by @ref glfwCreateWindow (formerly
 `glfwOpenWindow`).  Window handles are of the `GLFWwindow*` type, i.e. a pointer
 to an opaque struct.


 @subsection moving_monitor Multi-monitor support

 GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
 type and a set of related functions.  To request a full screen mode window,
 instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
 window to use.  There is @ref glfwGetPrimaryMonitor that provides behaviour
 similar to that of GLFW 2.


 @subsection moving_window_close Window closing

 Window closing initiated by the user is now just an event like any other.
 Unlike GLFW 2, windows and contexts created with GLFW 3 will not disappear from
 underfoot.  Each window now has a close flag, which is set when the user
 attempts to close it.  By default, nothing else happens and the window stays
 open and visible.  It is then up to you to either destroy the window, take some
 other action or simply ignore the request.  You can query the close flag at any
 time with @ref glfwWindowShouldClose and set it at any time with @ref
 glfwSetWindowShouldClose.

 The close callback no longer returns a value.  Instead, it is called after the
 close flag has been set so it can override its value, if it chooses to, before
 event processing completes.  You may however not call @ref glfwDestroyWindow
 from the close callback (or any other window related callback).

 GLFW itself never clears the close flag, allowing you to set it for other
 reasons for the window to close as well, for example the user choosing Quit from
 the main menu.


 @subsection moving_context Explicit context management

 Each GLFW 3 window has its own OpenGL context and only you, the user, can know
 which context should be current on which thread at any given time.  Therefore,
 GLFW 3 makes no assumptions about when you want a certain context to be current,
 leaving that decision to you.

 This means, among other things, that you need to call @ref
 glfwMakeContextCurrent after creating a window before you can call any OpenGL
 functions.


 @subsection moving_repeat Key repeat

 The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
 for both keys and characters.  A new key action, `GLFW_REPEAT`, has been added
 to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press
 from a repeat.  Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
 `GLFW_RELEASE`.


 @subsection moving_keys Physical key input

 GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
 the values generated by the current keyboard layout.  The tokens are named
 according to the values they would have using the standard US layout, but this
 is only a convenience, as most programmers are assumed to know that layout.
 This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
 is the same key in the same place regardless of what keyboard layouts the users
 of your program has.

 The key input facility was never meant for text input, although using it that
 way worked slightly better in GLFW 2.  If you were using it to input text, you
 should be using the character callback instead, on both GLFW 2 and 3.  This will
 give you the characters being input, as opposed to the keys being pressed.

 GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
 having to remember whether to check for `'a'` or `'A'`, you now check for
 `GLFW_KEY_A`.


 @subsection moving_joystick Joystick input

 The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.

 The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and
 `GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent
 function as well as axis and button counts returned by the @ref
 glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.


 @subsection moving_video_modes Video mode enumeration

 Video mode enumeration is now per-monitor.  The @ref glfwGetVideoModes function
 now returns all available modes for a specific monitor instead of requiring you
 to guess how large an array you need.  The `glfwGetDesktopMode` function, which
 had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
 returns the current mode of a monitor.


 @subsection moving_cursor Cursor positioning

 GLFW 3 only allows you to position the cursor within a window using @ref
 glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
 Unless the window is active, the function fails silently.


 @subsection moving_hints Persistent window hints

 Window hints are no longer reset to their default values on window creation, but
 instead retain their values until modified by @ref glfwWindowHint (formerly
 `glfwOpenWindowHint`) or @ref glfwDefaultWindowHints, or until the library is
 terminated and re-initialized.


 @section moving_renamed Name changes

 @subsection moving_renamed_files Library and header file

 The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
 avoid collisions with the headers of other major versions.  Similarly, the GLFW
 3 library is named `glfw3,` except when it's installed as a shared library on
 Unix-like systems, where it uses the
 [soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.


 @subsection moving_renamed_functions Functions

 | GLFW 2                      | GLFW 3                        | Notes |
 | --------------------------- | ----------------------------- | ----- |
 | `glfwOpenWindow`            | @ref glfwCreateWindow         | All channel bit depths are now hints
 | `glfwCloseWindow`           | @ref glfwDestroyWindow        |       |
 | `glfwOpenWindowHint`        | @ref glfwWindowHint           | Now accepts all `GLFW_*_BITS` tokens |
 | `glfwEnable`                | @ref glfwSetInputMode         |       |
 | `glfwDisable`               | @ref glfwSetInputMode         |       |
 | `glfwGetMousePos`           | @ref glfwGetCursorPos         |       |
 | `glfwSetMousePos`           | @ref glfwSetCursorPos         |       |
 | `glfwSetMousePosCallback`   | @ref glfwSetCursorPosCallback |       |
 | `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback    | Accepts two-dimensional scroll offsets as doubles |
 | `glfwGetJoystickPos`        | @ref glfwGetJoystickAxes      |       |
 | `glfwGetWindowParam`        | @ref glfwGetWindowAttrib      |       |
 | `glfwGetGLVersion`          | @ref glfwGetWindowAttrib      | Use `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and `GLFW_CONTEXT_REVISION` |
 | `glfwGetDesktopMode`        | @ref glfwGetVideoMode         | Returns the current mode of a monitor |
 | `glfwGetJoystickParam`      | @ref glfwJoystickPresent      | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons |

 @subsection moving_renamed_tokens Tokens

 | GLFW 2                      | GLFW 3                       | Notes |
 | --------------------------- | ---------------------------- | ----- |
 | `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well |
 | `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well |
 | `GLFW_FSAA_SAMPLES`         | `GLFW_SAMPLES`               | Renamed to match the OpenGL API |
 | `GLFW_ACTIVE`               | `GLFW_FOCUSED`               | Renamed to match the window focus callback |
 | `GLFW_WINDOW_NO_RESIZE`     | `GLFW_RESIZABLE`             | The default has been inverted |
 | `GLFW_MOUSE_CURSOR`         | `GLFW_CURSOR`                | Used with @ref glfwSetInputMode |
 | `GLFW_KEY_ESC`              | `GLFW_KEY_ESCAPE`            |       |
 | `GLFW_KEY_DEL`              | `GLFW_KEY_DELETE`            |       |
 | `GLFW_KEY_PAGEUP`           | `GLFW_KEY_PAGE_UP`           |       |
 | `GLFW_KEY_PAGEDOWN`         | `GLFW_KEY_PAGE_DOWN`         |       |
 | `GLFW_KEY_KP_NUM_LOCK`      | `GLFW_KEY_NUM_LOCK`          |       |
 | `GLFW_KEY_LCTRL`            | `GLFW_KEY_LEFT_CONTROL`      |       |
 | `GLFW_KEY_LSHIFT`           | `GLFW_KEY_LEFT_SHIFT`        |       |
 | `GLFW_KEY_LALT`             | `GLFW_KEY_LEFT_ALT`          |       |
 | `GLFW_KEY_LSUPER`           | `GLFW_KEY_LEFT_SUPER`        |       |
 | `GLFW_KEY_RCTRL`            | `GLFW_KEY_RIGHT_CONTROL`     |       |
 | `GLFW_KEY_RSHIFT`           | `GLFW_KEY_RIGHT_SHIFT`       |       |
 | `GLFW_KEY_RALT`             | `GLFW_KEY_RIGHT_ALT`         |       |
 | `GLFW_KEY_RSUPER`           | `GLFW_KEY_RIGHT_SUPER`       |       |

 */
	/*!

	@page moving Moving from GLFW 2 to 3

	@tableofcontents

	This is a transition guide for moving from GLFW 2 to 3. It describes what has
	changed or been removed, but does not include
	[new features](@ref news) unless they are required when moving an existing code
	base onto the new API. For example, use of the new multi-monitor functions are
	required to create full screen windows with GLFW 3.


	@section moving_removed Removed features

	@subsection moving_threads Threading functions

	The threading functions have been removed, including the sleep function. They
	were fairly primitive, under-used, poorly integrated and took time away from the
	focus of GLFW (i.e. context, input and window). There are better threading
	libraries available and native threading support is available in both C++11 and
	C11, both of which are gaining traction.

	If you wish to use the C++11 or C11 facilities but your compiler doesn't yet
	support them, see the
	[TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and
	[TinyCThread](https://gitorious.org/tinythread/tinycthread) projects created by
	the original author of GLFW. These libraries implement a usable subset of the
	threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use
	TinyCThread.

	However, GLFW 3 has better support for use from multiple threads than GLFW
	2 had. Contexts can be made current on and rendered with from secondary
	threads, and the documentation explicitly states which functions may be used
	from secondary threads and which may only be used from the main thread, i.e. the
	thread that calls main.


	@subsection moving_image Image and texture loading

	The image and texture loading functions have been removed. They only supported
	the Targa image format, making them mostly useful for beginner level examples.
	To become of sufficiently high quality to warrant keeping them in GLFW 3, they
	would need not only to support other formats, but also modern extensions to the
	OpenGL texturing facilities. This would either add a number of external
	dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions
	of these libraries.

	As there already are libraries doing this, it seems unnecessary both to
	duplicate this work and to tie this duplicate to GLFW. Projects similar to
	GLFW, such as freeglut, could also gain from such a library. Also, would be no
	platform-specific part of such a library, as both OpenGL and stdio are available
	wherever GLFW is.


	@subsection moving_char_up Character actions

	The action parameter of the [character callback](@ref GLFWcharfun) has been
	removed. This was an artefact of the origin of GLFW, i.e. being developed in
	English by a Swede. However, many keyboard layouts require more than one key to
	produce characters with diacritical marks. Even the Swedish keyboard layout
	requires this for uncommon cases like ü.

	Note that this is only the removal of the action parameter of the character
	callback, not the removal of the character callback itself.


	@subsection moving_wheel Mouse wheel position

	The `glfwGetMouseWheel` function has been removed. Scroll events do not
	represent an absolute state, but is instead an interpretation of a relative
	change in state, like character input. So, like character input, there is no
	sane 'current state' to return. The mouse wheel callback has been replaced by
	a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll
	offsets.


	@subsection moving_stdcall GLFWCALL macro

	The `GLFWCALL` macro, which made callback functions use
	[__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows,
	has been removed. GLFW is written in C, not Pascal. Removing this macro means
	there's one less thing for users of GLFW to remember, i.e. the requirement to
	mark all callback functions with `GLFWCALL`. It also simplifies the creation of
	DLLs and DLL link libraries, as there's no need to explicitly disable `@n` entry
	point suffixes.


	@subsection moving_mbcs Win32 MBCS support

	The Win32 port of GLFW 3 will not compile in
	[MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx).
	However, because the use of the Unicode version of the Win32 API doesn't affect
	the process as a whole, but only those windows created using it, it's perfectly
	possible to call MBCS functions from other parts of the same application.
	Therefore, even if an application using GLFW has MBCS mode code, there's no need
	for GLFW itself to support it.


	@subsection moving_windows Support for versions of Windows older than XP

	All explicit support for version of Windows older than XP has been removed.
	There is no code that actively prevents GLFW 3 from running on these earlier
	versions, but it uses Win32 functions that those versions lack.

	Windows XP was released in 2001, and by now (2013) it has not only
	replaced almost all earlier versions of Windows, but is itself rapidly being
	replaced by Windows 7 and 8. The MSDN library doesn't even provide
	documentation for version older than Windows 2000, making it difficult to
	maintain compatibility with these versions even if it was deemed worth the
	effort.

	The Win32 API has also not stood still, and GLFW 3 uses many functions only
	present on Windows XP or later. Even supporting an OS as new as XP (new
	from the perspective of GLFW 2, which still supports Windows 95) requires
	runtime checking for a number of functions that are present only on modern
	version of Windows.


	@subsection moving_syskeys Capture of system-wide hotkeys

	The ability to disable and capture system-wide hotkeys like Alt+Tab has been
	removed. Modern applications, whether they're games, scientific visualisations
	or something else, are nowadays expected to be good desktop citizens and allow
	these hotkeys to function even when running in full screen mode.


	@subsection moving_opened Window open parameter

	The `GLFW_OPENED` window parameter has been removed. As long as the
	[window object](@ref window_object) is around, the window is "open". To detect
	when the user attempts to close the window, see @ref glfwWindowShouldClose and
	the [close callback](@ref GLFWwindowclosefun).


	@subsection moving_autopoll Automatic polling of events

	GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which
	means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself.
	Unlike buffer swap, the event processing functions act on all windows at once.


	@subsection moving_terminate Automatic termination

	GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To
	properly release all resources allocated by GLFW, you should therefore call @ref
	glfwTerminate yourself before exiting.


	@subsection moving_glu GLU header inclusion

	GLFW 3 does not include the GLU header by default and GLU itself has been
	deprecated, but you can request that the GLFW 3 header includes it by defining
	`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header.


	@section moving_changed Changes to existing features

	@subsection moving_window_handles Window handles

	Because GLFW 3 supports multiple windows, window handle parameters have been
	added to all window-related GLFW functions and callbacks. The handle of
	a newly created window is returned by @ref glfwCreateWindow (formerly
	`glfwOpenWindow`). Window handles are of the `GLFWwindow*` type, i.e. a pointer
	to an opaque struct.


	@subsection moving_monitor Multi-monitor support

	GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle
	type and a set of related functions. To request a full screen mode window,
	instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the
	window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour
	similar to that of GLFW 2.


	@subsection moving_window_close Window closing

	Window closing initiated by the user is now just an event like any other.
	Unlike GLFW 2, windows and contexts created with GLFW 3 will not disappear from
	underfoot. Each window now has a close flag, which is set when the user
	attempts to close it. By default, nothing else happens and the window stays
	open and visible. It is then up to you to either destroy the window, take some
	other action or simply ignore the request. You can query the close flag at any
	time with @ref glfwWindowShouldClose and set it at any time with @ref
	glfwSetWindowShouldClose.

	The close callback no longer returns a value. Instead, it is called after the
	close flag has been set so it can override its value, if it chooses to, before
	event processing completes. You may however not call @ref glfwDestroyWindow
	from the close callback (or any other window related callback).

	GLFW itself never clears the close flag, allowing you to set it for other
	reasons for the window to close as well, for example the user choosing Quit from
	the main menu.


	@subsection moving_context Explicit context management

	Each GLFW 3 window has its own OpenGL context and only you, the user, can know
	which context should be current on which thread at any given time. Therefore,
	GLFW 3 makes no assumptions about when you want a certain context to be current,
	leaving that decision to you.

	This means, among other things, that you need to call @ref
	glfwMakeContextCurrent after creating a window before you can call any OpenGL
	functions.


	@subsection moving_repeat Key repeat

	The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled
	for both keys and characters. A new key action, `GLFW_REPEAT`, has been added
	to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press
	from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or
	`GLFW_RELEASE`.


	@subsection moving_keys Physical key input

	GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to
	the values generated by the current keyboard layout. The tokens are named
	according to the values they would have using the standard US layout, but this
	is only a convenience, as most programmers are assumed to know that layout.
	This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and
	is the same key in the same place regardless of what keyboard layouts the users
	of your program has.

	The key input facility was never meant for text input, although using it that
	way worked slightly better in GLFW 2. If you were using it to input text, you
	should be using the character callback instead, on both GLFW 2 and 3. This will
	give you the characters being input, as opposed to the keys being pressed.

	GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of
	having to remember whether to check for `'a'` or `'A'`, you now check for
	`GLFW_KEY_A`.


	@subsection moving_joystick Joystick input

	The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes.

	The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and
	`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent
	function as well as axis and button counts returned by the @ref
	glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions.


	@subsection moving_video_modes Video mode enumeration

	Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function
	now returns all available modes for a specific monitor instead of requiring you
	to guess how large an array you need. The `glfwGetDesktopMode` function, which
	had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which
	returns the current mode of a monitor.


	@subsection moving_cursor Cursor positioning

	GLFW 3 only allows you to position the cursor within a window using @ref
	glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active.
	Unless the window is active, the function fails silently.


	@subsection moving_hints Persistent window hints

	Window hints are no longer reset to their default values on window creation, but
	instead retain their values until modified by @ref glfwWindowHint (formerly
	`glfwOpenWindowHint`) or @ref glfwDefaultWindowHints, or until the library is
	terminated and re-initialized.


	@section moving_renamed Name changes

	@subsection moving_renamed_files Library and header file

	The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to
	avoid collisions with the headers of other major versions. Similarly, the GLFW
	3 library is named `glfw3,` except when it's installed as a shared library on
	Unix-like systems, where it uses the
	[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`.


	@subsection moving_renamed_functions Functions

	\| GLFW 2 \| GLFW 3 \| Notes \|
	\| --------------------------- \| ----------------------------- \| ----- \|
	\| `glfwOpenWindow` \| @ref glfwCreateWindow \| All channel bit depths are now hints
	\| `glfwCloseWindow` \| @ref glfwDestroyWindow \| \|
	\| `glfwOpenWindowHint` \| @ref glfwWindowHint \| Now accepts all `GLFW_*_BITS` tokens \|
	\| `glfwEnable` \| @ref glfwSetInputMode \| \|
	\| `glfwDisable` \| @ref glfwSetInputMode \| \|
	\| `glfwGetMousePos` \| @ref glfwGetCursorPos \| \|
	\| `glfwSetMousePos` \| @ref glfwSetCursorPos \| \|
	\| `glfwSetMousePosCallback` \| @ref glfwSetCursorPosCallback \| \|
	\| `glfwSetMouseWheelCallback` \| @ref glfwSetScrollCallback \| Accepts two-dimensional scroll offsets as doubles \|
	\| `glfwGetJoystickPos` \| @ref glfwGetJoystickAxes \| \|
	\| `glfwGetWindowParam` \| @ref glfwGetWindowAttrib \| \|
	\| `glfwGetGLVersion` \| @ref glfwGetWindowAttrib \| Use `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and `GLFW_CONTEXT_REVISION` \|
	\| `glfwGetDesktopMode` \| @ref glfwGetVideoMode \| Returns the current mode of a monitor \|
	\| `glfwGetJoystickParam` \| @ref glfwJoystickPresent \| The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons \|

	@subsection moving_renamed_tokens Tokens

	\| GLFW 2 \| GLFW 3 \| Notes \|
	\| --------------------------- \| ---------------------------- \| ----- \|
	\| `GLFW_OPENGL_VERSION_MAJOR` \| `GLFW_CONTEXT_VERSION_MAJOR` \| Renamed as it applies to OpenGL ES as well \|
	\| `GLFW_OPENGL_VERSION_MINOR` \| `GLFW_CONTEXT_VERSION_MINOR` \| Renamed as it applies to OpenGL ES as well \|
	\| `GLFW_FSAA_SAMPLES` \| `GLFW_SAMPLES` \| Renamed to match the OpenGL API \|
	\| `GLFW_ACTIVE` \| `GLFW_FOCUSED` \| Renamed to match the window focus callback \|
	\| `GLFW_WINDOW_NO_RESIZE` \| `GLFW_RESIZABLE` \| The default has been inverted \|
	\| `GLFW_MOUSE_CURSOR` \| `GLFW_CURSOR` \| Used with @ref glfwSetInputMode \|
	\| `GLFW_KEY_ESC` \| `GLFW_KEY_ESCAPE` \| \|
	\| `GLFW_KEY_DEL` \| `GLFW_KEY_DELETE` \| \|
	\| `GLFW_KEY_PAGEUP` \| `GLFW_KEY_PAGE_UP` \| \|
	\| `GLFW_KEY_PAGEDOWN` \| `GLFW_KEY_PAGE_DOWN` \| \|
	\| `GLFW_KEY_KP_NUM_LOCK` \| `GLFW_KEY_NUM_LOCK` \| \|
	\| `GLFW_KEY_LCTRL` \| `GLFW_KEY_LEFT_CONTROL` \| \|
	\| `GLFW_KEY_LSHIFT` \| `GLFW_KEY_LEFT_SHIFT` \| \|
	\| `GLFW_KEY_LALT` \| `GLFW_KEY_LEFT_ALT` \| \|
	\| `GLFW_KEY_LSUPER` \| `GLFW_KEY_LEFT_SUPER` \| \|
	\| `GLFW_KEY_RCTRL` \| `GLFW_KEY_RIGHT_CONTROL` \| \|
	\| `GLFW_KEY_RSHIFT` \| `GLFW_KEY_RIGHT_SHIFT` \| \|
	\| `GLFW_KEY_RALT` \| `GLFW_KEY_RIGHT_ALT` \| \|
	\| `GLFW_KEY_RSUPER` \| `GLFW_KEY_RIGHT_SUPER` \| \|

	*/