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