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.

364 lines
12 KiB

5 years ago
  1. /*!
  2. @page quick_guide Getting started
  3. @tableofcontents
  4. This guide takes you through writing a simple application using GLFW 3. The
  5. application will create a window and OpenGL context, render a rotating triangle
  6. and exit when the user closes the window or presses _Escape_. This guide will
  7. introduce a few of the most commonly used functions, but there are many more.
  8. This guide assumes no experience with earlier versions of GLFW. If you
  9. have used GLFW 2 in the past, read @ref moving_guide, as some functions
  10. behave differently in GLFW 3.
  11. @section quick_steps Step by step
  12. @subsection quick_include Including the GLFW header
  13. In the source files of your application where you use OpenGL or GLFW, you need
  14. to include the GLFW 3 header file.
  15. @code
  16. #include <GLFW/glfw3.h>
  17. @endcode
  18. This defines all the constants, types and function prototypes of the GLFW API.
  19. It also includes the OpenGL header from your development environment and
  20. defines all the constants and types necessary for it to work on your platform
  21. without including any platform-specific headers.
  22. In other words:
  23. - Do _not_ include the OpenGL header yourself, as GLFW does this for you in
  24. a platform-independent way
  25. - Do _not_ include `windows.h` or other platform-specific headers unless
  26. you plan on using those APIs yourself
  27. - If you _do_ need to include such headers, include them _before_ the GLFW
  28. header and it will detect this
  29. On some platforms supported by GLFW the OpenGL header and link library only
  30. expose older versions of OpenGL. The most extreme case is Windows, which only
  31. exposes OpenGL 1.2. The easiest way to work around this is to use an
  32. [extension loader library](@ref context_glext_auto).
  33. If you are using such a library then you should include its header _before_ the
  34. GLFW header. This lets it replace the OpenGL header included by GLFW without
  35. conflicts. This example uses
  36. [glad](https://github.com/Dav1dde/glad), but the same rule applies to all such
  37. libraries.
  38. @code
  39. #include <glad/glad.h>
  40. #include <GLFW/glfw3.h>
  41. @endcode
  42. @subsection quick_init_term Initializing and terminating GLFW
  43. Before you can use most GLFW functions, the library must be initialized. On
  44. successful initialization, `GLFW_TRUE` is returned. If an error occurred,
  45. `GLFW_FALSE` is returned.
  46. @code
  47. if (!glfwInit())
  48. {
  49. // Initialization failed
  50. }
  51. @endcode
  52. Note that `GLFW_TRUE` and `GLFW_FALSE` are and will always be just one and zero.
  53. When you are done using GLFW, typically just before the application exits, you
  54. need to terminate GLFW.
  55. @code
  56. glfwTerminate();
  57. @endcode
  58. This destroys any remaining windows and releases any other resources allocated by
  59. GLFW. After this call, you must initialize GLFW again before using any GLFW
  60. functions that require it.
  61. @subsection quick_capture_error Setting an error callback
  62. Most events are reported through callbacks, whether it's a key being pressed,
  63. a GLFW window being moved, or an error occurring. Callbacks are simply
  64. C functions (or C++ static methods) that are called by GLFW with arguments
  65. describing the event.
  66. In case a GLFW function fails, an error is reported to the GLFW error callback.
  67. You can receive these reports with an error callback. This function must have
  68. the signature below. This simple error callback just prints the error
  69. description to `stderr`.
  70. @code
  71. void error_callback(int error, const char* description)
  72. {
  73. fprintf(stderr, "Error: %s\n", description);
  74. }
  75. @endcode
  76. Callback functions must be set, so GLFW knows to call them. The function to set
  77. the error callback is one of the few GLFW functions that may be called before
  78. initialization, which lets you be notified of errors both during and after
  79. initialization.
  80. @code
  81. glfwSetErrorCallback(error_callback);
  82. @endcode
  83. @subsection quick_create_window Creating a window and context
  84. The window and its OpenGL context are created with a single call to @ref
  85. glfwCreateWindow, which returns a handle to the created combined window and
  86. context object
  87. @code
  88. GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
  89. if (!window)
  90. {
  91. // Window or OpenGL context creation failed
  92. }
  93. @endcode
  94. This creates a 640 by 480 windowed mode window with an OpenGL context. If
  95. window or OpenGL context creation fails, `NULL` will be returned. You should
  96. always check the return value. While window creation rarely fails, context
  97. creation depends on properly installed drivers and may fail even on machines
  98. with the necessary hardware.
  99. By default, the OpenGL context GLFW creates may have any version. You can
  100. require a minimum OpenGL version by setting the `GLFW_CONTEXT_VERSION_MAJOR` and
  101. `GLFW_CONTEXT_VERSION_MINOR` hints _before_ creation. If the required minimum
  102. version is not supported on the machine, context (and window) creation fails.
  103. @code
  104. glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 2);
  105. glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 0);
  106. GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
  107. if (!window)
  108. {
  109. // Window or context creation failed
  110. }
  111. @endcode
  112. The window handle is passed to all window related functions and is provided to
  113. along to all window related callbacks, so they can tell which window received
  114. the event.
  115. When a window and context is no longer needed, destroy it.
  116. @code
  117. glfwDestroyWindow(window);
  118. @endcode
  119. Once this function is called, no more events will be delivered for that window
  120. and its handle becomes invalid.
  121. @subsection quick_context_current Making the OpenGL context current
  122. Before you can use the OpenGL API, you must have a current OpenGL context.
  123. @code
  124. glfwMakeContextCurrent(window);
  125. @endcode
  126. The context will remain current until you make another context current or until
  127. the window owning the current context is destroyed.
  128. If you are using an [extension loader library](@ref context_glext_auto) to
  129. access modern OpenGL then this is when to initialize it, as the loader needs
  130. a current context to load from. This example uses
  131. [glad](https://github.com/Dav1dde/glad), but the same rule applies to all such
  132. libraries.
  133. @code
  134. gladLoadGLLoader((GLADloadproc) glfwGetProcAddress);
  135. @endcode
  136. @subsection quick_window_close Checking the window close flag
  137. Each window has a flag indicating whether the window should be closed.
  138. When the user attempts to close the window, either by pressing the close widget
  139. in the title bar or using a key combination like Alt+F4, this flag is set to 1.
  140. Note that __the window isn't actually closed__, so you are expected to monitor
  141. this flag and either destroy the window or give some kind of feedback to the
  142. user.
  143. @code
  144. while (!glfwWindowShouldClose(window))
  145. {
  146. // Keep running
  147. }
  148. @endcode
  149. You can be notified when the user is attempting to close the window by setting
  150. a close callback with @ref glfwSetWindowCloseCallback. The callback will be
  151. called immediately after the close flag has been set.
  152. You can also set it yourself with @ref glfwSetWindowShouldClose. This can be
  153. useful if you want to interpret other kinds of input as closing the window, like
  154. for example pressing the _Escape_ key.
  155. @subsection quick_key_input Receiving input events
  156. Each window has a large number of callbacks that can be set to receive all the
  157. various kinds of events. To receive key press and release events, create a key
  158. callback function.
  159. @code
  160. static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
  161. {
  162. if (key == GLFW_KEY_ESCAPE && action == GLFW_PRESS)
  163. glfwSetWindowShouldClose(window, GLFW_TRUE);
  164. }
  165. @endcode
  166. The key callback, like other window related callbacks, are set per-window.
  167. @code
  168. glfwSetKeyCallback(window, key_callback);
  169. @endcode
  170. In order for event callbacks to be called when events occur, you need to process
  171. events as described below.
  172. @subsection quick_render Rendering with OpenGL
  173. Once you have a current OpenGL context, you can use OpenGL normally. In this
  174. tutorial, a multi-colored rotating triangle will be rendered. The framebuffer
  175. size needs to be retrieved for `glViewport`.
  176. @code
  177. int width, height;
  178. glfwGetFramebufferSize(window, &width, &height);
  179. glViewport(0, 0, width, height);
  180. @endcode
  181. You can also set a framebuffer size callback using @ref
  182. glfwSetFramebufferSizeCallback and be notified when the size changes.
  183. Actual rendering with OpenGL is outside the scope of this tutorial, but there
  184. are [many](https://open.gl/) [excellent](http://learnopengl.com/)
  185. [tutorial](http://openglbook.com/) [sites](http://ogldev.atspace.co.uk/) that
  186. teach modern OpenGL. Some of them use GLFW to create the context and window
  187. while others use GLUT or SDL, but remember that OpenGL itself always works the
  188. same.
  189. @subsection quick_timer Reading the timer
  190. To create smooth animation, a time source is needed. GLFW provides a timer that
  191. returns the number of seconds since initialization. The time source used is the
  192. most accurate on each platform and generally has micro- or nanosecond
  193. resolution.
  194. @code
  195. double time = glfwGetTime();
  196. @endcode
  197. @subsection quick_swap_buffers Swapping buffers
  198. GLFW windows by default use double buffering. That means that each window has
  199. two rendering buffers; a front buffer and a back buffer. The front buffer is
  200. the one being displayed and the back buffer the one you render to.
  201. When the entire frame has been rendered, the buffers need to be swapped with one
  202. another, so the back buffer becomes the front buffer and vice versa.
  203. @code
  204. glfwSwapBuffers(window);
  205. @endcode
  206. The swap interval indicates how many frames to wait until swapping the buffers,
  207. commonly known as _vsync_. By default, the swap interval is zero, meaning
  208. buffer swapping will occur immediately. On fast machines, many of those frames
  209. will never be seen, as the screen is still only updated typically 60-75 times
  210. per second, so this wastes a lot of CPU and GPU cycles.
  211. Also, because the buffers will be swapped in the middle the screen update,
  212. leading to [screen tearing](https://en.wikipedia.org/wiki/Screen_tearing).
  213. For these reasons, applications will typically want to set the swap interval to
  214. one. It can be set to higher values, but this is usually not recommended,
  215. because of the input latency it leads to.
  216. @code
  217. glfwSwapInterval(1);
  218. @endcode
  219. This function acts on the current context and will fail unless a context is
  220. current.
  221. @subsection quick_process_events Processing events
  222. GLFW needs to communicate regularly with the window system both in order to
  223. receive events and to show that the application hasn't locked up. Event
  224. processing must be done regularly while you have visible windows and is normally
  225. done each frame after buffer swapping.
  226. There are two methods for processing pending events; polling and waiting. This
  227. example will use event polling, which processes only those events that have
  228. already been received and then returns immediately.
  229. @code
  230. glfwPollEvents();
  231. @endcode
  232. This is the best choice when rendering continually, like most games do. If
  233. instead you only need to update your rendering once you have received new input,
  234. @ref glfwWaitEvents is a better choice. It waits until at least one event has
  235. been received, putting the thread to sleep in the meantime, and then processes
  236. all received events. This saves a great deal of CPU cycles and is useful for,
  237. for example, many kinds of editing tools.
  238. @section quick_example Putting it together
  239. Now that you know how to initialize GLFW, create a window and poll for
  240. keyboard input, it's possible to create a simple program.
  241. This program creates a 640 by 480 windowed mode window and starts a loop that
  242. clears the screen, renders a triangle and processes events until the user either
  243. presses _Escape_ or closes the window.
  244. @snippet simple.c code
  245. The program above can be found in the
  246. [source package](http://www.glfw.org/download.html) as `examples/simple.c`
  247. and is compiled along with all other examples when you build GLFW. If you
  248. built GLFW from the source package then already have this as `simple.exe` on
  249. Windows, `simple` on Linux or `simple.app` on OS X.
  250. This tutorial used only a few of the many functions GLFW provides. There are
  251. guides for each of the areas covered by GLFW. Each guide will introduce all the
  252. functions for that category.
  253. - @ref intro_guide
  254. - @ref window_guide
  255. - @ref context_guide
  256. - @ref monitor_guide
  257. - @ref input_guide
  258. You can access reference documentation for any GLFW function by clicking it and
  259. the reference for each function links to related functions and guide sections.
  260. The tutorial ends here. Once you have written a program that uses GLFW, you
  261. will need to compile and link it. How to do that depends on the development
  262. environment you are using and is best explained by the documentation for that
  263. environment. To learn about the details that are specific to GLFW, see
  264. @ref build_guide.
  265. */