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.
327 lines
15 KiB
327 lines
15 KiB
/*! |
|
|
|
@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` | | |
|
|
|
*/
|
|
|