Display with associated rendering capabilities and modes. More...

Detailed Description

Display with associated rendering capabilities and modes.

An SRMConnector represents a screen where content is displayed, such as a laptop display, an HDMI monitor, and more.

Rendering

Each connector has its own dedicated rendering thread, which triggers common OpenGL events like initializeGL(), paintGL(), resizeGL() through an SRMConnectorInterface. You can initialize a connector using the srmConnectorInitialize() method.

Modes

Connectors usually support multiple display modes (SRMConnectorMode), which define their refresh rate and resolution.
These modes can be enumerated using srmConnectorGetModes() and selected using srmConnectorSetMode().

Enumerations
enum	SRM_PRESENTATION_TIME_FLAGS
	Bitmask of flags in an fb presentation. More...

enum	SRM_CONNECTOR_STATE
	Enumeration of connector states. More...

enum	SRM_CONNECTOR_SUBPIXEL
	Enumeration of connector subpixel layouts. More...

enum	SRM_CONNECTOR_CONTENT_TYPE
	Content type hint. More...

Functions
void	srmConnectorSetUserData (SRMConnector connector, void userData)
	Sets the connector user data. More...

void *	srmConnectorGetUserData (SRMConnector *connector)
	Retrieves the connector user data. More...

SRMDevice *	srmConnectorGetDevice (SRMConnector *connector)
	Get the device this connector belongs to. More...

SRMDevice *	srmConnectorGetRendererDevice (SRMConnector *connector)
	Retrieve the renderer device associated with the connector. More...

UInt32	srmConnectorGetID (SRMConnector *connector)
	Get the DRM connector ID. More...

SRM_CONNECTOR_STATE	srmConnectorGetState (SRMConnector *connector)
	Get the current state of the connector. More...

UInt8	srmConnectorIsConnected (SRMConnector *connector)
	Check if the connector is connected. More...

UInt32	srmConnectorGetmmWidth (SRMConnector *connector)
	Get the physical width of the connector in millimeters. More...

UInt32	srmConnectorGetmmHeight (SRMConnector *connector)
	Get the physical height of the connector in millimeters. More...

UInt32	srmConnectorGetType (SRMConnector *connector)
	Get the DRM type of the connector. More...

const char *	srmConnectorGetName (SRMConnector *connector)
	Get the name of the connector. More...

const char *	srmConnectorGetManufacturer (SRMConnector *connector)
	Get the manufacturer of the connector. More...

const char *	srmConnectorGetModel (SRMConnector *connector)
	Get the model of the connector. More...

SRMList *	srmConnectorGetEncoders (SRMConnector *connector)
	Get a list of available connector encoders. More...

SRMList *	srmConnectorGetModes (SRMConnector *connector)
	Get a list of available connector modes. More...

UInt8	srmConnectorHasHardwareCursor (SRMConnector *connector)
	Check if there is an available cursor plane for hardware cursor compositing. More...

UInt8	srmConnectorSetCursor (SRMConnector connector, UInt8 pixels)
	Set the pixels of the hardware cursor. More...

UInt8	srmConnectorSetCursorPos (SRMConnector *connector, Int32 x, Int32 y)
	Set the position of the hardware cursor relative to the connector's top-left origin. More...

SRMEncoder *	srmConnectorGetCurrentEncoder (SRMConnector *connector)
	Get the currently used encoder for the connector. More...

SRMCrtc *	srmConnectorGetCurrentCrtc (SRMConnector *connector)
	Get the currently used CRT controller (CRTC) for the connector. More...

SRMPlane *	srmConnectorGetCurrentPrimaryPlane (SRMConnector *connector)
	Get the currently used primary plane for the connector. More...

SRMPlane *	srmConnectorGetCurrentCursorPlane (SRMConnector *connector)
	Get the currently used cursor plane for the connector. More...

SRMConnectorMode *	srmConnectorGetPreferredMode (SRMConnector *connector)
	Get the preferred connector mode. More...

SRMConnectorMode *	srmConnectorGetCurrentMode (SRMConnector *connector)
	Get the current connector mode. More...

UInt8	srmConnectorSetMode (SRMConnector connector, SRMConnectorMode mode)
	Sets the current mode of the connector. More...

UInt8	srmConnectorInitialize (SRMConnector connector, SRMConnectorInterface interface, void *userData)
	Initializes a connector, creating its rendering thread and invoking `initializeGL()` once initialized. More...

UInt8	srmConnectorRepaint (SRMConnector *connector)
	Schedules a new rendering frame. More...

void	srmConnectorUninitialize (SRMConnector *connector)
	Uninitializes the connector. More...

UInt8	srmConnectorSuspend (SRMConnector *connector)
	Locks the rendering thread until srmConnectorResume() is called. More...

UInt8	srmConnectorResume (SRMConnector *connector)
	Unlocks the rendering thread if previously locked with srmConnectorSuspend(). More...

UInt32	srmConnectorGetFramebufferID (SRMConnector *connector)
	Retrieves the ID of the currently bound OpenGL framebuffer. More...

