Entry point of RAMSES client API. More...

#include <RamsesClient.h>

Inheritance diagram for ramses::RamsesClient:

Collaboration diagram for ramses::RamsesClient:

Public Member Functions
Scene *	createScene (sceneId_t sceneId, const SceneConfig &sceneConfig=SceneConfig(), const char *name=nullptr)
	Create a new empty Scene. More...

Scene *	loadSceneFromFile (const char *fileName, bool localOnly=false)
	Loads scene contents and resources from a file. More...

Scene *	loadSceneFromMemory (std::unique_ptr< unsigned char[], void()(const unsigned char )> data, size_t size, bool localOnly=false)
	Loads scene contents and resources from a memory buffer. More...

Scene *	loadSceneFromFileDescriptor (int fd, size_t offset, size_t length, bool localOnly=false)
	Loads scene contents and resources from an open file descriptor. More...

Scene *	loadSceneFromFileDescriptor (sceneId_t sceneId, int fd, size_t offset, size_t length, bool localOnly=false)
	Loads scene contents and resources from an open file descriptor. This overload overrides the sceneId stored in the file. More...

status_t	loadSceneFromFileAsync (const char *fileName, bool localOnly=false)
	Loads scene contents and resources asynchronously from a file. The file format has to match current Ramses SDK version in major and minor version number. This method is not backwards compatible and will fail if trying to load scene files saved using older Ramses SDK version. More...

status_t	destroy (Scene &scene)
	Destroys the given Scene. The reference of Scene is invalid after this call. More...

const Scene *	findSceneByName (const char *name) const
	Find a scene from the client by name. More...

Scene *	findSceneByName (const char *name)
	Find a scene from the client by name. More...

const Scene *	getScene (sceneId_t sceneId) const
	Get a scene from the client by scene id. More...

Scene *	getScene (sceneId_t sceneId)
	Get a scene from the client by scene id. More...

status_t	dispatchEvents (IClientEventHandler &clientEventHandler)
	Some methods on the client provide asynchronous results. These can be synchronously received by calling this functions at regular intervals. More...

	RamsesClient (RamsesClientImpl &)
	Constructor of RamsesClient. More...

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

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

RamsesClient &	operator= (const RamsesClient &other)=delete
	Deleted copy assignment. 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 RamsesClientImpl &	impl

Public Attributes inherited from ramses::RamsesObject
class RamsesObjectImpl &	impl

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

Friends
class	ClientFactory
	ClientFactory is the factory for RamsesClient. More...

Additional Inherited Members
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...

Detailed Description

Entry point of RAMSES client API.

The RAMSES client class handles application state and and is a factory for scenes and client resources.

Examples: ramses-example-basic-animation-realtime/src/main.cpp, ramses-example-basic-animation/src/main.cpp, ramses-example-basic-blending/src/main.cpp, ramses-example-basic-compositing/src/main.cpp, ramses-example-basic-effect-from-glsl/src/main.cpp, ramses-example-basic-file-loading/src/main.cpp, ramses-example-basic-geometry/src/main.cpp, ramses-example-basic-rendergroups/src/main.cpp, ramses-example-basic-renderpasses/src/main.cpp, ramses-example-basic-rendertarget/src/main.cpp, ramses-example-basic-scenegraph/src/main.cpp, ramses-example-basic-texturing/src/main.cpp, ramses-example-data-buffers-texture/src/main.cpp, ramses-example-data-buffers-vertices/src/main.cpp, ramses-example-dcsm-provider/src/main.cpp, ramses-example-geometry-instancing/src/main.cpp, ramses-example-interleaved-vertex-buffers/src/main.cpp, ramses-example-local-client-dcsm/src/main.cpp, ramses-example-local-client/src/main.cpp, ramses-example-local-datalink/src/main.cpp, ramses-example-local-displays/src/main.cpp, ramses-example-local-dma-offscreenbuffer/src/main.cpp, ramses-example-local-geometry-shaders/src/main.cpp, ramses-example-local-offscreenbuffer/src/main.cpp, ramses-example-local-pick-handling/src/main.cpp, ramses-example-local-scene-referencing/src/main.cpp, ramses-example-local-viewport-link/src/main.cpp, ramses-example-minimal/src/main.cpp, ramses-example-renderonce/src/main.cpp, ramses-example-text-basic/src/main.cpp, and ramses-example-text-languages/src/main.cpp.

Constructor & Destructor Documentation

◆ RamsesClient() [1/3]

ramses::RamsesClient::RamsesClient ( RamsesClientImpl & )

explicit

Constructor of RamsesClient.

◆ RamsesClient() [2/3]

ramses::RamsesClient::RamsesClient ( )

delete

Deleted default constructor.

