raygui-widget
Classes | Typedefs | Functions
Monitor reference

Functions and types related to monitors. More...

Classes

struct  GLFWvidmode
 Video mode type. More...
 
struct  GLFWgammaramp
 Gamma ramp. More...
 

Typedefs

typedef struct GLFWmonitor GLFWmonitor
 Opaque monitor object. More...
 
typedef void(* GLFWmonitorfun) (GLFWmonitor *monitor, int event)
 The function pointer type for monitor configuration callbacks. More...
 
typedef struct GLFWvidmode GLFWvidmode
 Video mode type. More...
 
typedef struct GLFWgammaramp GLFWgammaramp
 Gamma ramp. More...
 
typedef struct GLFWmonitor GLFWmonitor
 Opaque monitor object. More...
 
typedef void(* GLFWmonitorfun) (GLFWmonitor *monitor, int event)
 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

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

Detailed Description

Functions and types related to monitors.

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

Typedef Documentation

◆ GLFWgammaramp [1/2]

typedef struct GLFWgammaramp GLFWgammaramp

Gamma ramp.

This describes the gamma ramp for a monitor.

See also
monitor_gamma
glfwGetGammaRamp
glfwSetGammaRamp
Since
Added in version 3.0.

◆ GLFWgammaramp [2/2]

typedef struct GLFWgammaramp GLFWgammaramp

Gamma ramp.

This describes the gamma ramp for a monitor.

See also
monitor_gamma
glfwGetGammaRamp
glfwSetGammaRamp
Since
Added in version 3.0.

◆ GLFWmonitor [1/2]

typedef struct GLFWmonitor GLFWmonitor

Opaque monitor object.

Opaque monitor object.

See also
monitor_object
Since
Added in version 3.0.

◆ GLFWmonitor [2/2]

typedef struct GLFWmonitor GLFWmonitor

Opaque monitor object.

Opaque monitor object.

See also
monitor_object
Since
Added in version 3.0.

◆ GLFWmonitorfun [1/2]

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

The function pointer type for monitor configuration callbacks.

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]monitorThe monitor that was connected or disconnected.
[in]eventOne of GLFW_CONNECTED or GLFW_DISCONNECTED. Future releases may add more events.
See also
monitor_event
glfwSetMonitorCallback
Since
Added in version 3.0.

◆ GLFWmonitorfun [2/2]

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

The function pointer type for monitor configuration callbacks.

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]monitorThe monitor that was connected or disconnected.
[in]eventOne of GLFW_CONNECTED or GLFW_DISCONNECTED. Future releases may add more events.
See also
monitor_event
glfwSetMonitorCallback
Since
Added in version 3.0.

◆ GLFWvidmode [1/2]

typedef struct GLFWvidmode GLFWvidmode

Video mode type.

This describes a single video mode.

See also
monitor_modes
glfwGetVideoMode
glfwGetVideoModes
Since
Added in version 1.0. Added refresh rate member.

◆ GLFWvidmode [2/2]

typedef struct GLFWvidmode GLFWvidmode

Video mode type.

This describes a single video mode.

See also
monitor_modes
glfwGetVideoMode
glfwGetVideoModes
Since
Added in version 1.0. Added refresh rate member.

Function Documentation

◆ glfwGetGammaRamp()

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.

Parameters
[in]monitorThe monitor to query.
Returns
The current gamma ramp, or NULL if an error occurred.

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

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

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.

This function must only be called from the main thread.

See also
monitor_gamma
Since
Added in version 3.0.

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.

Possible errors include GLFW_NOT_INITIALIZED, GLFW_PLATFORM_ERROR and GLFW_FEATURE_UNAVAILABLE (see remarks).

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

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.

This function must only be called from the main thread.

See also
monitor_gamma
Since
Added in version 3.0.

◆ glfwGetMonitorContentScale()

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

Retrieves the content scale for the specified monitor.

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]monitorThe monitor to query.
[out]xscaleWhere to store the x-axis content scale, or NULL.
[out]yscaleWhere to store the y-axis content scale, or NULL.

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

This function must only be called from the main thread.

See also
monitor_scale
glfwGetWindowContentScale
Since
Added in version 3.3.

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]monitorThe monitor to query.
[out]xscaleWhere to store the x-axis content scale, or NULL.
[out]yscaleWhere to store the y-axis content scale, or NULL.

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Remarks
Fractional scaling information is not yet available for monitors, so this function only returns integer content scales.

This function must only be called from the main thread.

See also
monitor_scale
glfwGetWindowContentScale
Since
Added in version 3.3.

◆ glfwGetMonitorName()

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.

Parameters
[in]monitorThe monitor to query.
Returns
The UTF-8 encoded name of the monitor, or NULL if an error occurred.

Possible errors include GLFW_NOT_INITIALIZED.

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.

This function must only be called from the main thread.

See also
monitor_properties
Since
Added in version 3.0.

◆ glfwGetMonitorPhysicalSize()

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.

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.