EGLContext	srmConnectorGetContext (SRMConnector *connector)
	Retrieves the `EGLContext` associated with the rendering thread. More...

UInt32	srmConnectorGetCurrentBufferIndex (SRMConnector *connector)
	Returns the current framebuffer index. More...

UInt32	srmConnectorGetBuffersCount (SRMConnector *connector)
	Returns the number of framebuffers. More...

SRMBuffer *	srmConnectorGetBuffer (SRMConnector *connector, UInt32 bufferIndex)
	Returns the buffer of a specific framebuffer index, usable as a texture for rendering. More...

UInt8	srmConnectorHasBufferDamageSupport (SRMConnector *connector)
	Checks if the connector benefits from providing it damage information generated during the last `paintGL()` call. More...

UInt8	srmConnectorSetBufferDamage (SRMConnector connector, SRMRect rects, Int32 n)
	Notifies the connector of new damage generated during the last `paintGL()` call. More...

UInt8	srmConnectorSetBufferDamageBoxes (SRMConnector connector, SRMBox boxes, Int32 n)
	Notifies the connector of new damage generated during the last `paintGL()` call using boxes. More...

SRM_CONNECTOR_SUBPIXEL	srmConnectorGetSubPixel (SRMConnector *connector)
	Get the subpixel layout associated with a connector. More...

UInt64	srmConnectorGetGammaSize (SRMConnector *connector)
	Gets the number of elements used to represent each RGB gamma correction curve. More...

UInt8	srmConnectorSetGamma (SRMConnector connector, UInt16 table)
	Sets the gamma correction curves for each RGB component. More...

UInt8	srmConnectorHasVSyncControlSupport (SRMConnector *connector)
	Checks if the driver supports the ability to turn off vsync. More...

UInt8	srmConnectorIsVSyncEnabled (SRMConnector *connector)
	Returns the current vsync status. More...

UInt8	srmConnectorEnableVSync (SRMConnector *connector, UInt8 enabled)
	Enable or disable vsync. More...

void	srmConnectorSetRefreshRateLimit (SRMConnector *connector, Int32 hz)
	Sets the refresh rate limit when vsync is disabled. More...

Int32	srmConnectorGetRefreshRateLimit (SRMConnector *connector)
	Retrieves the current refresh rate limit when vsync is disabled. More...

clockid_t	srmConnectorGetPresentationClock (SRMConnector *connector)
	Gets the clock ID used for the timestamps returned by srmConnectorGetPresentationTime(). More...

const SRMPresentationTime *	srmConnectorGetPresentationTime (SRMConnector *connector)
	Retrieves information about how and when the current framebuffer displayed on the screen was presented. More...

void	srmConnectorSetContentType (SRMConnector *connector, SRM_CONNECTOR_CONTENT_TYPE contentType)
	Sets a hint of the content type being displayed. More...

SRM_CONNECTOR_CONTENT_TYPE	srmConnectorGetContentType (SRMConnector *connector)
	Gets the content type hint. More...

UInt8	srmConnectorSetCustomScanoutBuffer (SRMConnector connector, SRMBuffer buffer)
	Sets a custom scanout buffer for the primary plane. More...

UInt8	srmConnectorIsNonDesktop (SRMConnector *connector)
	Checks if the connector is not intended for desktop usage. More...

Typedef Documentation

◆ SRMConnector

typedef struct SRMConnectorStruct SRMConnector

Enumeration Type Documentation

◆ SRM_PRESENTATION_TIME_FLAGS

enum SRM_PRESENTATION_TIME_FLAGS

Bitmask of flags in an fb presentation.

These flags provide information about how the last framebuffer was presented on a connector display.

See also: SRMPresentationTime

Enumerator
SRM_PRESENTATION_TIME_FLAGS_VSYNC	Presentation was vsync'd.
SRM_PRESENTATION_TIME_FLAGS_HW_CLOCK	Hardware provided the presentation timestamp.
SRM_PRESENTATION_TIME_FLAGS_HW_COMPLETION	Hardware signaled the start of the presentation.

◆ SRM_CONNECTOR_STATE

enum SRM_CONNECTOR_STATE

Enumeration of connector states.

Enumerator
SRM_CONNECTOR_STATE_UNINITIALIZED	The connector is uninitialized.
SRM_CONNECTOR_STATE_INITIALIZED	The connector is initialized.
SRM_CONNECTOR_STATE_UNINITIALIZING	The connector is in the process of uninitializing.
SRM_CONNECTOR_STATE_INITIALIZING	The connector is in the process of initializing.
SRM_CONNECTOR_STATE_CHANGING_MODE	The connector is changing display mode.
SRM_CONNECTOR_STATE_REVERTING_MODE	Special case when changing mode fails and reverts to its previous mode.
SRM_CONNECTOR_STATE_SUSPENDING	The connector state is changing from initialized to suspended.
SRM_CONNECTOR_STATE_SUSPENDED	The connector is suspended.
SRM_CONNECTOR_STATE_RESUMING	The connector state is changing from suspended to initialized.

