Core functionality of SRM. More...

Detailed Description

Core functionality of SRM.

The SRMCore is in charge of setting up all DRM devices, finding the best allocator device, defining the rendering mode of each device, letting you listen to udev hotplugging events, and more.

Warning: You must create a single SRMCore instance per process, creating more than one could lead to undefined behavior.

Framebuffer damage

PRIME, DUMB and CPU modes can greatly benefit from receiving information about the changes occurring in the buffer within a frame, commonly known as "damage." By providing this damage information, we can optimize the performance of these modes. To define the generated damage, after rendering within a paintGL() event, you can add an array of rectangles (SRMRect) with the damage area using the srmConnectorSetBufferDamage() function. It is important to ensure that the coordinates of these rectangles originate from the top-left corner of the framebuffer and do not extend beyond its boundaries to avoid segmentation errors. The ITSELF mode does not benefit from buffer damages, and therefore, calling the function in that case is a no-op. To determine if a connector supports buffer damages, use the srmConnectorHasBufferDamageSupport() function.

Functions
SRMCore *	srmCoreCreate (SRMInterface interface, void userData)
	Creates a new SRMCore instance. More...

UInt8	srmCoreSuspend (SRMCore *core)
	Temporarily suspends SRM. More...

UInt8	srmCoreResume (SRMCore *core)
	Resumes SRM. More...

UInt8	srmCoreIsSuspended (SRMCore *core)
	Check if SRMCore is currently suspended. More...

void *	srmCoreGetUserData (SRMCore *core)
	Get the user data associated with the SRMCore instance. More...

void	srmCoreSetUserData (SRMCore core, void userData)
	Set user-defined data for the SRMCore instance. More...

SRMList *	srmCoreGetDevices (SRMCore *core)
	Get a list of all available devices (SRMDevice). More...

SRMVersion *	srmCoreGetVersion (SRMCore *core)
	Get the SRM version of the core. More...

SRMDevice *	srmCoreGetAllocatorDevice (SRMCore *core)
	Get the allocator device. More...

Int32	srmCoreGetMonitorFD (SRMCore *core)
	Get a pollable udev monitor file descriptor for listening to hotplugging events. More...

Int32	srmCoreProcessMonitor (SRMCore *core, Int32 msTimeout)
	Dispatch pending udev monitor events or block until an event occurs or a timeout is reached. More...

SRMListener *	srmCoreAddDeviceCreatedEventListener (SRMCore core, void(callback)(SRMListener , SRMDevice ), void *userData)
	Registers a new listener to be invoked when a new device (GPU) becomes available. More...

SRMListener *	srmCoreAddDeviceRemovedEventListener (SRMCore core, void(callback)(SRMListener , SRMDevice ), void *userData)
	Registers a new listener to be invoked when an already available device (GPU) becomes unavailable. More...

SRMListener *	srmCoreAddConnectorPluggedEventListener (SRMCore core, void(callback)(SRMListener , SRMConnector ), void *userData)
	Registers a new listener to be invoked when a new connector is plugged. More...

SRMListener *	srmCoreAddConnectorUnpluggedEventListener (SRMCore core, void(callback)(SRMListener , SRMConnector ), void *userData)
	Registers a new listener to be invoked when an already plugged connector is unplugged. More...

const SRMEGLCoreExtensions *	srmCoreGetEGLExtensions (SRMCore *core)
	Returns a structure with boolean variables indicating which EGL extensions are available. More...

const SRMEGLCoreFunctions *	srmCoreGetEGLFunctions (SRMCore *core)
	Returns a structure with pointers to many available EGL functions. More...

SRMList *	srmCoreGetSharedDMATextureFormats (SRMCore *core)
	Get a list of DMA formats supported by all rendering GPUs. More...

void	srmCoreDestroy (SRMCore *core)
	Uninitializes all initialized connectors, removes all resources associated, closes all DRM devices, and listeners. More...

Typedef Documentation

◆ SRMCore

typedef struct SRMCoreStruct SRMCore

Function Documentation

◆ srmCoreCreate()

