Ramses Rendeer API

enum class ERendererEventResult

Specifies the result of the operation referred to by renderer event.

Values:

enumerator Ok: Event referring to an operation that succeeded.

enumerator Indirect: Event referring to an operation that succeeded but was triggered by another event (eg. unmapped/unsubscribed after scene was unpublished by client)

enumerator Failed: Event referring to an operation that failed.

enum class EMouseEvent

Specifies events for mouse input.

Values:

enumerator Invalid

enumerator LeftButtonDown

enumerator LeftButtonUp

enumerator RightButtonDown

enumerator RightButtonUp

enumerator MiddleButtonDown

enumerator MiddleButtonUp

enumerator WheelUp

enumerator WheelDown

enumerator Move

enumerator WindowEnter

enumerator WindowLeave

enum class EKeyEvent

Specifies keypress events for keyboard input.

Values:

enumerator Invalid

enumerator Pressed

enumerator Released

enum EKeyCode

Specifies key codes for keyboard input.

Values:

enumerator EKeyCode_Unknown

enumerator EKeyCode_A

enumerator EKeyCode_B

enumerator EKeyCode_C

enumerator EKeyCode_D

enumerator EKeyCode_E

enumerator EKeyCode_F

enumerator EKeyCode_G

enumerator EKeyCode_H

enumerator EKeyCode_I

enumerator EKeyCode_J

enumerator EKeyCode_K

enumerator EKeyCode_L

enumerator EKeyCode_M

enumerator EKeyCode_N

enumerator EKeyCode_O

enumerator EKeyCode_P

enumerator EKeyCode_Q

enumerator EKeyCode_R

enumerator EKeyCode_S

enumerator EKeyCode_T

enumerator EKeyCode_U

enumerator EKeyCode_V

enumerator EKeyCode_W

enumerator EKeyCode_X

enumerator EKeyCode_Y

enumerator EKeyCode_Z

enumerator EKeyCode_0

enumerator EKeyCode_1

enumerator EKeyCode_2

enumerator EKeyCode_3

enumerator EKeyCode_4

enumerator EKeyCode_5

enumerator EKeyCode_6

enumerator EKeyCode_7

enumerator EKeyCode_8

enumerator EKeyCode_9

enumerator EKeyCode_NumLock

enumerator EKeyCode_Numpad_Add

enumerator EKeyCode_Numpad_Subtract

enumerator EKeyCode_Numpad_Multiply

enumerator EKeyCode_Numpad_Divide

enumerator EKeyCode_Numpad_Enter

enumerator EKeyCode_Numpad_Decimal

enumerator EKeyCode_Numpad_0

enumerator EKeyCode_Numpad_1

enumerator EKeyCode_Numpad_2

enumerator EKeyCode_Numpad_3

enumerator EKeyCode_Numpad_4

enumerator EKeyCode_Numpad_5

enumerator EKeyCode_Numpad_6

enumerator EKeyCode_Numpad_7

enumerator EKeyCode_Numpad_8

enumerator EKeyCode_Numpad_9

enumerator EKeyCode_Return

enumerator EKeyCode_Escape

enumerator EKeyCode_Backspace

enumerator EKeyCode_Tab

enumerator EKeyCode_Space

enumerator EKeyCode_Menu

enumerator EKeyCode_CapsLock

enumerator EKeyCode_ShiftLeft

enumerator EKeyCode_ShiftRight

enumerator EKeyCode_AltLeft

enumerator EKeyCode_AltRight

enumerator EKeyCode_ControlLeft

enumerator EKeyCode_ControlRight

enumerator EKeyCode_WindowsLeft

enumerator EKeyCode_WindowsRight

enumerator EKeyCode_F1

enumerator EKeyCode_F2

enumerator EKeyCode_F3

enumerator EKeyCode_F4

enumerator EKeyCode_F5

enumerator EKeyCode_F6

enumerator EKeyCode_F7

enumerator EKeyCode_F8

enumerator EKeyCode_F9

enumerator EKeyCode_F10

enumerator EKeyCode_F11

enumerator EKeyCode_F12

enumerator EKeyCode_PrintScreen

enumerator EKeyCode_ScrollLock

enumerator EKeyCode_Pause

enumerator EKeyCode_Insert

enumerator EKeyCode_Home

enumerator EKeyCode_PageUp

enumerator EKeyCode_Delete

enumerator EKeyCode_End

enumerator EKeyCode_PageDown

enumerator EKeyCode_Right

enumerator EKeyCode_Left

enumerator EKeyCode_Up

enumerator EKeyCode_Down

enumerator EKeyCode_Minus

enumerator EKeyCode_Equals

enumerator EKeyCode_LeftBracket

enumerator EKeyCode_RightBracket

enumerator EKeyCode_Backslash

enumerator EKeyCode_Semicolon

enumerator EKeyCode_Comma

enumerator EKeyCode_Period

enumerator EKeyCode_Slash

enumerator EKeyCode_Apostrophe

enumerator EKeyCode_Grave

enumerator EKeyCode_NumberSign

enum class EKeyModifier : uint32_t

Specifies key modifiers for keyboard input.

Values:

enumerator NoModifier

enumerator Ctrl

enumerator Shift

enumerator Alt

enumerator Function

enumerator Numpad

enum class ELoopMode

Specifies behavior of render loop.

Values:

enumerator UpdateAndRender: Render loop with update content and render.

enumerator UpdateOnly: Render loop will update content without rendering.

enum class EDepthBufferType

Specifies type of depth buffer created within an offscreen buffer.

Values:

enumerator None

enumerator Depth

enumerator DepthStencil

enum class EDeviceType

Specifies requested device type to create.

Values:

enumerator GLES_3_0

enumerator GL_4_2

enumerator GL_4_5

enum class EWindowType

Specifies type of window to create.

Values:

enumerator Windows

enumerator X11

enumerator Wayland_IVI

enumerator Wayland_Shell

enumerator Android

enumerator iOS

using effectId_t = rendererResourceId_t

Effect identifier used by the renderer to refer to an effect.

Note: the value is not the same as on client if calling ramses::Resource::getResourceId()

using KeyModifiers = Flags<EKeyModifier>

class BinaryShaderCache : public ramses::IBinaryShaderCache 

#include <BinaryShaderCache.h>

Provide default implementation for IBinaryShaderCache interface, to be used in RamsesRenderer by setting in RendererConfig. Also provides functions to serialize binary shaders to file and deserialize binary shaders from file.

Public Functions

BinaryShaderCache(): Default Constructor.

~BinaryShaderCache() override: Destructor of IBinaryShaderCache.

virtual void deviceSupportsBinaryShaderFormats(const binaryShaderFormatId_t *supportedFormats, uint32_t numSupportedFormats) override

Provides a list of binary shader formats supported by the device in use. The cache implementation should provide only shaders that were compiled and stored with using of those formats. The format ID is platform/driver specific, on OpenGL it is equivalent to those retrieved from GL_PROGRAM_BINARY_FORMATS parameter. This callback will be called only once, after at least one display is created and at latest before the first IBinaryShaderCache::hasBinaryShader query.

Parameters:

supportedFormats – [in] Pointer to first element of a list of supported formats, this array is valid only for in the scope of this callback
numSupportedFormats – [in] Number of elements in supportedFormats array, if zero there is no support for uploading binary shaders

virtual bool hasBinaryShader(effectId_t effectId) const override

Check if the cache contains the binary shader for the Effect with the given Effect Id.

Parameters:: effectId – Effect Id of the Effect
Returns:: true if there is binary shader for the Effect Id false otherwise

virtual uint32_t getBinaryShaderSize(effectId_t effectId) const override

Get the binary shader size in bytes for the Effect with the given Effect Id.

Parameters:: effectId – Effect Id of the Effect
Returns:: size in bytes for the Effect with the given Effect Id 0 if there is no binary shader in the cache for the Effect with the Effect Id.

virtual binaryShaderFormatId_t getBinaryShaderFormat(effectId_t effectId) const override

Get the binary shader format for the Effect with the given Effect Id.

Parameters:: effectId – Effect Id of the Effect
Returns:: binary shader format for the Effect with the given Effect Id. 0 if there is no binary shader in the cache for the Effect with the Effect Id.

virtual bool shouldBinaryShaderBeCached(effectId_t effectId, sceneId_t sceneId) const override

Returns for a specific effect whether it should be cached.

        This method is called if the shader is not cached yet but could be provided by the renderer.
        The cache can decide whether it the shader should be cached.

Parameters:

effectId – [in] Effect Id of the Effect
sceneId – [in] ID of scene that uses the effect

Returns:

true if the effect should be cached, false otherwise.

virtual void getBinaryShaderData(effectId_t effectId, std::byte *buffer, uint32_t bufferSize) const override

Get the binary shader data for the Effect with the given Effect Id.

Parameters:

effectId – Effect Id of the Effect
buffer – pointer to the buffer to get the binary shader data
bufferSize – the size of the buffer to get the binary shader data

virtual void storeBinaryShader(effectId_t effectId, sceneId_t sceneId, const std::byte *binaryShaderData, uint32_t binaryShaderDataSize, binaryShaderFormatId_t binaryShaderFormat) override

Store the binary shader into the cache.

Parameters:

effectId – Effect Id of the Effect
sceneId – ID of scene that uses the effect
binaryShaderData – pointer to the binary shader data
binaryShaderDataSize – size of the binary shader data
binaryShaderFormat – format of the binary shader

void saveToFile(std::string_view filePath) const

Save all binary shaders in the cache to the file with the given path.

Parameters:: filePath – the path of the file to save binary shaders

bool loadFromFile(std::string_view filePath)

Load all binary shaders from the file with the given path.

Parameters:: filePath – the path of the file to load binary shaders
Returns:: true when succeed in loading binary shaders from the file false when fail to load binary shaders from the file

virtual void binaryShaderUploaded(effectId_t effectId, bool success) const override

Used by RamsesRenderer to provide a callback with information on the result of a binary shader upload operation.

This method is called by the renderer after each attempted upload operation from a binary shader cache. It is intended for informational/debugging purposes in detecting an invalid binary shader cache.

Parameters:

effectId – Effect Id of the Effect
success – The result

BinaryShaderCache(const BinaryShaderCache &other) = delete

Deleted copy constructor.

Parameters:: other – unused

BinaryShaderCache &operator=(const BinaryShaderCache &other) = delete

Deleted copy assignment.

Parameters:: other – unused
Returns:: unused

internal::BinaryShaderCacheImpl &impl(): Get the internal data for implementation specifics of BinaryShaderCache.

const internal::BinaryShaderCacheImpl &impl() const: Get the internal data for implementation specifics of BinaryShaderCache.

class DisplayConfig

#include <DisplayConfig.h>

DisplayConfig holds a set of parameters to be used to initialize a display.

Public Functions