◆ SRM_CONNECTOR_SUBPIXEL

enum SRM_CONNECTOR_SUBPIXEL

Enumeration of connector subpixel layouts.

This enumeration defines different subpixel layouts that can be associated with a connector. Subpixels are individual color elements that make up a pixel on a display. Understanding the subpixel layout is crucial for accurate color interpretation and display.

Enumerator
SRM_CONNECTOR_SUBPIXEL_UNKNOWN	Unknown subpixel layout.
SRM_CONNECTOR_SUBPIXEL_HORIZONTAL_RGB	Horizontal subpixel layout with RGB order. Red, green, and blue subpixels are arranged horizontally.
SRM_CONNECTOR_SUBPIXEL_HORIZONTAL_BGR	Horizontal subpixel layout with BGR order. Blue, green, and red subpixels are arranged horizontally.
SRM_CONNECTOR_SUBPIXEL_VERTICAL_RGB	Vertical subpixel layout with RGB order. Red, green, and blue subpixels are arranged vertically.
SRM_CONNECTOR_SUBPIXEL_VERTICAL_BGR	Vertical subpixel layout with BGR order. Blue, green, and red subpixels are arranged vertically.
SRM_CONNECTOR_SUBPIXEL_NONE	No specific subpixel layout. The connector does not have a well-defined order for subpixels.

◆ SRM_CONNECTOR_CONTENT_TYPE

enum SRM_CONNECTOR_CONTENT_TYPE

Content type hint.

This hint is utilized by certain hardware displays to adjust settings optimally based on the displayed content. For example, setting the SRM_CONNECTOR_CONTENT_TYPE_GAME hint may prompt the hardware to minimize latency.

Enumerator
SRM_CONNECTOR_CONTENT_TYPE_GRAPHICS	Graphics.
SRM_CONNECTOR_CONTENT_TYPE_PHOTO	Photo.
SRM_CONNECTOR_CONTENT_TYPE_VIDEO	Video.
SRM_CONNECTOR_CONTENT_TYPE_GAME	Game.

Function Documentation

◆ srmConnectorSetUserData()

void srmConnectorSetUserData	(	SRMConnector *	connector,
		void *	userData
	)

Sets the connector user data.

This function sets the user data associated with the given SRMConnector.

Note: This user data is distinct from the one passed in srmConnectorInitialize().

Parameters

connector	Pointer to the SRMConnector whose user data is to be set.
userData	Pointer to the user data to be associated with the connector.

◆ srmConnectorGetUserData()

void* srmConnectorGetUserData ( SRMConnector * connector )

Retrieves the connector user data.

This function retrieves the user data associated with the given SRMConnector.

Note: This user data is distinct from the one passed in srmConnectorInitialize().

Parameters

connector Pointer to the SRMConnector from which to retrieve the user data.

Returns: Pointer to the user data associated with the connector.

◆ srmConnectorGetDevice()

SRMDevice* srmConnectorGetDevice ( SRMConnector * connector )

Get the device this connector belongs to.

This function returns the device to which the connector belongs.

Parameters

connector Pointer to the SRMConnector for which to retrieve the device.

Returns: Pointer to the SRMDevice to which the connector belongs.

Note: The device may not always be the same as the renderer device.

◆ srmConnectorGetRendererDevice()

SRMDevice* srmConnectorGetRendererDevice ( SRMConnector * connector )

Retrieve the renderer device associated with the connector.

This function returns the device responsible for rendering operations for the connector.

When the ITSELF rendering mode is used, this device is the same as the one obtained with srmConnectorGetDevice(). However, in the PRIME, DUMB or CPU modes, it differs.

Parameters

connector Pointer to the SRMConnector for which you want to obtain the renderer device.

Returns: Pointer to the SRMDevice responsible for rendering operations for the connector.

Note: Use this device when you need to access the OpenGL texture of a SRMBuffer with srmBufferGetTextureId().

◆ srmConnectorGetID()

UInt32 srmConnectorGetID ( SRMConnector * connector )

Get the DRM connector ID.

This function returns the DRM connector ID associated with the connector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the connector ID.

Returns: The DRM connector ID of the connector.

◆ srmConnectorGetState()

SRM_CONNECTOR_STATE srmConnectorGetState ( SRMConnector * connector )

Get the current state of the connector.

This function returns the current state for the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the state.

Returns: The current rendering state (e.g., initialized, uninitialized, etc).

◆ srmConnectorIsConnected()

UInt8 srmConnectorIsConnected ( SRMConnector * connector )

Check if the connector is connected.

This function checks whether the given SRMConnector is connected.

Note: Only connected connectors can be initialized. Calling srmConnectorInitialize() on a disconnected connector has no effect.

Parameters

connector Pointer to the SRMConnector to check for connection.

Returns: 1 if the connector is connected, 0 otherwise.

◆ srmConnectorGetmmWidth()

UInt32 srmConnectorGetmmWidth ( SRMConnector * connector )

Get the physical width of the connector in millimeters.

This function returns the physical width of the connector in millimeters.

