You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and dots ('.'), can be up to 35 characters long. Letters must be lowercase.
156 lines
4.4 KiB
156 lines
4.4 KiB
/*! |
|
|
|
@page monitor Multi-monitor guide |
|
|
|
@tableofcontents |
|
|
|
|
|
@section monitor_objects Monitor objects |
|
|
|
A monitor object represents a currently connected monitor and is represented as |
|
a pointer to the [opaque](https://en.wikipedia.org/wiki/Opaque_data_type) type |
|
@ref GLFWmonitor. Monitor objects cannot be created or destroyed by the |
|
application and retain their addresses until the monitors they represent are |
|
disconnected or until the library is [terminated](@ref intro_init_terminate). |
|
|
|
Each monitor has a human-readable name, a current video mode, a list of |
|
supported video modes, a virtual position, an estimated physical size and |
|
a gamma ramp. |
|
|
|
The virtual position of a monitor is in screen coordinates and, together with |
|
the current video mode, describes the viewports that the connected monitors |
|
provide into the virtual desktop that spans them. |
|
|
|
|
|
@subsection monitor_monitors Retrieving monitors |
|
|
|
The primary monitor is returned by @ref glfwGetPrimaryMonitor. It is the user's |
|
preferred monitor and is usually the one with global UI elements like task bar |
|
or menu bar. |
|
|
|
@code |
|
GLFWmonitor* primary = glfwGetPrimaryMonitor(); |
|
@endcode |
|
|
|
You can retrieve all currently connected monitors with @ref glfwGetMonitors. |
|
The primary monitor is always the first monitor in the returned array. |
|
|
|
@code |
|
int count; |
|
GLFWmonitor** monitors = glfwGetMonitors(&count); |
|
@endcode |
|
|
|
@note Monitors other than the primary monitor may be moved to a different index |
|
in the array if another monitor is disconnected. |
|
|
|
|
|
@section monitor_properties Monitor properties |
|
|
|
@subsection monitor_modes Video modes |
|
|
|
Although GLFW generally does a good job at selecting a suitable video |
|
mode for you when you open a full screen window, it is sometimes useful to |
|
know exactly which modes are available on a certain system. For example, |
|
you may want to present the user with a list of video modes to select |
|
from. To get a list of available video modes, you can use the function |
|
@ref glfwGetVideoModes. |
|
|
|
@code |
|
int count; |
|
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count); |
|
@endcode |
|
|
|
To get the current video mode of a monitor call @ref glfwGetVideoMode. |
|
|
|
@code |
|
const GLFWvidmode* mode = glfwGetVideoMode(monitor); |
|
@endcode |
|
|
|
|
|
@subsection monitor_size Physical size |
|
|
|
The physical size in millimetres of a monitor, or an estimation of it, can be |
|
retrieved with @ref glfwGetMonitorPhysicalSize. |
|
|
|
@code |
|
int widthMM, heightMM; |
|
glfwGetMonitorPhysicalSize(monitor, &widthMM, &heightMM); |
|
@endcode |
|
|
|
This can, for example, be used together with the current video mode to calculate |
|
the DPI of a monitor. |
|
|
|
@code |
|
const double dpi = mode->width / (widthMM / 25.4); |
|
@endcode |
|
|
|
|
|
@subsection monitor_pos Virtual position |
|
|
|
The position of the monitor on the virtual desktop, in screen coordinates, can |
|
be retrieved with @ref glfwGetMonitorPos. |
|
|
|
@code |
|
int xpos, ypos; |
|
glfwGetMonitorPos(monitor, &xpos, &ypos); |
|
@endcode |
|
|
|
|
|
@subsection monitor_name Human-readable name |
|
|
|
The human-readable name of a monitor is returned by @ref glfwGetMonitorName. |
|
It is a regular C string using the UTF-8 encoding. |
|
|
|
@code |
|
const char* name = glfwGetMonitorName(monitor); |
|
@endcode |
|
|
|
@note Monitor names are not guaranteed to be unique. Two monitors of the same |
|
model and make may have the same name. Only the address of a monitor object is |
|
guaranteed to be unique. |
|
|
|
|
|
@subsection monitor_gamma Gamma ramp |
|
|
|
The gamma ramp of a monitor can be set with @ref glfwSetGammaRamp, which accepts |
|
a monitor handle and a pointer to a @ref GLFWgammaramp structure. |
|
|
|
@code |
|
GLFWgammaramp ramp; |
|
unsigned short red[256], green[256], blue[256]; |
|
|
|
ramp.size = 256; |
|
ramp.red = red; |
|
ramp.green = green; |
|
ramp.blue = blue; |
|
|
|
for (i = 0; i < ramp.size; i++) |
|
{ |
|
// Fill out gamma ramp arrays as desired |
|
} |
|
|
|
glfwSetGammaRamp(monitor, &ramp); |
|
@endcode |
|
|
|
The gamma ramp data is copied before the function returns, so there is no need |
|
to keep it around once the ramp has been set. |
|
|
|
@note It is recommended to use gamma ramps of size 256, as that is the size |
|
supported by virtually all graphics cards on all platforms. |
|
|
|
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. The |
|
returned structure and its arrays are allocated and freed by GLFW. |
|
|
|
@code |
|
const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor); |
|
@endcode |
|
|
|
If you wish to set a regular gamma ramp, you can have GLFW calculate it for you |
|
from the desired exponent with @ref glfwSetGamma, which in turn calls @ref |
|
glfwSetGammaRamp with the resulting ramp. |
|
|
|
@code |
|
glfwSetGamma(monitor, 1.0); |
|
@endcode |
|
|
|
*/
|
|
|