Temporary functions for convenience. All of these can be implemented on top of the RAMSES Client API, but are offered here as convenience. More...

#include <ramses-utils.h>

Static Public Member Functions
template<typename T >
static const T *	TryConvert (const RamsesObject &obj)
	Converts object to a compatible object type. Object can be converted to any of its base classes. Eg. MeshNode can be converted to Node, SceneObject, ClientObject or RamsesObject. More...

template<typename T >
static T *	TryConvert (RamsesObject &obj)
	Converts object to a compatible object type. Object can be converted to any of its base classes. Eg. MeshNode can be converted to Node, SceneObject, ClientObject or RamsesObject. More...

static Texture2D *	CreateTextureResourceFromPng (const char pngFilePath, Scene &scene, const TextureSwizzle &swizzle={}, const char name=nullptr)
	Creates a Texture from the given png file. More...

static Texture2D *	CreateTextureResourceFromPngBuffer (const std::vector< unsigned char > &pngData, Scene &scene, const TextureSwizzle &swizzle={}, const char *name=nullptr)
	Creates a Texture from the given png memory buffer. More...

static MipLevelData *	GenerateMipMapsTexture2D (uint32_t width, uint32_t height, uint8_t bytesPerPixel, uint8_t *data, uint32_t &mipMapCount)
	Generate mip maps from original texture 2D data. You obtain ownership of all the data returned in the mip map data object. Note, that the original texture data gets copied and represents the first mip map level. More...

static bool	SaveImageBufferToPng (const std::string &filePath, const std::vector< uint8_t > &imageData, uint32_t width, uint32_t height)
	Creates a png from image data, e.g. data generated by RamsesClientService::readPixels. The image data is expected to be in the format rgba8. Width x Height x 4 (rgba8) have to exactly match the size of the image buffer, otherwise no png will be created. Also width * height cannot exceed the size 268435455 or png creation will fail. More...

static bool	SaveImageBufferToPng (const std::string &filePath, std::vector< uint8_t > &imageData, uint32_t width, uint32_t height, bool flipImageBufferVertically)
	Creates a png from image data, e.g. data generated by RamsesClientService::readPixels. The image data is expected to be in the format rgba8. Width x Height x 4 (rgba8) have to exactly match the size of the image buffer, otherwise no png will be created. Also width * height cannot exceed the size 268435455 or png creation will fail. The image data can be flipped vertically, as the data coming from a function like RamsesClientService::readPixels gets the data from OpenGL which has the origin in the lower left corner, whereas png has the origin in the upper left corner. So to capture what you see on screen you have to set the flag flipImageBufferVertically to true. More...

static CubeMipLevelData *	GenerateMipMapsTextureCube (uint32_t faceWidth, uint32_t faceHeight, uint8_t bytesPerPixel, uint8_t *data, uint32_t &mipMapCount)
	Generate mip maps from original texture cube data. You obtain ownership of all the data returned in the mip map data object. Note, that the original texture data gets copied and represents the first mip map level. More...

static void	DeleteGeneratedMipMaps (MipLevelData *&data, uint32_t mipMapCount)
	Deletes mip map data created with RamsesUtils::GenerateMipMapsTexture2D. More...

static void	DeleteGeneratedMipMaps (CubeMipLevelData *&data, uint32_t mipMapCount)
	Deletes mip map data created with RamsesUtils::GenerateMipMapsTextureCube. More...

static nodeId_t	GetNodeId (const Node &node)
	Returns the identifier of a node, which is printed in the renderer logs. The identifier is guaranteed to be unique within a Scene until the Node is destroyed. If a Node is destroyed, a newly created Node can get the identifier of the destroyed Node. More...

static bool	SetPerspectiveCameraFrustumToDataObjects (float fov, float aspectRatio, float nearPlane, float farPlane, DataVector4f &frustumPlanesData, DataVector2f &nearFarPlanesData)
	Convenience method to set perspective camera frustum using FOV and aspect ratio (like in ramses::PerspectiveCamera::setFrustum) to two ramses::DataObject instances which are or will be bound to a ramses::PerspectiveCamera using ramses::Camera::bindFrustumPlanes. More...

