glfw/docs/monitor.dox

/*!

@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

*/