mirror of
https://github.com/glfw/glfw.git
synced 2024-11-25 19:42:00 +00:00
157 lines
4.4 KiB
Plaintext
157 lines
4.4 KiB
Plaintext
/*!
|
|
|
|
@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
|
|
|
|
*/
|