Parameters

connector Pointer to the SRMConnector for which to retrieve the width.

Returns: The physical width of the connector in millimeters.

◆ srmConnectorGetmmHeight()

UInt32 srmConnectorGetmmHeight ( SRMConnector * connector )

Get the physical height of the connector in millimeters.

This function returns the physical height of the connector in millimeters.

Parameters

connector Pointer to the SRMConnector for which to retrieve the height.

Returns: The physical height of the connector in millimeters.

◆ srmConnectorGetType()

UInt32 srmConnectorGetType ( SRMConnector * connector )

Get the DRM type of the connector.

This function returns the DRM type associated with the connector (DRM_MODE_CONNECTOR_xx macros defined in drm_mode.h).

Parameters

connector Pointer to the SRMConnector for which to retrieve the type.

Returns: The DRM type of the connector.

◆ srmConnectorGetName()

const char* srmConnectorGetName ( SRMConnector * connector )

Get the name of the connector.

This function returns the name of the connector. The name is always unique, even across devices. For example, if there are two HDMI-A connectors, one will be called HDMI-A-0, and the other HDMI-A-1.

Parameters

connector Pointer to the SRMConnector for which to retrieve the name.

Returns: The name of the connector.

◆ srmConnectorGetManufacturer()

const char* srmConnectorGetManufacturer ( SRMConnector * connector )

Get the manufacturer of the connector.

This function returns the manufacturer of the connector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the manufacturer.

Returns: The manufacturer of the connector.

◆ srmConnectorGetModel()

const char * srmConnectorGetModel ( SRMConnector * connector )

Get the model of the connector.

This function returns the model of the connector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the model.

Returns: The model of the connector.

◆ srmConnectorGetEncoders()

SRMList * srmConnectorGetEncoders ( SRMConnector * connector )

Get a list of available connector encoders.

This function returns a list of available encoders for the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the encoders.

Returns: A list of available connector encoders (SRMEncoder).

◆ srmConnectorGetModes()

SRMList * srmConnectorGetModes ( SRMConnector * connector )

Get a list of available connector modes.

This function returns a list of available modes (resolutions and refresh rates) for the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the modes.

Returns: A list of available connector modes (SRMConnectorMode).

◆ srmConnectorHasHardwareCursor()

UInt8 srmConnectorHasHardwareCursor ( SRMConnector * connector )

Check if there is an available cursor plane for hardware cursor compositing.

This function checks if there is an available cursor plane for hardware cursor compositing on the given SRMConnector.

Parameters

connector Pointer to the SRMConnector to check for hardware cursor support.

Returns: 1 if hardware cursor support is available, 0 otherwise.

◆ srmConnectorSetCursor()

UInt8 srmConnectorSetCursor	(	SRMConnector *	connector,
		UInt8 *	pixels
	)

Set the pixels of the hardware cursor.

This function sets the pixels of the hardware cursor for the given SRMConnector.

The format of the buffer must be ARGB8888 with a size of 64x64 pixels. Passing NULL as the buffer hides the cursor.

Parameters

connector	Pointer to the SRMConnector for which to set the hardware cursor.
pixels	Pointer to the ARGB8888 pixel buffer for the cursor image.

Returns: 1 if the hardware cursor was successfully set, 0 if an error occurred.

◆ srmConnectorSetCursorPos()

UInt8 srmConnectorSetCursorPos	(	SRMConnector *	connector,
		Int32	x,
		Int32	y
	)

Set the position of the hardware cursor relative to the connector's top-left origin.

This function sets the position of the hardware cursor relative to the top-left origin of the connector.

Parameters

connector	Pointer to the SRMConnector for which to set the cursor position.
x	The X-coordinate of the cursor's position.
y	The Y-coordinate of the cursor's position.

Returns: 1 if the cursor position was successfully set, 0 if an error occurred.

◆ srmConnectorGetCurrentEncoder()

SRMEncoder* srmConnectorGetCurrentEncoder ( SRMConnector * connector )

Get the currently used encoder for the connector.

This function returns the currently used SRMEncoder associated with the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the current encoder.

Returns: The currently used SRMEncoder for the connector.

◆ srmConnectorGetCurrentCrtc()

SRMCrtc* srmConnectorGetCurrentCrtc ( SRMConnector * connector )

Get the currently used CRT controller (CRTC) for the connector.

This function returns the currently used SRMCrtc associated with the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the current CRTC.

Returns: The currently used SRMCrtc for the connector.

◆ srmConnectorGetCurrentPrimaryPlane()

SRMPlane* srmConnectorGetCurrentPrimaryPlane ( SRMConnector * connector )

Get the currently used primary plane for the connector.

This function returns the currently used SRMPlane associated with the primary display plane for the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the current primary plane.

Returns: The currently used SRMPlane for the primary display.

◆ srmConnectorGetCurrentCursorPlane()

SRMPlane* srmConnectorGetCurrentCursorPlane ( SRMConnector * connector )

Get the currently used cursor plane for the connector.