DisplayConfig(): Default constructor of DisplayConfig.

~DisplayConfig(): Destructor of DisplayConfig.

void validate(ValidationReport &report) const

Performs a (potentially slow!) validation of this object and its dependencies.

validate() may append issues to the provided report object, classified by warning or error:

errors need to be fixed, otherwise the object’s behaviour will be undefined
warnings indicate issues that are undesirable, but not necessarily cause problems (e.g. unused resources, performance issues)

Note

validate() will skip objects that are already part of the provided report. (Provide an empty report to force re-validation)

Parameters:: report – The report that the object writes to

bool setDeviceType(EDeviceType deviceType)

Sets the requested device type used for display context and device creation. By default a device type GLES 3.0 is requested.

Parameters:: deviceType – [in] Device type.
Returns:: true on success, false if an error occurred (error is logged)

EDeviceType getDeviceType() const

Get the device type used for display context and device creation.

Returns:: Device type used for display context and device creation. Default value is device type GLES 3.0.

bool setWindowType(EWindowType windowType)

Sets the window type used for display creation. By default any of the supported window types will be picked depending on build configuration.

Parameters:: windowType – [in] Window type.
Returns:: true on success, false if an error occurred (error is logged)

EWindowType getWindowType() const

Get the window type used for display creation.

Returns:: Window type used for display creation. Default value depends on build configuration.

bool setWindowRectangle(int32_t x, int32_t y, uint32_t width, uint32_t height)

Sets the window size and position in display pixel space. This is ignored if window is set fullscreen.

Parameters:

x – [in] Horizontal offset (distance from left border of the display)
y – [in] Vertical offset (distance from top border of the display)
width – [in] Width of the window
height – [in] Height of the window

Returns:

true on success, false if an error occurred (error is logged)

bool getWindowRectangle(int32_t &x, int32_t &y, uint32_t &width, uint32_t &height) const

Get the window size and position in display pixel space, as it was specified by setWindowRectangle() or command line options These values have no relevance if window is set fullscreen.

Parameters:

x – [out] Horizontal offset (distance from left border of the display)
y – [out] Vertical offset (distance from top border of the display)
width – [out] Width of the window
height – [out] Height of the window

Returns:

true on success, false if an error occurred (error is logged)

bool setWindowFullscreen(bool fullscreen)

Automatically sets the window size so that it fills the entire display. Overrides DisplayConfig::setWindowRectangle() when set to true.

Parameters:: fullscreen – [in] Flag specifying whether window should be fullscreen
Returns:: true on success, false if an error occurred (error is logged)

bool isWindowFullscreen() const

Gets the currently set fullscreen state, which was set either via DisplayConfig::setWindowFullscreen or parsed from command line arguments.

Returns:: True if this DisplayConfig is set to use fullscreen window, false otherwise.

bool setMultiSampling(uint32_t numSamples)

Set number of samples to be used for multisampled rendering.

Valid values are 1, 2, 4 or 8. Default value is 1 meaning multisampling is disabled. This value is just a hint for the device, the actual number of samples is guaranteed to be at least the given value but can be also more than that depending on device driver implementation. Ramses cannot check the device capability before the display is created, therefore exceeding the maximum number of samples supported by the device will likely result in fatal error.

Parameters:: numSamples – [in] Number of samples per pixel.
Returns:: true on success, false if an error occurred (error is logged)

bool getMultiSamplingSamples(uint32_t &numSamples) const

Get number of samples currently set.

Parameters:: numSamples – [out] Number of samples per pixel.
Returns:: true on success, false if an error occurred (error is logged)

bool setWaylandIviLayerID(waylandIviLayerId_t waylandIviLayerID)

[Mandatory on Wayland] Set IVI layer ID to use for attaching the IVI surface created by the display.

RAMSES does not try to create the layer, instead the layer must be already existing before creating the display. Trying to create a display on Wayland without setting this variable or giving it a non-valid layer ID, e.g., the ID of a non-existing layer, will result in display creation failure.

This values is ignored on other systems than Wayland.

Parameters:: waylandIviLayerID – [in] IVI layer ID to use for attaching the surface used by the display
Returns:: true on success, false if an error occurred (error is logged)

waylandIviLayerId_t getWaylandIviLayerID() const

Get the ID of the Wayland IVI layer to which the IVI surface used by the display is attached.

Returns:: the current setting of wayland IVI layer ID, returns waylandIviLayerId_t::Invalid() if no value has been set yet

bool setWaylandIviSurfaceID(waylandIviSurfaceId_t waylandIviSurfaceID)

[Mandatory on Wayland] Set IVI surface ID to use when creating the display window on Wayland.

This is the Wayland IVI surface ID, i.e. the ID that the display reports to Wayland so that the surface (=window) can be controlled over the system compositor controller
If the surface is not already existing it will be created during display creation

Parameters:: waylandIviSurfaceID – [in] IVI surface ID to use for the display window
Returns:: true on success, false if an error occurred (error is logged)

waylandIviSurfaceId_t getWaylandIviSurfaceID() const

Get the current setting of IVI surface ID.

Returns:: the current setting of IVI surface ID, returns waylandIviSurfaceId_t::Invalid() if no value has been set yet

void *getAndroidNativeWindow() const

Get the current setting of Android native window.

Returns:: the current setting of Android native window, returns nullptr if no value has been set yet

bool setAndroidNativeWindow(void *nativeWindowPtr)

[Mandatory on Android] Set native window to use for rendering on Android.

No ownership is transferred, the user is responsible to call ANativeWindow_release after destroying the RAMSES Renderer.

Parameters:: nativeWindowPtr – [in] ANativeWindow* which can be obtained with ANativeWindow_fromSurface() from a Java Surface object
Returns:: true on success, false if an error occurred (error is logged)

IOSNativeWindowPtr getIOSNativeWindow() const

Get the current setting of iOS native window.

Returns:: the current setting of iOS native window (CAMetalLayer), returns nullptr if no value has been set yet

bool setIOSNativeWindow(IOSNativeWindowPtr nativeWindowPtr)

[Mandatory on iOS] Set native window to use for rendering on iOS.

No ownership is transferred, the user is responsible to clean up the CAMetalLayer after destroying the RAMSES Renderer.

Parameters:: nativeWindowPtr – [in] Strongly typed value that wraps CAMetalLayer* which should be added to the view where RAMSES should rendered to.
Returns:: true for success, false otherwise (check log for details).

bool setWindowIviVisible()

Set IVI window to be visible right after window creation.

Returns:: true on success, false if an error occurred (error is logged)

bool setGPUMemoryCacheSize(uint64_t size)

Set the amount of GPU memory in bytes that will be used as cache for resources. Uploaded resources are kept in GPU memory even if not in use by any scene anymore. They are only freed from memory in order to make space for new resources to be uploaded which would not fit in the cache otherwise. First in first out method is used when deciding which unused resource to remove from cache.

Note that the cache size does not act as hard limit, the renderer can still upload resources taking up more space. As long as cache limit is exceeded, newly unused resources are unloaded immediately.

Only client resources are considered for this cache, not scene resources (eg. render targets/render buffers). Cache is disabled by default (size is 0).

Parameters:: size – [in] GPU resource cache size in bytes. Disabled if 0 (default)
Returns:: true on success, false if an error occurred (error is logged)

bool setResizable(bool resizable)

Enables/disables resizing of the window (Default=Disabled)

Parameters:: resizable – [in] The resizable flag
Returns:: true on success, false if an error occurred (error is logged)

bool setClearColor(const vec4f &color)

Sets the clear color of the displays framebuffer (Default=0.0, 0.0, 0.0, 1.0)

Parameters:: color – [in] clear color (rgba, channel values in range [0,1])
Returns:: true on success, false if an error occurred (error is logged)

bool setDepthStencilBufferType(EDepthBufferType depthBufferType)

Sets whether depth/stencil buffer should be created for the framebuffer of the display. The framebuffer always has a color buffer. By default depth-stencil buffer is created as well.

The set configuration will be passed to WGL/EGL, which uses this information as a lower-limit for the chosen configuration. If the configuration is not available exactly as requested, WGL/EGL will try the nearest configuration with the requested capabilities or more, e.g., if depth buffer is requested but stencil buffer is not it can happen that a stencil buffer will still be created because WGL/EGL does not have a configuration with that specific description.

Parameters:: depthBufferType – [in] Configure depth and stencil buffers.
Returns:: true on success, false if an error occurred (error is logged)

bool setX11WindowHandle(X11WindowHandle x11WindowHandle)

[Only for X11] Set the X11 window handle to create a ramses display from an existing X11 window.

This method is platform dependent!
On other backends except for X11, the value has no meaning

Parameters:

x11WindowHandle – [in] native X11 window id to use for the display window. The type is equivalent to

::Window

from the X11 headers.

Returns:

true on success, false if an error occurred (error is logged)

X11WindowHandle getX11WindowHandle() const

[Only for X11] Get the current setting of the X11 window handle

Returns:

the current setting of the X11 window handle, returns numerical maximum value if no value has been set yet. The returned type is equivalent to

::Window

from the X11 headers.

bool setWindowsWindowHandle(void *hwnd)

[Only for Windows] Set the HWND handle to create a ramses display from an existing HWND window on a Window platform.

This method is platform dependent!
On other systems except for Windows, calling this method has no meaning

Parameters:: hwnd – [in] Windows window handle to use for the display window
Returns:: true on success, false if an error occurred (error is logged)

void *getWindowsWindowHandle() const

Get the current setting of the Windows window handle (HWND)

Returns:: the current setting of the Windows window handle, returns nullptr if no value has been set yet

bool setWaylandDisplay(std::string_view waylandDisplay)

Set the Wayland display name to connect to. This will override the default behavior which is to use WAYLAND_DISPLAY environment variable.

Parameters:: waylandDisplay – [in] Wayland display name to use for connection
Returns:: true on success, false if an error occurred (error is logged)

std::string_view getWaylandDisplay() const

Get the current setting of Wayland display name.

Returns:: Wayland display name to use for connection, empty means default

bool setAsyncEffectUploadEnabled(bool enabled)

Sets whether async shader/effect compilation and upload should be enabled. By default async effect compile and upload is enabled.

Shader compilation can be a relatively slow and computationally intense task on some platforms. This can lead to undesirable performance overhead, i.e., if shader compilation stalls rendering and upload of other resources.

Enabling async effect upload lets the renderer create a shared context and a separate thread that are used exclusively for shader compilation and upload.

It is recommended to leave async effect compile and upload enabled, and to disable it only for development and debugging purposes when necessary. If async effect compile and upload is disabled using this function the renderer will still create the components normally used for this purpose, i.e., a shared context and an additional thread, but their logic will not be triggered. Instead, shaders will be compiled and uploaded within the rendering loop, i.e. potentially stalling rendering.

