RamsesRenderer is the main renderer component which provides API to configure and control the way content will be rendered on display(s). More...

#include <RamsesRenderer.h>

Inheritance diagram for ramses::RamsesRenderer:

[legend]

Collaboration diagram for ramses::RamsesRenderer:

[legend]

Public Member Functions
status_t	doOneLoop ()
	Prepare content to be rendered in next frame and render next frame. More...

status_t	startThread ()
	Starts update and render loop in threaded mode. More...

status_t	stopThread ()
	Stops thread(s) running the update and render of displays. More...

bool	isThreadRunning () const
	Get the current state of rendering thread(s) running. More...

status_t	setMaximumFramerate (float maximumFramerate)
	Sets the maximum frame rate per second for the update/render loop when in threaded mode. More...

float	getMaximumFramerate () const
	Get the current value for maximum frame rate per second currently set (setMaximumFramerate). More...

status_t	setLoopMode (ELoopMode loopMode)
	Sets the mode of operation for render loop. More...

ELoopMode	getLoopMode () const
	Get the current value for loop mode set using setLoopMode. More...

status_t	setFrameTimerLimits (uint64_t limitForSceneResourcesUpload, uint64_t limitForClientResourcesUpload, uint64_t limitForOffscreenBufferRender)
	Sets time limits for time-out of different sections of render and update loop. More...

status_t	setPendingFlushLimits (uint32_t forceApplyFlushLimit, uint32_t forceUnsubscribeSceneLimit)
	Sets the number of pending flushes accepted before force-applying them to their scene, or forcefully insubscribing the scene. More...

status_t	setSkippingOfUnmodifiedBuffers (bool enable=true)
	Enable or disable skipping of rendering of unmodified buffers. By default the renderer does not re-render buffers (framebuffer or offscreen buffer) if there was no change to any of the content assigned to the buffer. This can save hardware resources or free up resources for rendering of other buffers. It can be however desired to disable such optimization for profiling of worst case scenario or debugging of a graphical glitch. More...

displayId_t	createDisplay (const DisplayConfig &config)
	Creates a display based on provided display config. Creation of a display is an asynchronous action and the display will be created during the next render loop. The result of the createDisplay can be retrieved via dispatchEvents which will trigger a callback after the asynchronous action was processed. More...

status_t	destroyDisplay (displayId_t displayId)
	Destroy a display. Destruction of a display is an asynchronous action and the actual display components (window, device, etc.) will be released during the next render loop. The result of the destroyDisplay can be retrieved via dispatchEvents which will trigger a callback with the result after the asynchronous action was processed. More...

displayBufferId_t	getDisplayFramebuffer (displayId_t displayId) const
	Get display's framebuffer ID. Every display upon creation has one framebuffer which can be referenced by a display buffer ID to be used in various API methods that work with either a framebuffer or an offscreen buffer (e.g. RamsesRenderer::setBufferClearColor). More...

displayBufferId_t	createOffscreenBuffer (displayId_t display, uint32_t width, uint32_t height, uint32_t sampleCount=0u)
	Will create an offscreen buffer that can be used to render scenes into (see ramses::RendererSceneControl::setSceneDisplayBufferAssignment) and can be linked as input to a consumer texture sampler (see ramses::RendererSceneControl::linkOffscreenBuffer). More...

displayBufferId_t	createInterruptibleOffscreenBuffer (displayId_t display, uint32_t width, uint32_t height)
	Additional API to create an offscreen buffer as interruptible. (see createOffscreenBuffer) More...

displayBufferId_t	createDmaOffscreenBuffer (displayId_t display, uint32_t width, uint32_t height, uint32_t bufferFourccFormat, uint32_t usageFlags, uint64_t modifier)
	Additional API to create an offscreen buffer using DMA buffer for internal storage. (see createOffscreenBuffer) More...

status_t	getDmaOffscreenBufferFDAndStride (displayId_t display, displayBufferId_t displayBufferId, int &fd, uint32_t &stride) const
	Get the FD and stride for a DMA offscreen buffer previously created on the given display. More...

status_t	destroyOffscreenBuffer (displayId_t display, displayBufferId_t offscreenBuffer)
	Will destroy a previously created offscreen buffer. If there are any consumer texture samplers linked to this buffer, these links will be removed. Offscreen buffer will fail to be destroyed if there are any scenes assigned to it, these scenes have to be first assigned to another buffer or framebuffer or unmapped from display. More...

externalBufferId_t	createExternalBuffer (displayId_t display)
	Creates a buffer using OpenGL External textures for storage. More...

status_t	destroyExternalBuffer (displayId_t display, externalBufferId_t externalBuffer)
	Will destroy a previously created external buffer. If there are any consumer texture samplers linked to this buffer, these links will be removed. More...

bool	getExternalBufferGlId (displayId_t display, externalBufferId_t externalBuffer, uint32_t &textureGlId) const
	Will query the OpenGL texture Id for the external texture used for a created external buffer. More...