static Scene *	LoadSceneFromMemory (RamsesClient &client, std::unique_ptr< unsigned char[]> data, size_t size, bool localOnly)
	Convenience wrapper for RamsesClient::loadSceneFromMemory with automatic deleter. More...

Detailed Description

Temporary functions for convenience. All of these can be implemented on top of the RAMSES Client API, but are offered here as convenience.

Member Function Documentation

◆ CreateTextureResourceFromPng()

static Texture2D* ramses::RamsesUtils::CreateTextureResourceFromPng	(	const char *	pngFilePath,
		Scene &	scene,
		const TextureSwizzle &	swizzle = `{}`,
		const char *	name = `nullptr`
	)

static

Creates a Texture from the given png file.

Parameters

[in]	pngFilePath	Path to the png file to load
[in]	scene	Scene the texture object is to be created in
[in]	swizzle	Swizzling of texture color channels
[in]	name	Name for the created texture

Returns: Created texture object or nullptr on error

Examples: ramses-example-basic-compositing/src/main.cpp, ramses-example-basic-file-loading/src/main.cpp, ramses-example-basic-texturing/src/main.cpp, ramses-example-dcsm-provider/src/main.cpp, ramses-example-local-datalink/src/main.cpp, ramses-example-local-dma-offscreenbuffer/src/main.cpp, and ramses-example-local-offscreenbuffer/src/main.cpp.

◆ CreateTextureResourceFromPngBuffer()

static Texture2D* ramses::RamsesUtils::CreateTextureResourceFromPngBuffer	(	const std::vector< unsigned char > &	pngData,
		Scene &	scene,
		const TextureSwizzle &	swizzle = `{}`,
		const char *	name = `nullptr`
	)

static

Creates a Texture from the given png memory buffer.

Parameters

[in]	pngData	Buffer with PNG data to load
[in]	scene	Scene the texture object is to be created in
[in]	swizzle	Swizzling of texture color channels
[in]	name	Name for the created texture

Returns: Created texture object or nullptr on error

◆ DeleteGeneratedMipMaps() [1/2]

static void ramses::RamsesUtils::DeleteGeneratedMipMaps	(	CubeMipLevelData *&	data,
		uint32_t	mipMapCount
	)

static

Deletes mip map data created with RamsesUtils::GenerateMipMapsTextureCube.

Parameters

[in,out]	data	Generated mip map data.
[in]	mipMapCount	Number of mip map levels in the generated data.

◆ DeleteGeneratedMipMaps() [2/2]

static void ramses::RamsesUtils::DeleteGeneratedMipMaps	(	MipLevelData *&	data,
		uint32_t	mipMapCount
	)

static

Deletes mip map data created with RamsesUtils::GenerateMipMapsTexture2D.

Parameters

[in,out]	data	Generated mip map data.
[in]	mipMapCount	Number of mip map levels in the generated data.

◆ GenerateMipMapsTexture2D()

static MipLevelData* ramses::RamsesUtils::GenerateMipMapsTexture2D	(	uint32_t	width,
		uint32_t	height,
		uint8_t	bytesPerPixel,
		uint8_t *	data,
		uint32_t &	mipMapCount
	)

static

Generate mip maps from original texture 2D data. You obtain ownership of all the data returned in the mip map data object. Note, that the original texture data gets copied and represents the first mip map level.

See also: DeleteGeneratedMipMaps for deleting generated mip maps.

Parameters

[in]	width	Width of the original texture.
[in]	height	Height of the original texture.
[in]	bytesPerPixel	Number of bytes stored per pixel in the original texture data.
[in]	data	Original texture data.
[out]	mipMapCount	Number of generated mip map levels.

