Monitor reference

Overview

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;

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

typedef struct GLFWvidmode GLFWvidmode;
typedef struct GLFWgammaramp GLFWgammaramp;

// structs

struct GLFWgammaramp;
struct GLFWvidmode;

// global functions

GLFWAPI GLFWmonitor** glfwGetMonitors(int* count);
GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void);
GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM);
GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor);
GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp);

Typedefs

typedef struct GLFWmonitor GLFWmonitor

Opaque monitor object.

Added in version 3.0.

See also:

monitor_object

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

The function signature for monitor configuration callbacks.

This is the function signature for monitor configuration callback functions.

Added in version 3.0.

Parameters:

monitor	The monitor that was connected or disconnected.
event	One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.

See also:

monitor_event

glfwSetMonitorCallback

typedef struct GLFWvidmode GLFWvidmode

Video mode type.

This describes a single video mode.

Added in version 1.0. @glfw3 Added refresh rate member.

See also:

monitor_modes

glfwGetVideoMode glfwGetVideoModes

typedef struct GLFWgammaramp GLFWgammaramp

Gamma ramp.

This describes the gamma ramp for a monitor.

Added in version 3.0.

See also:

monitor_gamma

glfwGetGammaRamp glfwSetGammaRamp

Global Functions

GLFWAPI GLFWmonitor** glfwGetMonitors(int* count)

Returns the currently connected monitors.

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.

@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.

Added in version 3.0.

Parameters:

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.

See also:

monitor_monitors

monitor_event

glfwGetPrimaryMonitor

GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void)

Returns the primary monitor.

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

@errors Possible errors include GLFW_NOT_INITIALIZED.

@thread_safety This function must only be called from the main thread.

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

Added in version 3.0.

Returns:

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

See also:

monitor_monitors

glfwGetMonitors

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

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

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.

@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

@thread_safety This function must only be called from the main thread.

Added in version 3.0.

Parameters:

monitor	The monitor to query.
xpos	Where to store the monitor x-coordinate, or `NULL`.
ypos	Where to store the monitor y-coordinate, or `NULL`.

See also:

monitor_properties

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

Returns the physical size of the monitor.

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.

@errors Possible errors include GLFW_NOT_INITIALIZED.

@win32 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.

Added in version 3.0.

Parameters:

monitor	The monitor to query.
widthMM	Where to store the width, in millimetres, of the monitor’s display area, or `NULL`.
heightMM	Where to store the height, in millimetres, of the monitor’s display area, or `NULL`.

See also:

monitor_properties

GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor)

Returns the name of the specified 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.

@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.

Added in version 3.0.

Parameters:

monitor

The monitor to query.

Returns:

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

See also:

monitor_properties

GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun)

Sets the monitor configuration 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.

@errors Possible errors include GLFW_NOT_INITIALIZED.

@thread_safety This function must only be called from the main thread.

Added in version 3.0.

Parameters:

cbfun

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.

See also:

monitor_event

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

Returns the available video modes for the specified monitor.

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

@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.

Added in version 1.0. @glfw3 Changed to return an array of modes for a specific monitor.

Parameters:

monitor	The monitor to query.
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.

See also:

monitor_modes

glfwGetVideoMode

GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor)

Returns the current mode of the specified 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.

@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.

Added in version 3.0. Replaces glfwGetDesktopMode.

Parameters:

monitor

The monitor to query.

Returns:

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

See also:

monitor_modes

glfwGetVideoModes

GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma)

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

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

@errors Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_VALUE and GLFW_PLATFORM_ERROR.

@thread_safety This function must only be called from the main thread.

Added in version 3.0.

Parameters:

monitor	The monitor whose gamma ramp to set.
gamma	The desired exponent.

See also:

monitor_gamma

GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor)

Returns the current gamma ramp for the specified monitor.

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

@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

@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.

Added in version 3.0.

Parameters:

monitor

The monitor to query.

Returns:

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

See also:

monitor_gamma

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

Sets the current gamma ramp for the specified monitor.

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.

@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Gamma ramp sizes other than 256 are not supported by all platforms or graphics hardware.

@win32 The gamma ramp size must be 256.

@pointer_lifetime The specified gamma ramp is copied before this function returns.

@thread_safety This function must only be called from the main thread.

Added in version 3.0.

Parameters:

monitor	The monitor whose gamma ramp to set.
ramp	The gamma ramp to use.

See also:

monitor_gamma