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.

216 lines
6.2 KiB

5 years ago
  1. /*!
  2. @page monitor_guide Monitor guide
  3. @tableofcontents
  4. This guide introduces the monitor related functions of GLFW. For details on
  5. a specific function in this category, see the @ref monitor. There are also
  6. guides for the other areas of GLFW.
  7. - @ref intro_guide
  8. - @ref window_guide
  9. - @ref context_guide
  10. - @ref vulkan_guide
  11. - @ref input_guide
  12. @section monitor_object Monitor objects
  13. A monitor object represents a currently connected monitor and is represented as
  14. a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type
  15. @ref GLFWmonitor. Monitor objects cannot be created or destroyed by the
  16. application and retain their addresses until the monitors they represent are
  17. disconnected or until the library is [terminated](@ref intro_init_terminate).
  18. Each monitor has a current video mode, a list of supported video modes,
  19. a virtual position, a human-readable name, an estimated physical size and
  20. a gamma ramp. One of the monitors is the primary monitor.
  21. The virtual position of a monitor is in
  22. [screen coordinates](@ref coordinate_systems) and, together with the current
  23. video mode, describes the viewports that the connected monitors provide into the
  24. virtual desktop that spans them.
  25. To see how GLFW views your monitor setup and its available video modes, run the
  26. `monitors` test program.
  27. @subsection monitor_monitors Retrieving monitors
  28. The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's
  29. preferred monitor and is usually the one with global UI elements like task bar
  30. or menu bar.
  31. @code
  32. GLFWmonitor* primary = glfwGetPrimaryMonitor();
  33. @endcode
  34. You can retrieve all currently connected monitors with @ref glfwGetMonitors.
  35. See the reference documentation for the lifetime of the returned array.
  36. @code
  37. int count;
  38. GLFWmonitor** monitors = glfwGetMonitors(&count);
  39. @endcode
  40. The primary monitor is always the first monitor in the returned array, but other
  41. monitors may be moved to a different index when a monitor is connected or
  42. disconnected.
  43. @subsection monitor_event Monitor configuration changes
  44. If you wish to be notified when a monitor is connected or disconnected, set
  45. a monitor callback.
  46. @code
  47. glfwSetMonitorCallback(monitor_callback);
  48. @endcode
  49. The callback function receives the handle for the monitor that has been
  50. connected or disconnected and the event that occurred.
  51. @code
  52. void monitor_callback(GLFWmonitor* monitor, int event)
  53. {
  54. if (event == GLFW_CONNECTED)
  55. {
  56. // The monitor was connected
  57. }
  58. else if (event == GLFW_DISCONNECTED)
  59. {
  60. // The monitor was disconnected
  61. }
  62. }
  63. @endcode
  64. If a monitor is disconnected, any windows that are full screen on it get forced
  65. into windowed mode.
  66. @section monitor_properties Monitor properties
  67. Each monitor has a current video mode, a list of supported video modes,
  68. a virtual position, a human-readable name, an estimated physical size and
  69. a gamma ramp.
  70. @subsection monitor_modes Video modes
  71. GLFW generally does a good job selecting a suitable video mode when you create
  72. a full screen window, change its video mode or or make a windowed one full
  73. screen, but it is sometimes useful to know exactly which video modes are
  74. supported.
  75. Video modes are represented as @ref GLFWvidmode structures. You can get an
  76. array of the video modes supported by a monitor with @ref glfwGetVideoModes.
  77. See the reference documentation for the lifetime of the returned array.
  78. @code
  79. int count;
  80. GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
  81. @endcode
  82. To get the current video mode of a monitor call @ref glfwGetVideoMode. See the
  83. reference documentation for the lifetime of the returned pointer.
  84. @code
  85. const GLFWvidmode* mode = glfwGetVideoMode(monitor);
  86. @endcode
  87. The resolution of a video mode is specified in
  88. [screen coordinates](@ref coordinate_systems), not pixels.
  89. @subsection monitor_size Physical size
  90. The physical size of a monitor in millimetres, or an estimation of it, can be
  91. retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its
  92. current _resolution_, i.e. the width and height of its current
  93. [video mode](@ref monitor_modes).
  94. @code
  95. int widthMM, heightMM;
  96. glfwGetMonitorPhysicalSize(monitor, &widthMM, &heightMM);
  97. @endcode
  98. This can, for example, be used together with the current video mode to calculate
  99. the DPI of a monitor.
  100. @code
  101. const double dpi = mode->width / (widthMM / 25.4);
  102. @endcode
  103. @subsection monitor_pos Virtual position
  104. The position of the monitor on the virtual desktop, in
  105. [screen coordinates](@ref coordinate_systems), can be retrieved with @ref
  106. glfwGetMonitorPos.
  107. @code
  108. int xpos, ypos;
  109. glfwGetMonitorPos(monitor, &xpos, &ypos);
  110. @endcode
  111. @subsection monitor_name Human-readable name
  112. The human-readable, UTF-8 encoded name of a monitor is returned by @ref
  113. glfwGetMonitorName. See the reference documentation for the lifetime of the
  114. returned string.
  115. @code
  116. const char* name = glfwGetMonitorName(monitor);
  117. @endcode
  118. Monitor names are not guaranteed to be unique. Two monitors of the same model
  119. and make may have the same name. Only the monitor handle is guaranteed to be
  120. unique, and only until that monitor is disconnected.
  121. @subsection monitor_gamma Gamma ramp
  122. The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts
  123. a monitor handle and a pointer to a @ref GLFWgammaramp structure.
  124. @code
  125. GLFWgammaramp ramp;
  126. unsigned short red[256], green[256], blue[256];
  127. ramp.size = 256;
  128. ramp.red = red;
  129. ramp.green = green;
  130. ramp.blue = blue;
  131. for (i = 0; i < ramp.size; i++)
  132. {
  133. // Fill out gamma ramp arrays as desired
  134. }
  135. glfwSetGammaRamp(monitor, &ramp);
  136. @endcode
  137. The gamma ramp data is copied before the function returns, so there is no need
  138. to keep it around once the ramp has been set.
  139. @note It is recommended to use gamma ramps of size 256, as that is the size
  140. supported by all graphics cards on all platforms.
  141. The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. See
  142. the reference documentation for the lifetime of the returned structure.
  143. @code
  144. const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);
  145. @endcode
  146. If you wish to set a regular gamma ramp, you can have GLFW calculate it for you
  147. from the desired exponent with @ref glfwSetGamma, which in turn calls @ref
  148. glfwSetGammaRamp with the resulting ramp.
  149. @code
  150. glfwSetGamma(monitor, 1.0);
  151. @endcode
  152. */