This function returns the currently used SRMPlane associated with the cursor display plane for the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the current cursor plane.

Returns: The currently used SRMPlane for the cursor display or NULL if not assigned.

◆ srmConnectorGetPreferredMode()

SRMConnectorMode* srmConnectorGetPreferredMode ( SRMConnector * connector )

Get the preferred connector mode.

This function returns the preferred SRMConnectorMode for the given SRMConnector .
This mode typically has the higher resolution and refresh rate.

Parameters

connector Pointer to the SRMConnector for which to retrieve the preferred mode.

Returns: The preferred SRMConnectorMode for the connector.

◆ srmConnectorGetCurrentMode()

SRMConnectorMode* srmConnectorGetCurrentMode ( SRMConnector * connector )

Get the current connector mode.

This function returns the current SRMConnectorMode for the given SRMConnector.

Parameters

connector Pointer to the SRMConnector for which to retrieve the current mode.

Returns: The current SRMConnectorMode for the connector.

◆ srmConnectorSetMode()

UInt8 srmConnectorSetMode	(	SRMConnector *	connector,
		SRMConnectorMode *	mode
	)

Sets the current mode of the connector.

This function sets the current mode of the given SRMConnector. You can use srmConnectorGetModes() to obtain a list of all available modes. If the connector is initialized the resizeGL() event is invoked.

Note: All connector use the srmConnectorGetPreferredMode() by default.

Warning: Do not call this function from any of the OpenGL events, as it may result in a deadlock.

Parameters

connector	Pointer to the SRMConnector for which to set the mode.
mode	Pointer to the SRMConnectorMode to set as the current mode.

Returns: 1 if setting the mode is successful, 0 if an error occurs.

◆ srmConnectorInitialize()

UInt8 srmConnectorInitialize	(	SRMConnector *	connector,
		SRMConnectorInterface *	interface,
		void *	userData
	)

Initializes a connector, creating its rendering thread and invoking initializeGL() once initialized.

This function initializes the given SRMConnector. After initialization, calling srmConnectorRepaint() schedules a new rendering frame, which invokes paintGL() followed by a pageFlipped() event.

Parameters

connector	Pointer to the SRMConnector to initialize.
interface	Pointer to the SRMConnectorInterface struct to handle events.
userData	Pointer to user data to be associated with the connector.

Returns: 1 if initialization is successful, 0 if an error occurs.

Warning: Make sure to correctly set up the SRMConnectorInterface to handle all its events, otherwise, it may crash.

◆ srmConnectorRepaint()

UInt8 srmConnectorRepaint ( SRMConnector * connector )

Schedules a new rendering frame.

This function schedules a new rendering frame for the given SRMConnector. Calling this method multiple times during the same frame will not invoke paintGL() multiple times, only once. After each paintGL() event, this method must be called again to schedule a new frame.

Parameters

connector Pointer to the SRMConnector to schedule a new rendering frame.

Returns: 1 if scheduling is successful, 0 if an error occurs.

Note: This function triggers paintGL() and pageFlipped() events in the rendering process.

◆ srmConnectorUninitialize()

void srmConnectorUninitialize ( SRMConnector * connector )

Uninitializes the connector.

This function uninitializes the given SRMConnector, eventually calling uninitializeGL() once uninitialized.

Warning: Do not call this function from any of the OpenGL events, as it may result in a deadlock.

Parameters

connector Pointer to the SRMConnector to uninitialize.

◆ srmConnectorSuspend()

UInt8 srmConnectorSuspend ( SRMConnector * connector )

Locks the rendering thread until srmConnectorResume() is called.

This function locks the rendering thread of the SRMConnector until srmConnectorResume() is called to unlock it.

Warning: Do not call this function from any of the OpenGL events, as it may result in a deadlock.

Parameters

connector Pointer to the SRMConnector to suspend.

Returns: 1 if pausing is successful, 0 if an error occurs.

◆ srmConnectorResume()

UInt8 srmConnectorResume ( SRMConnector * connector )

Unlocks the rendering thread if previously locked with srmConnectorSuspend().

This function unlocks the rendering thread of the SRMConnector if it was previously locked with srmConnectorSuspend().

Warning: Do not call this function from any of the OpenGL events, as it may result in a deadlock.

Parameters

connector Pointer to the SRMConnector to resume.

Returns: 1 if resuming is successful, 0 if an error occurs.

◆ srmConnectorGetFramebufferID()

UInt32 srmConnectorGetFramebufferID ( SRMConnector * connector )

Retrieves the ID of the currently bound OpenGL framebuffer.

◆ srmConnectorGetContext()

EGLContext srmConnectorGetContext ( SRMConnector * connector )

Retrieves the EGLContext associated with the rendering thread.

Returns: The EGLContext of the rendering thread, or EGL_NO_CONTEXT if it is uninitialized.

◆ srmConnectorGetCurrentBufferIndex()

UInt32 srmConnectorGetCurrentBufferIndex ( SRMConnector * connector )

Returns the current framebuffer index.

This function returns the index of the current framebuffer where the rendered content is stored during a paintGL() event.

