OpenGL texture shared across GPUs. More...

Detailed Description

OpenGL texture shared across GPUs.

An SRMBuffer encapsulates an OpenGL ES 2.0 texture that is shared across multiple GPUs. It can be created from a variety of sources including DMA planes, main memory, GBM bo buffers, and more. This module provides functions to manage and use such shared textures.

Note: Buffers can be shared across all GPUs only if they adhere to the formats and modifiers specified in srmCoreGetSharedDMATextureFormats.

Enumerations
enum	SRM_BUFFER_CAP
	Enumerates the capabilities of an SRMBuffer. More...

enum	SRM_BUFFER_SRC
	Enumerates the possible sources of an SRMBuffer. More...

Functions
SRMBuffer *	srmBufferCreateFromGBM (SRMCore core, struct gbm_bo bo)
	Creates an SRMBuffer from a GBM bo. More...

SRMBuffer *	srmBufferCreateFromDMA (SRMCore core, SRMDevice allocator, SRMBufferDMAData *dmaPlanes)
	Creates an SRMBuffer from Direct Memory Access (DMA) planes. More...

SRMBuffer *	srmBufferCreateFromCPU (SRMCore core, SRMDevice allocator, UInt32 width, UInt32 height, UInt32 stride, const void *pixels, SRM_BUFFER_FORMAT format)
	Creates an SRMBuffer from main memory buffer. More...

SRMBuffer *	srmBufferCreateFromWaylandDRM (SRMCore core, void wlBuffer)
	Creates an SRMBuffer from a Wayland `wl_drm` buffer. More...

SRMBuffer *	srmBufferCreateGLTextureWrapper (SRMDevice *device, GLuint id, GLenum target, SRM_BUFFER_FORMAT format, UInt32 width, UInt32 height, UInt8 transferOwnership)
	Creates a wrapper for an already created OpenGL texture. More...

void	srmBufferDestroy (SRMBuffer *buffer)
	Destroys an SRMBuffer. More...

GLuint	srmBufferGetTextureID (SRMDevice device, SRMBuffer buffer)
	Retrieves an OpenGL texture ID associated with an SRMBuffer for a specific device (GPU). More...

GLenum	srmBufferGetTextureTarget (SRMBuffer *buffer)
	Gets the OpenGL texture target associated with an SRMBuffer. More...

EGLImage	srmBufferGetEGLImage (SRMDevice device, SRMBuffer buffer)
	Gets an `EGLImage` associated with a specific device. More...

UInt8	srmBufferWrite (SRMBuffer buffer, UInt32 stride, UInt32 dstX, UInt32 dstY, UInt32 dstWidth, UInt32 dstHeight, const void pixels)
	Writes pixel data to an SRMBuffer. More...

UInt8	srmBufferWrite2Begin (SRMBuffer *buffer)
	Prepares an SRMBuffer for writing. More...

UInt8	srmBufferWrite2Update (SRMBuffer buffer, UInt32 stride, UInt32 dstX, UInt32 dstY, UInt32 dstWidth, UInt32 dstHeight, const void pixels)
	Writes pixel data to the buffer. More...

UInt8	srmBufferWrite2End (SRMBuffer *buffer)
	Finalizes the write operation to the buffer. More...

UInt8	srmBufferRead (SRMBuffer buffer, Int32 srcX, Int32 srcY, Int32 srcW, Int32 srcH, Int32 dstX, Int32 dstY, Int32 dstStride, UInt8 dstBuffer)
	Reads pixel data from an SRMBuffer. More...

UInt32	srmBufferGetWidth (SRMBuffer *buffer)
	Retrieves the width of an SRMBuffer. More...

UInt32	srmBufferGetHeight (SRMBuffer *buffer)
	Retrieves the height of an SRMBuffer. More...

SRM_BUFFER_FORMAT	srmBufferGetFormat (SRMBuffer *buffer)
	Retrieves the format of an SRMBuffer. More...

SRMDevice *	srmBufferGetAllocatorDevice (SRMBuffer *buffer)
	Retrieves the allocator device associated with an SRMBuffer. More...

Typedef Documentation

◆ SRMBuffer

typedef struct SRMBufferStruct SRMBuffer

Enumeration Type Documentation

◆ SRM_BUFFER_CAP

enum SRM_BUFFER_CAP

Enumerates the capabilities of an SRMBuffer.

Enumerator
SRM_BUFFER_CAP_READ	Capability to read from the buffer.
SRM_BUFFER_CAP_WRITE	Capability to write to the buffer.
SRM_BUFFER_CAP_MAP	Capability to map the buffer.

