 |
RAMSES Documentation
27.0.130
Information for RAMSES users and developers
|
|
RAMSES Documentation
27.0.130
Information for RAMSES users and developers
|
The SceneReference object refers to another ramses scene using its sceneId. More...
#include <SceneReference.h>
Public Member Functions | |
| status_t | requestState (RendererSceneState requestedState) |
| Set a requested state for this scene reference. More... | |
| RendererSceneState | getRequestedState () const |
| Get the currently requested state for this scene reference. More... | |
| sceneId_t | getReferencedSceneId () const |
| Get the sceneId of the referenced scene. More... | |
| status_t | requestNotificationsForSceneVersionTags (bool flag) |
| Request callbacks (ramses::IClientEventHandler::sceneReferenceFlushed) to be triggered whenever a flush with valid version tag (ramses::Scene::flush) has been applied to the referenced scene on the renderer. Enabling notifications after they were previously disabled will also trigger said event once with the last applied valid version tag (i.e. version tag last applied before notifications were enabled). Note that in case there is flush with version applied and notifications enabled within the same renderer update loop the ramses::IClientEventHandler::sceneReferenceFlushed callback might be triggered twice reporting the same version, however the order of reporting is always strictly kept and matching order of flushes applied. More... | |
| status_t | setRenderOrder (int32_t renderOrder) |
| Set scene render order. More... | |
 Public Member Functions inherited from ramses::SceneObject | |