Parameters

connector Pointer to the SRMConnector to query for the current framebuffer index.

Returns: The current framebuffer index.

◆ srmConnectorGetBuffersCount()

UInt32 srmConnectorGetBuffersCount ( SRMConnector * connector )

Returns the number of framebuffers.

This function returns the number of framebuffers available for the given SRMConnector. The count may be 2 or 3, depending on the configuration (double or triple buffering).

The number of framebuffers can be modified by setting the SRM_RENDER_MODE_{ITSELF, PRIME, DUMB, CPU}_FB_COUNT environment variables.

Parameters

connector Pointer to the SRMConnector to query for the number of framebuffers.

Returns: The number of framebuffers.

◆ srmConnectorGetBuffer()

SRMBuffer* srmConnectorGetBuffer	(	SRMConnector *	connector,
		UInt32	bufferIndex
	)

Returns the buffer of a specific framebuffer index, usable as a texture for rendering.

This function returns the buffer of the specified framebuffer index of the given SRMConnector. This buffer can be used as a texture for rendering, but it may not always be supported. Always check if NULL is returned.

Additionally, note that the buffer may not always be shared among all GPUs. In such cases, calling srmBufferGetTextureID() may return 0.

Parameters

connector	Pointer to the SRMConnector for which to retrieve the framebuffer buffer.
bufferIndex	The index of the framebuffer buffer to retrieve.

Returns: A pointer to the SRMBuffer if available, or NULL if not supported.

◆ srmConnectorHasBufferDamageSupport()

UInt8 srmConnectorHasBufferDamageSupport ( SRMConnector * connector )

Checks if the connector benefits from providing it damage information generated during the last paintGL() call.

This function checks if the given SRMConnector benefits from receiving damage information generated during the last paintGL() call. Providing this information may improve performance, specifically when using DUMB or CPU render modes, as the connector will only copy the specified rectangles.

Parameters

connector Pointer to the SRMConnector to check for buffer damage support.

Returns: 1 if the connector supports buffer damage notifications, 0 otherwise.

◆ srmConnectorSetBufferDamage()

UInt8 srmConnectorSetBufferDamage	(	SRMConnector *	connector,
		SRMRect *	rects,
		Int32	n
	)

Notifies the connector of new damage generated during the last paintGL() call.

This function notifies the given SRMConnector of new damage areas generated during the last paintGL() call.
Providing this damage information can considerably improve performance when using the DUMB or CPU render modes, as the connector will only copy the specified region. The damage specified is only valid during the current frame and is cleared in the next frame.

Note: Use srmConnectorHasBufferDamageSupport() to determine whether the connector can benefit from providing this information.

Parameters

connector	Pointer to the SRMConnector to notify of buffer damage.
rects	An array of SRMRect structures representing the damaged area.
n	The number of rectangles in the array. Passing 0 unsets the current damage.

Returns: 1 if the damage notification is successful, 0 if an error occurs.

Warning: It is important to ensure that the coordinates of the rectangles originate from the top-left corner of the framebuffer and do not extend beyond its boundaries to avoid segmentation errors.

◆ srmConnectorSetBufferDamageBoxes()

UInt8 srmConnectorSetBufferDamageBoxes	(	SRMConnector *	connector,
		SRMBox *	boxes,
		Int32	n
	)

Notifies the connector of new damage generated during the last paintGL() call using boxes.

This method is analogous to srmConnectorSetBufferDamage(), but instead of SRMRect, it accepts SRMBox.

See also: srmConnectorSetBufferDamage().

Parameters

connector	Pointer to the SRMConnector structure to notify of buffer damage.
boxes	An array of SRMBox structures representing the damaged areas.
n	The number of boxes in the array. Passing 0 unsets the current damage.

Returns: Returns 1 if the damage notification is successful, 0 if an error occurs.

◆ srmConnectorGetSubPixel()

SRM_CONNECTOR_SUBPIXEL srmConnectorGetSubPixel ( SRMConnector * connector )

Get the subpixel layout associated with a connector.

This function retrieves the subpixel layout associated with a given connector. Subpixels are individual color elements that make up a pixel on a display, and the subpixel layout is crucial for accurate color interpretation and display. The returned value indicates how the red, green, and blue subpixels are arranged in relation to each other.

Note: The returned value is only meaningful when a display is connected. If the subpixel layout is unknown or not applicable, the method may return SRM_CONNECTOR_SUBPIXEL_UNKNOWN or SRM_CONNECTOR_SUBPIXEL_NONE, respectively.

Parameters

connector Pointer to the SRMConnector for which the subpixel layout is requested.

Returns: The subpixel layout associated with the connector.

◆ srmConnectorGetGammaSize()

UInt64 srmConnectorGetGammaSize ( SRMConnector * connector )

Gets the number of elements used to represent each RGB gamma correction curve.

This function retrieves the number of elements (N) used to represent each RGB gamma correction curve, where N is the count of UInt16 elements for red, green, and blue curves.

