+

+Monitor objects

+

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.

+

+Retrieving monitors

+

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.

+

GLFWmonitor* primary = glfwGetPrimaryMonitor();

+

GLFWmonitor

struct GLFWmonitor GLFWmonitor

Opaque monitor object.

Definition: glfw3.h:1173

+

glfwGetPrimaryMonitor

GLFWmonitor * glfwGetPrimaryMonitor(void)

Returns the primary monitor.

+

You can retrieve all currently connected monitors with glfwGetMonitors. See the reference documentation for the lifetime of the returned array.

+

int count;

+

GLFWmonitor** monitors = glfwGetMonitors(&count);

+

glfwGetMonitors

GLFWmonitor ** glfwGetMonitors(int *count)

Returns the currently connected monitors.

+

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.

+

+Monitor configuration changes

+

If you wish to be notified when a monitor is connected or disconnected, set a monitor callback.

+

glfwSetMonitorCallback(monitor_callback);

+

glfwSetMonitorCallback

GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun callback)

Sets the monitor configuration callback.

+

The callback function receives the handle for the monitor that has been connected or disconnected and the event that occurred.

+

void monitor_callback(GLFWmonitor* monitor, int event)

+{

+    if (event == GLFW_CONNECTED)

+    {

+        // The monitor was connected

+    }

+    else if (event == GLFW_DISCONNECTED)

+    {

+        // The monitor was disconnected

+    }

+}

+
+
+

If a monitor is disconnected, all windows that are full screen on it will be switched to windowed mode before the callback is called. Only glfwGetMonitorName and glfwGetMonitorUserPointer will return useful values for a disconnected monitor and only before the monitor callback returns.

+

+Monitor properties

+

Each monitor has a current video mode, a list of supported video modes, a virtual position, a content scale, a human-readable name, a user pointer, an estimated physical size and a gamma ramp.

+

+Video modes

+

GLFW generally does a good job selecting a suitable video mode when you create a full screen window, change its video mode or make a windowed one full screen, 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.

+

int count;

+

GLFWvidmode* modes = glfwGetVideoModes(monitor, &count);

+

glfwGetVideoModes

const GLFWvidmode * glfwGetVideoModes(GLFWmonitor *monitor, int *count)

Returns the available video modes for the specified monitor.

+

GLFWvidmode

Video mode type.

Definition: glfw3.h:1658

+

To get the current video mode of a monitor call glfwGetVideoMode. See the reference documentation for the lifetime of the returned pointer.

+

const GLFWvidmode* mode = glfwGetVideoMode(monitor);

+

glfwGetVideoMode

const GLFWvidmode * glfwGetVideoMode(GLFWmonitor *monitor)

Returns the current mode of the specified monitor.

+

The resolution of a video mode is specified in screen coordinates, not pixels.

+

+Physical size

+

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.

+

int width_mm, height_mm;

+

glfwGetMonitorPhysicalSize(monitor, &width_mm, &height_mm);

+

glfwGetMonitorPhysicalSize

void glfwGetMonitorPhysicalSize(GLFWmonitor *monitor, int *widthMM, int *heightMM)

Returns the physical size of the monitor.

+

While this can be used to calculate the raw DPI of a monitor, this is often not useful. Instead use the monitor content scale and window content scale to scale your content.

+

+Content scale

+

The content scale for a monitor can be retrieved with glfwGetMonitorContentScale.

+

float xscale, yscale;

+

glfwGetMonitorContentScale(monitor, &xscale, &yscale);

+

glfwGetMonitorContentScale

void glfwGetMonitorContentScale(GLFWmonitor *monitor, float *xscale, float *yscale)

Retrieves the content scale for the specified monitor.

+

The content scale is the ratio between the current DPI and the platform's default DPI. This is especially important for text and any UI elements. If the pixel dimensions of your UI scaled by this look appropriate on your machine then it should appear at a reasonable size on other machines regardless of their DPI and scaling settings. This relies on the system DPI and scaling settings being somewhat correct.

+

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.

+

+Virtual position

+

The position of the monitor on the virtual desktop, in screen coordinates, can be retrieved with glfwGetMonitorPos.

+

int xpos, ypos;

+

glfwGetMonitorPos(monitor, &xpos, &ypos);

+

glfwGetMonitorPos

void glfwGetMonitorPos(GLFWmonitor *monitor, int *xpos, int *ypos)

Returns the position of the monitor's viewport on the virtual screen.

+

+Work area

+

The area of a monitor not occupied by global task bars or menu bars is the work area. This is specified in screen coordinates and can be retrieved with glfwGetMonitorWorkarea.

+

int xpos, ypos, width, height;

+

glfwGetMonitorWorkarea(monitor, &xpos, &ypos, &width, &height);

+

glfwGetMonitorWorkarea

void glfwGetMonitorWorkarea(GLFWmonitor *monitor, int *xpos, int *ypos, int *width, int *height)

Retrieves the work area of the monitor.

+

+Human-readable name

+

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.

+

const char* name = glfwGetMonitorName(monitor);

+

glfwGetMonitorName

const char * glfwGetMonitorName(GLFWmonitor *monitor)

Returns the name of the specified monitor.

+

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.

+

+User pointer

+

Each monitor has a user pointer that can be set with glfwSetMonitorUserPointer and queried with glfwGetMonitorUserPointer. This can be used for any purpose you need and will not be modified by GLFW. The value will be kept until the monitor is disconnected or until the library is terminated.

+

The initial value of the pointer is NULL.

+

+Gamma ramp

+

The gamma ramp of a monitor can be set with glfwSetGammaRamp, which accepts a monitor handle and a pointer to a GLFWgammaramp structure.

+

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);

+
+
+
+
+
+
+

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.

+

It is recommended that your gamma ramp have the same size as the current gamma ramp for that monitor.

+

The current gamma ramp for a monitor is returned by glfwGetGammaRamp. See the reference documentation for the lifetime of the returned structure.

+

const GLFWgammaramp* ramp = glfwGetGammaRamp(monitor);

+

glfwGetGammaRamp

const GLFWgammaramp * glfwGetGammaRamp(GLFWmonitor *monitor)

Returns the current gamma ramp for the specified monitor.

+

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.

+

glfwSetGamma(monitor, 1.0);

+

glfwSetGamma

void glfwSetGamma(GLFWmonitor *monitor, float gamma)

Generates a gamma ramp and sets it for the specified monitor.

+

To experiment with gamma correction via the glfwSetGamma function, run the gamma test program.

+

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.

+

Table of Contents