| sceneObjectId_t | getSceneObjectId () const |
| Returns scene object id which is automatically assigned at creation time of object and is unique within scope of one scene. More... | |
| sceneId_t | getSceneId () const |
| Returns sceneid to which this object belongs to. More... | |
| Public Member Functions inherited from ramses::RamsesObject | |
| const char * | getName () const |
| Returns the name of the object. More... | |
| status_t | setName (const char *name) |
| Changes the name of the object. More... | |
| ERamsesObjectType | getType () const |
| Gets type of the object. More... | |
| bool | isOfType (ERamsesObjectType type) const |
| Checks if the object is of given type. More... | |
| Public Member Functions inherited from ramses::StatusObject | |
| status_t | validate () const |
| Generates verbose validation of the object. More... | |
| const char * | getValidationReport (EValidationSeverity minSeverity=EValidationSeverity_Info) const |
| Provides verbose report in human readable form generated by validate. More... | |
| const char * | getStatusMessage (status_t status) const |
| Get the string description for a status provided by a RAMSES API function. More... | |
| StatusObject (const StatusObject &other)=delete | |
| Deleted copy constructor. More... | |
| StatusObject & | operator= (const StatusObject &other)=delete |
| Deleted copy assignment. More... | |
Public Attributes | |
| class SceneReferenceImpl & | impl |
| Public Attributes inherited from ramses::SceneObject | |
| class SceneObjectImpl & | impl |
| Public Attributes inherited from ramses::ClientObject | |
| class ClientObjectImpl & | impl |
| Public Attributes inherited from ramses::RamsesObject | |
| class RamsesObjectImpl & | impl |
| Public Attributes inherited from ramses::StatusObject | |
| class StatusObjectImpl & | impl |
Protected Member Functions | |
| SceneReference (SceneReferenceImpl &pimpl) | |
| Constructor for SceneReference. More... | |
| virtual | ~SceneReference () override |
| Destructor of the SceneReference. More... | |
| Protected Member Functions inherited from ramses::SceneObject | |
| SceneObject (SceneObjectImpl &pimpl) | |
| Constructor for SceneObject. More... | |
| virtual | ~SceneObject () |
| Destructor of the SceneObject. More... | |
| Protected Member Functions inherited from ramses::ClientObject | |
| ClientObject (ClientObjectImpl &pimpl) | |
| Constructor for ClientObject. More... | |
| virtual | ~ClientObject () |
| Destructor of the ClientObject. More... | |
| Protected Member Functions inherited from ramses::RamsesObject | |
| RamsesObject (RamsesObjectImpl &pimpl) | |
| Constructor for RamsesObject. More... | |
| virtual | ~RamsesObject () |
| Destructor of the RamsesObject. More... | |
| Protected Member Functions inherited from ramses::StatusObject | |
| StatusObject (StatusObjectImpl &pimpl) | |
| Constructor for StatusObject. More... | |
| virtual | ~StatusObject () |
| Destructor of the StatusObject. More... | |
Friends | |
| class | SceneImpl |
| Scene is the factory for creating SceneReference instances. More... | |
The SceneReference object refers to another ramses scene using its sceneId.
The SceneReference object references a scene, which might be otherwise unknown to this RamsesClient, but is or expected to be known to a RamsesRenderer subscribed to its master scene (scene in which the reference was created using ramses::Scene::createSceneReference). The SceneReference allows to remotely change limited set of states of the referenced scene on renderer side, results of those requests are reported asynchronously in form of event callbacks, see ramses::IClientEventHandler.
There cannot be multiple instances of SceneReference referring to the same sceneId, however SceneReference can be destroyed using ramses::Scene::destroy and re-created with same sceneId in another scene, i.e. change its 'master' scene. It is recommended to get SceneReference to ramses::RendererSceneState::Available state and wait for confirmation (ramses::IClientEventHandler::sceneReferenceStateChanged) before destroying it, otherwise the scene remains on renderer side with no owner, potentially consuming resources and causing undesired results if shown, also any pending requests, events or actions will either fail or get lost (no master scene to report to). Even though recommended, setting referenced scene to Available before destroying is not strictly required, so it is possible to change its master scene regardless of its actual state on renderer side (even if actively rendered) but this should be done only with extra caution and understanding of the consequences mentioned above.
|
explicitprotected |
Constructor for SceneReference.
| [in] | pimpl | Internal data for implementation specifics of SceneReference (sink - instance becomes owner) |
|
overrideprotectedvirtual |
Destructor of the SceneReference.
| sceneId_t ramses::SceneReference::getReferencedSceneId | ( | ) | const |
Get the sceneId of the referenced scene.
| RendererSceneState ramses::SceneReference::getRequestedState | ( | ) | const |
Get the currently requested state for this scene reference.
| status_t ramses::SceneReference::requestNotificationsForSceneVersionTags | ( | bool | flag | ) |
Request callbacks (ramses::IClientEventHandler::sceneReferenceFlushed) to be triggered whenever a flush with valid version tag (ramses::Scene::flush) has been applied to the referenced scene on the renderer. Enabling notifications after they were previously disabled will also trigger said event once with the last applied valid version tag (i.e. version tag last applied before notifications were enabled). Note that in case there is flush with version applied and notifications enabled within the same renderer update loop the ramses::IClientEventHandler::sceneReferenceFlushed callback might be triggered twice reporting the same version, however the order of reporting is always strictly kept and matching order of flushes applied.
Scene reference has to be in Ready state to be able to receive scene version tag notifications.
| [in] | flag | enable/disable notifications for this scene |
| status_t ramses::SceneReference::requestState | ( | RendererSceneState | requestedState | ) |
Set a requested state for this scene reference.
The ramses::RamsesRenderer will bring the referenced scene to this state, if preconditions are met. When requesting ramses::RendererSceneState::Ready or higher the referenced scene will inherit display mapping from the master scene (ramses::Scene where this reference was created), that implies that the mapping of master scene has to be set on renderer side first (ramses::RendererSceneControl::setSceneMapping).
Whenever a state of the referenced scene changes on renderer side, there will be a callback ramses::IClientEventHandler::sceneReferenceStateChanged. Note that scene state on renderer side can also change due to reasons not controlled from client side (e.g. referenced scene is unpublished).
This is just a request to the renderer to change the scene state, there are requirements that have to be met for every scene state change. The renderer waits with the scene state change till all the conditions are met, therefore the request cannot fail but it might never happen. It is application's responsibility to implement a timeout logic if needed.
It is not allowed to request state Unavailable, as this state can only be the result of external conditions.
| [in] | requestedState |
| status_t ramses::SceneReference::setRenderOrder | ( | int32_t | renderOrder | ) |
Set scene render order.
Scenes are rendered one after each other on renderer side, lower number means scene will be rendered before all scenes with higher number. The render order specified here is relative to its master scene render order, master scene render order is set on renderer side (ramses::RendererSceneControl::setSceneDisplayBufferAssignment).
| [in] | renderOrder | Lower value means that a scene is rendered before a scene with higher value. Default is 0. |
|
friend |
Scene is the factory for creating SceneReference instances.
| class SceneReferenceImpl& ramses::SceneReference::impl |
Stores internal data for implementation specifics of SceneReference.
1.9.1