Display Management

The renderer setup consists of a ramses::RamsesRenderer object and a set of displays belonging to it. Every display can be configured through an individual ramses::DisplayConfig.

Scene control and scene states

A renderer offers a set of APIs to allow to control the scene states. Currently there are the RendererSceneControl and the DcsmContentControl. They can be created with the ramses::RamsesRenderer::getSceneControlAPI respectively the ramses::RamsesRenderer::createDcsmContentControl functions.

RendererSceneControl

Graphical content (a ramses::Scene provided from ramses::RamsesClient) is always in a certain state, a state in the context of single ramses::RamsesRenderer instance. Typically the desired state to reach is that the scene is rendered, however the scene has to go through several other states to reach that:

scene is published, i.e. client announced that the scene can be requested from one or more renderers
renderer requests scene and its data, any change to scene data will be transferred to renderer
renderer maps scene to a display, assigns to framebuffer or offscreen buffer and uploads all scene resources
renderer starts to render scene

These states and other parameters can be set/requested using ramses::RendererSceneControl, see its documentation for more details.

Renderer Scene States

DcsmContentControl

DcsmContentControl uses a RendererSceneControl and a DcsmConsumer to allow a user to render ramses scene Dcsm contents with one interface. Refer to the The Display Cluster State Management Protocol documentation for details.

Data Linking

In order to achieve scene interaction, it is possible to attach scene content of one scene to scene content of another scene. There are several types of data links, all of them have a data provider on one side and one or more consumers on the other side, the consumers then use the data of the provider.

Provider and consumer data is tagged with an ID on RAMSES client scene side and then can be linked on RAMSES renderer side. Scenes with provider and consumer data can come from different clients that do not have to know each other (only the tagged data IDs are globally known) and once the scenes are subscribed (mapped in case of texture linking) on renderer they can be linked together.

Data links are dynamic so any change to provider data (including animations) will be reflected to all its consumers.

Data links of any kind can only be established if provider scene and consumer scene are mapped to the same display via ramses::RendererSceneControl::setSceneMapping or - in case of DCSM contents - the contents' categories are mapped to the same display via ramses::DcsmContentControl::addContentCategory.

Transformation Linking

For transformation data linking the provided scene content is the transformation matrix of a scenegraph node (any ramses::Node typed object in scene), which can be consumed by node(s) of consumer scene(s). The consumer node (and all its children in scenegraph topology) will transform using the provider node's transformation.

DataObject Linking

ramses::DataObject can be used to set values of ramses::Appearance uniforms or ramses::Camera parameters which can also be linked across scenes. As long as data type is matched a data value stored in a ramses::DataObject of one scene can be used as uniform input of an ramses::Appearance in another scene.

Texture Linking

Texture resources can be tagged as data providers and can be consumed in another scene by ramses::TextureSampler.

Renderer API calls & Events

Renderer API calls are handled asynchronously. This means that the result or information about success of the requested renderer operation is not available immediately after the API call. The result of the API call will be delivered via renderer events. The ramses::RamsesRenderer and ramses::RendererSceneControl each offer its own event dispatching mechanism, such that an object implementing ramses::IRendererEventHandler/ramses::IRendererSceneControlEventHandler interface can handle and process renderer/scene control events.

Events generated as a result of a ramses::RamsesRenderer or ramses::RendererSceneControl API call can have different statuses reported:

[OK] the Renderer API call was successful
[FAIL] the Renderer API call was unsuccessful, check logs for error message
[INDIRECT] the event was generated as consequence of another event from Ramses client side (e.g. scene unpublish or disconnect) or some other internal event
A special case of status report is 'no status' - scene state change requests (ramses::RendererSceneControl::setSceneState) might not generate any event in case that a condition to reach desired state is not met (e.g. scene not published, display not created, etc.). Note that these will not timeout explicitly, it is responsibility of the application to implement timeout logic.

Renderer API transactions

The ramses::RamsesRenderer and ramses::RendererSceneControl calls are queued and only executed when committed. To commit a batch of calls use ramses::RamsesRenderer::flush() and ramses::RendererSceneControl::flush() respectively. All calls since the last flush will then be executed together (preserving order) in the very next renderer update loop (either ramses::RamsesRenderer::doOneLoop() or in render thread).