◆ SRM_BUFFER_SRC

enum SRM_BUFFER_SRC

Enumerates the possible sources of an SRMBuffer.

Enumerator
SRM_BUFFER_SRC_CPU	The buffer source is main memory.
SRM_BUFFER_SRC_DMA	The buffer source are DMA planes.
SRM_BUFFER_SRC_WL_DRM	The buffer source is a Wayland `wl_drm` buffer.
SRM_BUFFER_SRC_GBM	The buffer source is a bo from the Generic Buffer Manager (GBM) library.
SRM_BUFFER_SRC_GL	The buffer source is an already existing OpenGL texture.

Function Documentation

◆ srmBufferCreateFromGBM()

SRMBuffer* srmBufferCreateFromGBM	(	SRMCore *	core,
		struct gbm_bo *	bo
	)

Creates an SRMBuffer from a GBM bo.

This function creates an SRMBuffer object using the provided Generic Buffer Management (GBM) buffer object.

Warning: The struct gbm_bo must remain valid during the buffer lifetime. It is not destroyed when the buffer is destroyed and must be destroyed manually.

Note: Depending on the backing storage of the bo, the buffer may not be shareable across all devices.

Parameters

core	Pointer to the SRMCore instance.
bo	Pointer to the GBM buffer object.

Returns: A pointer to the created SRMBuffer, or NULL on failure.

◆ srmBufferCreateFromDMA()

SRMBuffer* srmBufferCreateFromDMA	(	SRMCore *	core,
		SRMDevice *	allocator,
		SRMBufferDMAData *	dmaPlanes
	)

Creates an SRMBuffer from Direct Memory Access (DMA) planes.

This function creates an SRMBuffer object using the provided DMA planes data, which includes information about width, height, format, stride of planes, and more.

Parameters

core	Pointer to the SRMCore instance.
allocator	Pointer to the SRMDevice responsible for memory allocation. Use `NULL` to enable texture sharing across all devices (GPUs).
dmaPlanes	Pointer to the SRMBufferDMAData containing DMA planes data.

Note: When NULL is passed as the allocator device, srmCoreGetAllocatorDevice() is used.
Buffers created from this device are shared across all GPUs and can be used for rendering in all connectors.

Returns: A pointer to the created SRMBuffer, or NULL on failure.

◆ srmBufferCreateFromCPU()

SRMBuffer* srmBufferCreateFromCPU	(	SRMCore *	core,
		SRMDevice *	allocator,
		UInt32	width,
		UInt32	height,
		UInt32	stride,
		const void *	pixels,
		SRM_BUFFER_FORMAT	format
	)

Creates an SRMBuffer from main memory buffer.

This function creates an SRMBuffer object using a main memory buffer, allowing you to define the buffer's width, height, stride, pixel data, and format.

Parameters

core	Pointer to the SRMCore instance.
allocator	Pointer to the SRMDevice responsible for memory allocation. Use `NULL` to enable texture sharing across all devices (GPUs).
width	Width of the src buffer.
height	Height of the src buffer.
stride	Stride (row pitch) of the src buffer in bytes.
pixels	Pointer to the pixel data.
format	Format of the pixel data.

Note: When NULL is passed as the allocator device, srmCoreGetAllocatorDevice() is used.
Buffers created from this device are shared across all GPUs and can be used for rendering in all connectors.

Returns: A pointer to the created SRMBuffer, or NULL on failure.

◆ srmBufferCreateFromWaylandDRM()

SRMBuffer* srmBufferCreateFromWaylandDRM	(	SRMCore *	core,
		void *	wlBuffer
	)

Creates an SRMBuffer from a Wayland wl_drm buffer.

This function creates an SRMBuffer object using the provided Wayland wl_drm buffer.

Note: Depending on the backing storage of the bo, the buffer may not be shared across all devices.

Parameters

core	Pointer to the SRMCore instance.
wlBuffer	Pointer to the Wayland DRM buffer.

Returns: A pointer to the created SRMBuffer, or NULL on failure.

◆ srmBufferCreateGLTextureWrapper()

SRMBuffer* srmBufferCreateGLTextureWrapper	(	SRMDevice *	device,
		GLuint	id,
		GLenum	target,
		SRM_BUFFER_FORMAT	format,
		UInt32	width,
		UInt32	height,
		UInt8	transferOwnership
	)

Creates a wrapper for an already created OpenGL texture.

This function allows you to use an existing OpenGL texture within the SRM framework.

Note: The texture can only be used by the provided SRMDevice.