Parameters:: enabled – [in] Set to true to enable async effect upload, false to disable it.
Returns:: true on success, false if an error occurred (error is logged)

bool setWaylandEmbeddedCompositingSocketName(std::string_view socketname)

Set the name to be used for the embedded compositing display socket name.

The embedded compositor communicates with its clients via a socket file. There are two distinct ways to connect the embedded compositor with its socketfile. Either you provide a name for the socket file or the file descriptor of the socket file.

This method is used to set the file name of the socket.

Providing the name of the socket file leads to the embedded compositor searching/creating the socket file in the directory pointed to by $XDG_RUNTIME_DIR. If a groupname is set, also the group is set.

Be aware that the socket file name is only used if the file descriptor is set to an invalid value (default), see RendererConfig::setWaylandEmbeddedCompositingSocketFD

If both filename and file descriptor are set display creation will fail.

Parameters:: socketname – [in] The file name of the socket file.
Returns:: true on success, false if an error occurred (error is logged)

std::string_view getWaylandEmbeddedCompositingSocketName() const

Get the current setting of embedded compositing display socket name.

Returns:: Wayland display name to use for embedded compositing socket

bool setWaylandEmbeddedCompositingSocketGroup(std::string_view groupname)

Request that the embedded compositing display socket belongs to the given group.

Parameters:: groupname – [in] The group name of the socket.
Returns:: true on success, false if an error occurred (error is logged)

bool setWaylandEmbeddedCompositingSocketFD(int socketFileDescriptor)

Set the file descriptor for the embedded compositor display socket.

The embedded compositor communicates with its clients via a socket file. There are two distinct ways to connect the embedded compositor with its socketfile.

Either you provide a name for the socket file or the file descriptor of the socket file.

This method is used to set the file descriptor.

When the file descriptor is set, the embedded compositor will use this file descriptor directly as its socket. It is expected that this file descriptor is belonging to a file already open, bind and listen to.

If both filename and file descriptor are set display creation will fail.

Parameters:: socketFileDescriptor – The file descriptor of the socket for the embedded compositor.
Returns:: true on success, false if an error occurred (error is logged)

bool setWaylandEmbeddedCompositingSocketPermissions(uint32_t permissions)

Request that the embedded compositing display socket obtains the permissions given.

The format should be the same as expected by chmod() mode argument. Permissions value may not be 0. If not set “user+group can read/write (0660)” is used as default.

The socket should be readable and writable for the required users, some examples values are:

Only user r/w: 384u (or in octal 0600)
User+Group r/w: 432u (or in octal 0660)
Everyone r/w: 438u (or in octal 0666)

This value is only used when socket is given as name, e.g. via setWaylandEmbeddedCompositingSocketName(), not when passed in as filedescriptor.

Parameters:: permissions – [in] The permissions of the socket.
Returns:: true on success, false if an error occurred (error is logged)

bool setSystemCompositorWaylandDisplay(std::string_view waylandDisplay)

Set the Wayland display name to connect system compositor to. This will override the default behavior which is to use WAYLAND_DISPLAY environment variable.

Parameters:: waylandDisplay – [in] Wayland display name to use for connection
Returns:: true on success, false if an error occurred (error is logged)

bool setPlatformRenderNode(std::string_view renderNode)

Set the render node to use for creating GBM buffer objects used for creating DMA Offscreen buffers on platforms that support creation of DMA buffers.

Set the socket of a DRM driver’s render node to load and create a GBM (Generic Buffer Manager) device. If the socket is opened successfully a GBM device is created using gbm_create_device. The GBM device can be used to create DMA buffers which act as regular offscreen buffers but also allow direct memory access from application’s side. This can be helpful for use cases that require CPU read or write of memory that is used for rendering as well.

Setting a valid render node is a pre-requisite to creating DMA offscreen buffers using ramses::RamsesRenderer::createDmaOffscreenBuffer. Setting an invalid render node, or failing to create a GBM device using the passed render node will result in display creation failure.

Parameters:: renderNode – [in] Render node used to load for creating of GBM device using gbm_create_device
Returns:: true on success, false if an error occurred (error is logged)

bool setSwapInterval(int32_t interval)

Specifies the minimum number of video frames that are displayed before a buffer swap will occur.

If interval is set to 0, buffer swaps are not synchronized to a video frame. Interval is silently clamped to a platform specific minimum and maximum value. Default value is platform dependent.

Parameters:: interval – [in] Minimum number of video frames that are displayed before a buffer swap will occur
Returns:: true on success, false if an error occurred (error is logged)

bool setScenePriority(sceneId_t sceneId, int32_t priority)

Specifies the scene’s priority on this display.

The renderer will apply scene updates according to scene priority so that there will be less latency between client scene flush and rendering for scenes with higher priority. This could result in more latency for scenes with less priority. This setting should be used in combination with time budgets for resource uploads (ramses::RamsesRenderer::setFrameTimerLimits) to get the desired effect.

Default priority is 0. Higher values mean less priority. (Use negative values to increase priority)

Parameters:

sceneId – [in] scene id of the preferred scene
priority – [in] scene priority. Higher value means less priority

Returns:

true on success, false if an error occurred (error is logged)

bool setResourceUploadBatchSize(uint32_t batchSize)

Sets the batch size for resource uploads.

The resource upload batch size defines the number of resources that should be uploaded in a single step. Time budgets (ramses::RamsesRenderer::setFrameTimerLimits) are checked at the latest when a batch was uploaded. It should be safe to configure a batch size of 1 unless time measurement has a significant performance impact on the target device. The batch size may not be 0.

Parameters:: batchSize – [in] the number of resources to upload in a single step (default: 10)
Returns:: true on success, false if an error occurred (error is logged)

DisplayConfig(const DisplayConfig &other)

Copy constructor.

Parameters:: other – source to copy from

DisplayConfig(DisplayConfig &&other) noexcept

Move constructor.

Parameters:: other – source to move from

DisplayConfig &operator=(const DisplayConfig &other)

Copy assignment.

Parameters:: other – source to copy from
Returns:: this instance

DisplayConfig &operator=(DisplayConfig &&other) noexcept

Move assignment.

Parameters:: other – source to move from
Returns:: this instance

internal::DisplayConfigImpl &impl(): Get the internal data for implementation specifics of DisplayConfig.

const internal::DisplayConfigImpl &impl() const: Get the internal data for implementation specifics of DisplayConfig.

class IBinaryShaderCache

#include <IBinaryShaderCache.h>

An interface used to exchange Binary Shader Cache with the RamsesRenderer. The RamsesRenderer will not delete this class, it is owned by the application.

Implementation of this interface can be be passed to RendererConfig, and it will be used by RamsesRenderer internally to obtain/provide binary shaders. The interface handles both directions: from the application to RamsesRenderer (i.e. providing pre-cached effects to RAMSES) as well as from RamsesRenderer to the application (using the on-line shader compiler, if supported by the driver, to inform the application about existing binary shader data and providing the data itself). The application can decide whether to save, and if yes, in which form to save the provided binary shader data.

RAMSES itself does not cache shaders internally - it only uses this interface to communicate with the application, which has the complete power how to manage binary shader data (file, memory, web-server)…

The interface works with the effectId_t to uniquely reference effects. Two different effects are guaranteed to have different such ids.

Example: Let S be the id of an effect which is cached in Database, and X be the id of an effect which is not cached. Database can be an indexed file, or just a hashmap in memory holding binary shaders and their mapping to effectId_t.

	<—————————

	hasBinaryShader(C)
hasData(C)	<—————————
<————–—
-—true———>
	–—true——————>

	getBinaryShaderFormat(C)
getFormat(C)	<—————————
<————–—
-—F————>
	—-—F—————-—>

	getBinaryShaderData(C)
getData(C)	<—————————
<————–—
-—data———>
	—-—data————-—>

		glProgramBinary(C, F, data)
		————————–—>

Subclassed by ramses::BinaryShaderCache

Public Functions

virtual ~IBinaryShaderCache() = default: Destructor of IBinaryShaderCache.

virtual void deviceSupportsBinaryShaderFormats(const binaryShaderFormatId_t *supportedFormats, uint32_t numSupportedFormats) = 0

Provides a list of binary shader formats supported by the device in use. The cache implementation should provide only shaders that were compiled and stored with using of those formats. The format ID is platform/driver specific, on OpenGL it is equivalent to those retrieved from GL_PROGRAM_BINARY_FORMATS parameter. This callback will be called only once, after at least one display is created and at latest before the first IBinaryShaderCache::hasBinaryShader query.

Parameters:

supportedFormats – [in] Pointer to first element of a list of supported formats, this array is valid only for in the scope of this callback
numSupportedFormats – [in] Number of elements in supportedFormats array, if zero there is no support for uploading binary shaders

virtual bool hasBinaryShader(effectId_t effectId) const = 0

Used by RamsesRenderer to ask the application if it provides binary data for the Effect with the given effectId.

Parameters:: effectId – Effect Id of the Effect
Returns:: true if there is binary shader for the Effect Id false otherwise

virtual uint32_t getBinaryShaderSize(effectId_t effectId) const = 0

Used by RamsesRenderer to ask the application for the size in bytes of the binary shader for the given effectId.

This method will only be used by RamsesRenderer if the call to hasBinaryShader() returned true

Parameters:: effectId – Effect Id of the Effect
Returns:: the application must return the exact size of the binary shader data for effectId in bytes. This is the amount of memory RAMSES will allocate for the buffer parameter in the getBinaryShaderData() method below

virtual binaryShaderFormatId_t getBinaryShaderFormat(effectId_t effectId) const = 0

Used by RamsesRenderer to ask the application for the shader format of the binary shader for the given effectId.

This method will only be used by RamsesRenderer if the call to hasBinaryShader() returned true

WARNING! OpenGL can behave very fragile if the shader format is wrong or forged! Never try to mix or interchange binary shaders from an offline shader compiler with storage format from an online shader compiler or vice-versa, as they may differ and using them wrongly can cause surprising driver crashes at unsuspected places!

Parameters:: effectId – Effect Id of the Effect
Returns:: The application must provide the exact shader format specified provided by either the offline shader compiler or the storeBinaryShader() call below, depending on whether the shader was generated by an offline compiler or loaded dynamically at runtime from the driver

virtual bool shouldBinaryShaderBeCached(effectId_t effectId, sceneId_t sceneId) const = 0

Used by RamsesRenderer to ask the application whether a specific effect should be cached.

        This method is called if the shader is not cached yet but could be provided by the renderer.
        The cache can decide whether it the shader should be cached.
        ID of scene that requires the given effect is provided to allow caching for certain scenes only.
        Note that the scene ID is simply the first scene that needs this effect for rendering, there can
        however be more scenes using the same effect.

Parameters:

