glfw/docs/monitor.dox

242 lines
7.2 KiB
Plaintext
Raw Permalink Normal View History

2013-05-27 15:10:34 +00:00
/*!
@page monitor_guide Monitor guide
2013-05-27 15:10:34 +00:00
2013-05-27 19:58:33 +00:00
@tableofcontents
This guide introduces the monitor related functions of GLFW. For details on
2016-08-11 17:04:21 +00:00
a specific function in this category, see the @ref monitor. There are also
guides for the other areas of GLFW.
2014-09-18 13:03:29 +00:00
- @ref intro_guide
- @ref window_guide
- @ref context_guide
2016-08-11 17:04:21 +00:00
- @ref vulkan_guide
- @ref input_guide
2014-09-18 13:03:29 +00:00
2013-05-27 19:58:33 +00:00
2015-01-18 00:55:25 +00:00
@section monitor_object Monitor objects
2013-05-27 15:10:34 +00:00
2014-04-23 11:30:11 +00:00
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).
2013-05-27 19:58:33 +00:00
2014-10-02 15:35:10 +00:00
Each monitor has a current video mode, a list of supported video modes,
a virtual position, a human-readable name, an estimated physical size and
a gamma ramp. One of the monitors is the primary monitor.
2013-07-07 10:06:59 +00:00
2014-10-07 21:37:59 +00:00
The virtual position of a monitor is in
[screen coordinates](@ref coordinate_systems) and, together with the current
video mode, describes the viewports that the connected monitors provide into the
virtual desktop that spans them.
2013-07-07 10:06:59 +00:00
2015-01-11 17:25:54 +00:00
To see how GLFW views your monitor setup and its available video modes, run the
2015-01-25 22:37:29 +00:00
`monitors` test program.
2015-01-11 17:25:54 +00:00
2014-04-23 11:30:11 +00:00
@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
2014-10-02 15:35:10 +00:00
or menu bar.
2013-05-27 19:58:33 +00:00
@code
GLFWmonitor* primary = glfwGetPrimaryMonitor();
@endcode
You can retrieve all currently connected monitors with @ref glfwGetMonitors.
2014-09-18 13:03:29 +00:00
See the reference documentation for the lifetime of the returned array.
2013-05-27 19:58:33 +00:00
@code
int count;
GLFWmonitor** monitors = glfwGetMonitors(&count);
@endcode
2014-09-18 13:03:29 +00:00
The primary monitor is always the first monitor in the returned array, but other
monitors may be moved to a different index when a monitor is connected or
disconnected.
@subsection monitor_event Monitor configuration changes
If you wish to be notified when a monitor is connected or disconnected, set
2014-10-02 15:35:10 +00:00
a monitor callback.
2014-09-18 13:03:29 +00:00
@code
glfwSetMonitorCallback(monitor_callback);
@endcode
The callback function receives the handle for the monitor that has been
connected or disconnected and the event that occurred.
2014-09-18 13:03:29 +00:00
@code
void monitor_callback(GLFWmonitor* monitor, int event)
{
if (event == GLFW_CONNECTED)
{
// The monitor was connected
}
else if (event == GLFW_DISCONNECTED)
{
// The monitor was disconnected
}
2014-09-18 13:03:29 +00:00
}
@endcode
2017-11-01 20:32:50 +00:00
If a monitor is disconnected, all windows that are full screen on it will be
switched to windowed mode.
2016-06-01 10:10:55 +00:00
2014-04-23 11:30:11 +00:00
@section monitor_properties Monitor properties
2013-05-27 15:10:34 +00:00
2014-10-02 15:35:10 +00:00
Each monitor has a current video mode, a list of supported video modes,
a virtual position, a human-readable name, an estimated physical size and
a gamma ramp.
2014-04-23 11:30:11 +00:00
@subsection monitor_modes Video modes
2013-05-27 15:10:34 +00:00
2014-10-07 21:37:59 +00:00
GLFW generally does a good job selecting a suitable video mode when you create
a full screen window, change its video mode or or make a windowed one full
screen, but it is sometimes useful to know exactly which video modes are
supported.
2014-09-18 13:03:29 +00:00
2014-10-07 21:37:59 +00:00
Video modes are represented as @ref GLFWvidmode structures. You can get an
array of the video modes supported by a monitor with @ref glfwGetVideoModes.
See the reference documentation for the lifetime of the returned array.
2013-05-27 15:10:34 +00:00
@code
int count;
GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);
@endcode
2014-09-18 13:03:29 +00:00
To get the current video mode of a monitor call @ref glfwGetVideoMode. See the
2014-10-07 21:37:59 +00:00
reference documentation for the lifetime of the returned pointer.
2013-05-27 15:10:34 +00:00
@code
const GLFWvidmode* mode = glfwGetVideoMode(monitor);
@endcode
2014-10-07 21:37:59 +00:00
The resolution of a video mode is specified in
[screen coordinates](@ref coordinate_systems), not pixels.
2013-05-27 15:10:34 +00:00
2014-04-23 11:30:11 +00:00
@subsection monitor_size Physical size
2013-05-27 19:58:33 +00:00
2014-10-07 21:37:59 +00:00
The physical size of a monitor in millimetres, or an estimation of it, can be
2014-10-06 21:18:33 +00:00
retrieved with @ref glfwGetMonitorPhysicalSize. This has no relation to its
current _resolution_, i.e. the width and height of its current
[video mode](@ref monitor_modes).
2013-05-27 19:58:33 +00:00
@code
int width_mm, height_mm;
glfwGetMonitorPhysicalSize(monitor, &width_mm, &height_mm);
2013-05-27 19:58:33 +00:00
@endcode
While this can be used to calculate the raw DPI of a monitor, this is often not
useful. Instead use the [monitor content scale](@ref monitor_scale) and
[window content scale](@ref window_scale) to scale your content.
@subsection monitor_scale Content scale
The content scale for a monitor can be retrieved with @ref
glfwGetMonitorContentScale.
2013-06-17 10:56:36 +00:00
@code
float xscale, yscale;
glfwGetMonitorContentScale(monitor, &xscale, &yscale);
2013-06-17 10:56:36 +00:00
@endcode
The content scale is the ratio between the current DPI and the platform's
default DPI. If you scale all pixel dimensions by this scale then your content
should appear at an appropriate size. This is especially important for text and
any UI elements.
The content scale may depend on both the monitor resolution and pixel density
and on user settings. It may be very different from the raw DPI calculated from
the physical size and current resolution.
2013-05-27 19:58:33 +00:00
2014-04-23 11:30:11 +00:00
@subsection monitor_pos Virtual position
2013-05-27 19:58:33 +00:00
2014-10-07 21:37:59 +00:00
The position of the monitor on the virtual desktop, in
[screen coordinates](@ref coordinate_systems), can be retrieved with @ref
glfwGetMonitorPos.
2014-04-23 11:30:11 +00:00
@code
int xpos, ypos;
glfwGetMonitorPos(monitor, &xpos, &ypos);
@endcode
@subsection monitor_name Human-readable name
2014-09-18 13:03:29 +00:00
The human-readable, UTF-8 encoded name of a monitor is returned by @ref
glfwGetMonitorName. See the reference documentation for the lifetime of the
returned string.
2013-05-27 19:58:33 +00:00
@code
const char* name = glfwGetMonitorName(monitor);
@endcode
2014-09-18 13:03:29 +00:00
Monitor names are not guaranteed to be unique. Two monitors of the same model
and make may have the same name. Only the monitor handle is guaranteed to be
unique, and only until that monitor is disconnected.
2013-05-27 19:58:33 +00:00
2014-04-23 11:30:11 +00:00
@subsection monitor_gamma Gamma ramp
2013-05-27 19:58:33 +00:00
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
2014-04-23 11:30:11 +00:00
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
}
2013-05-27 19:58:33 +00:00
glfwSetGammaRamp(monitor, &ramp);
@endcode
2014-04-23 11:30:11 +00:00
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.
2017-04-06 00:02:16 +00:00
It is recommended that your gamma ramp have the same size as the current gamma
ramp for that monitor.
2014-04-23 11:30:11 +00:00
2014-09-18 13:03:29 +00:00
The current gamma ramp for a monitor is returned by @ref glfwGetGammaRamp. See
the reference documentation for the lifetime of the returned structure.
2013-05-27 19:58:33 +00:00
@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
2013-05-27 15:10:34 +00:00
To experiment with gamma correction via the @ref glfwSetGamma function, run the
`gamma` test program.
2016-12-06 00:14:23 +00:00
@note The software controlled gamma ramp is applied _in addition_ to the
hardware gamma correction, which today is usually an approximation of sRGB
gamma. This means that setting a perfectly linear ramp, or gamma 1.0, will
produce the default (usually sRGB-like) behavior.
2013-05-27 15:10:34 +00:00
*/