Returns: generated mip map data. In case width or height are not values to the power of two, only the original mip map level is part of the result. You are responsible to destroy the generated data, e.g. by using RamsesUtils::DeleteGeneratedMipMaps

◆ GenerateMipMapsTextureCube()

static CubeMipLevelData* ramses::RamsesUtils::GenerateMipMapsTextureCube	(	uint32_t	faceWidth,
		uint32_t	faceHeight,
		uint8_t	bytesPerPixel,
		uint8_t *	data,
		uint32_t &	mipMapCount
	)

static

Generate mip maps from original texture cube data. You obtain ownership of all the data returned in the mip map data object. Note, that the original texture data gets copied and represents the first mip map level.

See also: DeleteGeneratedMipMaps for deleting generated mip maps.

Parameters

[in]	faceWidth	Width of the original texture.
[in]	faceHeight	Height of the original texture.
[in]	bytesPerPixel	Number of bytes stored per pixel in the original texture data.
[in]	data	Original texture data. Face data is expected in order [PX, NX, PY, NY, PZ, NZ]
[out]	mipMapCount	Number of generated mip map levels.

Returns: generated mip map data. In case width or height are not values to the power of two, only the original mip map level is part of the result. You are responsible to destroy the generated data, e.g. using RamsesUtils::DeleteGeneratedMipMaps

◆ GetNodeId()

static nodeId_t ramses::RamsesUtils::GetNodeId ( const Node & node )

static

Returns the identifier of a node, which is printed in the renderer logs. The identifier is guaranteed to be unique within a Scene until the Node is destroyed. If a Node is destroyed, a newly created Node can get the identifier of the destroyed Node.

Parameters

[in] node The node

Returns: the identifier of the given node.

◆ LoadSceneFromMemory()

Scene * ramses::RamsesUtils::LoadSceneFromMemory	(	RamsesClient &	client,
		std::unique_ptr< unsigned char[]>	data,
		size_t	size,
		bool	localOnly
	)

inlinestatic

Convenience wrapper for RamsesClient::loadSceneFromMemory with automatic deleter.

For details refer to ramses::RamsesClient::loadSceneFromMemory. This helper function automatically adds a deleter to the provided unique_ptr that is compiled into caller side and uses the caller heap. This methods can be used on all platforms as a convenience helper for memory that was allocated with new[].

On Windows this allows safe passing of ownership from caller into ramses when ramses is used as dll. This method should not be used when memory was not allocated with new[]. A custom deleter should also be provided when used on windows and the memory originates from yet another dll than the direct caller.

Parameters

[in]	client	The ramses client to use for loading the scene
[in]	data	Memory buffer with scene data.
[in]	size	Size in bytes of the scene data within data buffer
[in]	localOnly	Mark for local only optimization

Returns: The loaded ramses Scene or nullptr on error

◆ SaveImageBufferToPng() [1/2]

static bool ramses::RamsesUtils::SaveImageBufferToPng	(	const std::string &	filePath,
		const std::vector< uint8_t > &	imageData,
		uint32_t	width,
		uint32_t	height
	)

static

Creates a png from image data, e.g. data generated by RamsesClientService::readPixels. The image data is expected to be in the format rgba8. Width x Height x 4 (rgba8) have to exactly match the size of the image buffer, otherwise no png will be created. Also width * height cannot exceed the size 268435455 or png creation will fail.

Parameters

[in]	filePath	Path where the png will be saved
[in]	imageData	Buffer with rgba8 image data that should be saved to png
[in]	width	Width of the image
[in]	height	Height of the image

Returns: Success of png creation

Examples: ramses-example-local-dma-offscreenbuffer/src/main.cpp.

◆ SaveImageBufferToPng() [2/2]

static bool ramses::RamsesUtils::SaveImageBufferToPng	(	const std::string &	filePath,
		std::vector< uint8_t > &	imageData,
		uint32_t	width,
		uint32_t	height,
		bool	flipImageBufferVertically
	)