Parameters

device	The SRMDevice whose `EGLDisplay` was used to create the texture.
id	The OpenGL texture ID of the existing texture.
target	The target for the texture (e.g., `GL_TEXTURE_2D` or `GL_TEXTURE_EXTERNAL_OES`).
format	The DRM format of the texture.
width	The width of the texture in pixels.
height	The height of the texture in pixels.
transferOwnership	If non-zero, the texture will be destroyed when srmBufferDestroy() is called.

Returns: A pointer to the created SRMBuffer, or NULL on failure.

◆ srmBufferDestroy()

void srmBufferDestroy ( SRMBuffer * buffer )

Destroys an SRMBuffer.

This function destroys an SRMBuffer, freeing associated resources.

Parameters

buffer Pointer to the SRMBuffer to be destroyed.

◆ srmBufferGetTextureID()

GLuint srmBufferGetTextureID	(	SRMDevice *	device,
		SRMBuffer *	buffer
	)

Retrieves an OpenGL texture ID associated with an SRMBuffer for a specific device (GPU).

This function retrieves the OpenGL texture ID that corresponds to the given SRMBuffer for the specified device (GPU).

Note: You probably will call this function when doing rendering on a connector. To get the connector's renderer device, use srmConnectorGetRendererDevice().

Parameters

device	Pointer to the SRMDevice representing the specific device (GPU).
buffer	Pointer to the SRMBuffer for which the texture ID is requested.

Returns: The OpenGL texture ID associated with the SRMBuffer and device, or 0 on failure.

◆ srmBufferGetTextureTarget()

GLenum srmBufferGetTextureTarget ( SRMBuffer * buffer )

Gets the OpenGL texture target associated with an SRMBuffer.

This function retrieves the OpenGL texture target associated with the provided SRMBuffer.

For textures using the GL_TEXTURE_EXTERNAL_OES target, rendering requires the utilization of a custom shader, as demonstrated in the following example:

Fragment shader example

#extension GL_OES_EGL_image_external : require
uniform samplerExternalOES texture;
varying vec2 v_texcoord;
 
void main()
{
   gl_FragColor = texture2D(texture, v_texcoord);
}

Parameters

buffer Pointer to the SRMBuffer for which the texture target is needed.

Returns: The associated OpenGL texture target, which can be either GL_TEXTURE_2D or GL_TEXTURE_EXTERNAL_OES.

◆ srmBufferGetEGLImage()

EGLImage srmBufferGetEGLImage	(	SRMDevice *	device,
		SRMBuffer *	buffer
	)

Gets an EGLImage associated with a specific device.

The returned image is owned by the SRMBuffer and should not be destroyed manually.

Parameters

device	The device whose `EGLDisplay` is used to create the image.
buffer	Pointer to the SRMBuffer.

Returns: An EGLImage associated with the SRMDevice or EGL_NO_IMAGE on failure.

◆ srmBufferWrite()

UInt8 srmBufferWrite	(	SRMBuffer *	buffer,
		UInt32	stride,
		UInt32	dstX,
		UInt32	dstY,
		UInt32	dstWidth,
		UInt32	dstHeight,
		const void *	pixels
	)

Writes pixel data to an SRMBuffer.

This function writes pixel data to the specified region of an SRMBuffer.

Note: The source and destination buffer pixel format must match.

Parameters

buffer	Pointer to the SRMBuffer to write data to.
stride	Stride of the source pixel data.
dstX	X-coordinate of the top-left corner of the destination region.
dstY	Y-coordinate of the top-left corner of the destination region.
dstWidth	Width of the destination region.
dstHeight	Height of the destination region.
pixels	Pointer within the source buffer to copy from (not affected by dstX and dstY).

Returns: 1 on success, or 0 on failure.

◆ srmBufferWrite2Begin()

UInt8 srmBufferWrite2Begin ( SRMBuffer * buffer )

Prepares an SRMBuffer for writing.

The srmBufferWrite2 functions provide the same functionality as srmBufferWrite(), but they allow for multiple writes without requiring immediate internal syncing, yielding better performance.

If 1 is returned, calling any function except for srmBufferWrite2Update() or srmBufferWrite2End() will cause a deadlock.

If 0 is returned, it means it failed, and neither srmBufferWrite2Update() nor srmBufferWrite2End() should be called.

Parameters

buffer Pointer to the SRMBuffer to write data to.

Returns: 1 on success, or 0 on failure.

◆ srmBufferWrite2Update()