status_t	setDisplayBufferClearColor (displayId_t display, displayBufferId_t displayBuffer, float r, float g, float b, float a)
	Sets clear color of a display buffer (display's framebuffer or offscreen buffer). More...

status_t	setExternallyOwnedWindowSize (displayId_t display, uint32_t width, uint32_t height)
	Updates display window size after a resize event on windows not owned by renderer. More...

status_t	readPixels (displayId_t displayId, displayBufferId_t displayBuffer, uint32_t x, uint32_t y, uint32_t width, uint32_t height)
	Triggers an asynchronous read back of a display buffer memory from GPU to system memory. More...

RendererSceneControl *	getSceneControlAPI ()
	Get scene control API. More...

DcsmContentControl *	createDcsmContentControl ()
	Create ramses::DcsmContentControl to control content states. More...

status_t	setSurfaceVisibility (uint32_t surfaceId, bool visibility)
	Set visibility of given surface at the system compositor. More...

status_t	setSurfaceOpacity (uint32_t surfaceId, float opacity)
	Set opacity of given surface at the system compositor. More...

status_t	setSurfaceRectangle (uint32_t surfaceId, int32_t x, int32_t y, int32_t width, int32_t height)
	Set output rectangle of given surface at the system compositor. More...

status_t	setLayerVisibility (uint32_t layerId, bool visibility)
	Set visibility of given layer at the system compositor. More...

status_t	takeSystemCompositorScreenshot (const char *fileName, int32_t screenIviId)
	Trigger the System Compositor to take a screenshot and store it in a file. More...

status_t	updateWarpingMeshData (displayId_t displayId, const WarpingMeshData &newWarpingMeshData)
	Updates the warping mesh for the warping postprocessing based on the new config. More...

status_t	dispatchEvents (IRendererEventHandler &rendererEventHandler)
	Most RamsesRenderer methods push commands to an internal queue which is submitted when calling RamsesRenderer::flush. The commands are then executed during a render loop (RamsesRenderer::doOneLoop or in a render thread if used RamsesRenderer::startThread). Some of these calls result in an event (can be both informational and data). Such events and their result can be retrieved using the dispatchEvents call. IMPORTANT Renderer events must be regularly consumed by calling dispatchEvents() in order to prevent buffer overflow of the internal event queue, even if the application is not interested in those events. More...

status_t	flush ()
	Submits renderer commands (API calls on this instance of RamsesRenderer) since previous flush to be executed in the next renderer update loop. More...

status_t	logRendererInfo ()
	Prints detailed information about renderer state and contents to the log output. More...

	RamsesRenderer (RamsesRendererImpl &)
	Constructor of RamsesRenderer. More...

	RamsesRenderer ()=delete
	Deleted default constructor. More...

	RamsesRenderer (const RamsesRenderer &other)=delete
	Deleted copy constructor. More...

RamsesRenderer &	operator= (const RamsesRenderer &other)=delete
	Deleted copy assignment. More...

Public Member Functions inherited from ramses::StatusObject
status_t	validate () const
	Generates verbose validation of the object. More...

const char *	getValidationReport (EValidationSeverity minSeverity=EValidationSeverity_Info) const
	Provides verbose report in human readable form generated by validate. More...

const char *	getStatusMessage (status_t status) const
	Get the string description for a status provided by a RAMSES API function. More...

	StatusObject (const StatusObject &other)=delete
	Deleted copy constructor. More...

StatusObject &	operator= (const StatusObject &other)=delete
	Deleted copy assignment. More...

Static Public Member Functions
static status_t	setMaximumFramerate (RamsesRenderer &renderer, float maximumFramerate, displayId_t displayId)
	Sets the maximum frame rate per second for the update/render loop when in threaded mode for given display. More...

static displayBufferId_t	createOffscreenBuffer (RamsesRenderer &renderer, displayId_t display, uint32_t width, uint32_t height, uint32_t sampleCount=0u, EDepthBufferType depthBufferType=EDepthBufferType_DepthStencil)
	Will create an offscreen buffer that can be used to render scenes into (see ramses::RendererSceneControl::setSceneDisplayBufferAssignment) and can be linked as input to a consumer texture sampler (see ramses::RendererSceneControl::linkOffscreenBuffer). More...

static displayBufferId_t	createInterruptibleOffscreenBuffer (RamsesRenderer &renderer, displayId_t display, uint32_t width, uint32_t height, EDepthBufferType depthBufferType=EDepthBufferType_DepthStencil)
	Additional API to create an offscreen buffer as interruptible. This allows the renderer to interrupt rendering of scenes to such offscreen buffer if the time budget for rendering is exceeded within a frame (see setFrameTimerLimits). The rendering continues next frame starting from the interruption point. More...

static status_t	setDisplayBufferClearFlags (RamsesRenderer &renderer, displayId_t display, displayBufferId_t displayBuffer, uint32_t clearFlags)
	Sets clear flags for a display buffer (display's framebuffer or offscreen buffer). More...

Public Attributes
class RamsesRendererImpl &	impl

Public Attributes inherited from ramses::StatusObject
class StatusObjectImpl &	impl

Friends
class	RendererFactory
	RendererFactory is the factory for RamsesRenderer. More...

Additional Inherited Members
Protected Member Functions inherited from ramses::StatusObject
	StatusObject (StatusObjectImpl &pimpl)
	Constructor for StatusObject. More...

virtual	~StatusObject ()
	Destructor of the StatusObject. More...

Detailed Description

RamsesRenderer is the main renderer component which provides API to configure and control the way content will be rendered on display(s).

All the commands in this class are put to a queue and submitted only when RamsesRenderer::flush is called, they are then executed asynchronously in the renderer core, the order of execution is preserved. Most of the commands have a corresponding callback which reports the result back to the caller via RamsesRenderer::dispatchEvents. Some commands can fail immediately by returning a status with value other than StatusOK, in such case there will be no callback, because the command will not even be submitted. RamsesRenderer API is not thread-safe.

Examples: ramses-example-local-client-dcsm/src/main.cpp, ramses-example-local-client/src/main.cpp, ramses-example-local-datalink/src/main.cpp, ramses-example-local-displays/src/main.cpp, ramses-example-local-dma-offscreenbuffer/src/main.cpp, ramses-example-local-geometry-shaders/src/main.cpp, ramses-example-local-offscreenbuffer/src/main.cpp, ramses-example-local-pick-handling/src/main.cpp, ramses-example-local-scene-referencing/src/main.cpp, and ramses-example-local-viewport-link/src/main.cpp.

Constructor & Destructor Documentation

◆ RamsesRenderer() [1/3]

ramses::RamsesRenderer::RamsesRenderer ( RamsesRendererImpl & )

explicit

Constructor of RamsesRenderer.

◆ RamsesRenderer() [2/3]

ramses::RamsesRenderer::RamsesRenderer ( )

delete

Deleted default constructor.

◆ RamsesRenderer() [3/3]

ramses::RamsesRenderer::RamsesRenderer ( const RamsesRenderer & other )

delete

Deleted copy constructor.

Parameters

other unused

Member Function Documentation

◆ createDcsmContentControl()

DcsmContentControl* ramses::RamsesRenderer::createDcsmContentControl ( )

Create ramses::DcsmContentControl to control content states.

ramses::DcsmContentControl can be used to control content states (a DCSM content is an abstraction for a scene). In addition ramses::DcsmContentControl handles content states in the DCSM protocol context, it is essentially a combination of renderer scene control API and ramses::DcsmConsumer. There can be only a single instance of ramses::DcsmContentControl within RamsesRenderer. Calling this method more than once will fail. This method will return nullptr in case an internal policy disallows controlling of scenes through this API - this could mean that there is another, incompatible scene control mechanism in use. ramses::DcsmContentControl has its own event dispatching mechanism, see ramses::DcsmContentControl for details.

Obtaining the ramses::DcsmContentControl will disallow usage of different type of scene control (ramses::RendererSceneControl). RamsesRenderer is owner of the ramses::DcsmContentControl API and the pointer stays valid as long as this RamsesRenderer instance is alive. It cannot be destroyed without destroying the RamsesRenderer.

Returns: Pointer to ramses::DcsmContentControl, or nullptr on error

◆ createDisplay()

displayId_t ramses::RamsesRenderer::createDisplay ( const DisplayConfig & config )

Creates a display based on provided display config. Creation of a display is an asynchronous action and the display will be created during the next render loop. The result of the createDisplay can be retrieved via dispatchEvents which will trigger a callback after the asynchronous action was processed.

Parameters

config The display config to create and configure the new display.

Returns: Display id that can be used to refer to the created display. displayId_t::Invalid() in case of error. Display creation can still fail even if a valid display id is returned, the result of the actual creation can be retrieved via dispatchEvents.

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ createDmaOffscreenBuffer()

displayBufferId_t ramses::RamsesRenderer::createDmaOffscreenBuffer	(	displayId_t	display,
		uint32_t	width,
		uint32_t	height,
		uint32_t	bufferFourccFormat,
		uint32_t	usageFlags,
		uint64_t	modifier
	)

Additional API to create an offscreen buffer using DMA buffer for internal storage. (see createOffscreenBuffer)

The created offscreen buffer uses a DMA buffer based on a GBM buffer object for its internal storage, which can be mapped to CPU memory, instead of standard OpenGL textures and render storages. The created offscreen buffer can be rendered into and linked to texture consumers, like other offscreen buffer types. This type of offscreen buffers can be created only if the platform provides the necessary support, and if the render node for creation of GBM device is provided on ramses::DisplayConfig::setPlatformRenderNode.

DMA offscreen buffer can only have a color component, no depth or stencil.

Notes: It is of particular importance to avoid CPU operations on the mapped memory while GPU could be accessing the offscreen buffer's memory for executing asynchronous rendering commands.

If a DMA offscreen buffer is being used by the GPU for rendering operations, it is the responsibility of the user not to attempt accessing the CPU mapped memory for that buffer.
Due to the asynchronous nature of OpenGL and render pipeline execution, an offscreen buffer can still be in use after the call to doOneLoop is finished. It is important to submit the commands to get the offscreen buffer out of the rendering pipeline, then make at least two calls to doOneLoop (in case of double buffering) before accessing the CPU mapped memory for that buffer
An offscreen buffer is a part of the rendering pipeline as long as it is either being used as input, i.e., by linking to a texture consumer via ramses::RendererSceneControl::linkOffscreenBuffer, or being used for output by rendering some scenes into it via ramses::RendererSceneControl::setSceneDisplayBufferAssignment

It is only possible to create DMA offscreen buffers if renderer is running using doOneLoop. Calling this method on a renderer with display threads will fail right away with error status without invoking a callback ramses::IRendererEventHandler::offscreenBufferCreated.

Parameters

[in]	display	Id of display for which the buffer should be created
[in]	width	Width of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	height	Height of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	bufferFourccFormat	Format to be used for underlying storage of the buffer, as specified in drm_fourcc.h on the target platform
[in]	usageFlags	Usage flags used for creation of the underlying GBM buffer object, as specific in enum gbm_bo_flags on the target platform
[in]	modifier	Optional format modifier. If not needed set to DRM_FORMAT_MOD_INVALID.

Returns: Identifier of the created offscreen buffer. In case of unsupported resolution or renderer running in own thread displayBufferId_t::Invalid() will be returned with no renderer event generated. Note that the buffer will be created asynchronously and there will be a renderer event once the operation is finished.

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ createExternalBuffer()

externalBufferId_t ramses::RamsesRenderer::createExternalBuffer ( displayId_t display )

Creates a buffer using OpenGL External textures for storage.

The created buffer uses OpenGL External textures according to the OpenGL extension OES_EGL_image_external. The created texture can be used for compositing platform dependent content from native processes and applications on the target platforms.

In order to provide content to the created buffer, the callback for external buffer's creation should be handled in ramses::IRendererEventHandler, where on creation success the buffer's OpenGL Id should be provided. This texture Id should be passed to the native platform mechanisms. On Android the texture Id should be passed to a SurfaceTexture object which connects the texture with other Android platform constructs.

The created external buffer should be linked to a texture consumer created from ramses::TextureSamplerExternal. This can be used only with GLSL shader sampler of type "samplerExternalOES".

External buffers can be used with doOneLoop, since the user is expected to make platform specific calls to update the content of the external texture. Using a render thread could lead to race conditions and to unexpected and undesirable behavior on target platform, so it is prohibited. Trying to call this function if the renderer is not using doOneLoop will lead to failure, and an invalid external buffer id will be returned.

Parameters

[in] display Id of display that the buffer should be created on.

Returns: Identifier of the created external buffer. In case renderer is running in own thread externalBufferId_t::Invalid() will be returned.

◆ createInterruptibleOffscreenBuffer() [1/2]

displayBufferId_t ramses::RamsesRenderer::createInterruptibleOffscreenBuffer	(	displayId_t	display,
		uint32_t	width,
		uint32_t	height
	)

Additional API to create an offscreen buffer as interruptible. (see createOffscreenBuffer)

This allows the renderer to interrupt rendering of scenes to such offscreen buffer if the time budget for rendering is exceeded within a frame (see setFrameTimerLimits). The rendering continues next frame starting from the interruption point.

The renderer creates two render targets on GPU (front and back) for every interruptible offscreen buffer. It then renders into the back render target of the offscreen buffer, while it is possible to read the content of front render target with content from previous frame (or older if interrupted for several frames).

Note that whenever a scene gets assigned to interruptible offscreen buffer, it is not guaranteed anymore that it will be fully rendered every frame. Essentially it is rendered with lower priority.

The created offscreen buffer always has color, depth and stencil buffers.

Parameters

[in]	display	Id of display for which the buffer should be created
[in]	width	Width of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	height	Height of the buffer to be created (has to be higher than 0 and lower than 4096)

Returns: Identifier of the created offscreen buffer. In case of unsupported resolution displayBufferId_t::Invalid() will be returned with no renderer event generated. Note that the buffer will be created asynchronously and there will be a renderer event once the operation is finished.

◆ createInterruptibleOffscreenBuffer() [2/2]

static displayBufferId_t ramses::RamsesRenderer::createInterruptibleOffscreenBuffer	(	RamsesRenderer &	renderer,
		displayId_t	display,
		uint32_t	width,
		uint32_t	height,
		EDepthBufferType	depthBufferType = `EDepthBufferType_DepthStencil`
	)

static

Additional API to create an offscreen buffer as interruptible. This allows the renderer to interrupt rendering of scenes to such offscreen buffer if the time budget for rendering is exceeded within a frame (see setFrameTimerLimits). The rendering continues next frame starting from the interruption point.

The renderer creates two render targets on GPU (front and back) for every interruptible offscreen buffer. It then renders into the back render target of the offscreen buffer, while it is possible to read the content of front render target with content from previous frame (or older if interrupted for several frames).

Note that whenever a scene gets assigned to interruptible offscreen buffer, it is not guaranteed anymore that it will be fully rendered every frame. Essentially it is rendered with lower priority.

The created offscreen buffer always has a color buffer, but depth and stencil buffers can be configured.

Parameters

[in]	renderer	The renderer to call this method on. This API is temporarily added in static fashion for ABI compatibility.
[in]	display	Id of display for which the buffer should be created
[in]	width	Width of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	height	Height of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	depthBufferType	Optional setting to configure depth and stencil buffers.

Returns: Identifier of the created offscreen buffer. In case of unsupported resolution displayBufferId_t::Invalid() will be returned with no renderer event generated. Note that the buffer will be created asynchronously and there will be a renderer event once the operation is finished.

◆ createOffscreenBuffer() [1/2]

displayBufferId_t ramses::RamsesRenderer::createOffscreenBuffer	(	displayId_t	display,
		uint32_t	width,
		uint32_t	height,
		uint32_t	sampleCount = `0u`
	)

Will create an offscreen buffer that can be used to render scenes into (see ramses::RendererSceneControl::setSceneDisplayBufferAssignment) and can be linked as input to a consumer texture sampler (see ramses::RendererSceneControl::linkOffscreenBuffer).

The created offscreen buffer always has color, depth and stencil buffer attached. A multisampled buffer will be created if sampleCount greater than 0, note that the value is just a hint for the device, the actual number of samples might be different depending on device driver implementation. If the number of samples exceeds device capabilities the number of samples it will be clamped to its maximum supported (creation will succeeded with a warning log).

Parameters

[in]	display	id of display for which the buffer should be created
[in]	width	width of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	height	height of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	sampleCount	Optional sample count for MSAA. Default value is 0 for no MSAA.

Returns: Identifier of the created offscreen buffer. In case of unsupported resolution displayBufferId_t::Invalid() will be returned with no renderer event generated. Note that the buffer will be created asynchronously and there will be a renderer event once the operation is finished.

◆ createOffscreenBuffer() [2/2]

static displayBufferId_t ramses::RamsesRenderer::createOffscreenBuffer	(	RamsesRenderer &	renderer,
		displayId_t	display,
		uint32_t	width,
		uint32_t	height,
		uint32_t	sampleCount = `0u`,
		EDepthBufferType	depthBufferType = `EDepthBufferType_DepthStencil`
	)

static

Will create an offscreen buffer that can be used to render scenes into (see ramses::RendererSceneControl::setSceneDisplayBufferAssignment) and can be linked as input to a consumer texture sampler (see ramses::RendererSceneControl::linkOffscreenBuffer).

The created offscreen buffer always has a color buffer, but depth and stencil buffers can be configured.

Parameters

[in]	renderer	The renderer to call this method on. This API is temporarily added in static fashion for ABI compatibility.
[in]	display	id of display for which the buffer should be created
[in]	width	width of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	height	height of the buffer to be created (has to be higher than 0 and lower than 4096)
[in]	sampleCount	Optional sample count for MSAA number of samples. Default value is Zero, which disables MSAA for the offscreen buffer.
[in]	depthBufferType	Optional setting to configure depth and stencil buffers.

Returns: Identifier of the created offscreen buffer. In case of unsupported resolution displayBufferId_t::Invalid() will be returned with no renderer event generated. Note that the buffer will be created asynchronously and there will be a renderer event once the operation is finished.

◆ destroyDisplay()

status_t ramses::RamsesRenderer::destroyDisplay ( displayId_t displayId )

Destroy a display. Destruction of a display is an asynchronous action and the actual display components (window, device, etc.) will be released during the next render loop. The result of the destroyDisplay can be retrieved via dispatchEvents which will trigger a callback with the result after the asynchronous action was processed.

Parameters

displayId The display id of the display to destroy.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ destroyExternalBuffer()

status_t ramses::RamsesRenderer::destroyExternalBuffer	(	displayId_t	display,
		externalBufferId_t	externalBuffer
	)

Will destroy a previously created external buffer. If there are any consumer texture samplers linked to this buffer, these links will be removed.

Parameters

[in]	display	id of display which the buffer belongs to
[in]	externalBuffer	id of buffer to destroy

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ destroyOffscreenBuffer()

status_t ramses::RamsesRenderer::destroyOffscreenBuffer	(	displayId_t	display,
		displayBufferId_t	offscreenBuffer
	)

Will destroy a previously created offscreen buffer. If there are any consumer texture samplers linked to this buffer, these links will be removed. Offscreen buffer will fail to be destroyed if there are any scenes assigned to it, these scenes have to be first assigned to another buffer or framebuffer or unmapped from display.

Parameters

[in]	display	id of display which the buffer belongs to
[in]	offscreenBuffer	id of buffer to destroy

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ dispatchEvents()

status_t ramses::RamsesRenderer::dispatchEvents ( IRendererEventHandler & rendererEventHandler )

Most RamsesRenderer methods push commands to an internal queue which is submitted when calling RamsesRenderer::flush. The commands are then executed during a render loop (RamsesRenderer::doOneLoop or in a render thread if used RamsesRenderer::startThread). Some of these calls result in an event (can be both informational and data). Such events and their result can be retrieved using the dispatchEvents call. IMPORTANT Renderer events must be regularly consumed by calling dispatchEvents() in order to prevent buffer overflow of the internal event queue, even if the application is not interested in those events.

Parameters

rendererEventHandler User class that implements the callbacks that can be triggered if a corresponding event happened. Check ramses::IRendererEventHandler documentation for more details.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp, and ramses-example-local-offscreenbuffer/src/main.cpp.

◆ doOneLoop()

status_t ramses::RamsesRenderer::doOneLoop ( )

Prepare content to be rendered in next frame and render next frame.

Update and render of all displays is executed sequentially in caller's thread. For active rendering it is recommended to use threaded mode instead (startThread). Once this method is called a threaded mode cannot be used anymore.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

Examples: ramses-example-local-datalink/src/main.cpp, ramses-example-local-dma-offscreenbuffer/src/main.cpp, and ramses-example-local-viewport-link/src/main.cpp.

◆ flush()

status_t ramses::RamsesRenderer::flush ( )

Submits renderer commands (API calls on this instance of RamsesRenderer) since previous flush to be executed in the next renderer update loop.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ getDisplayFramebuffer()

displayBufferId_t ramses::RamsesRenderer::getDisplayFramebuffer ( displayId_t displayId ) const

Get display's framebuffer ID. Every display upon creation has one framebuffer which can be referenced by a display buffer ID to be used in various API methods that work with either a framebuffer or an offscreen buffer (e.g. RamsesRenderer::setBufferClearColor).

Parameters

displayId The ID of display for which the framebuffer ID is being queried.

Returns: Display's framebuffer ID or invalid ID if display does not exist.

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ getDmaOffscreenBufferFDAndStride()

status_t ramses::RamsesRenderer::getDmaOffscreenBufferFDAndStride	(	displayId_t	display,
		displayBufferId_t	displayBufferId,
		int &	fd,
		uint32_t &	stride
	)		const

Get the FD and stride for a DMA offscreen buffer previously created on the given display.

Get the file descriptor and stride for the underlying GBM buffer object used for a DMA offscreenbuffer that was created using ramses::RamsesRenderer::createDmaOffscreenBuffer. This function can be safely called only after a successful offscreen buffer event is disptched (using ramses::IRendererEventHandler::offscreenBufferCreated) for the meant offscreen buffer.

The file descriptor could be used for mapping the underlying memory used by the offscreen buffer to CPU. As long the mapped memory is in use it is important to watch the mentioned considerations in createDmaOffscreenBuffer. It is the responsibility of the user to unmap that memory on offscreen buffer destruction or when the CPU operations do not need to be applied to that memory any more.

Stride could be used for calculating addresses of specific pixels within mapped memory, where the data for each row in the image starts at a multiple of stride. Buffer stride can be different from the calculatable row size in bytes relying only on buffer width and format pixel size.

Parameters

[in]	display	Id of display for which the buffer was created
[in]	displayBufferId	Id of the DMA offscreen buffer for which the FD should be returned
[out]	fd	File descriptor of underlying GBM buffer object for DMA offscreen buffer
[out]	stride	Stride of DMA offsceen buffer in bytes

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ getExternalBufferGlId()

bool ramses::RamsesRenderer::getExternalBufferGlId	(	displayId_t	display,
		externalBufferId_t	externalBuffer,
		uint32_t &	textureGlId
	)		const

Will query the OpenGL texture Id for the external texture used for a created external buffer.

Parameters

[in]	display	id of display which the buffer belongs to
[in]	externalBuffer	id of buffer to query OpenGL texture ID for
[out]	textureGlId	On success the OpenGL texture ID of the underlying external texture is written to this variable. On failure the current value stored is not affected. The return value of the function must be checked for success before using this value.

Returns: true for success, false otherwise, e.g., if the buffer was not created yet, failed creation or was already destroyed.

◆ getLoopMode()

ELoopMode ramses::RamsesRenderer::getLoopMode ( ) const

Get the current value for loop mode set using setLoopMode.

Returns: The loop mode

◆ getMaximumFramerate()

float ramses::RamsesRenderer::getMaximumFramerate ( ) const

Get the current value for maximum frame rate per second currently set (setMaximumFramerate).

Returns: Maximum frame rate per second

◆ getSceneControlAPI()

RendererSceneControl* ramses::RamsesRenderer::getSceneControlAPI ( )

Get scene control API.

Typical application using Ramses has different components controlling the renderer (display management, frame limits and looping control, etc.) and controlling the states of content to be rendered (show/hide scene, data link, assign to display buffer, etc.). The scene control part can be obtained using this method, calling this method multiple times is allowed and will always return the same pointer, i.e. there is only a single instance per RamsesRenderer. This method will return nullptr in case an internal policy disallows controlling of scenes through this API - this could mean that there is another, incompatible scene control mechanism in use. Scene control API has its own independent flush and event dispatching, see ramses::RendererSceneControl for details.

Obtaining the ramses::RendererSceneControl will disallow usage of different type of scene control (ramses::DcsmContentControl). RamsesRenderer is owner of the ramses::RendererSceneControl API and the pointer stays valid as long as this RamsesRenderer instance is alive. It cannot be destroyed without destroying the RamsesRenderer.

Returns: Pointer to scene control API, or nullptr on error

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp, ramses-example-local-offscreenbuffer/src/main.cpp, and ramses-example-local-viewport-link/src/main.cpp.

◆ isThreadRunning()

bool ramses::RamsesRenderer::isThreadRunning ( ) const

Get the current state of rendering thread(s) running.

Returns: Returns true if thread is running (started and not stopped), false otherwise.

◆ logRendererInfo()

status_t ramses::RamsesRenderer::logRendererInfo ( )

Prints detailed information about renderer state and contents to the log output.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ operator=()

RamsesRenderer& ramses::RamsesRenderer::operator= ( const RamsesRenderer & other )

delete

Deleted copy assignment.

Parameters

other unused

Returns: unused

◆ readPixels()

status_t ramses::RamsesRenderer::readPixels	(	displayId_t	displayId,
		displayBufferId_t	displayBuffer,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height
	)

Triggers an asynchronous read back of a display buffer memory from GPU to system memory.

The color data from the provided rectangle coordinates will be read back and stored as RGBA8. If the coordinates lie outside the rendered region the result is undefined.

If a read pixels command is issued for a display buffer while a previous read pixels command for the same buffer was not yet executed only the last submitted read pixel command gets executed.

The pixel data can be obtained as a renderer event after the asynchronous read back is finished, see RamsesRenderer::dispatchEvents for details.

Parameters

[in]	displayId	id of display to read pixels from.
[in]	displayBuffer	Id of display buffer to read pixels from, if ramses::displayBufferId_t::Invalid() is passed then pixels are read from the display's framebuffer.
[in]	x	The starting offset in the original image (i.e. left border) in pixels.
[in]	y	The starting offset in the original image (i.e. lower border) in pixels. The origin of the image is supposed to be in the lower left corner.
[in]	width	The width of the read image in pixels. Must be greater than Zero.
[in]	height	The height of the read image in pixels. Must be greater than Zero.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage(). StatusOK does not guarantee successful read back, the result event has its own status.

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ setDisplayBufferClearColor()

status_t ramses::RamsesRenderer::setDisplayBufferClearColor	(	displayId_t	display,
		displayBufferId_t	displayBuffer,
		float	r,
		float	g,
		float	b,
		float	a
	)

Sets clear color of a display buffer (display's framebuffer or offscreen buffer).

Clear color is used to clear the whole buffer at the beginning of a rendering cycle (typically every frame). Default clear color is (0, 0, 0, 1). There is no event callback for this operation, the clear color change can be assumed to be effective in the next frame rendered after flushed.

Parameters

[in]	display	Id of display that the buffer to set clear color belongs to.
[in]	displayBuffer	Id of display buffer to set clear color, if ramses::displayBufferId_t::Invalid() is passed then the clear color is set for display's framebuffer.
[in]	r	Clear color red channel value [0,1]
[in]	g	Clear color green channel value [0,1]
[in]	b	Clear color blue channel value [0,1]
[in]	a	Clear color alpha channel value [0,1]

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setDisplayBufferClearFlags()

static status_t ramses::RamsesRenderer::setDisplayBufferClearFlags	(	RamsesRenderer &	renderer,
		displayId_t	display,
		displayBufferId_t	displayBuffer,
		uint32_t	clearFlags
	)

static

Sets clear flags for a display buffer (display's framebuffer or offscreen buffer).

By default all display buffers' color, depth and stencil are cleared every frame when they are rendered to. This can be overridden for performance or special effect reasons. There is no event callback for this operation, the change can be assumed to be effective in the next frame rendered after flushed.

Parameters

[in]	renderer	The renderer to call this method on. This API is temporarily added in static fashion for ABI compatibility.
[in]	display	Id of display that the buffer to set clearing belongs to.
[in]	displayBuffer	Id of display buffer to set clearing, if ramses::displayBufferId_t::Invalid() is passed then the clearing is set for display's framebuffer.
[in]	clearFlags	Bitmask of the ramses::EClearFlags, use bit OR to select which buffer component to clear or ramses::EClearFlags_All to clear all (default).

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ setExternallyOwnedWindowSize()

status_t ramses::RamsesRenderer::setExternallyOwnedWindowSize	(	displayId_t	display,
		uint32_t	width,
		uint32_t	height
	)

Updates display window size after a resize event on windows not owned by renderer.

Sets the new display window size after a resize event is externally handled for the window. RAMSES renderer handles window events within its render loop for windows that are created and owned by the renderer. Typically this can not be performed for windows that are created externally by the user, and provided to RAMSES renderer during display creation as a native handle, since the user handles window events explicitly.

This applies also to resize events, i.e., if an externally owned window gets resized RAMSES renderer does not handle the resize event internally and does not get to know about it. In this case API users are expected to call this function to let RAMSES update its information about display window size. The display window size can have visible effects, e.g., if the shaders use ramses::EEffectUniformSemantic::DisplayBufferResolution

This function will log an error if the platform does not support this feature, or if the display window was not explicitly provided by the user as a native handle.

Parameters

[in]	display	Id of display that the resized window belongs to.
[in]	width	New width of the resized window.
[in]	height	New height of the resized window.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setFrameTimerLimits()

status_t ramses::RamsesRenderer::setFrameTimerLimits	(	uint64_t	limitForSceneResourcesUpload,
		uint64_t	limitForClientResourcesUpload,
		uint64_t	limitForOffscreenBufferRender
	)

Sets time limits for time-out of different sections of render and update loop.

Setting time limits for render/update loop sections instructs the renderer to monitor the amount of time consumed by the sections and interrupt their execution if the set time limit was exceeded. The time limit for every section is calculated since beginning of frame. If a section is interrupted the renderer will execute the sections in the same order in the next frame, but it will continue to execute the interrupted section(s) from the point where it stopped.

Since time limits are calculated relative to the start of the frame, the values set should be monotonically increasing in the order of:

Uploading client resources
Uploading scene resources
Rendering scenes mapped to interruptible offscreen buffers

By default sections have infinite time limit, so renderer would not try to interrupt their execution.

!! IMPORTANT !! Scene resource actions can not be interrupted like other resources. Therefore, if this timer is exceeded, a scene will be force-unsubscribed. Use this timer with caution and merely as a sanity check, NOT as a performance measure! Scenes should not be over-using scene resources, precisely because they can not be interrupted.

Parameters

[in]	limitForSceneResourcesUpload	Time limit in microseconds (since beginning of frame) for uploading scene resources to GPU
[in]	limitForClientResourcesUpload	Time limit in microseconds (since beginning of frame) for uploading client resources to GPU
[in]	limitForOffscreenBufferRender	Time limit in microseconds (since beginning of frame) for rendering scenes that are mapped to interruptible offscreen buffers

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage(). StatusOK does not guarantee successful read back, the result event has its own status.

◆ setLayerVisibility()

status_t ramses::RamsesRenderer::setLayerVisibility	(	uint32_t	layerId,
		bool	visibility
	)

Set visibility of given layer at the system compositor.

Parameters

layerId	id identifying the layer
visibility	If `true` the layer's visibility will be enabled, otherwise disabled

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setLoopMode()

status_t ramses::RamsesRenderer::setLoopMode ( ELoopMode loopMode )

Sets the mode of operation for render loop.

Mode can be changed during run-time, in case of threaded mode also while running (no need to stopThread). By default loop mode is set to render and update.

Parameters

loopMode The mode to be used for render loop.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setMaximumFramerate() [1/2]

status_t ramses::RamsesRenderer::setMaximumFramerate ( float maximumFramerate )

Sets the maximum frame rate per second for the update/render loop when in threaded mode.

The parameter is of type float in order to specify any desired frame time (e.g. below 1 FPS). The same maximum frame rate will be applied to all displays. This function can only be used in threaded mode (startThread). The default value is 60 FPS.

Parameters

maximumFramerate The maximum frame rate per second to set for the render loop.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

Examples: ramses-example-local-displays/src/main.cpp.

◆ setMaximumFramerate() [2/2]

static status_t ramses::RamsesRenderer::setMaximumFramerate	(	RamsesRenderer &	renderer,
		float	maximumFramerate,
		displayId_t	displayId
	)

static

Sets the maximum frame rate per second for the update/render loop when in threaded mode for given display.

The maximumFramerate parameter is of type float in order to specify any desired frame time (e.g. below 1 FPS). The maximum frame rate will be applied to the display thread responsible for given display id. This function can only be used in threaded mode (startThread). The default value is 60 FPS.

Parameters

renderer	The renderer to apply the value to. This api is added in static fashion for ABI compatibility.
maximumFramerate	The maximum frame rate per second to set for the render loop.
displayId	The display id the framerate should be applied to.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setPendingFlushLimits()

status_t ramses::RamsesRenderer::setPendingFlushLimits	(	uint32_t	forceApplyFlushLimit,
		uint32_t	forceUnsubscribeSceneLimit
	)

Sets the number of pending flushes accepted before force-applying them to their scene, or forcefully insubscribing the scene.

RAMSES guarantees that a scene flush is only going to be rendered if all resources (textures, shaders etc.) are received and uploaded to the GPU. This allows a misbehaving client to flood a renderer with flushes which are never executed, causing the renderer to exhaust heap memory. If too many pending flushes are received and queued, they are force-applied to the scene, even if some resources are missing, thus potentially causing flickering. This method allows overriding the number of flushes after a scene is updated to the latest flush and all pending flushes wiped from memory. A low number (e.g. 1) will cause frequent flickering, whereas a high number (e.g. 100000) could cause the renderer to go out of memory. The second parameter (forceUnsubscribeSceneLimit) controls after how many pending flushes a scene is completely unsubscribed. This can be used as a protection against malicious remote scenes. It does not affect local scenes though. It is advisable to set forceUnsubscribeSceneLimit to higher number than forceApplyFlushLimit, because re-subscribing a scene is causing a lot of network traffic and unnecessary memory operations, not to mention the scene is then also not visible until re-subscribed, mapped and shown.

Parameters

[in]	forceApplyFlushLimit	Number of flushes that can be pending before force applying occurs.
[in]	forceUnsubscribeSceneLimit	Number of flushes that can be pending before force un-subscribe occurs.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setSkippingOfUnmodifiedBuffers()

status_t ramses::RamsesRenderer::setSkippingOfUnmodifiedBuffers ( bool enable = true )

Enable or disable skipping of rendering of unmodified buffers. By default the renderer does not re-render buffers (framebuffer or offscreen buffer) if there was no change to any of the content assigned to the buffer. This can save hardware resources or free up resources for rendering of other buffers. It can be however desired to disable such optimization for profiling of worst case scenario or debugging of a graphical glitch.

Parameters

[in] enable Enable or disable the feature (enabled initially)

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage(). StatusOK does not guarantee successful read back, the result event has its own status.

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ setSurfaceOpacity()

status_t ramses::RamsesRenderer::setSurfaceOpacity	(	uint32_t	surfaceId,
		float	opacity
	)

Set opacity of given surface at the system compositor.

Parameters

surfaceId	id of the surface to set opacity of
opacity	Opacity in the range 0.0 (fully transparent) to 1.0 (fully opaque)

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setSurfaceRectangle()

status_t ramses::RamsesRenderer::setSurfaceRectangle	(	uint32_t	surfaceId,
		int32_t	x,
		int32_t	y,
		int32_t	width,
		int32_t	height
	)

Set output rectangle of given surface at the system compositor.

Parameters

surfaceId	id of the surface to set the rectangle for
x	Output position of surface along the x-axis
y	Output position of surface along the y-axis
width	Output width of surface
height	Output height of surface

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ setSurfaceVisibility()

status_t ramses::RamsesRenderer::setSurfaceVisibility	(	uint32_t	surfaceId,
		bool	visibility
	)

Set visibility of given surface at the system compositor.

Parameters

surfaceId	id of the surface to set visibility of
visibility	visibility to set

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ startThread()

status_t ramses::RamsesRenderer::startThread ( )

Starts update and render loop in threaded mode.

Each display will update and render in its own thread. First call to this method enables threaded mode, afterwards it is not possible to call doOneLoop anymore.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ stopThread()

status_t ramses::RamsesRenderer::stopThread ( )

Stops thread(s) running the update and render of displays.

This function can only be used if startThread was successfully called before. The looping can be restarted by calling startThread again.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ takeSystemCompositorScreenshot()

status_t ramses::RamsesRenderer::takeSystemCompositorScreenshot	(	const char *	fileName,
		int32_t	screenIviId
	)

Trigger the System Compositor to take a screenshot and store it in a file.

Parameters

fileName	File name including path, for storing the screenshot.
screenIviId	>= 0 to trigger a screenshot on the given IVI screen id, -1 to trigger screenshot on a single existing screen (fails asynchronously if more than one screen exists)

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

◆ updateWarpingMeshData()

status_t ramses::RamsesRenderer::updateWarpingMeshData	(	displayId_t	displayId,
		const WarpingMeshData &	newWarpingMeshData
	)

Updates the warping mesh for the warping postprocessing based on the new config.

Display must be created with warping enabled in order for this operation to succeed.

Parameters

[in]	displayId	id of display to update.
[in]	newWarpingMeshData	Holds the geometry needed to create the mesh for display warping.

Returns: StatusOK for success, otherwise the returned status can be used to resolve error message using getStatusMessage().

Friends And Related Function Documentation

◆ RendererFactory

friend class RendererFactory

friend

RendererFactory is the factory for RamsesRenderer.

Member Data Documentation

◆ impl

class RamsesRendererImpl& ramses::RamsesRenderer::impl

Stores internal data for implementation specifics of RamsesRenderer

The documentation for this class was generated from the following file:

/home/runner/work/ramses/ramses/renderer/RendererLib/ramses-renderer-api/include/ramses-renderer-api/RamsesRenderer.h

Public Member Functions

Static Public Member Functions

Public Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ RamsesRenderer() [1/3]

◆ RamsesRenderer() [2/3]

◆ RamsesRenderer() [3/3]

Member Function Documentation

◆ createDcsmContentControl()

◆ createDisplay()

◆ createDmaOffscreenBuffer()

◆ createExternalBuffer()

◆ createInterruptibleOffscreenBuffer() [1/2]

◆ createInterruptibleOffscreenBuffer() [2/2]

◆ createOffscreenBuffer() [1/2]

◆ createOffscreenBuffer() [2/2]

◆ destroyDisplay()

◆ destroyExternalBuffer()

◆ destroyOffscreenBuffer()

◆ dispatchEvents()

◆ doOneLoop()

◆ flush()

◆ getDisplayFramebuffer()

◆ getDmaOffscreenBufferFDAndStride()

◆ getExternalBufferGlId()

◆ getLoopMode()

◆ getMaximumFramerate()

◆ getSceneControlAPI()

◆ isThreadRunning()

◆ logRendererInfo()

◆ operator=()

◆ readPixels()

◆ setDisplayBufferClearColor()

◆ setDisplayBufferClearFlags()

◆ setExternallyOwnedWindowSize()

◆ setFrameTimerLimits()

◆ setLayerVisibility()

◆ setLoopMode()

◆ setMaximumFramerate() [1/2]

◆ setMaximumFramerate() [2/2]

◆ setPendingFlushLimits()

◆ setSkippingOfUnmodifiedBuffers()

◆ setSurfaceOpacity()

◆ setSurfaceRectangle()

◆ setSurfaceVisibility()

◆ startThread()

◆ stopThread()

◆ takeSystemCompositorScreenshot()

◆ updateWarpingMeshData()

Friends And Related Function Documentation

◆ RendererFactory

Member Data Documentation

◆ impl