◆ RamsesClient() [3/3]

ramses::RamsesClient::RamsesClient ( const RamsesClient & other )

delete

Deleted copy constructor.

Parameters

other unused

Member Function Documentation

◆ createScene()

Scene* ramses::RamsesClient::createScene	(	sceneId_t	sceneId,
		const SceneConfig &	sceneConfig = `SceneConfig()`,
		const char *	name = `nullptr`
	)

Create a new empty Scene.

Parameters

[in]	sceneId	The scene id for global identification of the Scene (is used for scene mapping on renderer side).
[in]	sceneConfig	The optional scene configuration that can be used to change parameters of scene to be created.
[in]	name	The optional name of the created Scene.

Returns: A pointer to the created Scene, null on failure

Examples: ramses-example-local-datalink/src/main.cpp, ramses-example-local-displays/src/main.cpp, ramses-example-local-dma-offscreenbuffer/src/main.cpp, ramses-example-local-offscreenbuffer/src/main.cpp, ramses-example-local-scene-referencing/src/main.cpp, ramses-example-local-viewport-link/src/main.cpp, ramses-example-text-basic/src/main.cpp, and ramses-example-text-languages/src/main.cpp.

◆ destroy()

status_t ramses::RamsesClient::destroy ( Scene & scene )

Destroys the given Scene. The reference of Scene is invalid after this call.

Parameters

[in] scene The Scene to destroy

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

◆ dispatchEvents()

status_t ramses::RamsesClient::dispatchEvents ( IClientEventHandler & clientEventHandler )

Some methods on the client provide asynchronous results. These can be synchronously received by calling this functions at regular intervals.

The point in time and the ordering of asynchronous events from different calls is unspecified. The ordering of events from one asynchronous load call is as specified in the documentation for that call.

Parameters

[in] clientEventHandler User class that implements the callbacks that can be triggered if a corresponding event happened. Check IClientEventHandler documentation for more details.

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

◆ findSceneByName() [1/2]

Scene* ramses::RamsesClient::findSceneByName ( const char * name )

Find a scene from the client by name.

Parameters

[in] name The name of the scene to find.

Returns: Pointer to the scene if found, nullptr otherwise.

◆ findSceneByName() [2/2]

const Scene* ramses::RamsesClient::findSceneByName ( const char * name ) const

Find a scene from the client by name.

Parameters

[in] name The name of the scene to find.

Returns: Pointer to the scene if found, nullptr otherwise.

◆ getScene() [1/2]

Scene* ramses::RamsesClient::getScene ( sceneId_t sceneId )

Get a scene from the client by scene id.

Parameters

[in] sceneId The id of the scene to get.

Returns: Pointer to the scene if found, nullptr otherwise.

◆ getScene() [2/2]

const Scene* ramses::RamsesClient::getScene ( sceneId_t sceneId ) const

Get a scene from the client by scene id.

Parameters

[in] sceneId The id of the scene to get.

Returns: Pointer to the scene if found, nullptr otherwise.

◆ loadSceneFromFile()

Scene* ramses::RamsesClient::loadSceneFromFile	(	const char *	fileName,
		bool	localOnly = `false`
	)

Loads scene contents and resources from a file.

The file format has to match current Ramses SDK version in major and minor version number. This method is not back compatible and will fail if trying to load scene files saved using older Ramses SDK version.

Parameters

[in]	fileName	File name to load the scene from.
[in]	localOnly	Marks the scene to be loaded as valid for local only optimization. This has the same effect as calling SceneConfig::setPublicationMode(EScenePublicationMode_LocalOnly) before saving.

Returns: New instance of scene with contents loaded from a file.

◆ loadSceneFromFileAsync()

status_t ramses::RamsesClient::loadSceneFromFileAsync	(	const char *	fileName,
		bool	localOnly = `false`
	)

Loads scene contents and resources asynchronously from a file. The file format has to match current Ramses SDK version in major and minor version number. This method is not backwards compatible and will fail if trying to load scene files saved using older Ramses SDK version.

This method does not directly return a scene but provides its results after loading is finished when calling dispatchEvents(). There will be one event for each loaded resource file followed by an event for the scene file.

Parameters

[in]	fileName	File name to load the scene from.
[in]	localOnly	Marks the scene to be loaded as valid for local only optimization. This has the same effect as calling SceneConfig::setPublicationMode(EScenePublicationMode_LocalOnly) before saving.

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

◆ loadSceneFromFileDescriptor() [1/2]

Scene* ramses::RamsesClient::loadSceneFromFileDescriptor	(	int	fd,
		size_t	offset,
		size_t	length,
		bool	localOnly = `false`
	)

Loads scene contents and resources from an open file descriptor.

