Class used to offer ramses content and meta infos to a consumer and synchronize actions between client and renderer side applications. More...

#include <DcsmProvider.h>

Inheritance diagram for ramses::DcsmProvider:

[legend]

Collaboration diagram for ramses::DcsmProvider:

[legend]

Public Member Functions
status_t	offerContent (ContentID contentID, Category category, sceneId_t scene, EDcsmOfferingMode mode)
	Assigns a ramses scene ID to a contentID and category and offers that content to listening consumers. Should only be called if content could and should currently be shown. The ramses scene belonging to the scene ID does not have to exist yet. More...

status_t	offerContentWithMetadata (ContentID contentID, Category category, sceneId_t scene, EDcsmOfferingMode mode, const DcsmMetadataCreator &metadata)
	Same behavior as offerContent() but additionally send provided metadata to consumers that assigned content to themselves. More...

status_t	offerContent (ContentID contentID, Category category, waylandIviSurfaceId_t surfaceId, EDcsmOfferingMode mode)
	Assigns a Wayland IVI Surface ID to a contentID and category and offers that content to listening consumers. Should only be called if content could and should currently be shown. The Wayland IVI Surface belonging to the surface ID must not exist yet. More...

status_t	offerContentWithMetadata (ContentID contentID, Category category, waylandIviSurfaceId_t surfaceId, EDcsmOfferingMode mode, const DcsmMetadataCreator &metadata)
	Same behavior as offerContent() but additionally send provided metadata to consumers that assigned content to themselves. More...

status_t	updateContentMetadata (ContentID contentID, const DcsmMetadataCreator &metadata)
	Send metadata updates to consumers content is assigned to. The content is earliest sent to consumer on change change offered to assigned. More...

status_t	requestStopOfferContent (ContentID contentID)
	Request to stop offering a content. A successful request will trigger a call to stopOfferAccepted in the handler. More...

status_t	markContentReady (ContentID contentID)
	Marks the content ready for displaying. This function might be called any time after offerContent(). A connected DcsmConsumer might request a content to be marked as ready, resulting in a call to contentReadyRequest() in the event handler (see dispatchEvents). markContentReady shall be called after that. More...

status_t	enableFocusRequest (ContentID contentID, int32_t focusRequest)
	Requests an assigned DcsmConsumer to switch to/focus this content within a category. This function does not have to be called to enable a consumer to use this content, it is only needed when the provider side wants to influence the consumer application logic concerning which content to use. When the logical reason for the focus is no longer valid, the request should be disabled again. More...

status_t	disableFocusRequest (ContentID contentID, int32_t focusRequest)
	No longer request an assigned DcsmConsumer to focus this content for given focusrequest within a category. Should be called, when the logical reason for the focus is no longer given. More...

status_t	dispatchEvents (IDcsmProviderEventHandler &handler)
	Calls a callback function for every internal event except the content status event, which will be discarded. More...

status_t	dispatchEvents (IDcsmProviderEventHandlerExtended &handler)
	Calls a callback function for every internal event including the content status event. More...

	DcsmProvider (DcsmProviderImpl &)
	Constructor of DcsmProvider. More...

	~DcsmProvider ()
	Destructor of DcsmProvider. More...

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

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

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

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

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

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

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

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

Public Attributes
class DcsmProviderImpl &	impl

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

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

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

Detailed Description

Class used to offer ramses content and meta infos to a consumer and synchronize actions between client and renderer side applications.

Examples: ramses-example-dcsm-provider/src/main.cpp, and ramses-example-local-client-dcsm/src/main.cpp.

Constructor & Destructor Documentation

◆ DcsmProvider() [1/3]

ramses::DcsmProvider::DcsmProvider ( DcsmProviderImpl & )

explicit

Constructor of DcsmProvider.

◆ ~DcsmProvider()

ramses::DcsmProvider::~DcsmProvider ( )

Destructor of DcsmProvider.

◆ DcsmProvider() [2/3]

ramses::DcsmProvider::DcsmProvider ( )

