Monitor reference

## Description

This is the reference documentation for monitor related functions and types. For more task-oriented information, see the Monitor guide.

## Typedefs

typedef struct GLFWmonitor | GLFWmonitor
| Opaque monitor object. More...
typedef void(* | GLFWmonitorfun) (GLFWmonitor *, int)
| The function pointer type for monitor configuration callbacks. More...
typedef struct GLFWvidmode | GLFWvidmode
| Video mode type. More...
typedef struct GLFWgammaramp | GLFWgammaramp
| Gamma ramp. More...

## Functions

GLFWmonitor ** | glfwGetMonitors (int *count)
| Returns the currently connected monitors. More...
GLFWmonitor * | glfwGetPrimaryMonitor (void)
| Returns the primary monitor. More...
void | glfwGetMonitorPos (GLFWmonitor *monitor, int *xpos, int *ypos)
| Returns the position of the monitor's viewport on the virtual screen. More...
void | glfwGetMonitorWorkarea (GLFWmonitor *monitor, int *xpos, int *ypos, int *width, int *height)
| Retrieves the work area of the monitor. More...
void | glfwGetMonitorPhysicalSize (GLFWmonitor *monitor, int *widthMM, int *heightMM)
| Returns the physical size of the monitor. More...
void | glfwGetMonitorContentScale (GLFWmonitor *monitor, float *xscale, float *yscale)
| Retrieves the content scale for the specified monitor. More...
const char * | glfwGetMonitorName (GLFWmonitor *monitor)
| Returns the name of the specified monitor. More...
void | glfwSetMonitorUserPointer (GLFWmonitor *monitor, void *pointer)
| Sets the user pointer of the specified monitor. More...
void * | glfwGetMonitorUserPointer (GLFWmonitor *monitor)
| Returns the user pointer of the specified monitor. More...
GLFWmonitorfun | glfwSetMonitorCallback (GLFWmonitorfun callback)
| Sets the monitor configuration callback. More...
const GLFWvidmode * | glfwGetVideoModes (GLFWmonitor *monitor, int *count)
| Returns the available video modes for the specified monitor. More...
const GLFWvidmode * | glfwGetVideoMode (GLFWmonitor *monitor)
| Returns the current mode of the specified monitor. More...
void | glfwSetGamma (GLFWmonitor *monitor, float gamma)
| Generates a gamma ramp and sets it for the specified monitor. More...
const GLFWgammaramp * | glfwGetGammaRamp (GLFWmonitor *monitor)
| Returns the current gamma ramp for the specified monitor. More...
void | glfwSetGammaRamp (GLFWmonitor *monitor, const GLFWgammaramp *ramp)
| Sets the current gamma ramp for the specified monitor. More...

## Typedef Documentation

## GLFWmonitor

typedef struct GLFWmonitor GLFWmonitor

Opaque monitor object.

See also
  Monitor objects

Since
  Added in version 3.0.

## GLFWmonitorfun

typedef void(* GLFWmonitorfun) (GLFWmonitor *, int)

This is the function pointer type for monitor configuration callbacks. A monitor callback function has the following signature:

void function_name(GLFWmonitor* monitor, int event)

Parameters

  [in] | monitor | The monitor that was connected or disconnected.
  [in] | event | One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future releases may add more events.

See also
  Monitor configuration changes
  glfwSetMonitorCallback

Since
  Added in version 3.0.

## GLFWvidmode

typedef struct GLFWvidmode GLFWvidmode

This describes a single video mode.

See also
  Video modes
  glfwGetVideoMode
  glfwGetVideoModes

Since
  Added in version 1.0. GLFW 3: Added refresh rate member.

## GLFWgammaramp

typedef struct GLFWgammaramp GLFWgammaramp

This describes the gamma ramp for a monitor.

See also
  Gamma ramp
  glfwGetGammaRamp
  glfwSetGammaRamp

Since
  Added in version 3.0.

## Function Documentation

## glfwGetMonitors()

GLFWmonitor** glfwGetMonitors | ( | int * | count | ) |

This function returns an array of handles for all currently connected monitors. The primary monitor is always first in the returned array. If no monitors were found, this function returns `NULL`.

Parameters

  [out] | count | Where to store the number of monitors in the returned array. This is set to zero if an error occurred.

Returns
  An array of monitor handles, or `NULL` if no monitors were found or if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Pointer lifetime
  The returned array is allocated and freed by GLFW. You should not free it yourself. It is guaranteed to be valid only until the monitor configuration changes or the library is terminated.

Thread safety
  This function must only be called from the main thread.

See also
  Retrieving monitors
  Monitor configuration changes
  glfwGetPrimaryMonitor

Since
  Added in version 3.0.

## glfwGetPrimaryMonitor()

GLFWmonitor* glfwGetPrimaryMonitor | ( | void |  | ) |