Note: This method should only be called once the connector is assigned a CRTC, meaning after the connector is initialized. If called when uninitialized, it returns 0. If the connector is initialized and this method returns 0, it indicates that the driver does not support gamma correction.

Parameters

connector Pointer to the SRMConnector.

Returns: The number of elements used to represent each RGB gamma correction curve, or 0 if the connector is uninitialized or if the driver does not support gamma correction.

◆ srmConnectorSetGamma()

UInt8 srmConnectorSetGamma	(	SRMConnector *	connector,
		UInt16 *	table
	)

Sets the gamma correction curves for each RGB component.

This method allows you to set the gamma correction curves for each RGB component. The number of elements for each curve (N) should be obtained using srmConnectorGetGammaSize(). The table array should then have a size of 3 * N * sizeof(UInt16) bytes, with N UInt16 values for red, N for green, and N for blue, in that order. Each value of the curves can represent the full range of UInt16.

Note: This method must only be called after the connector is initialized. If the connector is uninitialized or the driver does not support gamma correction, the function returns 0.

The default gamma curves are linear.

Parameters

connector	Pointer to the SRMConnector.
table	Pointer to the array containing RGB curves for gamma correction.

Returns: On success, returns 1. On failure (uninitialized connector or no gamma correction support), returns 0.

◆ srmConnectorHasVSyncControlSupport()

UInt8 srmConnectorHasVSyncControlSupport ( SRMConnector * connector )

Checks if the driver supports the ability to turn off vsync.

If the return value is 0, it indicates that vsync is always enabled.

Note: Disabling vsync for the atomic API is supported only starting from Linux version 6.8. If you wish to enforce the use of the legacy API, set the SRM_FORCE_LEGACY_API environment variable to 1.

Parameters

connector The SRMConnector instance.

Returns: 1 if vsync control is supported, 0 otherwise.

◆ srmConnectorIsVSyncEnabled()

UInt8 srmConnectorIsVSyncEnabled ( SRMConnector * connector )

Returns the current vsync status.

Returns 1 if vsync is enabled, 0 otherwise. V-Sync is enabled by default.

Parameters

connector The SRMConnector instance.

Returns: 1 if vsync is enabled, 0 if not.

◆ srmConnectorEnableVSync()

UInt8 srmConnectorEnableVSync	(	SRMConnector *	connector,
		UInt8	enabled
	)

Enable or disable vsync.

Disabling vsync is only allowed if srmConnectorHasVSyncControlSupport() returns 1. VSync is enabled by default.

Note: Disabling vsync for the atomic API is supported only starting from Linux version 6.8. If you wish to enforce the use of the legacy API, set the SRM_FORCE_LEGACY_API environment variable to 1.

Parameters

connector	The SRMConnector instance.
enabled	Set to 1 to enable vsync, 0 to disable vsync.

Returns: 1 if the vsync change was successful, 0 otherwise.

◆ srmConnectorSetRefreshRateLimit()

void srmConnectorSetRefreshRateLimit	(	SRMConnector *	connector,
		Int32	hz
	)

Sets the refresh rate limit when vsync is disabled.

This function allows controlling the refresh rate limit when vsync is disabled

Parameters

connector	A pointer to the SRMConnector instance for which the refresh rate limit is to be set.
hz	The desired refresh rate limit in hertz. If hz is less than 0, the refresh rate limit is disabled. If hz is 0, the maximum refresh rate will be approximately twice the current display mode refresh rate. The default value is 0.

Note: Using a value of 0 (twice the current mode refresh rate) provides a good balance between avoiding unnecessary undisplayed frames and achieving snappier response times.

See also: srmConnectorGetRefreshRateLimit() to retrieve the current refresh rate limit.

Warning: Disabling the limit may result in visual artifacts and could potentially impact performance.

◆ srmConnectorGetRefreshRateLimit()

Int32 srmConnectorGetRefreshRateLimit ( SRMConnector * connector )

Retrieves the current refresh rate limit when vsync is disabled.

This function allows you to query the refresh rate limit that has been previously set using the srmConnectorSetRefreshRateLimit() function.

Parameters

connector A pointer to the SRMConnector instance for which the refresh rate limit is to be retrieved.

Returns: The current refresh rate limit in hertz. If the refresh rate limit is disabled, the returned value will be less than 0. If the returned value is 0, means the limit is about twice the current display mode refresh rate.

◆ srmConnectorGetPresentationClock()

clockid_t srmConnectorGetPresentationClock ( SRMConnector * connector )

Gets the clock ID used for the timestamps returned by srmConnectorGetPresentationTime().

The clock ID can be either CLOCK_MONOTONIC or CLOCK_REALTIME.

Parameters

connector A pointer to the SRMConnector instance.

Returns: The clock ID used for timestamps.

◆ srmConnectorGetPresentationTime()

const SRMPresentationTime* srmConnectorGetPresentationTime ( SRMConnector * connector )

Retrieves information about how and when the current framebuffer displayed on the screen was presented.

Parameters

connector A pointer to the SRMConnector instance.