static

Creates a png from image data, e.g. data generated by RamsesClientService::readPixels. The image data is expected to be in the format rgba8. Width x Height x 4 (rgba8) have to exactly match the size of the image buffer, otherwise no png will be created. Also width * height cannot exceed the size 268435455 or png creation will fail. The image data can be flipped vertically, as the data coming from a function like RamsesClientService::readPixels gets the data from OpenGL which has the origin in the lower left corner, whereas png has the origin in the upper left corner. So to capture what you see on screen you have to set the flag flipImageBufferVertically to true.

Parameters

[in]	filePath	Path where the png will be saved
[in]	imageData	Buffer with rgba8 image data that should be saved to png
[in]	width	Width of the image
[in]	height	Height of the image
[in]	flipImageBufferVertically	Vertical Flipping of image data

Returns: Success of png creation

◆ SetPerspectiveCameraFrustumToDataObjects()

static bool ramses::RamsesUtils::SetPerspectiveCameraFrustumToDataObjects	(	float	fov,
		float	aspectRatio,
		float	nearPlane,
		float	farPlane,
		DataVector4f &	frustumPlanesData,
		DataVector2f &	nearFarPlanesData
	)

static

Convenience method to set perspective camera frustum using FOV and aspect ratio (like in ramses::PerspectiveCamera::setFrustum) to two ramses::DataObject instances which are or will be bound to a ramses::PerspectiveCamera using ramses::Camera::bindFrustumPlanes.

Use case example: just create the two data objects, bind them to one or more cameras and then simply use this method whenever projection parameters need to change. If not all parameters need to be modified, simply query the parameter you want to keep unchanged from the camera (e.g. ramses::PerspectiveCamera::getAspectRatio) and use the same value here.

Parameters

[in]	fov	The vertical field of view to be set, must be > 0. This is the full vertical opening angle in degrees.
[in]	aspectRatio	Ratio between frustum width and height, must be > 0. This value is generally independent from the viewport width and height but typically matches the viewport aspect ratio.
[in]	nearPlane	Near plane of the camera frustum, must be > 0.
[in]	farPlane	Far plane of the camera frustum, must be > nearPlane.
[in]	frustumPlanesData	Data object where resulting first 4 frustum planes will be set to.
[in]	nearFarPlanesData	Data object where resulting near/far frustum planes will be set to.

Returns: True for success, false otherwise.

◆ TryConvert() [1/2]

template<typename T >

static const T* ramses::RamsesUtils::TryConvert ( const RamsesObject & obj )

static

Converts object to a compatible object type. Object can be converted to any of its base classes. Eg. MeshNode can be converted to Node, SceneObject, ClientObject or RamsesObject.

Parameters

[in] obj RamsesObject to convert.

Returns: Pointer to an object of a specific type, NULL if object type is not compatible with desired object class.

◆ TryConvert() [2/2]

template<typename T >

static T* ramses::RamsesUtils::TryConvert ( RamsesObject & obj )

static

Converts object to a compatible object type. Object can be converted to any of its base classes. Eg. MeshNode can be converted to Node, SceneObject, ClientObject or RamsesObject.

Parameters

[in] obj RamsesObject to convert.

Returns: Pointer to an object of a specific type, NULL if object type is not compatible with desired object class.

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

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

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ CreateTextureResourceFromPng()

◆ CreateTextureResourceFromPngBuffer()

◆ DeleteGeneratedMipMaps() [1/2]

◆ DeleteGeneratedMipMaps() [2/2]

◆ GenerateMipMapsTexture2D()

◆ GenerateMipMapsTextureCube()

◆ GetNodeId()

◆ LoadSceneFromMemory()

◆ SaveImageBufferToPng() [1/2]

◆ SaveImageBufferToPng() [2/2]

◆ SetPerspectiveCameraFrustumToDataObjects()

◆ TryConvert() [1/2]

◆ TryConvert() [2/2]