This function returns the primary monitor. This is usually the monitor where elements like the task bar or global menu bar are located.

Returns
  The primary monitor, or `NULL` if no monitors were found or if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function must only be called from the main thread.

Remarks
  The primary monitor is always first in the array returned by glfwGetMonitors.

See also
  Retrieving monitors
  glfwGetMonitors

Since
  Added in version 3.0.

## glfwGetMonitorPos()

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

This function returns the position, in screen coordinates, of the upper-left corner of the specified monitor.

Any or all of the position arguments may be `NULL`. If an error occurs, all non-`NULL` position arguments will be set to zero.

Parameters

  [in] | monitor | The monitor to query.
  [out] | xpos | Where to store the monitor x-coordinate, or `NULL`.
  [out] | ypos | Where to store the monitor y-coordinate, or `NULL`.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Thread safety
  This function must only be called from the main thread.

See also
  Monitor properties

Since
  Added in version 3.0.

## glfwGetMonitorWorkarea()

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

This function returns the position, in screen coordinates, of the upper-left corner of the work area of the specified monitor along with the work area size in screen coordinates. The work area is defined as the area of the monitor not occluded by the operating system task bar where present. If no task bar exists then the work area is the monitor resolution in screen coordinates.

Any or all of the position and size arguments may be `NULL`. If an error occurs, all non-`NULL` position and size arguments will be set to zero.

Parameters

  [in] | monitor | The monitor to query.
  [out] | xpos | Where to store the monitor x-coordinate, or `NULL`.
  [out] | ypos | Where to store the monitor y-coordinate, or `NULL`.
  [out] | width | Where to store the monitor width, or `NULL`.
  [out] | height | Where to store the monitor height, or `NULL`.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Thread safety
  This function must only be called from the main thread.

See also
  Work area

Since
  Added in version 3.3.

## glfwGetMonitorPhysicalSize()

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

This function returns the size, in millimetres, of the display area of the specified monitor.

Some systems do not provide accurate monitor size information, either because the monitor EDID data is incorrect or because the driver does not report it accurately.

Any or all of the size arguments may be `NULL`. If an error occurs, all non-`NULL` size arguments will be set to zero.

Parameters

  [in] | monitor | The monitor to query.
  [out] | widthMM | Where to store the width, in millimetres, of the monitor's display area, or `NULL`.
  [out] | heightMM | Where to store the height, in millimetres, of the monitor's display area, or `NULL`.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Remarks
  Windows: calculates the returned physical size from the current resolution and system DPI instead of querying the monitor EDID data.

Thread safety
  This function must only be called from the main thread.

See also
  Monitor properties

Since
  Added in version 3.0.

## glfwGetMonitorContentScale()

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

This function 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.

Parameters

  [in] | monitor | The monitor to query.
  [out] | xscale | Where to store the x-axis content scale, or `NULL`.
  [out] | yscale | Where to store the y-axis content scale, or `NULL`.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Thread safety
  This function must only be called from the main thread.

See also
  Content scale
  glfwGetWindowContentScale

Since
  Added in version 3.3.

## glfwGetMonitorName()

const char* glfwGetMonitorName | ( | GLFWmonitor * | monitor | ) |

This function returns a human-readable name, encoded as UTF-8, of the specified monitor. The name typically reflects the make and model of the monitor and is not guaranteed to be unique among the connected monitors.

Parameters

  [in] | monitor | The monitor to query.

Returns
  The UTF-8 encoded name of the monitor, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Pointer lifetime
  The returned string is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified monitor is disconnected or the library is terminated.

Thread safety
  This function must only be called from the main thread.

See also
  Monitor properties

Since
  Added in version 3.0.

## glfwSetMonitorUserPointer()

void glfwSetMonitorUserPointer | ( | GLFWmonitor * | monitor,
|  | void * | pointer
| ) |  |

This function sets the user-defined pointer of the specified monitor. The current value is retained until the monitor is disconnected. The initial value is `NULL`.

This function may be called from the monitor callback, even for a monitor that is being disconnected.

Parameters

  [in] | monitor | The monitor whose pointer to set.
  [in] | pointer | The new value.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

See also
  User pointer
  glfwGetMonitorUserPointer

Since
  Added in version 3.3.

## glfwGetMonitorUserPointer()

void* glfwGetMonitorUserPointer | ( | GLFWmonitor * | monitor | ) |

This function returns the current value of the user-defined pointer of the specified monitor. The initial value is `NULL`.

This function may be called from the monitor callback, even for a monitor that is being disconnected.

Parameters

  [in] | monitor | The monitor whose pointer to return.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function may be called from any thread. Access is not synchronized.

See also
  User pointer
  glfwSetMonitorUserPointer

Since
  Added in version 3.3.

## glfwSetMonitorCallback()