SRMCore* srmCoreCreate	(	SRMInterface *	interface,
		void *	userData
	)

Creates a new SRMCore instance.

Creates a new SRMCore instance, which will scan and open all available DRM devices using the provided interface, find the best allocator device, and configure its rendering modes.

Parameters

interface	A pointer to the SRMInterface that provides access to DRM devices.
userData	A pointer to the user data to associate with the SRMCore instance.

Returns: A pointer to the newly created SRMCore instance on success, or NULL on failure.

Note: The caller is responsible for releasing the SRMCore instance using srmCoreDestroy() when no longer needed.

◆ srmCoreSuspend()

UInt8 srmCoreSuspend ( SRMCore * core )

Temporarily suspends SRM.

This function temporarily suspends all connector rendering threads and evdev events within SRM.
It should be used when switching to another session in a multi-session system.
While the core is suspended, SRM no longer acts as the DRM master, and KMS operations cannot be performed.
For guidance on enabling multi-session functionality using libseat, please refer to the srm-multi-session example.

Note: Pending hotplugging events will be emitted once the core is resumed.

Parameters

core	A pointer to the SRMCore instance.

Returns: Returns 1 on success and 0 if the operation fails.

◆ srmCoreResume()

UInt8 srmCoreResume ( SRMCore * core )

Resumes SRM.

This function resumes a previously suspended SRMCore, allowing connectors rendering threads and evdev events to continue processing. It should be used after calling srmCoreSuspend() to bring the SRMCore back to an active state.

Parameters

core	A pointer to the SRMCore instance to resume.

Returns: Returns 1 on success and 0 if the operation fails.

◆ srmCoreIsSuspended()

UInt8 srmCoreIsSuspended ( SRMCore * core )

Check if SRMCore is currently suspended.

This function checks whether an SRMCore instance is currently in a suspended state, meaning that connector rendering threads and evdev events are temporarily halted.

Parameters

core	A pointer to the SRMCore instance to check.

Returns: Returns 1 if the SRMCore is suspended, and 0 if it is active.

◆ srmCoreGetUserData()

void* srmCoreGetUserData ( SRMCore * core )

Get the user data associated with the SRMCore instance.

Parameters

core	A pointer to the SRMCore instance.

Note: This is the same user data passed in srmCoreCreate().

Returns: A pointer to the user data associated with the SRMCore instance.

◆ srmCoreSetUserData()

void srmCoreSetUserData	(	SRMCore *	core,
		void *	userData
	)

Set user-defined data for the SRMCore instance.

Parameters

core	A pointer to the SRMCore instance.
userData	A pointer to the user data to associate with the SRMCore instance.

Note: This replaces the user data passed in srmCoreCreate().

◆ srmCoreGetDevices()

SRMList* srmCoreGetDevices ( SRMCore * core )

Get a list of all available devices (SRMDevice).

Parameters

core	A pointer to the SRMCore instance.

Returns: A list containing all available SRMDevice instances.

◆ srmCoreGetVersion()

SRMVersion* srmCoreGetVersion ( SRMCore * core )

Get the SRM version of the core.

Parameters

core	A pointer to the SRMCore instance.

Returns: A pointer to the core's SRMVersion instance.

◆ srmCoreGetAllocatorDevice()

SRMDevice* srmCoreGetAllocatorDevice ( SRMCore * core )

Get the allocator device.

The allocator device is responsible for creating buffers (textures) that can be shared among all devices.

Parameters

core	A pointer to the SRMCore instance.

Returns: A pointer to the allocator SRMDevice instance.

◆ srmCoreGetMonitorFD()

Int32 srmCoreGetMonitorFD ( SRMCore * core )

Get a pollable udev monitor file descriptor for listening to hotplugging events.

The returned fd can be used to monitor devices and connectors hotplugging events using polling mechanisms.
Use srmCoreProcessMonitor() to dispatch pending events.

Parameters

core	A pointer to the SRMCore instance.

Returns: The file descriptor for monitoring hotplugging events.