effectId – [in] Effect Id of the Effect
sceneId – [in] ID of scene that uses the effect.

Returns:

true if the effect should be cached, false otherwise.

virtual void getBinaryShaderData(effectId_t effectId, std::byte *buffer, uint32_t bufferSize) const = 0

Used by RamsesRenderer to ask the application to provide the binary shader data for the given effectId.

This method will only be used by RamsesRenderer if the call to hasBinaryShader() returned true

RamsesRenderer expects the application to write into ‘buffer’ which is guaranteed to have at least ‘bufferSize’ allocated bytes

Parameters:

effectId – Effect Id of the Effect
buffer – pointer to the buffer to be filled the binary shader data
bufferSize – the size of ‘buffer’

virtual void storeBinaryShader(effectId_t effectId, sceneId_t sceneId, const std::byte *binaryShaderData, uint32_t binaryShaderDataSize, binaryShaderFormatId_t binaryShaderFormat) = 0

Used by RamsesRenderer to provide the application with a binary shader data an effect with the given effectId.

If the driver supports reading binary shader cache for compiled shaders, then RamsesRenderer will call storeBinaryShader() whenever a new shader was compiled, to provide the application with the corresponding data Ramses will not cache this data itself - so if the effect is deleted and used again later, RamsesRenderer will compile it again, but before it does it will ask the application if a cache is available by calling hasBinaryShader(). So use storeBinaryShader() to cache shaders if they are not supposed to be recompiled.

ID of scene that requires the given effect is provided to allow caching for certain scenes only. Note that the scene ID is simply the first scene that needs this effect for rendering, there can however be more scenes using the same effect.

Parameters:

effectId – [in] Effect Id of the Effect
sceneId – [in] ID of scene that uses the effect.
binaryShaderData – [in] pointer to the binary shader data
binaryShaderDataSize – [in] size of the binary shader data
binaryShaderFormat – [in] format of the binary shader - platform/driver specific binary shader format ID

virtual void binaryShaderUploaded(effectId_t effectId, bool success) const = 0

Used by RamsesRenderer to provide a callback with information on the result of a binary shader upload operation.

This method is called by the renderer after each attempted upload operation from a binary shader cache. It is intended for informational/debugging purposes in detecting an invalid binary shader cache.

Parameters:

effectId – Effect Id of the Effect
success – The result

class IRendererEventHandler

#include <IRendererEventHandler.h>

Provides an interface for handling the result of renderer events. Implementation of this interface must be passed to RamsesRenderer::dispatchEvents which will in return invoke methods of the interface according to events that occurred since last dispatching.

Subclassed by ramses::RendererEventHandlerEmpty

Public Functions

virtual void offscreenBufferCreated(displayId_t displayId, displayBufferId_t offscreenBufferId, ERendererEventResult result) = 0

This method will be called after an offscreen buffer is created (or failed to be created) as a result of RamsesRenderer API createOffscreenBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
offscreenBufferId – The id of the offscreen buffer that was created or failed to be created.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

virtual void offscreenBufferDestroyed(displayId_t displayId, displayBufferId_t offscreenBufferId, ERendererEventResult result) = 0

This method will be called after an offscreen buffer is destroyed (or failed to be destroyed) as a result of RamsesRenderer API destroyOffscreenBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
offscreenBufferId – The id of the offscreen buffer that was destroyed or failed to be destroyed.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

virtual void framebufferPixelsRead(const uint8_t *pixelData, const uint32_t pixelDataSize, displayId_t displayId, displayBufferId_t displayBuffer, ERendererEventResult result) = 0

This method will be called when a read back of pixels from display buffer was finished. This is the result of RamsesRenderer::readPixels call which triggers an asynchronous read back from the internal device.

Parameters:

pixelData – Pointer to the pixel data in uncompressed RGBA8 format. Check result and pixelDataSize first to determine the state and size of the data. The data is available at the pointer only during the dispatch of this event. The pointer is nullptr in case of failure.
pixelDataSize – The number of elements in the data array pixelData, ie. number of pixels * 4 (color channels). The size is 0 in case of failure.
displayId – Display id of display that the callback refers to.
displayBuffer – Buffer id of buffer that the callback refers to.
result – Can be ERendererEventResult_OK if succeeded or ERendererEventResult_FAIL if failed.

virtual void displayCreated(displayId_t displayId, ERendererEventResult result) = 0

This method will be called after a display was created (or failed to create) as a result of RamsesRenderer API createDisplay call.

Parameters:

displayId – id of the display that was created and initialized (or failed in case of error).
result – Can be ERendererEventResult_OK if succeeded or ERendererEventResult_FAIL if failed.

virtual void displayDestroyed(displayId_t displayId, ERendererEventResult result) = 0

This method will be called after a display was destroyed (or failed to destroy) as a result of RamsesRenderer API destroyDisplay call.

Parameters:

displayId – Display id of display that the callback refers to.
result – Can be ERendererEventResult_OK if succeeded or ERendererEventResult_FAIL if failed.

virtual void keyEvent(displayId_t displayId, EKeyEvent eventType, KeyModifiers keyModifiers, EKeyCode keyCode) = 0

This method will be called when a key has been pressed while a display’s window was focused.

Parameters:

displayId – The display on which the event occurred
eventType – Specifies which type of key event has occurred
keyModifiers – Modifiers used while pressing a key (bit mask of EKeyModifier)
keyCode – The actual key which was pressed

virtual void mouseEvent(displayId_t displayId, EMouseEvent eventType, int32_t mousePosX, int32_t mousePosY) = 0

This method will be called when a mouse event action has occurred while a display’s window was focused.

Parameters:

displayId – The display on which the event occurred
eventType – Specifies which kind of mouse action has occurred
mousePosX – Horizontal mouse position related to window (left = 0)
mousePosY – Vertical mouse position related to window (top = 0)

virtual void windowResized(displayId_t displayId, uint32_t width, uint32_t height) = 0

This method will be called when a display’s window has been resized.

This applies specifically to windows that are created and maintained by the renderer during display creation, which is the default behavior of the renderer.

Parameters:

displayId – The ramses display whose corresponding window was resized
width – The new width of the window
height – The new height of the window

virtual void windowMoved(displayId_t displayId, int32_t windowPosX, int32_t windowPosY) = 0

This method will be called when a display’s window has been moved, if the renderer uses WGL/Windows or X11/Linux as a window system.

Parameters:

displayId – The ramses display whose corresponding window was resized
windowPosX – The new horizontal position of the window’s upper left corner
windowPosY – The new vertical position of the window’s upper left corner

virtual void windowClosed(displayId_t displayId) = 0

This method will be called when a display’s window has been closed.

Parameters:: displayId – The display on which the event occurred

inline virtual void renderThreadLoopTimings(displayId_t displayId, std::chrono::microseconds maximumLoopTime, std::chrono::microseconds averageLooptime)

This method will be called in period given to renderer config (ramses::RendererConfig::setRenderThreadLoopTimingReportingPeriod) and provides rough performance indicators - maximum and average loop (frame) time within that measure period.

This method will be called for all displays with different displayId values. There is no guarantee that all displays appear within the same dispatch call.

Parameters:

displayId – [in] The display the timing information is for
maximumLoopTime – [in] The maximum time a loop of the first display within the last measure period
averageLooptime – [in] The average time a loop of the first display within the last measure period

virtual void externalBufferCreated(displayId_t displayId, externalBufferId_t externalBufferId, uint32_t textureGlId, ERendererEventResult result) = 0

This method will be called after an external buffer is created (or failed to be created) as a result of RamsesRenderer API createExternalBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
externalBufferId – The id of the external buffer that was created or failed to be created.
textureGlId – The OpenGL texture id of the external texture object used for the external buffer on the device in case creation was successful.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

virtual void externalBufferDestroyed(displayId_t displayId, externalBufferId_t externalBufferId, ERendererEventResult result) = 0

This method will be called after an external buffer is destroyed (or failed to be destroyed) as a result of RamsesRenderer API destroyExternalBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
externalBufferId – The id of the external buffer that was destroyed or failed to be destroyed.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

virtual ~IRendererEventHandler() = default: Empty destructor.

class RendererEventHandlerEmpty : public ramses::IRendererEventHandler 

#include <IRendererEventHandler.h>

Convenience empty implementation of IRendererEventHandler that can be used to derive from when only subset of event handling methods need to be implemented.

Public Functions

inline virtual void offscreenBufferCreated(displayId_t displayId, displayBufferId_t offscreenBufferId, ERendererEventResult result) override

This method will be called after an offscreen buffer is created (or failed to be created) as a result of RamsesRenderer API createOffscreenBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
offscreenBufferId – The id of the offscreen buffer that was created or failed to be created.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

inline virtual void offscreenBufferDestroyed(displayId_t displayId, displayBufferId_t offscreenBufferId, ERendererEventResult result) override

This method will be called after an offscreen buffer is destroyed (or failed to be destroyed) as a result of RamsesRenderer API destroyOffscreenBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
offscreenBufferId – The id of the offscreen buffer that was destroyed or failed to be destroyed.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

inline virtual void framebufferPixelsRead(const uint8_t *pixelData, const uint32_t pixelDataSize, displayId_t displayId, displayBufferId_t displayBuffer, ERendererEventResult result) override

This method will be called when a read back of pixels from display buffer was finished. This is the result of RamsesRenderer::readPixels call which triggers an asynchronous read back from the internal device.

Parameters:

pixelData – Pointer to the pixel data in uncompressed RGBA8 format. Check result and pixelDataSize first to determine the state and size of the data. The data is available at the pointer only during the dispatch of this event. The pointer is nullptr in case of failure.
pixelDataSize – The number of elements in the data array pixelData, ie. number of pixels * 4 (color channels). The size is 0 in case of failure.
displayId – Display id of display that the callback refers to.
displayBuffer – Buffer id of buffer that the callback refers to.
result – Can be ERendererEventResult_OK if succeeded or ERendererEventResult_FAIL if failed.

inline virtual void displayCreated(displayId_t displayId, ERendererEventResult result) override

This method will be called after a display was created (or failed to create) as a result of RamsesRenderer API createDisplay call.

Parameters:

displayId – id of the display that was created and initialized (or failed in case of error).
result – Can be ERendererEventResult_OK if succeeded or ERendererEventResult_FAIL if failed.

inline virtual void displayDestroyed(displayId_t displayId, ERendererEventResult result) override

This method will be called after a display was destroyed (or failed to destroy) as a result of RamsesRenderer API destroyDisplay call.

Parameters:

displayId – Display id of display that the callback refers to.
result – Can be ERendererEventResult_OK if succeeded or ERendererEventResult_FAIL if failed.

inline virtual void keyEvent(displayId_t displayId, EKeyEvent eventType, KeyModifiers keyModifiers, EKeyCode keyCode) override

This method will be called when a key has been pressed while a display’s window was focused.