GLFWmonitorfun glfwSetMonitorCallback | ( | GLFWmonitorfun | callback | ) |

This function sets the monitor configuration callback, or removes the currently set callback. This is called when a monitor is connected to or disconnected from the system.

Parameters

  [in] | callback | The new callback, or `NULL` to remove the currently set callback.

Returns
  The previously set callback, or `NULL` if no callback was set or the library had not been initialized.

Callback signature
  void function_name(GLFWmonitor* monitor, int event)
  For more information about the callback parameters, see the function pointer type.

Errors
  Possible errors include GLFW_NOT_INITIALIZED.

Thread safety
  This function must only be called from the main thread.

See also
  Monitor configuration changes

Since
  Added in version 3.0.

## glfwGetVideoModes()

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

This function returns an array of all video modes supported by the specified monitor. The returned array is sorted in ascending order, first by color bit depth (the sum of all channel depths) and then by resolution area (the product of width and height).

Parameters

  [in] | monitor | The monitor to query.
  [out] | count | Where to store the number of video modes in the returned array. This is set to zero if an error occurred.

Returns
  An array of video modes, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime
  The returned array is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified monitor is disconnected, this function is called again for that monitor or the library is terminated.

Thread safety
  This function must only be called from the main thread.

See also
  Video modes
  glfwGetVideoMode

Since
  Added in version 1.0. GLFW 3: Changed to return an array of modes for a specific monitor.

## glfwGetVideoMode()

const GLFWvidmode* glfwGetVideoMode | ( | GLFWmonitor * | monitor | ) |

This function returns the current video mode of the specified monitor. If you have created a full screen window for that monitor, the return value will depend on whether that window is iconified.

Parameters

  [in] | monitor | The monitor to query.

Returns
  The current mode of the monitor, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime
  The returned array is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified monitor is disconnected or the library is terminated.

Thread safety
  This function must only be called from the main thread.

See also
  Video modes
  glfwGetVideoModes

Since
  Added in version 3.0. Replaces `glfwGetDesktopMode`.

## glfwSetGamma()

void glfwSetGamma | ( | GLFWmonitor * | monitor,
|  | float | gamma
| ) |  |

This function generates an appropriately sized gamma ramp from the specified exponent and then calls glfwSetGammaRamp with it. The value must be a finite number greater than zero.

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.

For gamma correct rendering with OpenGL or OpenGL ES, see the GLFW_SRGB_CAPABLE hint.

Parameters

  [in] | monitor | The monitor whose gamma ramp to set.
  [in] | gamma | The desired exponent.

Errors
  Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_VALUE and GLFW_PLATFORM_ERROR.

Remarks
  Wayland: Gamma handling is a privileged protocol, this function will thus never be implemented and emits GLFW_PLATFORM_ERROR.

Thread safety
  This function must only be called from the main thread.

See also
  Gamma ramp

Since
  Added in version 3.0.

## glfwGetGammaRamp()

const GLFWgammaramp* glfwGetGammaRamp | ( | GLFWmonitor * | monitor | ) |

This function returns the current gamma ramp of the specified monitor.

Parameters

  [in] | monitor | The monitor to query.

Returns
  The current gamma ramp, or `NULL` if an error occurred.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Remarks
  Wayland: Gamma handling is a privileged protocol, this function will thus never be implemented and emits GLFW_PLATFORM_ERROR while returning `NULL`.

Pointer lifetime
  The returned structure and its arrays are allocated and freed by GLFW. You should not free them yourself. They are valid until the specified monitor is disconnected, this function is called again for that monitor or the library is terminated.

Thread safety
  This function must only be called from the main thread.

See also
  Gamma ramp

Since
  Added in version 3.0.

## glfwSetGammaRamp()

void glfwSetGammaRamp | ( | GLFWmonitor * | monitor,
|  | const GLFWgammaramp * | ramp
| ) |  |

This function sets the current gamma ramp for the specified monitor. The original gamma ramp for that monitor is saved by GLFW the first time this function is called and is restored by glfwTerminate.

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.

For gamma correct rendering with OpenGL or OpenGL ES, see the GLFW_SRGB_CAPABLE hint.

Parameters

  [in] | monitor | The monitor whose gamma ramp to set.
  [in] | ramp | The gamma ramp to use.

Errors
  Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Remarks
  The size of the specified gamma ramp should match the size of the current ramp for that monitor.
  Windows: The gamma ramp size must be 256.
  Wayland: Gamma handling is a privileged protocol, this function will thus never be implemented and emits GLFW_PLATFORM_ERROR.

Pointer lifetime
  The specified gamma ramp is copied before this function returns.

Thread safety
  This function must only be called from the main thread.

See also
  Gamma ramp

Since
  Added in version 3.0.

GLFWmonitor
struct GLFWmonitor GLFWmonitor
Opaque monitor object.
Definition: glfw3.h:1140