Typedefs | Functions
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 signature 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...
 
GLFWmonitorglfwGetPrimaryMonitor (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 glfwGetMonitorPhysicalSize (GLFWmonitor *monitor, int *widthMM, int *heightMM)
 Returns the physical size of the monitor. More...
 
const char * glfwGetMonitorName (GLFWmonitor *monitor)
 Returns the name of the specified monitor. More...
 
GLFWmonitorfun glfwSetMonitorCallback (GLFWmonitorfun cbfun)
 Sets the monitor configuration callback. More...
 
const GLFWvidmodeglfwGetVideoModes (GLFWmonitor *monitor, int *count)
 Returns the available video modes for the specified monitor. More...
 
const GLFWvidmodeglfwGetVideoMode (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 GLFWgammarampglfwGetGammaRamp (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

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

◆ 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 signature for monitor configuration callback functions.

Parameters
[in]monitorThe monitor that was connected or disconnected.
[in]eventOne of GLFW_CONNECTED or GLFW_DISCONNECTED.
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.

Function Documentation

◆ glfwGetGammaRamp()

const GLFWgammaramp* glfwGetGammaRamp ( GLFWmonitor monitor)

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

Parameters
[in]monitorThe 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.
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.

◆ 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]monitorThe 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.

◆ 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]monitorThe monitor to query.
[out]widthMMWhere to store the width, in millimetres, of the monitor's display area, or NULL.
[out]heightMMWhere 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.

◆ 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]monitorThe monitor to query.
[out]xposWhere to store the monitor x-coordinate, or NULL.
[out]yposWhere 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.

◆ 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]countWhere 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.

◆ 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]monitorThe 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.

◆ 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]monitorThe monitor to query.
[out]countWhere 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.

◆ glfwSetGamma()

void glfwSetGamma ( GLFWmonitor monitor,
float  gamma 
)

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.

Parameters
[in]monitorThe monitor whose gamma ramp to set.
[in]gammaThe desired exponent.
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.
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.

Parameters
[in]monitorThe monitor whose gamma ramp to set.
[in]rampThe gamma ramp to use.
Errors
Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
Remarks
Gamma ramp sizes other than 256 are not supported by all platforms or graphics hardware.
Windows: 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.
See also
Gamma ramp
Since
Added in version 3.0.

◆ glfwSetMonitorCallback()

GLFWmonitorfun glfwSetMonitorCallback ( GLFWmonitorfun  cbfun)

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]cbfunThe 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.
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.