Parameters:

displayId – The display on which the event occurred
eventType – Specifies which type of key event has occurred
keyModifiers – Modifiers used while pressing a key (bit mask of EKeyModifier)
keyCode – The actual key which was pressed

inline virtual void mouseEvent(displayId_t displayId, EMouseEvent eventType, int32_t mousePosX, int32_t mousePosY) override

This method will be called when a mouse event action has occurred while a display’s window was focused.

Parameters:

displayId – The display on which the event occurred
eventType – Specifies which kind of mouse action has occurred
mousePosX – Horizontal mouse position related to window (left = 0)
mousePosY – Vertical mouse position related to window (top = 0)

inline virtual void windowResized(displayId_t displayId, uint32_t width, uint32_t height) override

This method will be called when a display’s window has been resized.

This applies specifically to windows that are created and maintained by the renderer during display creation, which is the default behavior of the renderer.

Parameters:

displayId – The ramses display whose corresponding window was resized
width – The new width of the window
height – The new height of the window

inline virtual void windowMoved(displayId_t displayId, int32_t windowPosX, int32_t windowPosY) override

This method will be called when a display’s window has been moved, if the renderer uses WGL/Windows or X11/Linux as a window system.

Parameters:

displayId – The ramses display whose corresponding window was resized
windowPosX – The new horizontal position of the window’s upper left corner
windowPosY – The new vertical position of the window’s upper left corner

inline virtual void windowClosed(displayId_t displayId) override

This method will be called when a display’s window has been closed.

Parameters:: displayId – The display on which the event occurred

inline virtual void renderThreadLoopTimings(displayId_t displayId, std::chrono::microseconds maximumLoopTime, std::chrono::microseconds averageLooptime) override

This method will be called in period given to renderer config (ramses::RendererConfig::setRenderThreadLoopTimingReportingPeriod) and provides rough performance indicators - maximum and average loop (frame) time within that measure period.

This method will be called for all displays with different displayId values. There is no guarantee that all displays appear within the same dispatch call.

Parameters:

displayId – [in] The display the timing information is for
maximumLoopTime – [in] The maximum time a loop of the first display within the last measure period
averageLooptime – [in] The average time a loop of the first display within the last measure period

inline virtual void externalBufferCreated(displayId_t displayId, externalBufferId_t externalBufferId, uint32_t textureGlId, ERendererEventResult result) override

This method will be called after an external buffer is created (or failed to be created) as a result of RamsesRenderer API createExternalBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
externalBufferId – The id of the external buffer that was created or failed to be created.
textureGlId – The OpenGL texture id of the external texture object used for the external buffer on the device in case creation was successful.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

inline virtual void externalBufferDestroyed(displayId_t displayId, externalBufferId_t externalBufferId, ERendererEventResult result) override

This method will be called after an external buffer is destroyed (or failed to be destroyed) as a result of RamsesRenderer API destroyExternalBuffer call.

Parameters:

displayId – Display id of display that the callback refers to.
externalBufferId – The id of the external buffer that was destroyed or failed to be destroyed.
result – Can be ERendererEventResult_OK if succeeded, ERendererEventResult_FAIL if failed.

class IRendererSceneControlEventHandler

#include <IRendererSceneControlEventHandler.h>

Provides an interface for handling the result of renderer scene control events. Implementation of this interface must be passed to ramses::RendererSceneControl::dispatchEvents which will in return invoke methods of the interface according to events that occurred since last dispatching.

Subclassed by ramses::RendererSceneControlEventHandlerEmpty

Public Functions

virtual void sceneStateChanged(sceneId_t sceneId, RendererSceneState state) = 0

This method will be called when state of a scene changes.

Typically this is a result of ramses::RendererSceneControl::setSceneState call but can be also triggered externally (e.g. scene was unpublished by client). Note that there can be multiple state change callbacks in a row depending on number of state transitions needed between the previous state and target state when calling ramses::RendererSceneControl::setSceneState.

Limitation: This callback will not be executed if there is no display created and running. All published scenes (Available state) will be announced only after a display is created and running. Also all published scenes will be announced again if display is destroyed and created again and it is the only display on renderer.

Parameters:

sceneId – The ID of scene with changed state
state – New state of the scene

virtual void offscreenBufferLinked(displayBufferId_t offscreenBufferId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) = 0

This method will be called when the data link between offscreen buffer and scene’s data slot is established.

This is a result of ramses::RendererSceneControl::linkOffscreenBuffer call.

Parameters:

offscreenBufferId – The ID of offscreen buffer which is linked as data provider
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer where the offscreen buffer is linked to
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

virtual void externalBufferLinked(externalBufferId_t externalBufferId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) = 0

This method will be called when the data link between external buffer and scene’s data slot is established.

This is a result of ramses::RendererSceneControl::linkExternalBuffer call.

Parameters:

externalBufferId – The ID of external buffer which is linked as data provider
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer where the external buffer is linked to
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

virtual void streamBufferLinked(streamBufferId_t streamBufferId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) = 0

This method will be called when the data link between stream buffer and scene’s data slot is established.

This is a result of ramses::RendererSceneControl::linkStreamBuffer call.

Parameters:

streamBufferId – The ID of stream buffer which is linked as data provider
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer where the stream buffer is linked to
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

virtual void dataLinked(sceneId_t providerScene, dataProviderId_t providerId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) = 0

This method will be called when the data link between a data provider and data consumer is established.

This is a result of ramses::RendererSceneControl::linkData call.

Parameters:

providerScene – The ID of scene where the data provider slot is
providerId – The ID of data provider which was linked
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer which was linked
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

virtual void dataUnlinked(sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) = 0

This method will be called when the data link between a data provider and data consumer is destroyed.

This is a result of ramses::RendererSceneControl::unlinkData call.

Parameters:

consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer which was unlinked
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

virtual void dataProviderCreated(sceneId_t sceneId, dataProviderId_t dataProviderId) = 0

This method will be called whenever a data provider is created.

The event is emitted also for every data provider in a newly available scene.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataProviderId – The created data provider id

virtual void dataProviderDestroyed(sceneId_t sceneId, dataProviderId_t dataProviderId) = 0

This method will be called when a data provider is destroyed.

The event is emitted only when data provider destroyed, not if scene becomes unavailable as a whole.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataProviderId – The destroyed data provider id

virtual void dataConsumerCreated(sceneId_t sceneId, dataConsumerId_t dataConsumerId) = 0

This method will be called whenever a data consumer is created.

The event is emitted also for every data consumer in a newly available scene.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataConsumerId – The created data consumer id

virtual void dataConsumerDestroyed(sceneId_t sceneId, dataConsumerId_t dataConsumerId) = 0

This method will be called when a data consumer is destroyed.

The event is emitted only when data consumer destroyed, not if scene becomes unavailable as a whole.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataConsumerId – The destroyed data consumer id

virtual void sceneFlushed(sceneId_t sceneId, sceneVersionTag_t sceneVersionTag) = 0

This method will be called after a flush with version tag (ramses::Scene::flush) has been applied.

Parameters:

sceneId – The scene id of the scene which the versioned flush belongs to
sceneVersionTag – The version tag of the scene flush

virtual void sceneExpirationMonitoringEnabled(sceneId_t sceneId) = 0

This method will be called whenever a scene which was not previously monitored for expiration has requested expiration monitoring by sending a scene flush with valid expiration timestamp (ramses::Scene::setExpirationTimestamp) and that flush was applied on renderer side. From this point on, the scene will be monitored, can expire and recover (sceneExpired, sceneRecoveredFromExpiration) until monitoring disabled again (sceneExpirationMonitoringDisabled).

Parameters:: sceneId – The scene id of the scene that will be monitored for expiration

virtual void sceneExpirationMonitoringDisabled(sceneId_t sceneId) = 0

This method will be called whenever a scene which was previously monitored for expiration has requested to stop being monitored by sending a scene flush with invalid expiration timestamp (ramses::Scene::setExpirationTimestamp) and that flush was applied on renderer side. This method will also be called if a previously monitored scene is unsubscribed from the renderer, i.e. drops state to ramses::RendererSceneState::Available from previous ramses::RendererSceneState::Ready (or potentially after canceled transition to ramses::RendererSceneState::Ready). From this point on, the scene will not be monitored anymore, regardless if it previously expired or not, i.e. there will be no expiration events (sceneExpired, sceneRecoveredFromExpiration) until monitoring enabled again (sceneExpirationMonitoringEnabled).

Parameters:: sceneId – The scene id of the scene that will not be monitored for expiration anymore

virtual void sceneExpired(sceneId_t sceneId) = 0

This method will be called if a scene which is enabled for expiration monitoring (sceneExpirationMonitoringEnabled) is on renderer (not necessarily rendered) at a state that expired, i.e. current time is after the expiration timestamp set via ramses::Scene::setExpirationTimestamp. This callback is called only once when the scene expires even if scene stays expired in subsequent frames. When the scene is updated again with a new not anymore expired timestamp, sceneRecoveredFromExpiration is called.

Parameters:: sceneId – The scene id of the scene on which the event occurred

virtual void sceneRecoveredFromExpiration(sceneId_t sceneId) = 0

This method will be called if a scene which previously expired (ramses::Scene::setExpirationTimestamp and sceneExpired) was updated with a new expiration timestamp that is not expired anymore. This callback is called only once when the scene switches state from expired to not expired. This callback is not called when monitoring becomes disabled (sceneExpirationMonitoringDisabled) while scene is expired (sceneExpired).

Parameters:: sceneId – The scene id of the scene on which the event occurred

virtual void streamAvailabilityChanged(waylandIviSurfaceId_t streamId, bool available) = 0

This method will be called when a new IVI video stream becomes available, or when an existing stream disappears In terms of Wayland protocol, a stream is available if an “ivi_application” exists which has created a wayland surface (wl_surface) with ivi_id=streamId, and the surface has at least one attached non-nullptr buffer (i.e. renderable content).

It is possible that the ivi_application does not update its surface (by providing new buffers/frames), but RAMSES has no way of knowing that, hence a stream is not reported unavailable in that case.

A surface becomes unavailable whenever either the ivi_application is closed or when it attached a nullptr buffer to the stream surface with id=streamId (i.e. actively told wayland that it should not render contents to this ivi surface).

Parameters:

streamId – The IVI stream id
available – True if the stream became available, and false if it disappeared

virtual void objectsPicked(sceneId_t sceneId, const pickableObjectId_t *pickedObjects, size_t pickedObjectsCount) = 0

This method will be called when there were scene objects picked. A ramses::PickableObject can be ‘picked’ via a pick input event which is passed to ramses::RendererSceneControl when the scene is rendered (see ramses::RendererSceneControl::handlePickEvent).

Parameters:

sceneId – [in] ID of scene to which the picked objects belong.
pickedObjects – [in] Pointer to first ID of the picked objects array, this array is valid only for the time of calling this method. Picked objects are sorted from closest to farthest w.r.t. their assigned camera.
pickedObjectsCount – [in] Number of picked object IDs in the pickedObjects array.

virtual ~IRendererSceneControlEventHandler() = default: Empty destructor.

class RendererSceneControlEventHandlerEmpty : public ramses::IRendererSceneControlEventHandler 

#include <IRendererSceneControlEventHandler.h>

Convenience empty implementation of IRendererSceneControlEventHandler that can be used to derive from when only subset of event handling methods need to be implemented.

Public Functions

inline virtual void sceneStateChanged(sceneId_t sceneId, RendererSceneState state) override

This method will be called when state of a scene changes.

Typically this is a result of ramses::RendererSceneControl::setSceneState call but can be also triggered externally (e.g. scene was unpublished by client). Note that there can be multiple state change callbacks in a row depending on number of state transitions needed between the previous state and target state when calling ramses::RendererSceneControl::setSceneState.

Limitation: This callback will not be executed if there is no display created and running. All published scenes (Available state) will be announced only after a display is created and running. Also all published scenes will be announced again if display is destroyed and created again and it is the only display on renderer.

Parameters:

sceneId – The ID of scene with changed state
state – New state of the scene

inline virtual void offscreenBufferLinked(displayBufferId_t offscreenBufferId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) override

This method will be called when the data link between offscreen buffer and scene’s data slot is established.

This is a result of ramses::RendererSceneControl::linkOffscreenBuffer call.

Parameters:

offscreenBufferId – The ID of offscreen buffer which is linked as data provider
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer where the offscreen buffer is linked to
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

inline virtual void externalBufferLinked(externalBufferId_t externalBufferId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) override

This method will be called when the data link between external buffer and scene’s data slot is established.

This is a result of ramses::RendererSceneControl::linkExternalBuffer call.

Parameters:

externalBufferId – The ID of external buffer which is linked as data provider
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer where the external buffer is linked to
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

inline virtual void streamBufferLinked(streamBufferId_t streamBufferId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) override

This method will be called when the data link between stream buffer and scene’s data slot is established.

This is a result of ramses::RendererSceneControl::linkStreamBuffer call.

Parameters:

streamBufferId – The ID of stream buffer which is linked as data provider
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer where the stream buffer is linked to
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

inline virtual void dataLinked(sceneId_t providerScene, dataProviderId_t providerId, sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) override

This method will be called when the data link between a data provider and data consumer is established.

This is a result of ramses::RendererSceneControl::linkData call.

Parameters:

providerScene – The ID of scene where the data provider slot is
providerId – The ID of data provider which was linked
consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer which was linked
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

inline virtual void dataUnlinked(sceneId_t consumerScene, dataConsumerId_t consumerId, bool success) override

This method will be called when the data link between a data provider and data consumer is destroyed.

This is a result of ramses::RendererSceneControl::unlinkData call.

Parameters:

consumerScene – The ID of scene where the data consumer slot is
consumerId – The ID of data consumer which was unlinked
success – True if succeeded, false otherwise - check renderer logs for concrete error message.

inline virtual void dataProviderCreated(sceneId_t sceneId, dataProviderId_t dataProviderId) override

This method will be called whenever a data provider is created.

The event is emitted also for every data provider in a newly available scene.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataProviderId – The created data provider id

inline virtual void dataProviderDestroyed(sceneId_t sceneId, dataProviderId_t dataProviderId) override

This method will be called when a data provider is destroyed.

The event is emitted only when data provider destroyed, not if scene becomes unavailable as a whole.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataProviderId – The destroyed data provider id

inline virtual void dataConsumerCreated(sceneId_t sceneId, dataConsumerId_t dataConsumerId) override

This method will be called whenever a data consumer is created.

The event is emitted also for every data consumer in a newly available scene.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataConsumerId – The created data consumer id

inline virtual void dataConsumerDestroyed(sceneId_t sceneId, dataConsumerId_t dataConsumerId) override

This method will be called when a data consumer is destroyed.

The event is emitted only when data consumer destroyed, not if scene becomes unavailable as a whole.

Parameters:

sceneId – The scene id of the scene on which the event occurred
dataConsumerId – The destroyed data consumer id

inline virtual void sceneFlushed(sceneId_t sceneId, sceneVersionTag_t sceneVersionTag) override

This method will be called after a flush with version tag (ramses::Scene::flush) has been applied.

Parameters:

sceneId – The scene id of the scene which the versioned flush belongs to
sceneVersionTag – The version tag of the scene flush

inline virtual void sceneExpirationMonitoringEnabled(sceneId_t sceneId) override

This method will be called whenever a scene which was not previously monitored for expiration has requested expiration monitoring by sending a scene flush with valid expiration timestamp (ramses::Scene::setExpirationTimestamp) and that flush was applied on renderer side. From this point on, the scene will be monitored, can expire and recover (sceneExpired, sceneRecoveredFromExpiration) until monitoring disabled again (sceneExpirationMonitoringDisabled).

Parameters:: sceneId – The scene id of the scene that will be monitored for expiration

inline virtual void sceneExpirationMonitoringDisabled(sceneId_t sceneId) override

This method will be called whenever a scene which was previously monitored for expiration has requested to stop being monitored by sending a scene flush with invalid expiration timestamp (ramses::Scene::setExpirationTimestamp) and that flush was applied on renderer side. This method will also be called if a previously monitored scene is unsubscribed from the renderer, i.e. drops state to ramses::RendererSceneState::Available from previous ramses::RendererSceneState::Ready (or potentially after canceled transition to ramses::RendererSceneState::Ready). From this point on, the scene will not be monitored anymore, regardless if it previously expired or not, i.e. there will be no expiration events (sceneExpired, sceneRecoveredFromExpiration) until monitoring enabled again (sceneExpirationMonitoringEnabled).

Parameters:: sceneId – The scene id of the scene that will not be monitored for expiration anymore

inline virtual void sceneExpired(sceneId_t sceneId) override

This method will be called if a scene which is enabled for expiration monitoring (sceneExpirationMonitoringEnabled) is on renderer (not necessarily rendered) at a state that expired, i.e. current time is after the expiration timestamp set via ramses::Scene::setExpirationTimestamp. This callback is called only once when the scene expires even if scene stays expired in subsequent frames. When the scene is updated again with a new not anymore expired timestamp, sceneRecoveredFromExpiration is called.

Parameters:: sceneId – The scene id of the scene on which the event occurred

inline virtual void sceneRecoveredFromExpiration(sceneId_t sceneId) override

This method will be called if a scene which previously expired (ramses::Scene::setExpirationTimestamp and sceneExpired) was updated with a new expiration timestamp that is not expired anymore. This callback is called only once when the scene switches state from expired to not expired. This callback is not called when monitoring becomes disabled (sceneExpirationMonitoringDisabled) while scene is expired (sceneExpired).

Parameters:: sceneId – The scene id of the scene on which the event occurred

inline virtual void streamAvailabilityChanged(waylandIviSurfaceId_t streamId, bool available) override

This method will be called when a new IVI video stream becomes available, or when an existing stream disappears In terms of Wayland protocol, a stream is available if an “ivi_application” exists which has created a wayland surface (wl_surface) with ivi_id=streamId, and the surface has at least one attached non-nullptr buffer (i.e. renderable content).

It is possible that the ivi_application does not update its surface (by providing new buffers/frames), but RAMSES has no way of knowing that, hence a stream is not reported unavailable in that case.

A surface becomes unavailable whenever either the ivi_application is closed or when it attached a nullptr buffer to the stream surface with id=streamId (i.e. actively told wayland that it should not render contents to this ivi surface).

Parameters:

streamId – The IVI stream id
available – True if the stream became available, and false if it disappeared

inline virtual void objectsPicked(sceneId_t sceneId, const pickableObjectId_t *pickedObjects, size_t pickedObjectsCount) override

This method will be called when there were scene objects picked. A ramses::PickableObject can be ‘picked’ via a pick input event which is passed to ramses::RendererSceneControl when the scene is rendered (see ramses::RendererSceneControl::handlePickEvent).

Parameters:

sceneId – [in] ID of scene to which the picked objects belong.
pickedObjects – [in] Pointer to first ID of the picked objects array, this array is valid only for the time of calling this method. Picked objects are sorted from closest to farthest w.r.t. their assigned camera.
pickedObjectsCount – [in] Number of picked object IDs in the pickedObjects array.

class RamsesRenderer

#include <RamsesRenderer.h>

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 ramses::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 ramses::RamsesRenderer::dispatchEvents. Some commands can fail immediately by returning false, in such case there will be no callback, because the command will not even be submitted. ramses::RamsesRenderer API is not thread-safe.

Public Functions

bool 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:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool isThreadRunning() const

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

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

bool setFramerateLimit(displayId_t displayId, float fpsLimit)

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). This function can only be used in threaded mode (startThread). The default value is 60 FPS.

Note that FPS limit can be set also for a display that was not yet created internally (i.e. ramses::IRendererEventHandler::displayCreated event has not been dispatched yet), this makes it easier to set a FPS limit on a display right after creation without having to wait for the result. If setting FPS limit on display which was previously destroyed this method will return true but will have no effect.

Parameters:

displayId – The ID of the display the framerate should be applied to. The default value is 60 FPS.
fpsLimit – The maximum frame rate per second to set for the render loop.

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

float getFramerateLimit(displayId_t displayId) const

Get the maximum frame rate per second set for given display using setFramerateLimit.

This method returns the FPS limit set by user using setFramerateLimit, or the default (60 FPS) if not modified by user. In both cases regardless if the display exists or not.

Parameters:: displayId – The ID of the display to query the maximum framerate.
Returns:: The FPS limit for given display set by user or default FPS limit.

bool 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:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

ELoopMode getLoopMode() const

Get the current value for loop mode set using setLoopMode.

Returns:: The loop mode

bool 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:

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

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:

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

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:: enable – [in] Enable or disable the feature (enabled initially)
Returns:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

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.

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.

bool 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:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

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. ramses::RamsesRenderer::setDisplayBufferClearColor).

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.

displayBufferId_t createOffscreenBuffer(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).

The created offscreen buffer always has a color buffer. Depth/stencil buffer can be configured (depth/stencil combined is attached by default). 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:

display – [in] id of display for which the buffer should be created
width – [in] width of the buffer to be created (has to be higher than 0)
height – [in] height of the buffer to be created (has to be higher than 0)
sampleCount – [in] Optional sample count for MSAA. Default value is 0 for no MSAA.
depthBufferType – [in] Optional setting to configure depth and stencil buffers, default is depth/stencil buffer will be created in addition to color buffer.

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.