Possible errors include GLFW_NOT_INITIALIZED.

Remarks
On Windows 8 and earlier the physical size is calculated from the current resolution and system DPI instead of querying the monitor EDID data.

This function must only be called from the main thread.

See also
monitor_properties
Since
Added in version 3.0.

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

Some platforms 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.

Possible errors include GLFW_NOT_INITIALIZED.

Remarks
On Windows 8 and earlier the physical size is calculated from the current resolution and system DPI instead of querying the monitor EDID data.

This function must only be called from the main thread.

See also
monitor_properties
Since
Added in version 3.0.

◆ glfwGetMonitorPos()

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.

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.

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

This function must only be called from the main thread.

See also
monitor_properties
Since
Added in version 3.0.

◆ glfwGetMonitors()

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.

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.

Possible errors include GLFW_NOT_INITIALIZED.

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.

This function must only be called from the main thread.

See also
monitor_monitors
monitor_event
glfwGetPrimaryMonitor
Since
Added in version 3.0.

◆ glfwGetMonitorUserPointer()

GLFWAPI void * glfwGetMonitorUserPointer ( GLFWmonitor monitor)

Returns the user pointer of the specified 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]monitorThe monitor whose pointer to return.

Possible errors include GLFW_NOT_INITIALIZED.

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

See also
monitor_userptr
glfwSetMonitorUserPointer
Since
Added in version 3.3.

◆ glfwGetMonitorWorkarea()

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

Retrieves the work area of the monitor.

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

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

This function must only be called from the main thread.

See also
monitor_workarea
Since
Added in version 3.3.

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 window 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]monitorThe monitor to query.
[out]xposWhere to store the monitor x-coordinate, or NULL.
[out]yposWhere to store the monitor y-coordinate, or NULL.
[out]widthWhere to store the monitor width, or NULL.
[out]heightWhere to store the monitor height, or NULL.

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

This function must only be called from the main thread.

See also
monitor_workarea
Since
Added in version 3.3.

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

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

Possible errors include GLFW_NOT_INITIALIZED.

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
monitor_monitors
glfwGetMonitors
Since
Added in version 3.0.

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

Parameters
[in]monitorThe monitor to query.
Returns
The current mode of the monitor, or NULL if an error occurred.

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

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.

This function must only be called from the main thread.

See also
monitor_modes
glfwGetVideoModes
Since
Added in version 3.0. Replaces glfwGetDesktopMode.

◆ glfwGetVideoModes()

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), then by resolution area (the product of width and height), then resolution width and finally by refresh rate.

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.

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

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.

This function must only be called from the main thread.

See also
monitor_modes
glfwGetVideoMode
Since
Added in version 1.0. Changed to return an array of modes for a specific monitor.

◆ glfwSetGamma()

GLFWAPI void glfwSetGamma ( GLFWmonitor monitor,
float  gamma 
)

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

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

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_VALUE and GLFW_PLATFORM_ERROR.

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

This function must only be called from the main thread.

See also
monitor_gamma
Since
Added in version 3.0.

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

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_VALUE, GLFW_PLATFORM_ERROR and GLFW_FEATURE_UNAVAILABLE (see remarks).

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

This function must only be called from the main thread.

See also
monitor_gamma
Since
Added in version 3.0.

◆ glfwSetGammaRamp()

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.

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]monitorThe monitor whose gamma ramp to set.
[in]rampThe gamma ramp to use.

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.
The gamma ramp size must be 256.
Gamma handling is a privileged protocol, this function will thus never be implemented and emits GLFW_PLATFORM_ERROR.

The specified gamma ramp is copied before this function returns.

This function must only be called from the main thread.

See also
monitor_gamma
Since
Added in version 3.0.

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]monitorThe monitor whose gamma ramp to set.
[in]rampThe gamma ramp to use.

Possible errors include GLFW_NOT_INITIALIZED, GLFW_PLATFORM_ERROR and GLFW_FEATURE_UNAVAILABLE (see remarks).

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

The specified gamma ramp is copied before this function returns.

This function must only be called from the main thread.

See also
monitor_gamma
Since
Added in version 3.0.

◆ glfwSetMonitorCallback()

GLFWAPI GLFWmonitorfun glfwSetMonitorCallback ( GLFWmonitorfun  callback)

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.

Parameters
[in]callbackThe 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.
void function_name(GLFWmonitor* monitor, int event)

For more information about the callback parameters, see the function pointer type.

Possible errors include GLFW_NOT_INITIALIZED.

This function must only be called from the main thread.

See also
monitor_event
Since
Added in version 3.0.

◆ glfwSetMonitorUserPointer()

GLFWAPI void glfwSetMonitorUserPointer ( GLFWmonitor monitor,
void *  pointer 
)

Sets the user pointer of the specified monitor.

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]monitorThe monitor whose pointer to set.
[in]pointerThe new value.

Possible errors include GLFW_NOT_INITIALIZED.

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

See also
monitor_userptr
glfwGetMonitorUserPointer
Since
Added in version 3.3.