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

 /*!

 @page moving Moving from GLFW 2 to 3

 @tableofcontents

 This is a guide for people moving from GLFW 2 to 3.  It describes API *changes*,
 but does *not* include entirely new features unless they are required when
 moving an existing code base onto the new API.  One example of this is the new
 multi-monitor support, which you are now required to use to create fullscreen
 windows.

 @section moving_names Library and header names

 The GLFW 3 header is named @ref glfw3.h, to avoid collisions with the GLFW 2
 `glfw.h` header, in case they are both installed.  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`.

 @section moving_threads Removal of threading functions

 The threading functions have been removed.  However, GLFW 3 has better support
 for use from multiple threads than GLFW 2 had.  Contexts can be made current on
 and used from secondary threads, and the documentation explicitly states which
 functions may and may not be used from secondary threads.

 @section moving_image Removal of image and texture loading

 The image and texture loading support has been removed.

 @section moving_window_handles Window handles

 Because GLFW 3 supports multiple windows, window handle parameters have been
 added to all window-related functions and callbacks.  Window handles are of the
 `GLFWwindow*` type, i.e. a pointer to an opaque struct.

 @section 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 fullscreen mode window, you
 need to specify which monitor you wish the window to use.  There is @ref
 glfwGetPrimaryMonitor that provides something similar to the earlier behaviour.

 @section moving_window_close Window closing

 Window closing is now just an event like any other.  GLFW 3 windows won't
 disappear from underfoot even when no close callback is set; instead the
 window's close flag is set.  You can query this flag using @ref
 glfwWindowShouldClose, or capture close events by setting a close callback.  The
 return value of the close callback then becomes the new value of the close flag.

 @section 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 current,
 leaving that decision to you.

 This means that you need to call @ref glfwMakeContextCurrent after creating
 a window but before calling any OpenGL functions.

 @section moving_keys Physical key input

 GLFW 3 uses the physical key locations named after the symbols they generate
 using the US keyboard layout, instead of layout-dependent characters like in
 GLFW 2.  This means that (for example) `GLFW_KEY_BACKSLASH` 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.

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

 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.

 @section moving_video_modes Video mode enumeration

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

 @section moving_glu GLU header inclusion

 Unlike GLFW 2, GLFW 3 doesn't include the GLU header by default, but you can
 make it do so by defining `GLFW_INCLUDE_GLU` before including the GLFW
 3 header.

 @section moving_cursor Cursor positioning

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

 @section moving_renamed Symbol name changes

 @subsection moving_renamed_functions Renamed functions

 | GLFW 2                      | GLFW 3                        | Notes |
 | --------------------------- | ----------------------------- | ----- |
 | `glfwOpenWindow`            | @ref glfwCreateWindow         | All channel bit depths are now hints<br />Accepts initial window title, optional monitor to go fullscreen on and optional context to share objects with |
 | `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      |       |
 | `glfwGetGLVersion`          | @ref glfwGetWindowParam       | Use `GLFW_OPENGL_VERSION_MAJOR`, `GLFW_OPENGL_VERSION_MINOR` and `GLFW_OPENGL_REVISION` |
 | `glfwGetDesktopMode`        | @ref glfwGetVideoMode         | Returns the current mode of a monitor |

 @subsection moving_renamed_tokens Renamed 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_MODE`           | 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 guide for people moving from GLFW 2 to 3. It describes API changes,
	but does not include entirely new features unless they are required when
	moving an existing code base onto the new API. One example of this is the new
	multi-monitor support, which you are now required to use to create fullscreen
	windows.

	@section moving_names Library and header names

	The GLFW 3 header is named @ref glfw3.h, to avoid collisions with the GLFW 2
	`glfw.h` header, in case they are both installed. 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`.

	@section moving_threads Removal of threading functions

	The threading functions have been removed. However, GLFW 3 has better support
	for use from multiple threads than GLFW 2 had. Contexts can be made current on
	and used from secondary threads, and the documentation explicitly states which
	functions may and may not be used from secondary threads.

	@section moving_image Removal of image and texture loading

	The image and texture loading support has been removed.

	@section moving_window_handles Window handles

	Because GLFW 3 supports multiple windows, window handle parameters have been
	added to all window-related functions and callbacks. Window handles are of the
	`GLFWwindow*` type, i.e. a pointer to an opaque struct.

	@section 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 fullscreen mode window, you
	need to specify which monitor you wish the window to use. There is @ref
	glfwGetPrimaryMonitor that provides something similar to the earlier behaviour.

	@section moving_window_close Window closing

	Window closing is now just an event like any other. GLFW 3 windows won't
	disappear from underfoot even when no close callback is set; instead the
	window's close flag is set. You can query this flag using @ref
	glfwWindowShouldClose, or capture close events by setting a close callback. The
	return value of the close callback then becomes the new value of the close flag.

	@section 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 current,
	leaving that decision to you.

	This means that you need to call @ref glfwMakeContextCurrent after creating
	a window but before calling any OpenGL functions.

	@section moving_keys Physical key input

	GLFW 3 uses the physical key locations named after the symbols they generate
	using the US keyboard layout, instead of layout-dependent characters like in
	GLFW 2. This means that (for example) `GLFW_KEY_BACKSLASH` 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.

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

	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.

	@section moving_video_modes Video mode enumeration

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

	@section moving_glu GLU header inclusion

	Unlike GLFW 2, GLFW 3 doesn't include the GLU header by default, but you can
	make it do so by defining `GLFW_INCLUDE_GLU` before including the GLFW
	3 header.

	@section moving_cursor Cursor positioning

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

	@section moving_renamed Symbol name changes

	@subsection moving_renamed_functions Renamed functions

	\| GLFW 2 \| GLFW 3 \| Notes \|
	\| --------------------------- \| ----------------------------- \| ----- \|
	\| `glfwOpenWindow` \| @ref glfwCreateWindow \| All channel bit depths are now hints<br />Accepts initial window title, optional monitor to go fullscreen on and optional context to share objects with \|
	\| `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 \| \|
	\| `glfwGetGLVersion` \| @ref glfwGetWindowParam \| Use `GLFW_OPENGL_VERSION_MAJOR`, `GLFW_OPENGL_VERSION_MINOR` and `GLFW_OPENGL_REVISION` \|
	\| `glfwGetDesktopMode` \| @ref glfwGetVideoMode \| Returns the current mode of a monitor \|

	@subsection moving_renamed_tokens Renamed 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_MODE` \| 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` \| \|

	*/