displayBufferId_t createInterruptibleOffscreenBuffer(displayId_t display, uint32_t width, uint32_t height, EDepthBufferType depthBufferType = EDepthBufferType::DepthStencil)

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 a color buffer. Depth/stencil buffer can be configured (depth/stencil combined is attached by default).

Parameters:

display – [in] Id of display for which the buffer should be created
width – [in] Width of the buffer to be created (has to be higher than 0)
height – [in] Height of the buffer to be created (has to be higher than 0)
depthBufferType – [in] Optional setting to configure depth and stencil buffers, default is depth/stencil buffer will be created in addition to color buffer.

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.

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)

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:

display – [in] Id of display for which the buffer should be created
width – [in] Width of the buffer to be created (has to be higher than 0)
height – [in] Height of the buffer to be created (has to be higher than 0)
bufferFourccFormat – [in] Format to be used for underlying storage of the buffer, as specified in drm_fourcc.h on the target platform
usageFlags – [in] Usage flags used for creation of the underlying GBM buffer object, as specific in enum gbm_bo_flags on the target platform
modifier – [in] 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.

bool 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:

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

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:

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

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

externalBufferId_t 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:: display – [in] 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.

bool 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:

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

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

streamBufferId_t createStreamBuffer(displayId_t display, ramses::waylandIviSurfaceId_t surfaceId)

Creates a buffer for viewing wayland surfaces from the embedded compositor. The created buffer can be linked as input to a consumer texture sampler (see ramses::RendererSceneControl::linkStreamBuffer).

Parameters:

display – [in] Id of display that the buffer should be created on.
surfaceId – [in] Id of the wayland surface that the buffer should render from.

Returns:

Identifier of the created external buffer.

bool destroyStreamBuffer(displayId_t display, ramses::streamBufferId_t bufferId)

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

Parameters:

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

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool setDisplayBufferClearFlags(displayId_t display, displayBufferId_t displayBuffer, ClearFlags clearFlags)

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:

display – [in] Id of display that the buffer to set clearing belongs to.
displayBuffer – [in] Id of display buffer to set clearing, if ramses::displayBufferId_t::Invalid() is passed then the clearing is set for display’s framebuffer.
clearFlags – [in] Bitmask of the ramses::EClearFlag, use bit OR to select which buffer component to clear or ramses::EClearFlag::All to clear all (default).

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool setDisplayBufferClearColor(displayId_t display, displayBufferId_t displayBuffer, const vec4f &color)

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:

display – [in] Id of display that the buffer to set clear color belongs to.
displayBuffer – [in] 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.
color – [in] Clear color (rgba, channel values in range [0,1])

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:

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

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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 ramses::RamsesRenderer::dispatchEvents for details.

Parameters:

displayId – [in] id of display to read pixels from.
displayBuffer – [in] Id of display buffer to read pixels from, if ramses::displayBufferId_t::Invalid() is passed then pixels are read from the display’s framebuffer.
x – [in] The starting offset in the original image (i.e. left border) in pixels.
y – [in] 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.
width – [in] The width of the read image in pixels. Must be greater than Zero.
height – [in] The height of the read image in pixels. Must be greater than Zero.

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details). true does not guarantee successful read back, the result event has its own status.

RendererSceneControl *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 ramses::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.

ramses::RamsesRenderer is owner of the ramses::RendererSceneControl API and the pointer stays valid as long as this ramses::RamsesRenderer instance is alive. It cannot be destroyed without destroying the ramses::RamsesRenderer.

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

bool 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:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool 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:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool takeSystemCompositorScreenshot(std::string_view 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:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool dispatchEvents(IRendererEventHandler &rendererEventHandler)

Most RamsesRenderer methods push commands to an internal queue which is submitted when calling ramses::RamsesRenderer::flush. The commands are then executed during a render loop (ramses::RamsesRenderer::doOneLoop or in a render thread if used ramses::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:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool flush()

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

Returns:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool logRendererInfo()

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

Returns:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

RamsesRenderer(const RamsesRenderer&) = delete: Deleted copy constructor.

RamsesRenderer(RamsesRenderer&&) = delete: Deleted move constructor.

RamsesRenderer &operator=(const RamsesRenderer&) = delete

Deleted copy assignment.

Returns:: unused

RamsesRenderer &operator=(RamsesRenderer&&) = delete

Deleted move assignment.

Returns:: unused

internal::RamsesRendererImpl &impl(): Get the internal data for implementation specifics of RamsesRenderer.

const internal::RamsesRendererImpl &impl() const: Get the internal data for implementation specifics of RamsesRenderer.

Friends

friend class internal::RendererFactory

class RendererConfig

#include <RendererConfig.h>

The RendererConfig holds a set of parameters to be used to initialize a renderer.

Public Functions

RendererConfig(): Default constructor of RendererConfig.

~RendererConfig(): Destructor of RendererConfig.

bool setBinaryShaderCache(IBinaryShaderCache &cache)

Set the Binary Shader Cache to be used in Renderer.

Parameters:: cache – [in] the binary shader cache to be used by the Renderer
Returns:: true on success, false if an error occurred (error is logged)

bool enableSystemCompositorControl()

Enable the renderer to communicate with the system compositor. This flag needs to be enabled before calling any of the system compositor related calls, otherwise an error will be reported when issuing such commands.

Returns:: true on success, false if an error occurred (error is logged)

bool setFrameCallbackMaxPollTime(uint64_t waitTimeInUsec)

Set the maximum time to wait for the system compositor frame callback before aborting and skipping rendering of current frame. This is an advanced function to be used by experts only. Be warned that the synchronization of frame callbacks with the system compositor and the display controller vsync is a sensitive topic and can majorly influence system performance.

Parameters:: waitTimeInUsec – [in] The maximum time wait for a frame callback, in microseconds
Returns:: true on success, false if an error occurred (error is logged)

bool setSystemCompositorWaylandDisplay(std::string_view waylandDisplay)

Set the Wayland display name to connect system compositor to. This will override the default behavior which is to use WAYLAND_DISPLAY environment variable.

Parameters:: waylandDisplay – [in] Wayland display name to use for connection
Returns:: true on success, false if an error occurred (error is logged)

std::string_view getSystemCompositorWaylandDisplay() const

Get the current setting of Wayland display name.

Returns:: Wayland display name to use for connection, empty means default

bool setRenderThreadLoopTimingReportingPeriod(std::chrono::milliseconds period)

Set the desired reporting period for first display loop timings.

The values are reported periodically via the renderer callback ramses::IRendererEventHandler::renderThreadLoopTimings. Only the first display is measured. A value of zero disables reporting and is the default.

Parameters:: period – [in] Cyclic time period after which timing information should be reported
Returns:: true on success, false if an error occurred (error is logged)

std::chrono::milliseconds getRenderThreadLoopTimingReportingPeriod() const

Get the current reporting period for renderThread loop timings.

Returns:: Reporting period for renderThread loop timings

RendererConfig(const RendererConfig &other)

Copy constructor.

Parameters:: other – source to copy from

RendererConfig(RendererConfig &&other) noexcept

Move constructor.

Parameters:: other – source to move from

RendererConfig &operator=(const RendererConfig &other)

Copy assignment.

Parameters:: other – source to copy from
Returns:: this instance

RendererConfig &operator=(RendererConfig &&other) noexcept

Move assignment.

Parameters:: other – source to move from
Returns:: this instance

internal::RendererConfigImpl &impl(): Get the internal data for implementation specifics of RendererConfig.

const internal::RendererConfigImpl &impl() const: Get the internal data for implementation specifics of RendererConfig.

class RendererSceneControl

#include <RendererSceneControl.h>

RendererSceneControl controls the states of scenes.

Where ramses::RamsesRenderer is used to configure general rendering (create displays, control looping and other global rendering states), RendererSceneControl is used to configure which content should be rendered and where. Scenes can be assigned to display buffers, shown, hidden, data linked, etc. All the commands in this class are put to a queue and submitted only when 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 dispatchEvents. Some commands can fail immediately by returning false, in such case there will be no callback, because the command will not even be submitted.

Public Functions

bool setSceneState(sceneId_t sceneId, RendererSceneState state)

Request state change of a scene.

Ramses scenes are containers carrying content data from client, apart from the content state there is also a rendering state of a scene on renderer side, see RendererSceneState for description of the states. Any scene state can be requested even if scene was not yet published, internal logic will start state transitions automatically as soon as scene gets published and will emit corresponding state change callbacks for each transition. A valid display mapping has to be set (setSceneMapping) before requesting a scene to be RendererSceneState::Ready or RendererSceneState::Rendered, otherwise this request will fail.

State change request when executed results in a state change callback. If and only if there was an actual scene state change executed in the renderer a ramses::IRendererSceneControlEventHandler::sceneStateChanged is emitted.

Only these transitions are guaranteed to be fully executed in the very next frame after calling flush : RendererSceneState::Ready -> RendererSceneState::Rendered (start rendering) RendererSceneState::Rendered -> RendererSceneState::Ready (stop rendering)

On the other hand a transition to RendererSceneState::Ready from any of the lower states should be expected to take longer time (potentially multiple update loops) due to the need of uploading scene’s resources.

Parameters:

sceneId – [in] Scene to request state change for.
state – [in] Scene state to request.

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details). true does not guarantee success, the result argument in dispatched event has its own status.

bool setSceneMapping(sceneId_t sceneId, displayId_t displayId)

Set scene display mapping.

Every scene has to be mapped to a display first in order to render it on that display. This is crucial for the renderer to know how to manage scene’s resources, namely which rendering context to upload them to. A valid scene mapping is a prerequisite for a request to change scene’s state to RendererSceneState::Ready or RendererSceneState::Rendered.

Scene’s display mapping can only be changed if scene is in a state below RendererSceneState::Ready and not yet requested to switch its state to Ready/Rendered. Setting a scene mapping resets display buffer assignment to its default (framebuffer), see setSceneDisplayBufferAssignment.

Given display ID must refer to an existing display at the time of scene being mapped to that display, i.e. when its state transition to RendererSceneState::Ready is executed.

There is no event callback for this operation, the mapping is set immediately and will be used when executing scene state transition to RendererSceneState::Ready.

Parameters:

sceneId – [in] Scene to set display mapping.
displayId – [in] Display to set as target for scene when mapped.

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool setSceneDisplayBufferAssignment(sceneId_t sceneId, displayBufferId_t displayBuffer, int32_t sceneRenderOrder = 0)

Set scene display buffer assignment.

When scene’s display mapping is set (setSceneMapping) the scene can only be rendered in the context of that display, either into display’s framebuffer or an offscreen buffer belonging to that display. Explicit assignment is not required for a scene to be rendered, a default assignment will be used then which is display’s framebuffer. A display always has a framebuffer, its display buffer ID can be obtained via ramses::RamsesRenderer::getDisplayFramebuffer. Unlike display mapping the assignment to a display buffer can be changed in any of the scene’s states, the only requirement is that a valid display mapping was previously set (setSceneMapping).

Assigning a scene to display buffer changes the way its render order is determined. The render order of following buffer groups is fixed:

Offscreen buffers
Framebuffer
Interruptible offscreen buffers So the scene render order only affects the sorting within its corresponding group.

There is no event callback for this operation, the assignment can be assumed to be effective in the next frame scene is rendered after flushed.

Parameters:

sceneId – [in] Scene to assign to given display buffer.
displayBuffer – [in] Id of display buffer (framebuffer or offscreen buffer) the scene should be assigned to. If provided buffer Id is invalid, framebuffer of display where scene is mapped is used.
sceneRenderOrder – [in] Lower value means that a scene is rendered before a scene with higher value. Default is 0.

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool linkOffscreenBuffer(displayBufferId_t offscreenBufferId, sceneId_t consumerSceneId, dataConsumerId_t consumerDataSlotId)

Links display’s offscreen buffer to a data consumer in scene.

This is a special case of Ramses data linking where offscreen buffer acts as texture provider. Offscreen buffer can be used as texture data in one or more scene’s texture sampler(s) (ramses::Scene::createTextureConsumer). For successful link, the consumer scene must be RendererSceneState::Ready or RendererSceneState::Rendered and has to be mapped (setSceneMapping) to the same display that the offscreen buffer belongs to. If the data consumer is already linked to a provider (data or offscreen buffer), the old link will be discarded, however if the new link fails it is undefined whether previous link was discarded or not. Note: To unlink offscreen buffer use unlinkData as with any other type of data linking.

ramses::IRendererSceneControlEventHandler::offscreenBufferLinked will be emitted after offscreen buffer linked to consumer. If successful the operation can be assumed to be effective in the next frame consumer scene is rendered after flushed.

Parameters:

offscreenBufferId – [in] ID of the offscreen buffer to use as texture provider.
consumerSceneId – [in] Scene which consumes the data.
consumerDataSlotId – [in] Data consumer within the consumer scene (ramses::Scene::createTextureConsumer).

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details). true does not guarantee success, the result argument in dispatched event has its own status.