The file format has to match current Ramses SDK version in major and minor version number. This method is not back compatible and will fail if trying to load scene files saved using older Ramses SDK version.

The ramses scene must be in the already opened filedescriptor at absolute position offset within the file. The filedescriptor must be opened for read access and may not be modified anymore after this call. The filedescriptor must support seeking. Ramses takes ownership of the filedescriptor and will close it when not needed anymore.

The behavior is undefined if the filedescriptor does not contain a complete serialized ramses scene at offset.

Parameters

[in]	fd	Open and readable filedescriptor.
[in]	offset	Absolute starting position of ramses scenen within fd.
[in]	length	Size of the scene data within fd.
[in]	localOnly	Marks the scene to be loaded as valid for local only optimization. This has the same effect as calling SceneConfig::setPublicationMode(EScenePublicationMode_LocalOnly) before saving.

Returns: New instance of scene with contents loaded from a file.

◆ loadSceneFromFileDescriptor() [2/2]

Scene* ramses::RamsesClient::loadSceneFromFileDescriptor	(	sceneId_t	sceneId,
		int	fd,
		size_t	offset,
		size_t	length,
		bool	localOnly = `false`
	)

Loads scene contents and resources from an open file descriptor. This overload overrides the sceneId stored in the file.

The file format has to match current Ramses SDK version in major and minor version number. This method is not back compatible and will fail if trying to load scene files saved using older Ramses SDK version.

The ramses scene must be in the already opened filedescriptor at absolute position offset within the file. The filedescriptor must be opened for read access and may not be modified anymore after this call. The filedescriptor must support seeking. Ramses takes ownership of the filedescriptor and will close it when not needed anymore.

The behavior is undefined if the filedescriptor does not contain a complete serialized ramses scene at offset.

Parameters

[in]	sceneId	The sceneId to use for the returned scene.
[in]	fd	Open and readable filedescriptor.
[in]	offset	Absolute starting position of ramses scenen within fd.
[in]	length	Size of the scene data within fd.
[in]	localOnly	Marks the scene to be loaded as valid for local only optimization. This has the same effect as calling SceneConfig::setPublicationMode(EScenePublicationMode_LocalOnly) before saving.

Returns: New instance of scene with contents loaded from a file.

◆ loadSceneFromMemory()

Scene* ramses::RamsesClient::loadSceneFromMemory	(	std::unique_ptr< unsigned char[], void()(const unsigned char )>	data,
		size_t	size,
		bool	localOnly = `false`
	)

Loads scene contents and resources from a memory buffer.

The file format has to match current Ramses SDK version in major and minor version number. This method is not back compatible and will fail if trying to load scene files saved using older Ramses SDK version.

Ramses takes ownership of the memory buffer passed in via data and will delete it via the provided deleter from unique_ptr when not used anymore. The caller may not modify the referenced memory anymore after this call. The behavior is undefined if data does not contain a complete serialized ramses scene or if size does not match the size of the scene data in bytes.

The deleter on data allows safe memory ownership passing on windows when ramses is used as dll. For more details and a convenience wrapper see ramses::RamsesUtils::LoadSceneFromMemory.

Parameters

[in]	data	Memory buffer to load the scene from.
[in]	size	The size in bytes of the data memory.
[in]	localOnly	Marks the scene to be loaded as valid for local only optimization. This has the same effect as calling SceneConfig::setPublicationMode(EScenePublicationMode_LocalOnly) before saving.

Returns: New instance of scene with contents loaded from a file.

◆ operator=()

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

delete

Deleted copy assignment.

Parameters

other unused

Returns: unused

Friends And Related Function Documentation

◆ ClientFactory

friend class ClientFactory

friend

ClientFactory is the factory for RamsesClient.

Member Data Documentation

◆ impl

class RamsesClientImpl& ramses::RamsesClient::impl

Stores internal data for implementation specifics of the API.

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

/home/runner/work/ramses/ramses/client/ramses-client/ramses-client-api/include/ramses-client-api/RamsesClient.h

Public Member Functions

Public Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ RamsesClient() [1/3]

◆ RamsesClient() [2/3]

◆ RamsesClient() [3/3]

Member Function Documentation

◆ createScene()

◆ destroy()

◆ dispatchEvents()

◆ findSceneByName() [1/2]

◆ findSceneByName() [2/2]

◆ getScene() [1/2]

◆ getScene() [2/2]

◆ loadSceneFromFile()

◆ loadSceneFromFileAsync()

◆ loadSceneFromFileDescriptor() [1/2]

◆ loadSceneFromFileDescriptor() [2/2]

◆ loadSceneFromMemory()

◆ operator=()

Friends And Related Function Documentation

◆ ClientFactory

Member Data Documentation

◆ impl