◆ srmCoreProcessMonitor()

Int32 srmCoreProcessMonitor	(	SRMCore *	core,
		Int32	msTimeout
	)

Dispatch pending udev monitor events or block until an event occurs or a timeout is reached.

Passing a timeout value of -1 makes the function block indefinitely until an event occurs.

Parameters

core	A pointer to the SRMCore instance.
msTimeout	The timeout value in milliseconds. Use -1 to block indefinitely.

Returns: (>= 0) on success, or -1 on error.

◆ srmCoreAddDeviceCreatedEventListener()

SRMListener* srmCoreAddDeviceCreatedEventListener	(	SRMCore *	core,
		void()(SRMListener , SRMDevice *)	callback,
		void *	userData
	)

Registers a new listener to be invoked when a new device (GPU) becomes available.

Parameters

core	A pointer to the SRMCore instance.
callback	A callback function to be called when a new device is available.
userData	A pointer to user-defined data to be passed to the callback.

Returns: A pointer to the newly registered SRMListener instance for device creation events.

◆ srmCoreAddDeviceRemovedEventListener()

SRMListener* srmCoreAddDeviceRemovedEventListener	(	SRMCore *	core,
		void()(SRMListener , SRMDevice *)	callback,
		void *	userData
	)

Registers a new listener to be invoked when an already available device (GPU) becomes unavailable.

Parameters

core	A pointer to the SRMCore instance.
callback	A callback function to be called when a device becomes unavailable.
userData	A pointer to user-defined data to be passed to the callback.

Returns: A pointer to the newly registered SRMListener instance for device removal events.

◆ srmCoreAddConnectorPluggedEventListener()

SRMListener* srmCoreAddConnectorPluggedEventListener	(	SRMCore *	core,
		void()(SRMListener , SRMConnector *)	callback,
		void *	userData
	)

Registers a new listener to be invoked when a new connector is plugged.

Parameters

core	A pointer to the SRMCore instance.
callback	A callback function to be called when a new connector is plugged.
userData	A pointer to user-defined data to be passed to the callback.

Returns: A pointer to the newly registered SRMListener instance for connector plugged events.

◆ srmCoreAddConnectorUnpluggedEventListener()

SRMListener* srmCoreAddConnectorUnpluggedEventListener	(	SRMCore *	core,
		void()(SRMListener , SRMConnector *)	callback,
		void *	userData
	)

Registers a new listener to be invoked when an already plugged connector is unplugged.

Parameters

core	A pointer to the SRMCore instance.
callback	A callback function to be called when a connector is unplugged.
userData	A pointer to user-defined data to be passed to the callback.

Returns: A pointer to the newly registered SRMListener instance for connector unplugged events.

◆ srmCoreGetEGLExtensions()

const SRMEGLCoreExtensions* srmCoreGetEGLExtensions ( SRMCore * core )

Returns a structure with boolean variables indicating which EGL extensions are available.

Parameters

core	A pointer to the SRMCore instance.

Returns: A pointer to the SRMEGLCoreExtensions structure indicating the availability of EGL extensions.

◆ srmCoreGetEGLFunctions()

const SRMEGLCoreFunctions* srmCoreGetEGLFunctions ( SRMCore * core )

Returns a structure with pointers to many available EGL functions.

Parameters

core	A pointer to the SRMCore instance.

Returns: A pointer to the SRMEGLCoreFunctions structure containing pointers to avaliable EGL functions.

◆ srmCoreGetSharedDMATextureFormats()

SRMList* srmCoreGetSharedDMATextureFormats ( SRMCore * core )

Get a list of DMA formats supported by all rendering GPUs.

Parameters

core	A pointer to the SRMCore instance.

Returns: A list containing supported DMA texture formats (SRMFormat).

◆ srmCoreDestroy()

void srmCoreDestroy ( SRMCore * core )

Uninitializes all initialized connectors, removes all resources associated, closes all DRM devices, and listeners.

Note: Buffers must be destroyed manually before calling this method.

Parameters

core	A pointer to the SRMCore instance to be destroyed.