bool linkStreamBuffer(streamBufferId_t streamBufferId, sceneId_t consumerSceneId, dataConsumerId_t consumerDataSlotId)

Links display’s stream buffer to a data consumer in scene.

This is a special case of Ramses data linking where stream buffer acts as texture provider. Stream buffer can be used as texture data in one or more scene’s texture sampler(s) (ramses::Scene::createTextureConsumer). For successful link, the consumer scene must be RendererSceneState::Ready or RendererSceneState::Rendered and has to be mapped (setSceneMapping) to the same display that the stream buffer belongs to. If the data consumer is already linked to a provider (data or stream buffer), the old link will be discarded, however if the new link fails it is undefined whether previous link was discarded or not. Note: To unlink stream buffer use unlinkData as with any other type of data linking.

A stream buffer can be linked successfully regardless of whether content from the wayland surface is available at the time of linking. If content from the wayland surface is - or becomes - unavailable the linked texture consumers use the original texture samplers’ content before linking.

ramses::IRendererSceneControlEventHandler::streamBufferLinked will be emitted after stream buffer linked to consumer. If successful the operation can be assumed to be effective in the next frame consumer scene is rendered after flushed.

Parameters:

streamBufferId – [in] ID of the stream buffer to use as texture provider.
consumerSceneId – [in] Scene which consumes the data.
consumerDataSlotId – [in] Data consumer within the consumer scene (ramses::Scene::createTextureConsumer).

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details). true does not guarantee success, the result argument in dispatched event has its own status.

bool linkExternalBuffer(externalBufferId_t externalBufferId, sceneId_t consumerSceneId, dataConsumerId_t consumerDataSlotId)

Links external buffer to a data consumer in scene.

This is a case of Ramses data linking where external buffer acts as texture data provider. External buffer can be used as texture data in one or more scene’s external texture sampler(s) (ramses::Scene::createTextureConsumer). For successful link, the consumer scene must be RendererSceneState::Ready or RendererSceneState::Rendered and has to be mapped (setSceneMapping) to the same display that the external buffer belongs to. If the data consumer is already linked to a provider (data or external buffer), the old link will be discarded, however if the new link fails it is undefined whether previous link was discarded or not. Note: To unlink external buffer use unlinkData as with any other type of data linking.

If target compile definition for enabling events for external buffers is explicitly defined, then ramses::IRendererSceneControlEventHandler::externalBufferLinked will be emitted after external buffer linked to consumer. If successful the operation can be assumed to be effective in the next frame consumer scene is rendered after flushed.

Parameters:

externalBufferId – [in] ID of the external buffer to use as external texture provider.
consumerSceneId – [in] Scene which consumes the data.
consumerDataSlotId – [in] Data consumer within the consumer scene (ramses::Scene::createTextureConsumer).

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details). true does not guarantee success, the result argument in dispatched event has its own status.

bool linkData(sceneId_t providerSceneId, dataProviderId_t providerId, sceneId_t consumerSceneId, dataConsumerId_t consumerId)

Links a data provider from one scene to a data consumer in another scene.

Linking data means that the consumer’s data property will be overridden by provider’s data property. Consumer can be linked to only one provider, a provider can be linked to multiple consumers. ramses::IRendererSceneControlEventHandler::dataLinked will be emitted after the link is established. Both provider scene and consumer scene have to be mapped (ramses::RendererSceneControl::setSceneMapping) to the same display and must be in state RendererSceneState::Ready or above. The link will fail (reported via callback result argument) if either the provider or consumer does not exist or their data type does not match. If successful the operation can be assumed to be effective in the next frame consumer scene is rendered after flushed. If the data consumer is already linked to a provider (data or offscreen buffer), the old link will be discarded, however if the new link fails it is undefined whether previous link was discarded or not.

Parameters:

providerSceneId – Provider scene containing provided data.
providerId – ID of provided data.
consumerSceneId – Consumer scene containing consumer slot.
consumerId – ID of consumer slot.

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details). true does not guarantee success, the result argument in dispatched event has its own status.

bool unlinkData(sceneId_t consumerSceneId, dataConsumerId_t consumerId)

Removes an existing link between data provider and consumer (linkData) or offscreen buffer and consumer (linkOffscreenBuffer).

Data link is fully defined by consumer scene and its data slot as there can only be one link from consumer to provider. ramses::IRendererSceneControlEventHandler::dataUnlinked will be emitted after consumer unlinked from provider. If successful the operation can be assumed to be effective in the next frame consumer scene is rendered after flushed.

Parameters:

consumerSceneId – Consumer scene containing consumer slot.
consumerId – ID of consumer slot.

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details). true does not guarantee success, the result argument in dispatched event has its own status.

bool handlePickEvent(sceneId_t sceneId, float bufferNormalizedCoordX, float bufferNormalizedCoordY)

Trigger renderer to test if given pick event with coordinates intersects with any instances of ramses::PickableObject contained in given scene. If so, the intersected PickableObjects are reported to ramses::RendererSceneControl (see ramses::IRendererEventHandler::objectsPicked) using their user IDs given at creation time (see ramses::Scene::createPickableObject).

PickCoordinates

Coordinates normalized to range <-1, 1> where (-1, -1) is bottom left corner of the buffer where scene is mapped to and (1, 1) is top right corner. If the scene to test is rendered directly to framebuffer then display size should be used, i.e. (-1, -1) is bottom left corner of the display and (1, 1) top right corner of display. If the scene is mapped to an offscreen buffer and rendered as a texture mapped on a mesh in another scene, the given coordinates need to be mapped to the offscreen buffer dimensions in the same way. For example if the scene’s offscreen buffer is mapped on a 2D quad placed somewhere on screen then the coordinates provided need to be within the region of the 2D quad, i.e. (-1, -1) at bottom left corner of the quad and (1, 1) at top right corner.

Parameters:

sceneId – Id of scene to check for intersected PickableObjects.
bufferNormalizedCoordX – Normalized X pick coordinate within buffer size (see PickCoordinates).
bufferNormalizedCoordY – Normalized Y pick coordinate within buffer size (see PickCoordinates).

Returns:

true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool flush()

Submits scene control commands (API calls on RendererSceneControl) since previous flush to be executed in the next renderer update loop. This mechanism allows for ‘atomic’ changes that are applied within a single update loop, thus a single rendered frame. For example one scene can be hidden, another scene shown and data linked, all within single frame. Not all state changes can be executed within a single update loop, see setSceneState for details.

Returns:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

bool dispatchEvents(IRendererSceneControlEventHandler &eventHandler)

RendererSceneControl methods push commands to an internal queue which is submitted when calling flush. The commands are then executed during a render loop (ramses::RamsesRenderer::doOneLoop or in a render thread if used ramses::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. Scene control events should 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:: eventHandler – User class that implements the callbacks that can be triggered if a corresponding event happened. Check ramses::IRendererSceneControlEventHandler documentation for more details.
Returns:: true for success, false otherwise (check log or ramses::RamsesFramework::getLastError for details).

RendererSceneControl(const RendererSceneControl&) = delete: Deleted copy constructor.

RendererSceneControl(RendererSceneControl&&) = delete: Deleted move constructor.

RendererSceneControl &operator=(const RendererSceneControl&) = delete

Deleted copy assignment.

Returns:: unused

RendererSceneControl &operator=(RendererSceneControl&&) = delete

Deleted move assignment.

Returns:: unused

internal::RendererSceneControlImpl &impl(): Get the internal data for implementation specifics of RendererSceneControl.

const internal::RendererSceneControlImpl &impl() const: Get the internal data for implementation specifics of RendererSceneControl.

struct rendererResourceId_t

#include <Types.h>

Resource identifier used to refer to a resource on the renderer.

Param low:: [in] The low 64 bits of the value
Param high:: [in] The high 64 bits of the value

Public Functions

constexpr rendererResourceId_t() = default: Default constructor constructs invalid value.

inline constexpr rendererResourceId_t(uint64_t low, uint64_t high)

The constructor.

Parameters:

low – [in] The low bits of the ID
high – [in] The high bits of the ID

inline constexpr bool operator==(const rendererResourceId_t &rhs) const

The comparison operator.

Parameters:: rhs – [in] The instance to compare to
Returns:: True if same, false otherwise

inline constexpr bool operator!=(const rendererResourceId_t &rhs) const

The comparison operator.

Parameters:: rhs – [in] The instance to compare to
Returns:: True if same, false otherwise

Public Members

uint64_t lowPart = {0}: The lower bits of the resource id.

uint64_t highPart = {0}: The higher bits of the resource id.

template<> struct is_flag<EKeyModifier> : public std::true_type: #include <Types.h>