1/*! 2 3@page moving_guide 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, the new multi-monitor functions are 11required to create full screen windows with GLFW 3. 12 13 14@section moving_removed Changed and removed features 15 16@subsection moving_renamed_files Renamed library and header file 17 18The GLFW 3 header is named @ref glfw3.h and moved to the `GLFW` directory, to 19avoid collisions with the headers of other major versions. Similarly, the GLFW 203 library is named `glfw3,` except when it's installed as a shared library on 21Unix-like systems, where it uses the 22[soname](https://en.wikipedia.org/wiki/soname) `libglfw.so.3`. 23 24@par Old syntax 25@code 26#include <GL/glfw.h> 27@endcode 28 29@par New syntax 30@code 31#include <GLFW/glfw3.h> 32@endcode 33 34 35@subsection moving_threads Removal of threading functions 36 37The threading functions have been removed, including the per-thread sleep 38function. They were fairly primitive, under-used, poorly integrated and took 39time away from the focus of GLFW (i.e. context, input and window). There are 40better threading libraries available and native threading support is available 41in both [C++11](https://en.cppreference.com/w/cpp/thread) and 42[C11](https://en.cppreference.com/w/c/thread), both of which are gaining 43traction. 44 45If you wish to use the C++11 or C11 facilities but your compiler doesn't yet 46support them, see the 47[TinyThread++](https://gitorious.org/tinythread/tinythreadpp) and 48[TinyCThread](https://github.com/tinycthread/tinycthread) projects created by 49the original author of GLFW. These libraries implement a usable subset of the 50threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use 51TinyCThread. 52 53However, GLFW 3 has better support for _use from multiple threads_ than GLFW 542 had. Contexts can be made current on any thread, although only a single 55thread at a time, and the documentation explicitly states which functions may be 56used from any thread and which must only be used from the main thread. 57 58@par Removed functions 59`glfwSleep`, `glfwCreateThread`, `glfwDestroyThread`, `glfwWaitThread`, 60`glfwGetThreadID`, `glfwCreateMutex`, `glfwDestroyMutex`, `glfwLockMutex`, 61`glfwUnlockMutex`, `glfwCreateCond`, `glfwDestroyCond`, `glfwWaitCond`, 62`glfwSignalCond`, `glfwBroadcastCond` and `glfwGetNumberOfProcessors`. 63 64@par Removed types 65`GLFWthreadfun` 66 67 68@subsection moving_image Removal of image and texture loading 69 70The image and texture loading functions have been removed. They only supported 71the Targa image format, making them mostly useful for beginner level examples. 72To become of sufficiently high quality to warrant keeping them in GLFW 3, they 73would need not only to support other formats, but also modern extensions to 74OpenGL texturing. This would either add a number of external 75dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions 76of these libraries. 77 78As there already are libraries doing this, it is unnecessary both to duplicate 79the work and to tie the duplicate to GLFW. The resulting library would also be 80platform-independent, as both OpenGL and stdio are available wherever GLFW is. 81 82@par Removed functions 83`glfwReadImage`, `glfwReadMemoryImage`, `glfwFreeImage`, `glfwLoadTexture2D`, 84`glfwLoadMemoryTexture2D` and `glfwLoadTextureImage2D`. 85 86 87@subsection moving_stdcall Removal of GLFWCALL macro 88 89The `GLFWCALL` macro, which made callback functions use 90[__stdcall](https://msdn.microsoft.com/en-us/library/zxk0tw93.aspx) on Windows, 91has been removed. GLFW is written in C, not Pascal. Removing this macro means 92there's one less thing for application programmers to remember, i.e. the 93requirement to mark all callback functions with `GLFWCALL`. It also simplifies 94the creation of DLLs and DLL link libraries, as there's no need to explicitly 95disable `@n` entry point suffixes. 96 97@par Old syntax 98@code 99void GLFWCALL callback_function(...); 100@endcode 101 102@par New syntax 103@code 104void callback_function(...); 105@endcode 106 107 108@subsection moving_window_handles Window handle parameters 109 110Because GLFW 3 supports multiple windows, window handle parameters have been 111added to all window-related GLFW functions and callbacks. The handle of 112a newly created window is returned by @ref glfwCreateWindow (formerly 113`glfwOpenWindow`). Window handles are pointers to the 114[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWwindow. 115 116@par Old syntax 117@code 118glfwSetWindowTitle("New Window Title"); 119@endcode 120 121@par New syntax 122@code 123glfwSetWindowTitle(window, "New Window Title"); 124@endcode 125 126 127@subsection moving_monitor Explicit monitor selection 128 129GLFW 3 provides support for multiple monitors. To request a full screen mode window, 130instead of passing `GLFW_FULLSCREEN` you specify which monitor you wish the 131window to use. The @ref glfwGetPrimaryMonitor function returns the monitor that 132GLFW 2 would have selected, but there are many other 133[monitor functions](@ref monitor_guide). Monitor handles are pointers to the 134[opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type @ref GLFWmonitor. 135 136@par Old basic full screen 137@code 138glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN); 139@endcode 140 141@par New basic full screen 142@code 143window = glfwCreateWindow(640, 480, "My Window", glfwGetPrimaryMonitor(), NULL); 144@endcode 145 146@note The framebuffer bit depth parameters of `glfwOpenWindow` have been turned 147into [window hints](@ref window_hints), but as they have been given 148[sane defaults](@ref window_hints_values) you rarely need to set these hints. 149 150 151@subsection moving_autopoll Removal of automatic event polling 152 153GLFW 3 does not automatically poll for events in @ref glfwSwapBuffers, meaning 154you need to call @ref glfwPollEvents or @ref glfwWaitEvents yourself. Unlike 155buffer swap, which acts on a single window, the event processing functions act 156on all windows at once. 157 158@par Old basic main loop 159@code 160while (...) 161{ 162 // Process input 163 // Render output 164 glfwSwapBuffers(); 165} 166@endcode 167 168@par New basic main loop 169@code 170while (...) 171{ 172 // Process input 173 // Render output 174 glfwSwapBuffers(window); 175 glfwPollEvents(); 176} 177@endcode 178 179 180@subsection moving_context Explicit context management 181 182Each GLFW 3 window has its own OpenGL context and only you, the application 183programmer, can know which context should be current on which thread at any 184given time. Therefore, GLFW 3 leaves that decision to you. 185 186This means that you need to call @ref glfwMakeContextCurrent after creating 187a window before you can call any OpenGL functions. 188 189 190@subsection moving_hidpi Separation of window and framebuffer sizes 191 192Window positions and sizes now use screen coordinates, which may not be the same 193as pixels on machines with high-DPI monitors. This is important as OpenGL uses 194pixels, not screen coordinates. For example, the rectangle specified with 195`glViewport` needs to use pixels. Therefore, framebuffer size functions have 196been added. You can retrieve the size of the framebuffer of a window with @ref 197glfwGetFramebufferSize function. A framebuffer size callback has also been 198added, which can be set with @ref glfwSetFramebufferSizeCallback. 199 200@par Old basic viewport setup 201@code 202glfwGetWindowSize(&width, &height); 203glViewport(0, 0, width, height); 204@endcode 205 206@par New basic viewport setup 207@code 208glfwGetFramebufferSize(window, &width, &height); 209glViewport(0, 0, width, height); 210@endcode 211 212 213@subsection moving_window_close Window closing changes 214 215The `GLFW_OPENED` window parameter has been removed. As long as the window has 216not been destroyed, whether through @ref glfwDestroyWindow or @ref 217glfwTerminate, the window is "open". 218 219A user attempting to close a window is now just an event like any other. Unlike 220GLFW 2, windows and contexts created with GLFW 3 will never be destroyed unless 221you choose them to be. Each window now has a close flag that is set to 222`GLFW_TRUE` when the user attempts to close that window. By default, nothing else 223happens and the window stays visible. It is then up to you to either destroy 224the window, take some other action or ignore the request. 225 226You can query the close flag at any time with @ref glfwWindowShouldClose and set 227it at any time with @ref glfwSetWindowShouldClose. 228 229@par Old basic main loop 230@code 231while (glfwGetWindowParam(GLFW_OPENED)) 232{ 233 ... 234} 235@endcode 236 237@par New basic main loop 238@code 239while (!glfwWindowShouldClose(window)) 240{ 241 ... 242} 243@endcode 244 245The close callback no longer returns a value. Instead, it is called after the 246close flag has been set so it can override its value, if it chooses to, before 247event processing completes. You may however not call @ref glfwDestroyWindow 248from the close callback (or any other window related callback). 249 250@par Old syntax 251@code 252int GLFWCALL window_close_callback(void); 253@endcode 254 255@par New syntax 256@code 257void window_close_callback(GLFWwindow* window); 258@endcode 259 260@note GLFW never clears the close flag to `GLFW_FALSE`, meaning you can use it 261for other reasons to close the window as well, for example the user choosing 262Quit from an in-game menu. 263 264 265@subsection moving_hints Persistent window hints 266 267The `glfwOpenWindowHint` function has been renamed to @ref glfwWindowHint. 268 269Window hints are no longer reset to their default values on window creation, but 270instead retain their values until modified by @ref glfwWindowHint or @ref 271glfwDefaultWindowHints, or until the library is terminated and re-initialized. 272 273 274@subsection moving_video_modes Video mode enumeration 275 276Video mode enumeration is now per-monitor. The @ref glfwGetVideoModes function 277now returns all available modes for a specific monitor instead of requiring you 278to guess how large an array you need. The `glfwGetDesktopMode` function, which 279had poorly defined behavior, has been replaced by @ref glfwGetVideoMode, which 280returns the current mode of a monitor. 281 282 283@subsection moving_char_up Removal of character actions 284 285The action parameter of the [character callback](@ref GLFWcharfun) has been 286removed. This was an artefact of the origin of GLFW, i.e. being developed in 287English by a Swede. However, many keyboard layouts require more than one key to 288produce characters with diacritical marks. Even the Swedish keyboard layout 289requires this for uncommon cases like ü. 290 291@par Old syntax 292@code 293void GLFWCALL character_callback(int character, int action); 294@endcode 295 296@par New syntax 297@code 298void character_callback(GLFWwindow* window, int character); 299@endcode 300 301 302@subsection moving_cursorpos Cursor position changes 303 304The `glfwGetMousePos` function has been renamed to @ref glfwGetCursorPos, 305`glfwSetMousePos` to @ref glfwSetCursorPos and `glfwSetMousePosCallback` to @ref 306glfwSetCursorPosCallback. 307 308The cursor position is now `double` instead of `int`, both for the direct 309functions and for the callback. Some platforms can provide sub-pixel cursor 310movement and this data is now passed on to the application where available. On 311platforms where this is not provided, the decimal part is zero. 312 313GLFW 3 only allows you to position the cursor within a window using @ref 314glfwSetCursorPos (formerly `glfwSetMousePos`) when that window is active. 315Unless the window is active, the function fails silently. 316 317 318@subsection moving_wheel Wheel position replaced by scroll offsets 319 320The `glfwGetMouseWheel` function has been removed. Scrolling is the input of 321offsets and has no absolute position. The mouse wheel callback has been 322replaced by a [scroll callback](@ref GLFWscrollfun) that receives 323two-dimensional floating point scroll offsets. This allows you to receive 324precise scroll data from for example modern touchpads. 325 326@par Old syntax 327@code 328void GLFWCALL mouse_wheel_callback(int position); 329@endcode 330 331@par New syntax 332@code 333void scroll_callback(GLFWwindow* window, double xoffset, double yoffset); 334@endcode 335 336@par Removed functions 337`glfwGetMouseWheel` 338 339 340@subsection moving_repeat Key repeat action 341 342The `GLFW_KEY_REPEAT` enable has been removed and key repeat is always enabled 343for both keys and characters. A new key action, `GLFW_REPEAT`, has been added 344to allow the [key callback](@ref GLFWkeyfun) to distinguish an initial key press 345from a repeat. Note that @ref glfwGetKey still returns only `GLFW_PRESS` or 346`GLFW_RELEASE`. 347 348 349@subsection moving_keys Physical key input 350 351GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to 352the values generated by the current keyboard layout. The tokens are named 353according to the values they would have using the standard US layout, but this 354is only a convenience, as most programmers are assumed to know that layout. 355This means that (for example) `GLFW_KEY_LEFT_BRACKET` is always a single key and 356is the same key in the same place regardless of what keyboard layouts the users 357of your program has. 358 359The key input facility was never meant for text input, although using it that 360way worked slightly better in GLFW 2. If you were using it to input text, you 361should be using the character callback instead, on both GLFW 2 and 3. This will 362give you the characters being input, as opposed to the keys being pressed. 363 364GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of 365having to remember whether to check for `a` or `A`, you now check for 366@ref GLFW_KEY_A. 367 368 369@subsection moving_joystick Joystick function changes 370 371The `glfwGetJoystickPos` function has been renamed to @ref glfwGetJoystickAxes. 372 373The `glfwGetJoystickParam` function and the `GLFW_PRESENT`, `GLFW_AXES` and 374`GLFW_BUTTONS` tokens have been replaced by the @ref glfwJoystickPresent 375function as well as axis and button counts returned by the @ref 376glfwGetJoystickAxes and @ref glfwGetJoystickButtons functions. 377 378 379@subsection moving_mbcs Win32 MBCS support 380 381The Win32 port of GLFW 3 will not compile in 382[MBCS mode](https://msdn.microsoft.com/en-us/library/5z097dxa.aspx). 383However, because the use of the Unicode version of the Win32 API doesn't affect 384the process as a whole, but only those windows created using it, it's perfectly 385possible to call MBCS functions from other parts of the same application. 386Therefore, even if an application using GLFW has MBCS mode code, there's no need 387for GLFW itself to support it. 388 389 390@subsection moving_windows Support for versions of Windows older than XP 391 392All explicit support for version of Windows older than XP has been removed. 393There is no code that actively prevents GLFW 3 from running on these earlier 394versions, but it uses Win32 functions that those versions lack. 395 396Windows XP was released in 2001, and by now (January 2015) it has not only 397replaced almost all earlier versions of Windows, but is itself rapidly being 398replaced by Windows 7 and 8. The MSDN library doesn't even provide 399documentation for version older than Windows 2000, making it difficult to 400maintain compatibility with these versions even if it was deemed worth the 401effort. 402 403The Win32 API has also not stood still, and GLFW 3 uses many functions only 404present on Windows XP or later. Even supporting an OS as new as XP (new 405from the perspective of GLFW 2, which still supports Windows 95) requires 406runtime checking for a number of functions that are present only on modern 407version of Windows. 408 409 410@subsection moving_syskeys Capture of system-wide hotkeys 411 412The ability to disable and capture system-wide hotkeys like Alt+Tab has been 413removed. Modern applications, whether they're games, scientific visualisations 414or something else, are nowadays expected to be good desktop citizens and allow 415these hotkeys to function even when running in full screen mode. 416 417 418@subsection moving_terminate Automatic termination 419 420GLFW 3 does not register @ref glfwTerminate with `atexit` at initialization, 421because `exit` calls registered functions from the calling thread and while it 422is permitted to call `exit` from any thread, @ref glfwTerminate must only be 423called from the main thread. 424 425To release all resources allocated by GLFW, you should call @ref glfwTerminate 426yourself, from the main thread, before the program terminates. Note that this 427destroys all windows not already destroyed with @ref glfwDestroyWindow, 428invalidating any window handles you may still have. 429 430 431@subsection moving_glu GLU header inclusion 432 433GLFW 3 does not by default include the GLU header and GLU itself has been 434deprecated by [Khronos](https://en.wikipedia.org/wiki/Khronos_Group). __New 435projects should not use GLU__, but if you need it for legacy code that 436has been moved to GLFW 3, you can request that the GLFW header includes it by 437defining @ref GLFW_INCLUDE_GLU before the inclusion of the GLFW header. 438 439@par Old syntax 440@code 441#include <GL/glfw.h> 442@endcode 443 444@par New syntax 445@code 446#define GLFW_INCLUDE_GLU 447#include <GLFW/glfw3.h> 448@endcode 449 450There are many libraries that offer replacements for the functionality offered 451by GLU. For the matrix helper functions, see math libraries like 452[GLM](https://github.com/g-truc/glm) (for C++), 453[linmath.h](https://github.com/datenwolf/linmath.h) (for C) and others. For the 454tessellation functions, see for example 455[libtess2](https://github.com/memononen/libtess2). 456 457 458@section moving_tables Name change tables 459 460 461@subsection moving_renamed_functions Renamed functions 462 463| GLFW 2 | GLFW 3 | Notes | 464| --------------------------- | ----------------------------- | ----- | 465| `glfwOpenWindow` | @ref glfwCreateWindow | All channel bit depths are now hints 466| `glfwCloseWindow` | @ref glfwDestroyWindow | | 467| `glfwOpenWindowHint` | @ref glfwWindowHint | Now accepts all `GLFW_*_BITS` tokens | 468| `glfwEnable` | @ref glfwSetInputMode | | 469| `glfwDisable` | @ref glfwSetInputMode | | 470| `glfwGetMousePos` | @ref glfwGetCursorPos | | 471| `glfwSetMousePos` | @ref glfwSetCursorPos | | 472| `glfwSetMousePosCallback` | @ref glfwSetCursorPosCallback | | 473| `glfwSetMouseWheelCallback` | @ref glfwSetScrollCallback | Accepts two-dimensional scroll offsets as doubles | 474| `glfwGetJoystickPos` | @ref glfwGetJoystickAxes | | 475| `glfwGetWindowParam` | @ref glfwGetWindowAttrib | | 476| `glfwGetGLVersion` | @ref glfwGetWindowAttrib | Use `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and `GLFW_CONTEXT_REVISION` | 477| `glfwGetDesktopMode` | @ref glfwGetVideoMode | Returns the current mode of a monitor | 478| `glfwGetJoystickParam` | @ref glfwJoystickPresent | The axis and button counts are provided by @ref glfwGetJoystickAxes and @ref glfwGetJoystickButtons | 479 480 481@subsection moving_renamed_types Renamed types 482 483| GLFW 2 | GLFW 3 | Notes | 484| ------------------- | --------------------- | | 485| `GLFWmousewheelfun` | @ref GLFWscrollfun | | 486| `GLFWmouseposfun` | @ref GLFWcursorposfun | | 487 488 489@subsection moving_renamed_tokens Renamed tokens 490 491| GLFW 2 | GLFW 3 | Notes | 492| --------------------------- | ---------------------------- | ----- | 493| `GLFW_OPENGL_VERSION_MAJOR` | `GLFW_CONTEXT_VERSION_MAJOR` | Renamed as it applies to OpenGL ES as well | 494| `GLFW_OPENGL_VERSION_MINOR` | `GLFW_CONTEXT_VERSION_MINOR` | Renamed as it applies to OpenGL ES as well | 495| `GLFW_FSAA_SAMPLES` | `GLFW_SAMPLES` | Renamed to match the OpenGL API | 496| `GLFW_ACTIVE` | `GLFW_FOCUSED` | Renamed to match the window focus callback | 497| `GLFW_WINDOW_NO_RESIZE` | `GLFW_RESIZABLE` | The default has been inverted | 498| `GLFW_MOUSE_CURSOR` | `GLFW_CURSOR` | Used with @ref glfwSetInputMode | 499| `GLFW_KEY_ESC` | `GLFW_KEY_ESCAPE` | | 500| `GLFW_KEY_DEL` | `GLFW_KEY_DELETE` | | 501| `GLFW_KEY_PAGEUP` | `GLFW_KEY_PAGE_UP` | | 502| `GLFW_KEY_PAGEDOWN` | `GLFW_KEY_PAGE_DOWN` | | 503| `GLFW_KEY_KP_NUM_LOCK` | `GLFW_KEY_NUM_LOCK` | | 504| `GLFW_KEY_LCTRL` | `GLFW_KEY_LEFT_CONTROL` | | 505| `GLFW_KEY_LSHIFT` | `GLFW_KEY_LEFT_SHIFT` | | 506| `GLFW_KEY_LALT` | `GLFW_KEY_LEFT_ALT` | | 507| `GLFW_KEY_LSUPER` | `GLFW_KEY_LEFT_SUPER` | | 508| `GLFW_KEY_RCTRL` | `GLFW_KEY_RIGHT_CONTROL` | | 509| `GLFW_KEY_RSHIFT` | `GLFW_KEY_RIGHT_SHIFT` | | 510| `GLFW_KEY_RALT` | `GLFW_KEY_RIGHT_ALT` | | 511| `GLFW_KEY_RSUPER` | `GLFW_KEY_RIGHT_SUPER` | | 512 513*/ 514