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.

1008 lines
38 KiB

5 years ago
  1. /*!
  2. @page window_guide Window guide
  3. @tableofcontents
  4. This guide introduces the window related functions of GLFW. For details on
  5. a specific function in this category, see the @ref window. There are also
  6. guides for the other areas of GLFW.
  7. - @ref intro_guide
  8. - @ref context_guide
  9. - @ref vulkan_guide
  10. - @ref monitor_guide
  11. - @ref input_guide
  12. @section window_object Window objects
  13. The @ref GLFWwindow object encapsulates both a window and a context. They are
  14. created with @ref glfwCreateWindow and destroyed with @ref glfwDestroyWindow, or
  15. @ref glfwTerminate, if any remain. As the window and context are inseparably
  16. linked, the object pointer is used as both a context and window handle.
  17. To see the event stream provided to the various window related callbacks, run
  18. the `events` test program.
  19. @subsection window_creation Window creation
  20. A window and its OpenGL or OpenGL ES context are created with @ref
  21. glfwCreateWindow, which returns a handle to the created window object. For
  22. example, this creates a 640 by 480 windowed mode window:
  23. @code
  24. GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", NULL, NULL);
  25. @endcode
  26. If window creation fails, `NULL` will be returned, so it is necessary to check
  27. the return value.
  28. The window handle is passed to all window related functions and is provided to
  29. along with all input events, so event handlers can tell which window received
  30. the event.
  31. @subsubsection window_full_screen Full screen windows
  32. To create a full screen window, you need to specify which monitor the window
  33. should use. In most cases, the user's primary monitor is a good choice.
  34. For more information about retrieving monitors, see @ref monitor_monitors.
  35. @code
  36. GLFWwindow* window = glfwCreateWindow(640, 480, "My Title", glfwGetPrimaryMonitor(), NULL);
  37. @endcode
  38. Full screen windows cover the entire display area of a monitor, have no border
  39. or decorations.
  40. Windowed mode windows can be made full screen by setting a monitor with @ref
  41. glfwSetWindowMonitor, and full screen ones can be made windowed by unsetting it
  42. with the same function.
  43. Each field of the @ref GLFWvidmode structure corresponds to a function parameter
  44. or window hint and combine to form the _desired video mode_ for that window.
  45. The supported video mode most closely matching the desired video mode will be
  46. set for the chosen monitor as long as the window has input focus. For more
  47. information about retrieving video modes, see @ref monitor_modes.
  48. Video mode field | Corresponds to
  49. ----------------------- | ------------------------
  50. GLFWvidmode.width | `width` parameter
  51. GLFWvidmode.height | `height` parameter
  52. GLFWvidmode.redBits | `GLFW_RED_BITS` hint
  53. GLFWvidmode.greenBits | `GLFW_GREEN_BITS` hint
  54. GLFWvidmode.blueBits | `GLFW_BLUE_BITS` hint
  55. GLFWvidmode.refreshRate | `GLFW_REFRESH_RATE` hint
  56. Once you have a full screen window, you can change its resolution, refresh rate
  57. and monitor with @ref glfwSetWindowMonitor. If you just need change its
  58. resolution you can also call @ref glfwSetWindowSize. In all cases, the new
  59. video mode will be selected the same way as the video mode chosen by @ref
  60. glfwCreateWindow. If the window has an OpenGL or OpenGL ES context, it will be
  61. unaffected.
  62. By default, the original video mode of the monitor will be restored and the
  63. window iconified if it loses input focus, to allow the user to switch back to
  64. the desktop. This behavior can be disabled with the `GLFW_AUTO_ICONIFY` window
  65. hint, for example if you wish to simultaneously cover multiple windows with full
  66. screen windows.
  67. @subsubsection window_windowed_full_screen "Windowed full screen" windows
  68. If the closest match for the desired video mode is the current one, the video
  69. mode will not be changed, making window creation faster and application
  70. switching much smoother. This is sometimes called _windowed full screen_ or
  71. _borderless full screen_ window and counts as a full screen window. To create
  72. such a window, simply request the current video mode.
  73. @code
  74. const GLFWvidmode* mode = glfwGetVideoMode(monitor);
  75. glfwWindowHint(GLFW_RED_BITS, mode->redBits);
  76. glfwWindowHint(GLFW_GREEN_BITS, mode->greenBits);
  77. glfwWindowHint(GLFW_BLUE_BITS, mode->blueBits);
  78. glfwWindowHint(GLFW_REFRESH_RATE, mode->refreshRate);
  79. GLFWwindow* window = glfwCreateWindow(mode->width, mode->height, "My Title", monitor, NULL);
  80. @endcode
  81. This also works for windowed mode windows that are made full screen.
  82. @code
  83. const GLFWvidmode* mode = glfwGetVideoMode(monitor);
  84. glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
  85. @endcode
  86. Note that @ref glfwGetVideoMode returns the _current_ video mode of a monitor,
  87. so if you already have a full screen window on that monitor that you want to
  88. make windowed full screen, you need to have saved the desktop resolution before.
  89. @subsection window_destruction Window destruction
  90. When a window is no longer needed, destroy it with @ref glfwDestroyWindow.
  91. @code
  92. glfwDestroyWindow(window);
  93. @endcode
  94. Window destruction always succeeds. Before the actual destruction, all
  95. callbacks are removed so no further events will be delivered for the window.
  96. All windows remaining when @ref glfwTerminate is called are destroyed as well.
  97. When a full screen window is destroyed, the original video mode of its monitor
  98. is restored, but the gamma ramp is left untouched.
  99. @subsection window_hints Window creation hints
  100. There are a number of hints that can be set before the creation of a window and
  101. context. Some affect the window itself, others affect the framebuffer or
  102. context. These hints are set to their default values each time the library is
  103. initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
  104. and reset all at once to their defaults with @ref glfwDefaultWindowHints.
  105. Note that hints need to be set _before_ the creation of the window and context
  106. you wish to have the specified attributes.
  107. @subsubsection window_hints_hard Hard and soft constraints
  108. Some window hints are hard constraints. These must match the available
  109. capabilities _exactly_ for window and context creation to succeed. Hints
  110. that are not hard constraints are matched as closely as possible, but the
  111. resulting context and framebuffer may differ from what these hints requested.
  112. The following hints are always hard constraints:
  113. - `GLFW_STEREO`
  114. - `GLFW_DOUBLEBUFFER`
  115. - `GLFW_CLIENT_API`
  116. - `GLFW_CONTEXT_CREATION_API`
  117. The following additional hints are hard constraints when requesting an OpenGL
  118. context, but are ignored when requesting an OpenGL ES context:
  119. - `GLFW_OPENGL_FORWARD_COMPAT`
  120. - `GLFW_OPENGL_PROFILE`
  121. @subsubsection window_hints_wnd Window related hints
  122. `GLFW_RESIZABLE` specifies whether the windowed mode window will be resizable
  123. _by the user_. The window will still be resizable using the @ref
  124. glfwSetWindowSize function. This hint is ignored for full screen windows.
  125. `GLFW_VISIBLE` specifies whether the windowed mode window will be initially
  126. visible. This hint is ignored for full screen windows.
  127. `GLFW_DECORATED` specifies whether the windowed mode window will have window
  128. decorations such as a border, a close widget, etc. An undecorated window may
  129. still allow the user to generate close events on some platforms. This hint is
  130. ignored for full screen windows.
  131. `GLFW_FOCUSED` specifies whether the windowed mode window will be given input
  132. focus when created. This hint is ignored for full screen and initially hidden
  133. windows.
  134. `GLFW_AUTO_ICONIFY` specifies whether the full screen window will
  135. automatically iconify and restore the previous video mode on input focus loss.
  136. This hint is ignored for windowed mode windows.
  137. `GLFW_FLOATING` specifies whether the windowed mode window will be floating
  138. above other regular windows, also called topmost or always-on-top. This is
  139. intended primarily for debugging purposes and cannot be used to implement proper
  140. full screen windows. This hint is ignored for full screen windows.
  141. `GLFW_MAXIMIZED` specifies whether the windowed mode window will be maximized
  142. when created. This hint is ignored for full screen windows.
  143. @subsubsection window_hints_fb Framebuffer related hints
  144. `GLFW_RED_BITS`, `GLFW_GREEN_BITS`, `GLFW_BLUE_BITS`, `GLFW_ALPHA_BITS`,
  145. `GLFW_DEPTH_BITS` and `GLFW_STENCIL_BITS` specify the desired bit depths of the
  146. various components of the default framebuffer. `GLFW_DONT_CARE` means the
  147. application has no preference.
  148. `GLFW_ACCUM_RED_BITS`, `GLFW_ACCUM_GREEN_BITS`, `GLFW_ACCUM_BLUE_BITS` and
  149. `GLFW_ACCUM_ALPHA_BITS` specify the desired bit depths of the various components
  150. of the accumulation buffer. `GLFW_DONT_CARE` means the application has no
  151. preference.
  152. @par
  153. Accumulation buffers are a legacy OpenGL feature and should not be used in new
  154. code.
  155. `GLFW_AUX_BUFFERS` specifies the desired number of auxiliary buffers.
  156. `GLFW_DONT_CARE` means the application has no preference.
  157. @par
  158. Auxiliary buffers are a legacy OpenGL feature and should not be used in new
  159. code.
  160. `GLFW_STEREO` specifies whether to use stereoscopic rendering. This is a hard
  161. constraint.
  162. `GLFW_SAMPLES` specifies the desired number of samples to use for multisampling.
  163. Zero disables multisampling. `GLFW_DONT_CARE` means the application has no
  164. preference.
  165. `GLFW_SRGB_CAPABLE` specifies whether the framebuffer should be sRGB capable.
  166. If supported, a created OpenGL context will support the `GL_FRAMEBUFFER_SRGB`
  167. enable, also called `GL_FRAMEBUFFER_SRGB_EXT`) for controlling sRGB rendering
  168. and a created OpenGL ES context will always have sRGB rendering enabled.
  169. `GLFW_DOUBLEBUFFER` specifies whether the framebuffer should be double buffered.
  170. You nearly always want to use double buffering. This is a hard constraint.
  171. @subsubsection window_hints_mtr Monitor related hints
  172. `GLFW_REFRESH_RATE` specifies the desired refresh rate for full screen windows.
  173. If set to `GLFW_DONT_CARE`, the highest available refresh rate will be used.
  174. This hint is ignored for windowed mode windows.
  175. @subsubsection window_hints_ctx Context related hints
  176. `GLFW_CLIENT_API` specifies which client API to create the context for.
  177. Possible values are `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` and `GLFW_NO_API`.
  178. This is a hard constraint.
  179. `GLFW_CONTEXT_CREATION_API` specifies which context creation API to use to
  180. create the context. Possible values are `GLFW_NATIVE_CONTEXT_API` and
  181. `GLFW_EGL_CONTEXT_API`. This is a hard constraint. If no client API is
  182. requested, this hint is ignored.
  183. @par
  184. __OS X:__ The EGL API is not available on this platform and requests to use it
  185. will fail.
  186. @par
  187. __Wayland, Mir:__ The EGL API _is_ the native context creation API, so this hint
  188. will have no effect.
  189. @note An OpenGL extension loader library that assumes it knows which context
  190. creation API is used on a given platform may fail if you change this hint. This
  191. can be resolved by having it load via @ref glfwGetProcAddress, which always uses
  192. the selected API.
  193. @bug On some Linux systems, creating contexts via both the native and EGL APIs
  194. in a single process will cause the application to segfault. Stick to one API or
  195. the other on Linux for now.
  196. `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` specify the client
  197. API version that the created context must be compatible with. The exact
  198. behavior of these hints depend on the requested client API.
  199. @par
  200. __OpenGL:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
  201. not hard constraints, but creation will fail if the OpenGL version of the
  202. created context is less than the one requested. It is therefore perfectly safe
  203. to use the default of version 1.0 for legacy code and you will still get
  204. backwards-compatible contexts of version 3.0 and above when available.
  205. @par
  206. While there is no way to ask the driver for a context of the highest supported
  207. version, GLFW will attempt to provide this when you ask for a version 1.0
  208. context, which is the default for these hints.
  209. @par
  210. __OpenGL ES:__ `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR` are
  211. not hard constraints, but creation will fail if the OpenGL ES version of the
  212. created context is less than the one requested. Additionally, OpenGL ES 1.x
  213. cannot be returned if 2.0 or later was requested, and vice versa. This is
  214. because OpenGL ES 3.x is backward compatible with 2.0, but OpenGL ES 2.0 is not
  215. backward compatible with 1.x.
  216. `GLFW_OPENGL_FORWARD_COMPAT` specifies whether the OpenGL context should be
  217. forward-compatible, i.e. one where all functionality deprecated in the requested
  218. version of OpenGL is removed. This must only be used if the requested OpenGL
  219. version is 3.0 or above. If OpenGL ES is requested, this hint is ignored.
  220. @par
  221. Forward-compatibility is described in detail in the
  222. [OpenGL Reference Manual](https://www.opengl.org/registry/).
  223. `GLFW_OPENGL_DEBUG_CONTEXT` specifies whether to create a debug OpenGL context,
  224. which may have additional error and performance issue reporting functionality.
  225. If OpenGL ES is requested, this hint is ignored.
  226. `GLFW_OPENGL_PROFILE` specifies which OpenGL profile to create the context for.
  227. Possible values are one of `GLFW_OPENGL_CORE_PROFILE` or
  228. `GLFW_OPENGL_COMPAT_PROFILE`, or `GLFW_OPENGL_ANY_PROFILE` to not request
  229. a specific profile. If requesting an OpenGL version below 3.2,
  230. `GLFW_OPENGL_ANY_PROFILE` must be used. If OpenGL ES is requested,
  231. this hint is ignored.
  232. @par
  233. OpenGL profiles are described in detail in the
  234. [OpenGL Reference Manual](https://www.opengl.org/registry/).
  235. `GLFW_CONTEXT_ROBUSTNESS` specifies the robustness strategy to be used by the
  236. context. This can be one of `GLFW_NO_RESET_NOTIFICATION` or
  237. `GLFW_LOSE_CONTEXT_ON_RESET`, or `GLFW_NO_ROBUSTNESS` to not request
  238. a robustness strategy.
  239. `GLFW_CONTEXT_RELEASE_BEHAVIOR` specifies the release behavior to be
  240. used by the context. Possible values are one of `GLFW_ANY_RELEASE_BEHAVIOR`,
  241. `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`. If the
  242. behavior is `GLFW_ANY_RELEASE_BEHAVIOR`, the default behavior of the context
  243. creation API will be used. If the behavior is `GLFW_RELEASE_BEHAVIOR_FLUSH`,
  244. the pipeline will be flushed whenever the context is released from being the
  245. current one. If the behavior is `GLFW_RELEASE_BEHAVIOR_NONE`, the pipeline will
  246. not be flushed on release.
  247. @par
  248. Context release behaviors are described in detail by the
  249. [GL_KHR_context_flush_control](https://www.opengl.org/registry/specs/KHR/context_flush_control.txt)
  250. extension.
  251. `GLFW_CONTEXT_NO_ERROR` specifies whether errors should be generated by the
  252. context. If enabled, situations that would have generated errors instead cause
  253. undefined behavior.
  254. @par
  255. The no error mode for OpenGL and OpenGL ES is described in detail by the
  256. [GL_KHR_no_error](https://www.opengl.org/registry/specs/KHR/no_error.txt)
  257. extension.
  258. @note This hint is experimental in its current state. There are currently
  259. (October 2015) no corresponding WGL or GLX extensions. That makes this hint
  260. a [hard constraint](@ref window_hints_hard) for those backends, as creation will
  261. fail if unsupported context flags are requested. Once the extensions are
  262. available, they will be required and creation of `GL_KHR_no_error` contexts may
  263. fail on early drivers where this flag is supported without those extensions
  264. being listed.
  265. @subsubsection window_hints_values Supported and default values
  266. Window hint | Default value | Supported values
  267. ------------------------------- | --------------------------- | ----------------
  268. `GLFW_RESIZABLE` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
  269. `GLFW_VISIBLE` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
  270. `GLFW_DECORATED` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
  271. `GLFW_FOCUSED` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
  272. `GLFW_AUTO_ICONIFY` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
  273. `GLFW_FLOATING` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
  274. `GLFW_MAXIMIZED` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
  275. `GLFW_RED_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  276. `GLFW_GREEN_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  277. `GLFW_BLUE_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  278. `GLFW_ALPHA_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  279. `GLFW_DEPTH_BITS` | 24 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  280. `GLFW_STENCIL_BITS` | 8 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  281. `GLFW_ACCUM_RED_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  282. `GLFW_ACCUM_GREEN_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  283. `GLFW_ACCUM_BLUE_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  284. `GLFW_ACCUM_ALPHA_BITS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  285. `GLFW_AUX_BUFFERS` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  286. `GLFW_SAMPLES` | 0 | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  287. `GLFW_REFRESH_RATE` | `GLFW_DONT_CARE` | 0 to `INT_MAX` or `GLFW_DONT_CARE`
  288. `GLFW_STEREO` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
  289. `GLFW_SRGB_CAPABLE` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
  290. `GLFW_DOUBLEBUFFER` | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
  291. `GLFW_CLIENT_API` | `GLFW_OPENGL_API` | `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`
  292. `GLFW_CONTEXT_CREATION_API` | `GLFW_NATIVE_CONTEXT_API` | `GLFW_NATIVE_CONTEXT_API` or `GLFW_EGL_CONTEXT_API`
  293. `GLFW_CONTEXT_VERSION_MAJOR` | 1 | Any valid major version number of the chosen client API
  294. `GLFW_CONTEXT_VERSION_MINOR` | 0 | Any valid minor version number of the chosen client API
  295. `GLFW_CONTEXT_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS` | `GLFW_NO_ROBUSTNESS`, `GLFW_NO_RESET_NOTIFICATION` or `GLFW_LOSE_CONTEXT_ON_RESET`
  296. `GLFW_CONTEXT_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR` | `GLFW_ANY_RELEASE_BEHAVIOR`, `GLFW_RELEASE_BEHAVIOR_FLUSH` or `GLFW_RELEASE_BEHAVIOR_NONE`
  297. `GLFW_OPENGL_FORWARD_COMPAT` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
  298. `GLFW_OPENGL_DEBUG_CONTEXT` | `GLFW_FALSE` | `GLFW_TRUE` or `GLFW_FALSE`
  299. `GLFW_OPENGL_PROFILE` | `GLFW_OPENGL_ANY_PROFILE` | `GLFW_OPENGL_ANY_PROFILE`, `GLFW_OPENGL_COMPAT_PROFILE` or `GLFW_OPENGL_CORE_PROFILE`
  300. @section window_events Window event processing
  301. See @ref events.
  302. @section window_properties Window properties and events
  303. @subsection window_userptr User pointer
  304. Each window has a user pointer that can be set with @ref
  305. glfwSetWindowUserPointer and fetched with @ref glfwGetWindowUserPointer. This
  306. can be used for any purpose you need and will not be modified by GLFW throughout
  307. the life-time of the window.
  308. The initial value of the pointer is `NULL`.
  309. @subsection window_close Window closing and close flag
  310. When the user attempts to close the window, for example by clicking the close
  311. widget or using a key chord like Alt+F4, the _close flag_ of the window is set.
  312. The window is however not actually destroyed and, unless you watch for this
  313. state change, nothing further happens.
  314. The current state of the close flag is returned by @ref glfwWindowShouldClose
  315. and can be set or cleared directly with @ref glfwSetWindowShouldClose. A common
  316. pattern is to use the close flag as a main loop condition.
  317. @code
  318. while (!glfwWindowShouldClose(window))
  319. {
  320. render(window);
  321. glfwSwapBuffers(window);
  322. glfwPollEvents();
  323. }
  324. @endcode
  325. If you wish to be notified when the user attempts to close a window, set a close
  326. callback.
  327. @code
  328. glfwSetWindowCloseCallback(window, window_close_callback);
  329. @endcode
  330. The callback function is called directly _after_ the close flag has been set.
  331. It can be used for example to filter close requests and clear the close flag
  332. again unless certain conditions are met.
  333. @code
  334. void window_close_callback(GLFWwindow* window)
  335. {
  336. if (!time_to_close)
  337. glfwSetWindowShouldClose(window, GLFW_FALSE);
  338. }
  339. @endcode
  340. @subsection window_size Window size
  341. The size of a window can be changed with @ref glfwSetWindowSize. For windowed
  342. mode windows, this sets the size, in
  343. [screen coordinates](@ref coordinate_systems) of the _client area_ or _content
  344. area_ of the window. The window system may impose limits on window size.
  345. @code
  346. glfwSetWindowSize(window, 640, 480);
  347. @endcode
  348. For full screen windows, the specified size becomes the new resolution of the
  349. window's desired video mode. The video mode most closely matching the new
  350. desired video mode is set immediately. The window is resized to fit the
  351. resolution of the set video mode.
  352. If you wish to be notified when a window is resized, whether by the user or
  353. the system, set a size callback.
  354. @code
  355. glfwSetWindowSizeCallback(window, window_size_callback);
  356. @endcode
  357. The callback function receives the new size, in screen coordinates, of the
  358. client area of the window when it is resized.
  359. @code
  360. void window_size_callback(GLFWwindow* window, int width, int height)
  361. {
  362. }
  363. @endcode
  364. There is also @ref glfwGetWindowSize for directly retrieving the current size of
  365. a window.
  366. @code
  367. int width, height;
  368. glfwGetWindowSize(window, &width, &height);
  369. @endcode
  370. @note Do not pass the window size to `glViewport` or other pixel-based OpenGL
  371. calls. The window size is in screen coordinates, not pixels. Use the
  372. [framebuffer size](@ref window_fbsize), which is in pixels, for pixel-based
  373. calls.
  374. The above functions work with the size of the client area, but decorated windows
  375. typically have title bars and window frames around this rectangle. You can
  376. retrieve the extents of these with @ref glfwGetWindowFrameSize.
  377. @code
  378. int left, top, right, bottom;
  379. glfwGetWindowFrameSize(window, &left, &top, &right, &bottom);
  380. @endcode
  381. The returned values are the distances, in screen coordinates, from the edges of
  382. the client area to the corresponding edges of the full window. As they are
  383. distances and not coordinates, they are always zero or positive.
  384. @subsection window_fbsize Framebuffer size
  385. While the size of a window is measured in screen coordinates, OpenGL works with
  386. pixels. The size you pass into `glViewport`, for example, should be in pixels.
  387. On some machines screen coordinates and pixels are the same, but on others they
  388. will not be. There is a second set of functions to retrieve the size, in
  389. pixels, of the framebuffer of a window.
  390. If you wish to be notified when the framebuffer of a window is resized, whether
  391. by the user or the system, set a size callback.
  392. @code
  393. glfwSetFramebufferSizeCallback(window, framebuffer_size_callback);
  394. @endcode
  395. The callback function receives the new size of the framebuffer when it is
  396. resized, which can for example be used to update the OpenGL viewport.
  397. @code
  398. void framebuffer_size_callback(GLFWwindow* window, int width, int height)
  399. {
  400. glViewport(0, 0, width, height);
  401. }
  402. @endcode
  403. There is also @ref glfwGetFramebufferSize for directly retrieving the current
  404. size of the framebuffer of a window.
  405. @code
  406. int width, height;
  407. glfwGetFramebufferSize(window, &width, &height);
  408. glViewport(0, 0, width, height);
  409. @endcode
  410. The size of a framebuffer may change independently of the size of a window, for
  411. example if the window is dragged between a regular monitor and a high-DPI one.
  412. @subsection window_sizelimits Window size limits
  413. The minimum and maximum size of the client area of a windowed mode window can be
  414. enforced with @ref glfwSetWindowSizeLimits. The user may resize the window to
  415. any size and aspect ratio within the specified limits, unless the aspect ratio
  416. is also set.
  417. @code
  418. glfwSetWindowSizeLimits(window, 200, 200, 400, 400);
  419. @endcode
  420. To specify only a minimum size or only a maximum one, set the other pair to
  421. `GLFW_DONT_CARE`.
  422. @code
  423. glfwSetWindowSizeLimits(window, 640, 480, GLFW_DONT_CARE, GLFW_DONT_CARE);
  424. @endcode
  425. To disable size limits for a window, set them all to `GLFW_DONT_CARE`.
  426. The aspect ratio of the client area of a windowed mode window can be enforced
  427. with @ref glfwSetWindowAspectRatio. The user may resize the window freely
  428. unless size limits are also set, but the size will be constrained to maintain
  429. the aspect ratio.
  430. @code
  431. glfwSetWindowAspectRatio(window, 16, 9);
  432. @endcode
  433. The aspect ratio is specified as a numerator and denominator, corresponding to
  434. the width and height, respectively. If you want a window to maintain its
  435. current aspect ratio, simply use its current size as the ratio.
  436. @code
  437. int width, height;
  438. glfwGetWindowSize(window, &width, &height);
  439. glfwSetWindowAspectRatio(window, width, height);
  440. @endcode
  441. To disable the aspect ratio limit for a window, set both terms to
  442. `GLFW_DONT_CARE`.
  443. You can have both size limits and aspect ratio set for a window, but the results
  444. are undefined if they conflict.
  445. @subsection window_pos Window position
  446. The position of a windowed-mode window can be changed with @ref
  447. glfwSetWindowPos. This moves the window so that the upper-left corner of its
  448. client area has the specified [screen coordinates](@ref coordinate_systems).
  449. The window system may put limitations on window placement.
  450. @code
  451. glfwSetWindowPos(window, 100, 100);
  452. @endcode
  453. If you wish to be notified when a window is moved, whether by the user, system
  454. or your own code, set a position callback.
  455. @code
  456. glfwSetWindowPosCallback(window, window_pos_callback);
  457. @endcode
  458. The callback function receives the new position of the upper-left corner of the
  459. client area when the window is moved.
  460. @code
  461. void window_pos_callback(GLFWwindow* window, int xpos, int ypos)
  462. {
  463. }
  464. @endcode
  465. There is also @ref glfwGetWindowPos for directly retrieving the current position
  466. of the client area of the window.
  467. @code
  468. int xpos, ypos;
  469. glfwGetWindowPos(window, &xpos, &ypos);
  470. @endcode
  471. @subsection window_title Window title
  472. All GLFW windows have a title, although undecorated or full screen windows may
  473. not display it or only display it in a task bar or similar interface. You can
  474. set a UTF-8 encoded window title with @ref glfwSetWindowTitle.
  475. @code
  476. glfwSetWindowTitle(window, "My Window");
  477. @endcode
  478. The specified string is copied before the function returns, so there is no need
  479. to keep it around.
  480. As long as your source file is encoded as UTF-8, you can use any Unicode
  481. characters directly in the source.
  482. @code
  483. glfwSetWindowTitle(window, "カウボーイビバップ");
  484. @endcode
  485. If you are using C++11 or C11, you can use a UTF-8 string literal.
  486. @code
  487. glfwSetWindowTitle(window, u8"This is always a UTF-8 string");
  488. @endcode
  489. @subsection window_icon Window icon
  490. Decorated windows have icons on some platforms. You can set this icon by
  491. specifying a list of candidate images with @ref glfwSetWindowIcon.
  492. @code
  493. GLFWimage images[2];
  494. images[0] = load_icon("my_icon.png");
  495. images[1] = load_icon("my_icon_small.png");
  496. glfwSetWindowIcon(window, 2, images);
  497. @endcode
  498. To revert to the default window icon, pass in an empty image array.
  499. @code
  500. glfwSetWindowIcon(window, 0, NULL);
  501. @endcode
  502. @subsection window_monitor Window monitor
  503. Full screen windows are associated with a specific monitor. You can get the
  504. handle for this monitor with @ref glfwGetWindowMonitor.
  505. @code
  506. GLFWmonitor* monitor = glfwGetWindowMonitor(window);
  507. @endcode
  508. This monitor handle is one of those returned by @ref glfwGetMonitors.
  509. For windowed mode windows, this function returns `NULL`. This is how to tell
  510. full screen windows from windowed mode windows.
  511. You can move windows between monitors or between full screen and windowed mode
  512. with @ref glfwSetWindowMonitor. When making a window full screen on the same or
  513. on a different monitor, specify the desired monitor, resolution and refresh
  514. rate. The position arguments are ignored.
  515. @code
  516. const GLFWvidmode* mode = glfwGetVideoMode(monitor);
  517. glfwSetWindowMonitor(window, monitor, 0, 0, mode->width, mode->height, mode->refreshRate);
  518. @endcode
  519. When making the window windowed, specify the desired position and size. The
  520. refresh rate argument is ignored.
  521. @code
  522. glfwSetWindowMonitor(window, NULL, xpos, ypos, width, height, 0);
  523. @endcode
  524. This restores any previous window settings such as whether it is decorated,
  525. floating, resizable, has size or aspect ratio limits, etc.. To restore a window
  526. that was originally windowed to its original size and position, save these
  527. before making it full screen and then pass them in as above.
  528. @subsection window_iconify Window iconification
  529. Windows can be iconified (i.e. minimized) with @ref glfwIconifyWindow.
  530. @code
  531. glfwIconifyWindow(window);
  532. @endcode
  533. When a full screen window is iconified, the original video mode of its monitor
  534. is restored until the user or application restores the window.
  535. Iconified windows can be restored with @ref glfwRestoreWindow.
  536. @code
  537. glfwRestoreWindow(window);
  538. @endcode
  539. When a full screen window is restored, the desired video mode is restored to its
  540. monitor as well.
  541. If you wish to be notified when a window is iconified or restored, whether by
  542. the user, system or your own code, set a iconify callback.
  543. @code
  544. glfwSetWindowIconifyCallback(window, window_iconify_callback);
  545. @endcode
  546. The callback function receives changes in the iconification state of the window.
  547. @code
  548. void window_iconify_callback(GLFWwindow* window, int iconified)
  549. {
  550. if (iconified)
  551. {
  552. // The window was iconified
  553. }
  554. else
  555. {
  556. // The window was restored
  557. }
  558. }
  559. @endcode
  560. You can also get the current iconification state with @ref glfwGetWindowAttrib.
  561. @code
  562. int iconified = glfwGetWindowAttrib(window, GLFW_ICONIFIED);
  563. @endcode
  564. @subsection window_hide Window visibility
  565. Windowed mode windows can be hidden with @ref glfwHideWindow.
  566. @code
  567. glfwHideWindow(window);
  568. @endcode
  569. This makes the window completely invisible to the user, including removing it
  570. from the task bar, dock or window list. Full screen windows cannot be hidden
  571. and calling @ref glfwHideWindow on a full screen window does nothing.
  572. Hidden windows can be shown with @ref glfwShowWindow.
  573. @code
  574. glfwShowWindow(window);
  575. @endcode
  576. Windowed mode windows can be created initially hidden with the `GLFW_VISIBLE`
  577. [window hint](@ref window_hints_wnd). Windows created hidden are completely
  578. invisible to the user until shown. This can be useful if you need to set up
  579. your window further before showing it, for example moving it to a specific
  580. location.
  581. You can also get the current visibility state with @ref glfwGetWindowAttrib.
  582. @code
  583. int visible = glfwGetWindowAttrib(window, GLFW_VISIBLE);
  584. @endcode
  585. @subsection window_focus Window input focus
  586. Windows can be given input focus and brought to the front with @ref
  587. glfwFocusWindow.
  588. @code
  589. glfwFocusWindow(window);
  590. @endcode
  591. If you wish to be notified when a window gains or loses input focus, whether by
  592. the user, system or your own code, set a focus callback.
  593. @code
  594. glfwSetWindowFocusCallback(window, window_focus_callback);
  595. @endcode
  596. The callback function receives changes in the input focus state of the window.
  597. @code
  598. void window_focus_callback(GLFWwindow* window, int focused)
  599. {
  600. if (focused)
  601. {
  602. // The window gained input focus
  603. }
  604. else
  605. {
  606. // The window lost input focus
  607. }
  608. }
  609. @endcode
  610. You can also get the current input focus state with @ref glfwGetWindowAttrib.
  611. @code
  612. int focused = glfwGetWindowAttrib(window, GLFW_FOCUSED);
  613. @endcode
  614. @subsection window_refresh Window damage and refresh
  615. If you wish to be notified when the contents of a window is damaged and needs
  616. to be refreshed, set a window refresh callback.
  617. @code
  618. glfwSetWindowRefreshCallback(m_handle, window_refresh_callback);
  619. @endcode
  620. The callback function is called when the contents of the window needs to be
  621. refreshed.
  622. @code
  623. void window_refresh_callback(GLFWwindow* window)
  624. {
  625. draw_editor_ui(window);
  626. glfwSwapBuffers(window);
  627. }
  628. @endcode
  629. @note On compositing window systems such as Aero, Compiz or Aqua, where the
  630. window contents are saved off-screen, this callback might only be called when
  631. the window or framebuffer is resized.
  632. @subsection window_attribs Window attributes
  633. Windows have a number of attributes that can be returned using @ref
  634. glfwGetWindowAttrib. Some reflect state that may change during the lifetime of
  635. the window, while others reflect the corresponding hints and are fixed at the
  636. time of creation. Some are related to the actual window and others to its
  637. context.
  638. @code
  639. if (glfwGetWindowAttrib(window, GLFW_FOCUSED))
  640. {
  641. // window has input focus
  642. }
  643. @endcode
  644. @subsubsection window_attribs_wnd Window related attributes
  645. `GLFW_FOCUSED` indicates whether the specified window has input focus. Initial
  646. input focus is controlled by the [window hint](@ref window_hints_wnd) with the
  647. same name.
  648. `GLFW_ICONIFIED` indicates whether the specified window is iconified, whether by
  649. the user or with @ref glfwIconifyWindow.
  650. `GLFW_MAXIMIZED` indicates whether the specified window is maximized, whether by
  651. the user or with @ref glfwMaximizeWindow.
  652. `GLFW_VISIBLE` indicates whether the specified window is visible. Window
  653. visibility can be controlled with @ref glfwShowWindow and @ref glfwHideWindow
  654. and initial visibility is controlled by the [window hint](@ref window_hints_wnd)
  655. with the same name.
  656. `GLFW_RESIZABLE` indicates whether the specified window is resizable _by the
  657. user_. This is set on creation with the [window hint](@ref window_hints_wnd)
  658. with the same name.
  659. `GLFW_DECORATED` indicates whether the specified window has decorations such as
  660. a border, a close widget, etc. This is set on creation with the
  661. [window hint](@ref window_hints_wnd) with the same name.
  662. `GLFW_FLOATING` indicates whether the specified window is floating, also called
  663. topmost or always-on-top. This is controlled by the
  664. [window hint](@ref window_hints_wnd) with the same name.
  665. @subsubsection window_attribs_ctx Context related attributes
  666. `GLFW_CLIENT_API` indicates the client API provided by the window's context;
  667. either `GLFW_OPENGL_API`, `GLFW_OPENGL_ES_API` or `GLFW_NO_API`.
  668. `GLFW_CONTEXT_CREATION_API` indicates the context creation API used to create
  669. the window's context; either `GLFW_NATIVE_CONTEXT_API` or
  670. `GLFW_EGL_CONTEXT_API`.
  671. `GLFW_CONTEXT_VERSION_MAJOR`, `GLFW_CONTEXT_VERSION_MINOR` and
  672. `GLFW_CONTEXT_REVISION` indicate the client API version of the window's context.
  673. `GLFW_OPENGL_FORWARD_COMPAT` is `GLFW_TRUE` if the window's context is an OpenGL
  674. forward-compatible one, or `GLFW_FALSE` otherwise.
  675. `GLFW_OPENGL_DEBUG_CONTEXT` is `GLFW_TRUE` if the window's context is an OpenGL
  676. debug context, or `GLFW_FALSE` otherwise.
  677. `GLFW_OPENGL_PROFILE` indicates the OpenGL profile used by the context. This is
  678. `GLFW_OPENGL_CORE_PROFILE` or `GLFW_OPENGL_COMPAT_PROFILE` if the context uses
  679. a known profile, or `GLFW_OPENGL_ANY_PROFILE` if the OpenGL profile is unknown
  680. or the context is an OpenGL ES context. Note that the returned profile may not
  681. match the profile bits of the context flags, as GLFW will try other means of
  682. detecting the profile when no bits are set.
  683. `GLFW_CONTEXT_ROBUSTNESS` indicates the robustness strategy used by the context.
  684. This is `GLFW_LOSE_CONTEXT_ON_RESET` or `GLFW_NO_RESET_NOTIFICATION` if the
  685. window's context supports robustness, or `GLFW_NO_ROBUSTNESS` otherwise.
  686. @subsubsection window_attribs_fb Framebuffer related attributes
  687. GLFW does not expose attributes of the default framebuffer (i.e. the framebuffer
  688. attached to the window) as these can be queried directly with either OpenGL,
  689. OpenGL ES or Vulkan.
  690. If you are using version 3.0 or later of OpenGL or OpenGL ES, the
  691. `glGetFramebufferAttachmentParameteriv` function can be used to retrieve the
  692. number of bits for the red, green, blue, alpha, depth and stencil buffer
  693. channels. Otherwise, the `glGetIntegerv` function can be used.
  694. The number of MSAA samples are always retrieved with `glGetIntegerv`. For
  695. contexts supporting framebuffer objects, the number of samples of the currently
  696. bound framebuffer is returned.
  697. Attribute | glGetIntegerv | glGetFramebufferAttachmentParameteriv
  698. ------------ | ----------------- | -------------------------------------
  699. Red bits | `GL_RED_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_RED_SIZE`
  700. Green bits | `GL_GREEN_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_GREEN_SIZE`
  701. Blue bits | `GL_BLUE_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_BLUE_SIZE`
  702. Alpha bits | `GL_ALPHA_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_ALPHA_SIZE`
  703. Depth bits | `GL_DEPTH_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_DEPTH_SIZE`
  704. Stencil bits | `GL_STENCIL_BITS` | `GL_FRAMEBUFFER_ATTACHMENT_STENCIL_SIZE`
  705. MSAA samples | `GL_SAMPLES` | _Not provided by this function_
  706. When calling `glGetFramebufferAttachmentParameteriv`, the red, green, blue and
  707. alpha sizes are queried from the `GL_BACK_LEFT`, while the depth and stencil
  708. sizes are queried from the `GL_DEPTH` and `GL_STENCIL` attachments,
  709. respectively.
  710. @section buffer_swap Buffer swapping
  711. GLFW windows are by default double buffered. That means that you have two
  712. rendering buffers; a front buffer and a back buffer. The front buffer is
  713. the one being displayed and the back buffer the one you render to.
  714. When the entire frame has been rendered, it is time to swap the back and the
  715. front buffers in order to display what has been rendered and begin rendering
  716. a new frame. This is done with @ref glfwSwapBuffers.
  717. @code
  718. glfwSwapBuffers(window);
  719. @endcode
  720. Sometimes it can be useful to select when the buffer swap will occur. With the
  721. function @ref glfwSwapInterval it is possible to select the minimum number of
  722. monitor refreshes the driver wait should from the time @ref glfwSwapBuffers was
  723. called before swapping the buffers:
  724. @code
  725. glfwSwapInterval(1);
  726. @endcode
  727. If the interval is zero, the swap will take place immediately when @ref
  728. glfwSwapBuffers is called without waiting for a refresh. Otherwise at least
  729. interval retraces will pass between each buffer swap. Using a swap interval of
  730. zero can be useful for benchmarking purposes, when it is not desirable to
  731. measure the time it takes to wait for the vertical retrace. However, a swap
  732. interval of one lets you avoid tearing.
  733. Note that this may not work on all machines, as some drivers have
  734. user-controlled settings that override any swap interval the application
  735. requests.
  736. */