SRM  v0.10.0-1
Simple Rendering Manager
SRMBuffer

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

SRMBuffersrmBufferCreateFromGBM (SRMCore *core, struct gbm_bo *bo)
 Creates an SRMBuffer from a GBM bo. More...
 
SRMBuffersrmBufferCreateFromDMA (SRMCore *core, SRMDevice *allocator, SRMBufferDMAData *dmaPlanes)
 Creates an SRMBuffer from Direct Memory Access (DMA) planes. More...
 
SRMBuffersrmBufferCreateFromCPU (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...
 
SRMBuffersrmBufferCreateFromWaylandDRM (SRMCore *core, void *wlBuffer)
 Creates an SRMBuffer from a Wayland wl_drm buffer. More...
 
SRMBuffersrmBufferCreateGLTextureWrapper (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 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...
 
SRMDevicesrmBufferGetAllocatorDevice (SRMBuffer *buffer)
 Retrieves the allocator device associated with an SRMBuffer. More...
 

Typedef Documentation

◆ SRMBuffer

typedef struct SRMBufferStruct SRMBuffer

Enumeration Type Documentation

◆ 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

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
corePointer to the SRMCore instance.
boPointer 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
corePointer to the SRMCore instance.
allocatorPointer to the SRMDevice responsible for memory allocation. Use NULL to enable texture sharing across all devices (GPUs).
dmaPlanesPointer 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
corePointer to the SRMCore instance.
allocatorPointer to the SRMDevice responsible for memory allocation. Use NULL to enable texture sharing across all devices (GPUs).
widthWidth of the src buffer.
heightHeight of the src buffer.
strideStride (row pitch) of the src buffer in bytes.
pixelsPointer to the pixel data.
formatFormat 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
corePointer to the SRMCore instance.
wlBufferPointer 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
deviceThe SRMDevice whose EGLDisplay was used to create the texture.
idThe OpenGL texture ID of the existing texture.
targetThe target for the texture (e.g., GL_TEXTURE_2D or GL_TEXTURE_EXTERNAL_OES).
formatThe DRM format of the texture.
widthThe width of the texture in pixels.
heightThe height of the texture in pixels.
transferOwnershipIf 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
bufferPointer 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
devicePointer to the SRMDevice representing the specific device (GPU).
bufferPointer 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
bufferPointer 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
deviceThe device whose EGLDisplay is used to create the image.
bufferPointer 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
bufferPointer to the SRMBuffer to write data to.
strideStride of the source pixel data.
dstXX-coordinate of the top-left corner of the destination region.
dstYY-coordinate of the top-left corner of the destination region.
dstWidthWidth of the destination region.
dstHeightHeight of the destination region.
pixelsPointer within the source buffer to copy from (not affected by dstX and dstY).
Returns
1 on success, or 0 on failure.

◆ 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
bufferPointer to the SRMBuffer to read data from.
srcXX-coordinate of the top-left corner of the source region.
srcYY-coordinate of the top-left corner of the source region.
srcWWidth of the source region.
srcHHeight of the source region.
dstXX-coordinate of the top-left corner of the destination region in the destination buffer.
dstYY-coordinate of the top-left corner of the destination region in the destination buffer.
dstStrideStride (row pitch) of the destination buffer.
dstBufferPointer 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
bufferPointer 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
bufferPointer 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
bufferPointer 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
bufferPointer to the SRMBuffer.
Returns
Pointer to the SRMDevice responsible for memory allocation, or NULL on failure.