UInt8 srmBufferWrite2Update	(	SRMBuffer *	buffer,
		UInt32	stride,
		UInt32	dstX,
		UInt32	dstY,
		UInt32	dstWidth,
		UInt32	dstHeight,
		const void *	pixels
	)

Writes pixel data to the buffer.

This function can only be called if srmBufferWrite2Begin() was previously called and returned 1. The parameters are the same as those defined in srmBufferWrite().

Returns: 1 on success, or 0 on failure.

◆ srmBufferWrite2End()

UInt8 srmBufferWrite2End ( SRMBuffer * buffer )

Finalizes the write operation to the buffer.

This function should be called after completing all write operations initiated by srmBufferWrite2Begin(). It ensures that any pending writes are completed and the buffer is in a consistent state.

Parameters

buffer Pointer to the SRMBuffer that was used for writing.

Returns: 1 on success, or 0 if srmBufferWrite2Begin() wasn't called or failed.

◆ srmBufferRead()

UInt8 srmBufferRead	(	SRMBuffer *	buffer,
		Int32	srcX,
		Int32	srcY,
		Int32	srcW,
		Int32	srcH,
		Int32	dstX,
		Int32	dstY,
		Int32	dstStride,
		UInt8 *	dstBuffer
	)

Reads pixel data from an SRMBuffer.

This function reads pixel data from the specified region of an SRMBuffer and copies it to the destination buffer.

Note: On failure, the texture should still be readable by attaching the texture ID returned by srmBufferGetTextureID() to a GL framebuffer and using glReadPixels().

Parameters

buffer	Pointer to the SRMBuffer to read data from.
srcX	X-coordinate of the top-left corner of the source region.
srcY	Y-coordinate of the top-left corner of the source region.
srcW	Width of the source region.
srcH	Height of the source region.
dstX	X-coordinate of the top-left corner of the destination region in the destination buffer.
dstY	Y-coordinate of the top-left corner of the destination region in the destination buffer.
dstStride	Stride (row pitch) of the destination buffer.
dstBuffer	Pointer to the destination buffer where the pixel data will be copied.

Returns: 1 on success, or 0 on failure.

◆ srmBufferGetWidth()

UInt32 srmBufferGetWidth ( SRMBuffer * buffer )

Retrieves the width of an SRMBuffer.

This function retrieves the width of the specified SRMBuffer.

Parameters

buffer Pointer to the SRMBuffer.

Returns: The width of the SRMBuffer.

◆ srmBufferGetHeight()

UInt32 srmBufferGetHeight ( SRMBuffer * buffer )

Retrieves the height of an SRMBuffer.

This function retrieves the height of the specified SRMBuffer.

Parameters

buffer Pointer to the SRMBuffer.

Returns: The height of the SRMBuffer.

◆ srmBufferGetFormat()

SRM_BUFFER_FORMAT srmBufferGetFormat ( SRMBuffer * buffer )

Retrieves the format of an SRMBuffer.

This function retrieves the pixel format of the specified SRMBuffer.

Parameters

buffer Pointer to the SRMBuffer.

Returns: The SRM_BUFFER_FORMAT representing the pixel format of the SRMBuffer.

◆ srmBufferGetAllocatorDevice()

SRMDevice* srmBufferGetAllocatorDevice ( SRMBuffer * buffer )

Retrieves the allocator device associated with an SRMBuffer.

This function retrieves the SRMDevice responsible for memory allocation associated with the specified SRMBuffer.

Parameters

buffer Pointer to the SRMBuffer.

Returns: Pointer to the SRMDevice responsible for memory allocation, or NULL on failure.

Detailed Description

Enumerations

Functions

Typedef Documentation

◆ SRMBuffer

Enumeration Type Documentation

◆ SRM_BUFFER_CAP

◆ SRM_BUFFER_SRC

Function Documentation

◆ srmBufferCreateFromGBM()

◆ srmBufferCreateFromDMA()

◆ srmBufferCreateFromCPU()

◆ srmBufferCreateFromWaylandDRM()

◆ srmBufferCreateGLTextureWrapper()

◆ srmBufferDestroy()

◆ srmBufferGetTextureID()

◆ srmBufferGetTextureTarget()

Fragment shader example

◆ srmBufferGetEGLImage()

◆ srmBufferWrite()

◆ srmBufferWrite2Begin()

◆ srmBufferWrite2Update()

◆ srmBufferWrite2End()

◆ srmBufferRead()

◆ srmBufferGetWidth()

◆ srmBufferGetHeight()

◆ srmBufferGetFormat()

◆ srmBufferGetAllocatorDevice()