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.

224 lines
11 KiB

5 years ago
  1. /*!
  2. @page compat_guide Standards conformance
  3. @tableofcontents
  4. This guide describes the various API extensions used by this version of GLFW.
  5. It lists what are essentially implementation details, but which are nonetheless
  6. vital knowledge for developers intending to deploy their applications on a wide
  7. range of machines.
  8. The information in this guide is not a part of GLFW API, but merely
  9. preconditions for some parts of the library to function on a given machine. Any
  10. part of this information may change in future versions of GLFW and that will not
  11. be considered a breaking API change.
  12. @section compat_x11 X11 extensions, protocols and IPC standards
  13. As GLFW uses Xlib directly, without any intervening toolkit
  14. library, it has sole responsibility for interacting well with the many and
  15. varied window managers in use on Unix-like systems. In order for applications
  16. and window managers to work well together, a number of standards and
  17. conventions have been developed that regulate behavior outside the scope of the
  18. X11 API; most importantly the
  19. [Inter-Client Communication Conventions Manual](http://www.tronche.com/gui/x/icccm/)
  20. (ICCCM) and
  21. [Extended Window Manager Hints](http://standards.freedesktop.org/wm-spec/wm-spec-latest.html)
  22. (EWMH) standards.
  23. GLFW uses the `_MOTIF_WM_HINTS` window property to support borderless windows.
  24. If the running window manager does not support this property, the
  25. `GLFW_DECORATED` hint will have no effect.
  26. GLFW uses the ICCCM `WM_DELETE_WINDOW` protocol to intercept the user
  27. attempting to close the GLFW window. If the running window manager does not
  28. support this protocol, the close callback will never be called.
  29. GLFW uses the EWMH `_NET_WM_PING` protocol, allowing the window manager notify
  30. the user when the application has stopped responding, i.e. when it has ceased to
  31. process events. If the running window manager does not support this protocol,
  32. the user will not be notified if the application locks up.
  33. GLFW uses the EWMH `_NET_WM_STATE_FULLSCREEN` window state to tell the window
  34. manager to make the GLFW window full screen. If the running window manager does
  35. not support this state, full screen windows may not work properly. GLFW has
  36. a fallback code path in case this state is unavailable, but every window manager
  37. behaves slightly differently in this regard.
  38. GLFW uses the EWMH `_NET_WM_BYPASS_COMPOSITOR` window property to tell a
  39. compositing window manager to un-redirect full screen GLFW windows. If the
  40. running window manager uses compositing but does not support this property then
  41. additional copying may be performed for each buffer swap of full screen windows.
  42. GLFW uses the
  43. [clipboard manager protocol](http://www.freedesktop.org/wiki/ClipboardManager/)
  44. to push a clipboard string (i.e. selection) owned by a GLFW window about to be
  45. destroyed to the clipboard manager. If there is no running clipboard manager,
  46. the clipboard string will be unavailable once the window has been destroyed.
  47. GLFW uses the
  48. [X drag-and-drop protocol](http://www.freedesktop.org/wiki/Specifications/XDND/)
  49. to provide file drop events. If the application originating the drag does not
  50. support this protocol, drag and drop will not work.
  51. GLFW uses the XRandR 1.3 extension to provide multi-monitor support. If the
  52. running X server does not support this version of this extension, multi-monitor
  53. support will not function and only a single, desktop-spanning monitor will be
  54. reported.
  55. GLFW uses the XRandR 1.3 and Xf86vidmode extensions to provide gamma ramp
  56. support. If the running X server does not support either or both of these
  57. extensions, gamma ramp support will not function.
  58. GLFW uses the Xkb extension and detectable auto-repeat to provide keyboard
  59. input. If the running X server does not support this extension, a non-Xkb
  60. fallback path is used.
  61. @section compat_glx GLX extensions
  62. The GLX API is the default API used to create OpenGL contexts on Unix-like
  63. systems using the X Window System.
  64. GLFW uses the GLX 1.3 `GLXFBConfig` functions to enumerate and select framebuffer pixel
  65. formats. If GLX 1.3 is not supported, @ref glfwInit will fail.
  66. GLFW uses the `GLX_MESA_swap_control,` `GLX_EXT_swap_control` and
  67. `GLX_SGI_swap_control` extensions to provide vertical retrace synchronization
  68. (or _vsync_), in that order of preference. Where none of these extension are
  69. available, calling @ref glfwSwapInterval will have no effect.
  70. GLFW uses the `GLX_ARB_multisample` extension to create contexts with
  71. multisampling anti-aliasing. Where this extension is unavailable, the
  72. `GLFW_SAMPLES` hint will have no effect.
  73. GLFW uses the `GLX_ARB_create_context` extension when available, even when
  74. creating OpenGL contexts of version 2.1 and below. Where this extension is
  75. unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
  76. hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
  77. will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
  78. `GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
  79. glfwCreateWindow to fail.
  80. GLFW uses the `GLX_ARB_create_context_profile` extension to provide support for
  81. context profiles. Where this extension is unavailable, setting the
  82. `GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE`, or setting
  83. `GLFW_CLIENT_API` to anything but `GLFW_OPENGL_API` or `GLFW_NO_API` will cause
  84. @ref glfwCreateWindow to fail.
  85. GLFW uses the `GLX_ARB_context_flush_control` extension to provide control over
  86. whether a context is flushed when it is released (made non-current). Where this
  87. extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
  88. effect and the context will always be flushed when released.
  89. GLFW uses the `GLX_ARB_framebuffer_sRGB` and `GLX_EXT_framebuffer_sRGB`
  90. extensions to provide support for sRGB framebuffers. Where both of these
  91. extensions are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
  92. @section compat_wgl WGL extensions
  93. The WGL API is used to create OpenGL contexts on Microsoft Windows and other
  94. implementations of the Win32 API, such as Wine.
  95. GLFW uses either the `WGL_EXT_extension_string` or the
  96. `WGL_ARB_extension_string` extension to check for the presence of all other WGL
  97. extensions listed below. If both are available, the EXT one is preferred. If
  98. neither is available, no other extensions are used and many GLFW features
  99. related to context creation will have no effect or cause errors when used.
  100. GLFW uses the `WGL_EXT_swap_control` extension to provide vertical retrace
  101. synchronization (or _vsync_). Where this extension is unavailable, calling @ref
  102. glfwSwapInterval will have no effect.
  103. GLFW uses the `WGL_ARB_pixel_format` and `WGL_ARB_multisample` extensions to
  104. create contexts with multisampling anti-aliasing. Where these extensions are
  105. unavailable, the `GLFW_SAMPLES` hint will have no effect.
  106. GLFW uses the `WGL_ARB_create_context` extension when available, even when
  107. creating OpenGL contexts of version 2.1 and below. Where this extension is
  108. unavailable, the `GLFW_CONTEXT_VERSION_MAJOR` and `GLFW_CONTEXT_VERSION_MINOR`
  109. hints will only be partially supported, the `GLFW_OPENGL_DEBUG_CONTEXT` hint
  110. will have no effect, and setting the `GLFW_OPENGL_PROFILE` or
  111. `GLFW_OPENGL_FORWARD_COMPAT` hints to `GLFW_TRUE` will cause @ref
  112. glfwCreateWindow to fail.
  113. GLFW uses the `WGL_ARB_create_context_profile` extension to provide support for
  114. context profiles. Where this extension is unavailable, setting the
  115. `GLFW_OPENGL_PROFILE` hint to anything but `GLFW_OPENGL_ANY_PROFILE` will cause
  116. @ref glfwCreateWindow to fail.
  117. GLFW uses the `WGL_ARB_context_flush_control` extension to provide control over
  118. whether a context is flushed when it is released (made non-current). Where this
  119. extension is unavailable, the `GLFW_CONTEXT_RELEASE_BEHAVIOR` hint will have no
  120. effect and the context will always be flushed when released.
  121. GLFW uses the `WGL_ARB_framebuffer_sRGB` and `WGL_EXT_framebuffer_sRGB`
  122. extensions to provide support for sRGB framebuffers. Where both of these
  123. extension are unavailable, the `GLFW_SRGB_CAPABLE` hint will have no effect.
  124. @section compat_osx OpenGL 3.2 and later on OS X
  125. Support for OpenGL 3.2 and above was introduced with OS X 10.7 and even then
  126. only forward-compatible, core profile contexts are supported. Support for
  127. OpenGL 4.1 was introduced with OS X 10.9, also limited to forward-compatible,
  128. core profile contexts. There is also still no mechanism for requesting debug
  129. contexts. Versions of Mac OS X earlier than 10.7 support at most OpenGL
  130. version 2.1.
  131. Because of this, on OS X 10.7 and later, the `GLFW_CONTEXT_VERSION_MAJOR` and
  132. `GLFW_CONTEXT_VERSION_MINOR` hints will cause @ref glfwCreateWindow to fail if
  133. given version 3.0 or 3.1, the `GLFW_OPENGL_FORWARD_COMPAT` hint must be set to
  134. `GLFW_TRUE` and the `GLFW_OPENGL_PROFILE` hint must be set to
  135. `GLFW_OPENGL_CORE_PROFILE` when creating OpenGL 3.2 and later contexts and the
  136. `GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
  137. Also, on Mac OS X 10.6 and below, the `GLFW_CONTEXT_VERSION_MAJOR` and
  138. `GLFW_CONTEXT_VERSION_MINOR` hints will fail if given a version above 2.1,
  139. setting the `GLFW_OPENGL_PROFILE` or `GLFW_OPENGL_FORWARD_COMPAT` hints to
  140. a non-default value will cause @ref glfwCreateWindow to fail and the
  141. `GLFW_OPENGL_DEBUG_CONTEXT` hint is ignored.
  142. @section compat_vulkan Vulkan loader and API
  143. GLFW uses the standard system-wide Vulkan loader to access the Vulkan API.
  144. This should be installed by graphics drivers and Vulkan SDKs. If this is not
  145. available, @ref glfwVulkanSupported will return `GLFW_FALSE` and all other
  146. Vulkan-related functions will fail with an @ref GLFW_API_UNAVAILABLE error.
  147. @section compat_wsi Vulkan WSI extensions
  148. The Vulkan WSI extensions are used to create Vulkan surfaces for GLFW windows on
  149. all supported platforms.
  150. GLFW uses the `VK_KHR_surface` and `VK_KHR_win32_surface` extensions to create
  151. surfaces on Microsoft Windows. If any of these extensions are not available,
  152. @ref glfwGetRequiredInstanceExtensions will return an empty list and window
  153. surface creation will fail.
  154. GLFW uses the `VK_KHR_surface` and either the `VK_KHR_xlib_surface` or
  155. `VK_KHR_xcb_surface` extensions to create surfaces on X11. If `VK_KHR_surface`
  156. or both `VK_KHR_xlib_surface` and `VK_KHR_xcb_surface` are not available, @ref
  157. glfwGetRequiredInstanceExtensions will return an empty list and window surface
  158. creation will fail.
  159. GLFW uses the `VK_KHR_surface` and `VK_KHR_wayland_surface` extensions to create
  160. surfaces on Wayland. If any of these extensions are not available, @ref
  161. glfwGetRequiredInstanceExtensions will return an empty list and window surface
  162. creation will fail.
  163. GLFW uses the `VK_KHR_surface` and `VK_KHR_mir_surface` extensions to create
  164. surfaces on Mir. If any of these extensions are not available, @ref
  165. glfwGetRequiredInstanceExtensions will return an empty list and window surface
  166. creation will fail.
  167. GLFW does not support any extensions for window surface creation on OS X,
  168. meaning@ref glfwGetRequiredInstanceExtensions will return an empty list and
  169. window surface creation will fail.
  170. */