You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and dots ('.'), can be up to 35 characters long. Letters must be lowercase.
280 lines
8.3 KiB
280 lines
8.3 KiB
/*! |
|
|
|
@page moving Moving from GLFW 2 to 3 |
|
|
|
This is a guide for people moving from GLFW 2 to 3. It describes API @em |
|
changes, but does @em 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 @c |
|
glfw.h header, in case they are both installed. Similarly, the GLFW 3 library |
|
is named @c glfw3, except when it's installed as a shared library on |
|
Unix-like systems, where it uses the |
|
<a href="https://en.wikipedia.org/wiki/soname">soname</a> @c 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 |
|
@c 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 @c 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. You can query |
|
whether the user has requested that the window be closed using the @c |
|
GLFW_CLOSE_REQUESTED window parameter, or by setting a close callback. The |
|
return value of the close callback becomes the new value of the window |
|
parameter. |
|
|
|
@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) @c 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 @c 'a' or @c 'A', you now check for @c 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 @c 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 @c 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 |
|
|
|
<table> |
|
<tr> |
|
<td>GLFW 2</td> |
|
<td>GLFW 3</td> |
|
<td>Notes</td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwOpenWindow</td> |
|
<td>@ref glfwCreateWindow</td> |
|
<td>All channel bit depths are now hints<br />The defaults are 24-bit color |
|
and depth buffers<br />Accepts initial window title, optional monitor to go |
|
fullscreen on and optional context to share objects with</td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwCloseWindow</td> |
|
<td>@ref glfwDestroyWindow</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwOpenWindowHint</td> |
|
<td>@ref glfwWindowHint</td> |
|
<td>Now also accepts @c GLFW_RED_BITS, @c GLFW_GREEN_BITS, @c |
|
GLFW_BLUE_BITS, @c GLFW_ALPHA_BITS, @c GLFW_DEPTH_BITS and @c |
|
GLFW_STENCIL_BITS</td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwEnable</td> |
|
<td>@ref glfwSetInputMode</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwDisable</td> |
|
<td>@ref glfwSetInputMode</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwGetMousePos</td> |
|
<td>@ref glfwGetCursorPos</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwSetMousePos</td> |
|
<td>@ref glfwSetCursorPos</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwSetMousePosCallback</td> |
|
<td>@ref glfwSetCursorPosCallback</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwSetMouseWheelCallback</td> |
|
<td>@ref glfwSetScrollCallback</td> |
|
<td>Accepts two-dimensional scroll offsets as doubles</td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwGetJoystickPos</td> |
|
<td>@ref glfwGetJoystickAxes</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwGetGLVersion</td> |
|
<td>@ref glfwGetWindowParam</td> |
|
<td>Use @c GLFW_OPENGL_VERSION_MAJOR, @c GLFW_OPENGL_VERSION_MINOR and @c |
|
GLFW_OPENGL_REVISION</td> |
|
</tr> |
|
<tr> |
|
<td>@c glfwGetDesktopMode</td> |
|
<td>@ref glfwGetVideoMode</td> |
|
<td>Returns the current mode of a monitor</td> |
|
</tr> |
|
</table> |
|
|
|
@subsection moving_renamed_tokens Renamed tokens |
|
|
|
<table> |
|
<tr> |
|
<td>GLFW 2</td> |
|
<td>GLFW 3</td> |
|
<td>Notes</td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_OPENGL_VERSION_MAJOR</td> |
|
<td>@c GLFW_CONTEXT_VERSION_MAJOR</td> |
|
<td>Renamed as it applies to OpenGL ES as well</td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_OPENGL_VERSION_MINOR</td> |
|
<td>@c GLFW_CONTEXT_VERSION_MINOR</td> |
|
<td>Renamed as it applies to OpenGL ES as well</td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_FSAA_SAMPLES</td> |
|
<td>@c GLFW_SAMPLES</td> |
|
<td>Renamed to match the OpenGL API</td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_ACTIVE</td> |
|
<td>@c GLFW_FOCUSED</td> |
|
<td>Renamed to match the window focus callback</td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_WINDOW_NO_RESIZE</td> |
|
<td>@c GLFW_RESIZABLE</td> |
|
<td>The default has been inverted</td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_MOUSE_CURSOR</td> |
|
<td>@c GLFW_CURSOR_MODE</td> |
|
<td>Used with @c glfwSetInputMode<br />Accepts @c GLFW_CURSOR_NORMAL, @c |
|
GLFW_CURSOR_HIDDEN and @c GLFW_CURSOR_CAPTURED</td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_ESC</td> |
|
<td>@c GLFW_KEY_ESCAPE</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_DEL</td> |
|
<td>@c GLFW_KEY_DELETE</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_PAGEUP</td> |
|
<td>@c GLFW_KEY_PAGE_UP</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_PAGEDOWN</td> |
|
<td>@c GLFW_KEY_PAGE_DOWN</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_KP_NUM_LOCK</td> |
|
<td>@c GLFW_KEY_NUM_LOCK</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_LCTRL</td> |
|
<td>@c GLFW_KEY_LEFT_CONTROL</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_LSHIFT</td> |
|
<td>@c GLFW_KEY_LEFT_SHIFT</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_LALT</td> |
|
<td>@c GLFW_KEY_LEFT_ALT</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_LSUPER</td> |
|
<td>@c GLFW_KEY_LEFT_SUPER</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_RCTRL</td> |
|
<td>@c GLFW_KEY_RIGHT_CONTROL</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_RSHIFT</td> |
|
<td>@c GLFW_KEY_RIGHT_SHIFT</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_RALT</td> |
|
<td>@c GLFW_KEY_RIGHT_ALT</td> |
|
<td></td> |
|
</tr> |
|
<tr> |
|
<td>@c GLFW_KEY_RSUPER</td> |
|
<td>@c GLFW_KEY_RIGHT_SUPER</td> |
|
<td></td> |
|
</tr> |
|
</table> |
|
|
|
*/
|
|
|