This guide introduces the monitor related functions of GLFW. There are also guides for the other areas of GLFW.
A monitor object represents a currently connected monitor and is represented as a pointer to the opaque type 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.
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.
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.
To see how GLFW views your monitor setup and its available video modes, run the monitors
test program.
The primary monitor is returned by glfwGetPrimaryMonitor. It is the user's preferred monitor and is usually the one with global UI elements like task bar or menu bar.
You can retrieve all currently connected monitors with glfwGetMonitors. See the reference documentation for the lifetime of the returned array.
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.
If you wish to be notified when a monitor is connected or disconnected, set a monitor callback.
The callback function receives the handle for the monitor that has been connected or disconnected and a monitor action.
The action is one of GLFW_CONNECTED
or GLFW_DISCONNECTED
.
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.
GLFW generally does a good job selecting a suitable video mode when you create a full screen window, but it is sometimes useful to know exactly which video modes are supported.
Video modes are represented as GLFWvidmode structures. You can get an array of the video modes supported by a monitor with glfwGetVideoModes. See the reference documentation for the lifetime of the returned array.
To get the current video mode of a monitor call glfwGetVideoMode. See the reference documentation for the lifetime of the returned pointer.
The resolution of a video mode is specified in screen coordinates, not pixels.
The physical size of a monitor in millimetres, or an estimation of it, can be retrieved with glfwGetMonitorPhysicalSize. This has no relation to its current resolution, i.e. the width and height of its current video mode.
This can, for example, be used together with the current video mode to calculate the DPI of a monitor.
The position of the monitor on the virtual desktop, in screen coordinates, can be retrieved with glfwGetMonitorPos.
The human-readable, UTF-8 encoded name of a monitor is returned by glfwGetMonitorName. See the reference documentation for the lifetime of the returned string.
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.
The gamma ramp of a monitor can be set with glfwSetGammaRamp, which accepts a monitor handle and a pointer to a GLFWgammaramp structure.
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.
The current gamma ramp for a monitor is returned by glfwGetGammaRamp. See the reference documentation for the lifetime of the returned structure.
If you wish to set a regular gamma ramp, you can have GLFW calculate it for you from the desired exponent with glfwSetGamma, which in turn calls glfwSetGammaRamp with the resulting ramp.
Last update on Sun Nov 4 2018 for GLFW 3.1.2