Platformer in OpenGL
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

506 lines
20 KiB

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