delete

Deleted default constructor.

◆ DcsmProvider() [3/3]

ramses::DcsmProvider::DcsmProvider ( const DcsmProvider & other )

delete

Deleted copy constructor.

Parameters

other unused

Member Function Documentation

◆ disableFocusRequest()

status_t ramses::DcsmProvider::disableFocusRequest	(	ContentID	contentID,
		int32_t	focusRequest
	)

No longer request an assigned DcsmConsumer to focus this content for given focusrequest within a category. Should be called, when the logical reason for the focus is no longer given.

Parameters

contentID	The ID of the content for which to disable the focus request for
focusRequest	The focusRequest to disable

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

◆ dispatchEvents() [1/2]

status_t ramses::DcsmProvider::dispatchEvents ( IDcsmProviderEventHandler & handler )

Calls a callback function for every internal event except the content status event, which will be discarded.

Communication from DcsmConsumer will be handled by a DcsmProvider. Some of this communication results in an event. Calls handler functions synchronously in the caller context for DCSM events which were received asynchronously. This function must be called regularly to avoid buffer overflow of the internal queue.

Parameters

handler A class which handles feedback from DcsmProvider

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

◆ dispatchEvents() [2/2]

status_t ramses::DcsmProvider::dispatchEvents ( IDcsmProviderEventHandlerExtended & handler )

Calls a callback function for every internal event including the content status event.

Communication from DcsmConsumer will be handled by a DcsmProvider. Some of this communication results in an event. Calls handler functions synchronously in the caller context for DCSM events which were received asynchronously. This function must be called regularly to avoid buffer overflow of the internal queue.

Parameters

handler A class which handles feedback from DcsmProvider

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

◆ enableFocusRequest()

status_t ramses::DcsmProvider::enableFocusRequest	(	ContentID	contentID,
		int32_t	focusRequest
	)

Requests an assigned DcsmConsumer to switch to/focus this content within a category. This function does not have to be called to enable a consumer to use this content, it is only needed when the provider side wants to influence the consumer application logic concerning which content to use. When the logical reason for the focus is no longer valid, the request should be disabled again.

Parameters

contentID	The ID of the content to request focus for
focusRequest	An arbitrary identifier for this focusRequest

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

◆ markContentReady()

status_t ramses::DcsmProvider::markContentReady ( ContentID contentID )

Marks the content ready for displaying. This function might be called any time after offerContent(). A connected DcsmConsumer might request a content to be marked as ready, resulting in a call to contentReadyRequest() in the event handler (see dispatchEvents). markContentReady shall be called after that.

When a previously marked ready content is released by the consumer the ready state is automatically reset. Should this or another consumer request the content ready again, this function has to be called again for this content to indicate renewed readiness.

Parameters

contentID The ID of the content to be marked ready

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

Precondition: Ramses scene content: Scene associated with content is set up and published.

◆ offerContent() [1/2]

status_t ramses::DcsmProvider::offerContent	(	ContentID	contentID,
		Category	category,
		sceneId_t	scene,
		EDcsmOfferingMode	mode
	)

Assigns a ramses scene ID to a contentID and category and offers that content to listening consumers. Should only be called if content could and should currently be shown. The ramses scene belonging to the scene ID does not have to exist yet.

A content must only be offered in a way that one scene is not associated with two categories which get assigned to different ramses displays on the renderer/consumer side. Otherwise contents might never be able to reach ready state.

A failing offerContent call might trigger a stopOfferAccepted event, which can be safely ignored.

Parameters

contentID	The ID of the content to be offered
category	The category the content is made for
scene	The ramses scene ID containing the content.
mode	Indicates if content should be offered within same process only

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

◆ offerContent() [2/2]

status_t ramses::DcsmProvider::offerContent	(	ContentID	contentID,
		Category	category,
		waylandIviSurfaceId_t	surfaceId,
		EDcsmOfferingMode	mode
	)

Assigns a Wayland IVI Surface ID to a contentID and category and offers that content to listening consumers. Should only be called if content could and should currently be shown. The Wayland IVI Surface belonging to the surface ID must not exist yet.

