1/*! 2 3@page moving Moving from GLFW 2 to 3 4 5@tableofcontents 6 7This is a transition guide for moving from GLFW 2 to 3. It describes what has 8changed or been removed, but does *not* include 9[new features](@ref news) unless they are required when moving an existing code 10base onto the new API. For example, use of the new multi-monitor functions are 11required to create full screen windows with GLFW 3. 12 13 14@section moving_removed Removed features 15 16@subsection moving_threads Threading functions 17 18The threading functions have been removed, including the sleep function. They 19were fairly primitive, under-used, poorly integrated and took time away from the 20focus of GLFW (i.e. context, input and window). There are better threading 21libraries available and native threading support is available in both C++11 and 22C11, both of which are gaining traction. 23 24If you wish to use the C++11 or C11 facilities but your compiler doesn't yet 25support them, see the 26[TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and 27[TinyCThread](https://gitorious.org/tinythread/tinycthread) projects created by 28the original author of GLFW. These libraries implement a usable subset of the 29threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use 30TinyCThread. 31 32However, GLFW 3 has better support for *use from multiple threads* than GLFW 332 had. Contexts can be made current on and rendered with from secondary 34threads, and the documentation explicitly states which functions may be used 35from secondary threads and which may only be used from the main thread, i.e. the 36thread that calls main. 37 38 39@subsection moving_image Image and texture loading 40 41The image and texture loading functions have been removed. They only supported 42the Targa image format, making them mostly useful for beginner level examples. 43To become of sufficiently high quality to warrant keeping them in GLFW 3, they 44would need not only to support other formats, but also modern extensions to the 45OpenGL texturing facilities. This would either add a number of external 46dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions 47of these libraries. 48 49As there already are libraries doing this, it seems unnecessary both to 50duplicate this work and to tie this duplicate to GLFW. Projects similar to 51GLFW, such as freeglut, could also gain from such a library. Also, would be no 52platform-specific part of such a library, as both OpenGL and stdio are available 53wherever GLFW is. 54 55 56@subsection moving_char_up Character actions 57 58The action parameter of the [character callback](@ref GLFWcharfun) has been 59removed. This was an artefact of the origin of GLFW, i.e. being developed in 60English by a Swede. However, many keyboard layouts require more than one key to 61produce characters with diacritical marks. Even the Swedish keyboard layout 62requires this for uncommon cases like ü. 63 64Note that this is only the removal of the *action parameter* of the character 65callback, *not* the removal of the character callback itself. 66 67 68@subsection moving_wheel Mouse wheel position 69 70The `glfwGetMouseWheel` function has been removed. Scroll events do not 71represent an absolute state, but is instead an interpretation of a relative 72change in state, like character input. So, like character input, there is no 73sane 'current state' to return. The mouse wheel callback has been replaced by 74a [scroll callback](@ref GLFWscrollfun) that receives two-dimensional scroll 75offsets. 76 77 78@subsection moving_stdcall GLFWCALL macro 79 80The `GLFWCALL` macro, which made callback functions use 81[__stdcall](http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows, 82has been removed. GLFW is written in C, not Pascal. Removing this macro means 83there's one less thing for users of GLFW to remember, i.e. the requirement to 84mark all callback functions with `GLFWCALL`. It also simplifies the creation of 85DLLs and DLL link libraries, as there's no need to explicitly disable `@n` entry 86point suffixes. 87 88 89@subsection moving_mbcs Win32 MBCS support 90 91The Win32 port of GLFW 3 will not compile in 92[MBCS mode](http://msdn.microsoft.com/en-us/library/5z097dxa.aspx). 93However, because the use of the Unicode version of the Win32 API doesn't affect 94the process as a whole, but only those windows created using it, it's perfectly 95possible to call MBCS functions from other parts of the same application. 96Therefore, even if an application using GLFW has MBCS mode code, there's no need 97for GLFW itself to support it. 98 99 100@subsection moving_windows Support for versions of Windows older than XP 101 102All explicit support for version of Windows older than XP has been removed. 103There is no code that actively prevents GLFW 3 from running on these earlier 104versions, but it uses Win32 functions that those versions lack. 105 106Windows XP was released in 2001, and by now (2013) it has not only 107replaced almost all earlier versions of Windows, but is itself rapidly being 108replaced by Windows 7 and 8. The MSDN library doesn't even provide 109documentation for version older than Windows 2000, making it difficult to 110maintain compatibility with these versions even if it was deemed worth the 111effort. 112 113The Win32 API has also not stood still, and GLFW 3 uses many functions only 114present on Windows XP or later. Even supporting an OS as new as XP (new 115from the perspective of GLFW 2, which still supports Windows 95) requires 116runtime checking for a number of functions that are present only on modern 117version of Windows. 118 119 120@subsection moving_syskeys Capture of system-wide hotkeys 121 122The ability to disable and capture system-wide hotkeys like Alt+Tab has been 123removed. Modern applications, whether they're games, scientific visualisations 124or something else, are nowadays expected to be good desktop citizens and allow 125these hotkeys to function even when running in full screen mode. 126 127 128@subsection moving_opened Window open parameter 129 130The `GLFW_OPENED` window parameter has been removed. As long as the 131[window object](@ref window_object) is around, the window is "open". To detect 132when the user attempts to close the window, see @ref glfwWindowShouldClose and 133the [close callback](@ref GLFWwindowclosefun). 134 135 136@subsection moving_autopoll Automatic polling of events 137 138GLFW 3 does not automatically poll for events on @ref glfwSwapBuffers, which 139means you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. 140Unlike buffer swap, the event processing functions act on all windows at once. 141 142 143@subsection moving_terminate Automatic termination 144 145GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization. To 146properly release all resources allocated by GLFW, you should therefore call @ref 147glfwTerminate yourself before exiting. 148 149 150@subsection moving_glu GLU header inclusion 151 152GLFW 3 does not include the GLU header by default and GLU itself has been 153deprecated, but you can request that the GLFW 3 header includes it by defining 154`GLFW_INCLUDE_GLU` before the inclusion of the GLFW 3 header. 155 156 157@section moving_changed Changes to existing features 158 159@subsection moving_window_handles Window handles 160 161Because GLFW 3 supports multiple windows, window handle parameters have been 162added to all window-related GLFW functions and callbacks. The handle of 163a newly created window is returned by @ref glfwCreateWindow (formerly 164`glfwOpenWindow`). Window handles are of the `GLFWwindow*` type, i.e. a pointer 165to an opaque struct. 166 167 168@subsection moving_monitor Multi-monitor support 169 170GLFW 3 provides support for multiple monitors, adding the `GLFWmonitor*` handle 171type and a set of related functions. To request a full screen mode window, 172instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the 173window to use. There is @ref glfwGetPrimaryMonitor that provides behaviour 174similar to that of GLFW 2. 175 176 177@subsection moving_window_close Window closing 178 179Window closing is now just an event like any other. GLFW 3 windows won't 180disappear from underfoot even when no close callback is set; instead the 181window's close flag is set. You can query this flag using @ref 182glfwWindowShouldClose, or capture close events by setting a close callback. The 183close flag can be modified from any point in your program using @ref 184glfwSetWindowShouldClose. 185 186 187@subsection moving_context Explicit context management 188 189Each GLFW 3 window has its own OpenGL context and only you, the user, can know 190which context should be current on which thread at any given time. Therefore, 191GLFW 3 makes no assumptions about when you want a certain context to be current, 192leaving that decision to you. 193 194This means, among other things, that you need to call @ref 195glfwMakeContextCurrent after creating a window before you can call any OpenGL 196functions. 197 198 199@subsection moving_repeat Key repeat 200 201The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled 202for both keys and characters. A new key action, `GLFW_REPEAT`, has been added 203to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press 204from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or 205`GLFW_RELEASE`. 206 207 208@subsection moving_keys Physical key input 209 210GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to 211the values generated by the current keyboard layout. The tokens are named 212according to the values they would have using the standard US layout, but this 213is only a convenience, as most programmers are assumed to know that layout. 214This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and 215is the same key in the same place regardless of what keyboard layouts the users 216of your program has. 217 218The key input facility was never meant for text input, although using it that 219way worked slightly better in GLFW 2. If you were using it to input text, you 220should be using the character callback instead, on both GLFW 2 and 3. This will 221give you the characters being input, as opposed to the keys being pressed. 222 223GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of 224having to remember whether to check for `'a'` or `'A'`, you now check for 225`GLFW_KEY_A`. 226 227 228@subsection moving_joystick Joystick input 229 230The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes. 231 232The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and 233`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent 234function as well as axis and button counts returned by the @ref 235glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions. 236 237 238@subsection moving_video_modes Video mode enumeration 239 240Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function 241now returns all available modes for a specific monitor instead of requiring you 242to guess how large an array you need. The `glfwGetDesktopMode` function, which 243had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which 244returns the current mode of a monitor. 245 246 247@subsection moving_cursor Cursor positioning 248 249GLFW 3 only allows you to position the cursor within a window using @ref 250glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active. 251Unless the window is active, the function fails silently. 252 253 254@subsection moving_hints Persistent window hints 255 256Window hints are no longer reset to their default values on window creation, but 257instead retain their values until modified by @ref glfwWindowHint (formerly 258`glfwOpenWindowHint`) or @ref glfwDefaultWindowHints, or until the library is 259terminated and re-initialized. 260 261 262@section moving_renamed Name changes 263 264@subsection moving_renamed_files Library and header file 265 266The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to 267avoid collisions with the headers of other major versions. Similarly, the GLFW 2683 library is named `glfw3,` except when it's installed as a shared library on 269Unix-like systems, where it uses the 270[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`. 271 272 273@subsection moving_renamed_functions Functions 274 275| GLFW 2 | GLFW 3 | Notes | 276| --------------------------- | ----------------------------- | ----- | 277| `glfwOpenWindow` | @ref glfwCreateWindow | All channel bit depths are now hints 278| `glfwCloseWindow` | @ref glfwDestroyWindow | | 279| `glfwOpenWindowHint` | @ref glfwWindowHint | Now accepts all `GLFW_*_BITS` tokens | 280| `glfwEnable` | @ref glfwSetInputMode | | 281| `glfwDisable` | @ref glfwSetInputMode | | 282| `glfwGetMousePos` | @ref glfwGetCursorPos | | 283| `glfwSetMousePos` | @ref glfwSetCursorPos | | 284| `glfwSetMousePosCallback` | @ref glfwSetCursorPosCallback | | 285| `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback | Accepts two-dimensional scroll offsets as doubles | 286| `glfwGetJoystickPos` | @ref glfwGetJoystickAxes | | 287| `glfwGetWindowParam` | @ref glfwGetWindowAttrib | | 288| `glfwGetGLVersion` | @ref glfwGetWindowAttrib | Use `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and `GLFW_CONTEXT_REVISION` | 289| `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor | 290| `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons | 291 292@subsection moving_renamed_tokens Tokens 293 294| GLFW 2 | GLFW 3 | Notes | 295| --------------------------- | ---------------------------- | ----- | 296| `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well | 297| `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well | 298| `GLFW_FSAA_SAMPLES` | `GLFW_SAMPLES` | Renamed to match the OpenGL API | 299| `GLFW_ACTIVE` | `GLFW_FOCUSED` | Renamed to match the window focus callback | 300| `GLFW_WINDOW_NO_RESIZE` | `GLFW_RESIZABLE` | The default has been inverted | 301| `GLFW_MOUSE_CURSOR` | `GLFW_CURSOR` | Used with @ref glfwSetInputMode | 302| `GLFW_KEY_ESC` | `GLFW_KEY_ESCAPE` | | 303| `GLFW_KEY_DEL` | `GLFW_KEY_DELETE` | | 304| `GLFW_KEY_PAGEUP` | `GLFW_KEY_PAGE_UP` | | 305| `GLFW_KEY_PAGEDOWN` | `GLFW_KEY_PAGE_DOWN` | | 306| `GLFW_KEY_KP_NUM_LOCK` | `GLFW_KEY_NUM_LOCK` | | 307| `GLFW_KEY_LCTRL` | `GLFW_KEY_LEFT_CONTROL` | | 308| `GLFW_KEY_LSHIFT` | `GLFW_KEY_LEFT_SHIFT` | | 309| `GLFW_KEY_LALT` | `GLFW_KEY_LEFT_ALT` | | 310| `GLFW_KEY_LSUPER` | `GLFW_KEY_LEFT_SUPER` | | 311| `GLFW_KEY_RCTRL` | `GLFW_KEY_RIGHT_CONTROL` | | 312| `GLFW_KEY_RSHIFT` | `GLFW_KEY_RIGHT_SHIFT` | | 313| `GLFW_KEY_RALT` | `GLFW_KEY_RIGHT_ALT` | | 314| `GLFW_KEY_RSUPER` | `GLFW_KEY_RIGHT_SUPER` | | 315 316*/ 317