Returns: Pointer to the structure containing presentation time information, see SRMPresentationTime.

◆ srmConnectorSetContentType()

void srmConnectorSetContentType	(	SRMConnector *	connector,
		SRM_CONNECTOR_CONTENT_TYPE	contentType
	)

Sets a hint of the content type being displayed.

See also: SRM_CONNECTOR_CONTENT_TYPE

Note: The default value is SRM_CONNECTOR_CONTENT_TYPE_GRAPHICS

Parameters

connector	A pointer to the SRMConnector instance.
contentType	The content type hint.

◆ srmConnectorGetContentType()

SRM_CONNECTOR_CONTENT_TYPE srmConnectorGetContentType ( SRMConnector * connector )

Gets the content type hint.

See also: srmConnectorSetContentType()

Parameters

connector A pointer to the SRMConnector instance.

◆ srmConnectorSetCustomScanoutBuffer()

UInt8 srmConnectorSetCustomScanoutBuffer	(	SRMConnector *	connector,
		SRMBuffer *	buffer
	)

Sets a custom scanout buffer for the primary plane.

This function allows you to set a custom scanout buffer for the primary plane only during a single frame. It must called within a paintGL() event. Calling it outside a paintGL() will result in an error.

If successfully set, the current buffer index is not updated, and no OpenGL rendering operations should be performed within the paintGL() event. If not set again in subsequent frames, the connector's framebuffers are restored, and the current buffer index continues to be updated as usual.

Note: The size of the buffer must match the dimensions of the current connector's mode.

If successfully set, the internal reference counter of the buffer is increased, ensuring it remains scannable for at least the given frame even if it is destroyed.

Note: If SRM_DISABLE_CUSTOM_SCANOUT is set to 1, this function always return 0.

Parameters

connector	A pointer to the SRMConnector instance.
buffer	The buffer to scan, or `NULL` to restore the default connector framebuffers.

Returns: 1 if the custom buffer will be scanned, 0 otherwise.

◆ srmConnectorIsNonDesktop()

UInt8 srmConnectorIsNonDesktop ( SRMConnector * connector )

Checks if the connector is not intended for desktop usage.

Some connectors, such as VR headsets, set this property to 1 to indicate they are not meant for desktop use.

Returns: 1 if not meant for desktop usage, 0 if meant for desktop or if disconnected.

Detailed Description

Rendering

Modes

Enumerations

Functions

Typedef Documentation

◆ SRMConnector

Enumeration Type Documentation

◆ SRM_PRESENTATION_TIME_FLAGS

◆ SRM_CONNECTOR_STATE

◆ SRM_CONNECTOR_SUBPIXEL

◆ SRM_CONNECTOR_CONTENT_TYPE

Function Documentation

◆ srmConnectorSetUserData()

◆ srmConnectorGetUserData()

◆ srmConnectorGetDevice()

◆ srmConnectorGetRendererDevice()

◆ srmConnectorGetID()

◆ srmConnectorGetState()

◆ srmConnectorIsConnected()

◆ srmConnectorGetmmWidth()

◆ srmConnectorGetmmHeight()

◆ srmConnectorGetType()

◆ srmConnectorGetName()

◆ srmConnectorGetManufacturer()

◆ srmConnectorGetModel()

◆ srmConnectorGetEncoders()

◆ srmConnectorGetModes()

◆ srmConnectorHasHardwareCursor()

◆ srmConnectorSetCursor()

◆ srmConnectorSetCursorPos()

◆ srmConnectorGetCurrentEncoder()

◆ srmConnectorGetCurrentCrtc()

◆ srmConnectorGetCurrentPrimaryPlane()

◆ srmConnectorGetCurrentCursorPlane()

◆ srmConnectorGetPreferredMode()

◆ srmConnectorGetCurrentMode()

◆ srmConnectorSetMode()

◆ srmConnectorInitialize()

◆ srmConnectorRepaint()

◆ srmConnectorUninitialize()

◆ srmConnectorSuspend()

◆ srmConnectorResume()

◆ srmConnectorGetFramebufferID()

◆ srmConnectorGetContext()

◆ srmConnectorGetCurrentBufferIndex()

◆ srmConnectorGetBuffersCount()

◆ srmConnectorGetBuffer()

◆ srmConnectorHasBufferDamageSupport()

◆ srmConnectorSetBufferDamage()

◆ srmConnectorSetBufferDamageBoxes()

◆ srmConnectorGetSubPixel()

◆ srmConnectorGetGammaSize()

◆ srmConnectorSetGamma()

◆ srmConnectorHasVSyncControlSupport()

◆ srmConnectorIsVSyncEnabled()

◆ srmConnectorEnableVSync()

◆ srmConnectorSetRefreshRateLimit()

◆ srmConnectorGetRefreshRateLimit()

◆ srmConnectorGetPresentationClock()

◆ srmConnectorGetPresentationTime()

◆ srmConnectorSetContentType()

◆ srmConnectorGetContentType()

◆ srmConnectorSetCustomScanoutBuffer()

◆ srmConnectorIsNonDesktop()