A failing offerContent call might trigger a stopOfferAccepted event, which can be safely ignored.

Parameters

contentID	The ID of the content to be offered
category	The category the content is made for
surfaceId	The Wayland IVI Surface id containing the content.
mode	Indicates if content should be offered within same process only

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

◆ offerContentWithMetadata() [1/2]

status_t ramses::DcsmProvider::offerContentWithMetadata	(	ContentID	contentID,
		Category	category,
		sceneId_t	scene,
		EDcsmOfferingMode	mode,
		const DcsmMetadataCreator &	metadata
	)

Same behavior as offerContent() but additionally send provided metadata to consumers that assigned content to themselves.

This method should be used to attach metadata immediately on offer to a content but is no prerequisite for later calls to updateContentMetadata().

A failing offerContentWithMetadata call might trigger a stopOfferAccepted event, which can be safely ignored.

Parameters

contentID	The ID of the content to be offered
category	The category the content is made for
scene	The ramses scene ID containing the content.
mode	Indicates if content should be offered within same process only
metadata	metadata creator filled with metadata

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

◆ offerContentWithMetadata() [2/2]

status_t ramses::DcsmProvider::offerContentWithMetadata	(	ContentID	contentID,
		Category	category,
		waylandIviSurfaceId_t	surfaceId,
		EDcsmOfferingMode	mode,
		const DcsmMetadataCreator &	metadata
	)

Same behavior as offerContent() but additionally send provided metadata to consumers that assigned content to themselves.

This method should be used to attach metadata immediately on offer to a content but is no prerequisite for later calls to updateContentMetadata().

A failing offerContentWithMetadata call might trigger a stopOfferAccepted event, which can be safely ignored.

Parameters

contentID	The ID of the content to be offered
category	The category the content is made for
surfaceId	The Wayland IVI Surface id containing the content.
mode	Indicates if content should be offered within same process only
metadata	metadata creator filled with metadata

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

◆ operator=()

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

delete

Deleted copy assignment.

Parameters

other unused

Returns: unused

◆ requestStopOfferContent()

status_t ramses::DcsmProvider::requestStopOfferContent ( ContentID contentID )

Request to stop offering a content. A successful request will trigger a call to stopOfferAccepted in the handler.

Parameters

contentID The ID of the content to be stopped offering.

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

◆ updateContentMetadata()

status_t ramses::DcsmProvider::updateContentMetadata	(	ContentID	contentID,
		const DcsmMetadataCreator &	metadata
	)

Send metadata updates to consumers content is assigned to. The content is earliest sent to consumer on change change offered to assigned.

contentID must belong to a content currently offered by this provider. A consumer initially gets the last combined state of all metadata updates (later updated values overwrite earlier values) when they become assigned. The initial state is given by offerContentWithMetadata() or empty if offerContent() is used. After the initial send updates are directly provided to the assigned consumer.

Parameters

contentID	The ID of the content for which metadata should be updated
metadata	metadata creator filled with metadata

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

Member Data Documentation

◆ impl

class DcsmProviderImpl& ramses::DcsmProvider::impl

Stores internal data for implementation specifics of DcsmProvider

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

/home/runner/work/ramses/ramses/framework/ramses-framework-api/include/ramses-framework-api/DcsmProvider.h

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DcsmProvider() [1/3]

◆ ~DcsmProvider()

◆ DcsmProvider() [2/3]

◆ DcsmProvider() [3/3]

Member Function Documentation

◆ disableFocusRequest()

◆ dispatchEvents() [1/2]

◆ dispatchEvents() [2/2]

◆ enableFocusRequest()

◆ markContentReady()

◆ offerContent() [1/2]

◆ offerContent() [2/2]

◆ offerContentWithMetadata() [1/2]

◆ offerContentWithMetadata() [2/2]

◆ operator=()

◆ requestStopOfferContent()

◆ updateContentMetadata()

Member Data Documentation

◆ impl