Ramses Logic API

class AnchorPoint : public ramses::LogicNode

#include <AnchorPoint.h>

Anchor point is a ramses::LogicNode which calculates viewport coordinates (and depth) of a Ramses node’s origin. The projected coordinates are accessible via its output property and can be linked to another logic node. Anchor point requires a ramses::NodeBinding and a ramses::CameraBinding at creation time, see ramses::LogicEngine::createAnchorPoint.

The update logic retrieves a model matrix from the provided Ramses node (via its binding), a projection and view matrix from the provided Ramses camera (via its binding) and projects a point (0, 0, 0) (which represents origin of the given node’s local space) using those matrices: projectedPoint = projectionMatrix * viewMatrix * modelMatrix * (0, 0, 0, 1) Perspective correction will be applied (relevant only if using perspective camera) and then the result is transformed into viewport space of the given camera, i.e. the final values are coordinates within the camera viewport.

This means that if the given Ramses node represents a transformation of a renderable mesh, the anchor point will calculate where in viewport (or on screen if viewport matches screen dimensions) the origin of the mesh would be rendered. This can be useful for example for 2D overlay graphical elements or text following a 3D object.

• Property output:

  • viewportCoords (ramses::EPropertyType::Vec2f)

    • provides [viewportCoordX, viewportCoordY] representing the [X,Y] coordinates of the projected node transformation in viewport space

    • note that it is up to user if and how he decides to round the floating point values to snap to discrete pixels

    • note that the coordinates will not be clamped to the viewport, so viewport coordinates can be negative or larger than viewport width/height if the tracked object is outside of frustum

  • depth (float)

    • non-linear depth in [0,1] range (if within frustum), 0 at near plane, 1 at far plane of the camera frustum (equivalent to the actual value stored in depth buffer for depth testing)

    • note that the depth can be outside of the [0,1] range if the tracked object is outside of frustum

Important note on update order dependency: Unlike other logic nodes the calculation done inside AnchorPoint does not depend on input properties but on states in Ramses scene instead

• namely node transformations and camera settings. Imagine a case where AnchorPoint tracks a Ramses node and this node’s ancestor (in transformation topology) is being animated by a logic node (animation or script), i.e. the animation indirectly affects the result of AnchorPoint. As this dependency is outside of Ramses logic network (it is in Ramses transformation topology) and identifying it in runtime (can change every frame) by querying Ramses is not feasible, the proper ordering of logic network update is NOT guaranteed in such case. It means the AnchorPoint calculation might be executed first before the animation is and thus giving incorrect (old) result. If you end up using such setup, please use a workaround: UPDATE the ramses::LogicEngine TWICE, right after each other in every frame/update iteration.

Performance remark: Unlike other logic nodes AnchorPoint does not use dirtiness mechanism monitoring node’s inputs which then updates the outputs only if anything changed. Anchor point depends on Ramses objects and their states, which cannot be easily monitored and therefore it has to be updated every time ramses::LogicEngine::update is called. For this reason it is highly recommended to keep the number of anchor nodes to a necessary minimum.

Public Functions

const ramses::Node &getRamsesNode() const

Returns given ramses node which is used to calculate coordinates.

Returns:

Ramses node to track

const ramses::Camera &getRamsesCamera() const

Returns given ramses camera which is used to calculate coordinates.

Returns:

Ramses camera associated with node to track

internal::AnchorPointImpl &impl()

Get the internal data for implementation specifics of AnchorPoint.

const internal::AnchorPointImpl &impl() const

Get the internal data for implementation specifics of AnchorPoint.

class AnimationNode : public ramses::LogicNode

#include <AnimationNode.h>

Animation node can be used to animate properties in logic network.

Animation node itself is a logic node and has a set of input and output properties:

• Fixed inputs:

  • progress (float) - point within [0;1] normalized range of where to jump to in the animation

    • in this range 0 marks the time 0 (regardless of timestamp of the first keyframe), and 1 marks the end of the animation determined by the duration of the animation

    • values outside of the [0;1] range are accepted and will be clamped

• Fixed outputs:

  • duration (float) - total duration of the animation, determined by the highest timestamp from all its channels

    • is affected by modifications to timestamp data via properties (see ramses::AnimationNodeConfig::setExposingOfChannelDataAsProperties)

• Channel outputs: Each animation channel provided at creation time (ramses::LogicEngine::createAnimationNode) will be represented as output property with name of the channel (ramses::AnimationChannel::name) and a value of type matching element in ramses::AnimationChannel::keyframes. If the data type of keyframes is ramses::EPropertyType::Array (i.e. each keyframe is represented by an array of floats), the output property is also of array type and contains corresponding number of children properties of type ramses::EPropertyType::Float. Channel value output is a result of keyframes interpolation based on the ‘progress’ input above, it can be linked to another logic node input to use the animation result.

• Channel data inputs (only if created with ramses::AnimationNodeConfig::setExposingOfChannelDataAsProperties enabled):

  • channelsData (struct) - contains all channels and their data in a hierarchy. For each channel:

    • [channelName] (struct)

      • timestamps (array of float) - each element represents a timestamp value

      • keyframes (array of T) - each element represents a keyframe value

        • type T is the data type matching this channel’s original keyframes

During update when ‘progress’ input is set the following logic is executed:

• calculate local animation time based on progress

• for each channel:

  • lookup closest previous and next timestamp/keyframe pair according to the local animation time,

  • interpolate between them according to the interpolation type of that channel,

  • and finally set this value to the channel’s output property.

Note that all channel outputs will always have a value determined by corresponding keyframes, also when the time falls outside of the first/last animation timestamps:

• channel output value equals first keyframe for any time at or before the first keyframe timestamp

• channel output value equals last keyframe for any time at or after the last keyframe timestamp This can be useful for example when it is needed to initialize the outputs before playing the animation, when updating the animation node with progress 0, the logic will execute and update outputs to their first keyframes.

Public Functions

const AnimationChannels &getChannels() const

Returns channel data used in this animation (as provided at creation time ramses::LogicEngine::createAnimationNode).

Note that the retrieved data is not affected by any modifications via channel data input properties (see ramses::AnimationNodeConfig::setExposingOfChannelDataAsProperties). If modifications were made, only corresponding properties hold the actual values used during animation.

Returns:

animation channels used in this animation.

internal::AnimationNodeImpl &impl()

Get the internal data for implementation specifics of AnimationNode.

const internal::AnimationNodeImpl &impl() const

Get the internal data for implementation specifics of AnimationNode.

class AnimationNodeConfig

#include <AnimationNodeConfig.h>

Holds the data and settings for ramses::AnimationNode creation using ramses::LogicEngine::createAnimationNode.

Public Functions

bool addChannel(const AnimationChannel &channelData)

Adds a data to animate. ramses::AnimationNode can use multiple animation channels to animate, see ramses::AnimationNode and ramses::AnimationChannel for details. This call can fail, see ramses::AnimationChannel for rules that channel data must follow.

Parameters:

channelData – channel data to add to configuration

Returns:

true if the channel was added successfully, false otherwise. In case of an error, check the logs.

const AnimationChannels &getChannels() const

Returns all channels data added to this AnimationNodeConfig so far.

Returns:

animation channels in this AnimationNodeConfig.

bool setExposingOfChannelDataAsProperties(bool enabled)

If enabled, the created ramses::AnimationNode will expose its basic channel data (timestamps and keyframes) in form of logic node properties. These properties can be set and linked allowing for control over actual animation data to be animated. The data can be adjusted at any point in time, also during playing the animation.

This functionality comes at a price - there is performance overhead and strict limit of how many keyframes the animation can have. All timestamp/keyframe values are represented as child properties within an array, per channel, refer to ramses::AnimationNode for the exact structure of these inputs. Processing the animation data in this form is not cheap compared to a regular animation node and there is a limit of 255 timestamps/keyframes any channel can have. Always try to minimize the amount of animation data when using this type of animation node.

Note that all modifications to the animation data are considered temporary and will NOT be preserved when saving to a file. All values and corresponding properties will be reset to original values (provided in this AnimationNodeConfig from when the ramses::AnimationNode was created) when loading from a file.

By default this feature is disabled. This feature cannot be enabled (this call will fail) if the AnimationNodeConfig contains a channel with ramses::DataArray using data type ramses::EPropertyType::Array.

Parameters:

enabled – flag to enable or disable exposing of channels data as properties.

Returns:

true if enabled successfully, false otherwise. In case of an error, check the logs.

bool getExposingOfChannelDataAsProperties() const

Returns the currently set state of the exposing of channel data as properties.

Returns:

the currently set state of the exposing of channel data as properties.

~AnimationNodeConfig() noexcept

Destructor of AnimationNodeConfig

AnimationNodeConfig(const AnimationNodeConfig &other)

Copy Constructor of AnimationNodeConfig

Parameters:

other – the other AnimationNodeConfig to copy from

AnimationNodeConfig(AnimationNodeConfig &&other) noexcept

Move Constructor of AnimationNodeConfig

Parameters:

other – the other AnimationNodeConfig to move from

AnimationNodeConfig &operator=(const AnimationNodeConfig &other)

Assignment operator of AnimationNodeConfig

Parameters:

other – the other AnimationNodeConfig to copy from

Returns:

self

AnimationNodeConfig &operator=(AnimationNodeConfig &&other) noexcept

Move assignment operator of AnimationNodeConfig

Parameters:

other – the other AnimationNodeConfig to move from

Returns:

self

internal::AnimationNodeConfigImpl &impl()

Get the internal data for implementation specifics of AnimationNodeConfig.

const internal::AnimationNodeConfigImpl &impl() const

Get the internal data for implementation specifics of AnimationNodeConfig.

class AppearanceBinding : public ramses::RamsesBinding

#include <AppearanceBinding.h>

The AppearanceBinding is a type of ramses::RamsesBinding which allows the ramses::LogicEngine to control instances of ramses::Appearance. AppearanceBinding’s can be created with ramses::LogicEngine::createAppearanceBinding.

The AppearanceBinding has a static link to a ramses::Appearance. After creation, ramses::LogicNode::getInputs will return a struct property with children equivalent to the uniform inputs of the provided ramses Appearance.

Since the AppearanceBinding derives from ramses::RamsesBinding, it also provides the ramses::LogicNode::getInputs and ramses::LogicNode::getOutputs method. For this particular implementation, the methods behave as follows:

• ramses::LogicNode::getInputs: returns the inputs corresponding to the available shader uniforms of the bound ramses::Appearance

• ramses::LogicNode::getOutputs: returns always nullptr, because a AppearanceBinding does not have outputs, it implicitly controls the ramses Appearance

• The values of this binding’s inputs are initialized to default values (0, 0.0f, etc) and not loaded from the values in Ramses

All shader uniforms are supported, except the following:

• texture samplers of any kind

• matrix types (e.g. mat4, mat23 etc.)

• any uniform with attached semantics (e.g. display resolution) - see ramses::EEffectUniformSemantic docs

Uniform types which are not supported are not available when queried over ramses::LogicNode::getInputs.

Public Functions

ramses::Appearance &getRamsesAppearance() const

Returns the bound Ramses Appearance.

Returns:

the bound ramses appearance

internal::AppearanceBindingImpl &impl()

Get the internal data for implementation specifics of AppearanceBinding.

const internal::AppearanceBindingImpl &impl() const

Get the internal data for implementation specifics of AppearanceBinding.

class CameraBinding : public ramses::RamsesBinding

#include <CameraBinding.h>

CameraBinding is a type of ramses::RamsesBinding which allows the ramses::LogicEngine to control instances of ramses::Camera. CameraBinding can be created with ramses::LogicEngine::createCameraBinding or ramses::LogicEngine::createCameraBindingWithFrustumPlanes, which affects the set of input properties that will be used to control camera frustum as described below.

CameraBinding has a static link to a ramses::Camera. After creation, ramses::LogicNode::getInputs will return a struct property with children equivalent to the camera settings of the provided ramses::Camera.

There are two types of ramses::Camera:

• ramses::PerspectiveCamera

• ramses::OrthographicCamera

Both camera types are defined through their viewport and their frustum properties. These are represented as two separate property structs in the CameraBinding. Be aware if you set one or more values to one of the structs on the binding and update the LogicEngine it will lead to all properties of this struct being set on the actual ramses::Camera. For example if you only set the ‘offsetX’ of the Camera viewport it will set all other viewport properties as well (offsetY, width and height) to whatever their state is at that moment. The values of the CameraBinding inputs are initialized with the values of the provided ramses::Camera during creation. The frustum values of the ramses::Camera are not affected when setting viewport values, and vice-versa. Check the ramses::Camera API to see which values belong together. To avoid unexpected behavior, we highly recommend setting all viewport values together, and also setting all frustum planes together (either by link or by setting them directly). This way unwanted behavior can be avoided.

Since CameraBinding derives from ramses::RamsesBinding, it also provides the ramses::LogicNode::getInputs and ramses::LogicNode::getOutputs method. For this class, the methods behave as follows:

• ramses::LogicNode::getInputs: returns inputs struct with two child properties: viewport and frustum.

  • ’viewport’ (type struct) with these children:

    • ’offsetX’ (type Int32) - viewport offset horizontal

    • ’offsetY’ (type Int32) - viewport offset vertical

    • ’width’ (type Int32) - viewport width

    • ’height’ (type Int32) - viewport height

  • ’frustum’ (type struct) children vary depending on frustum parameters to use, it will be one of the following sets of parameters:

    • full set of frustum plane properties:

      • ’nearPlane’ (type Float) - frustum plane near

      • ’farPlane’ (type Float) - frustum plane far

      • ’leftPlane’ (type Float) - frustum plane left

      • ’rightPlane’ (type Float) - frustum plane right

      • ’bottomPlane’ (type Float) - frustum plane bottom

      • ’topPlane’ (type Float) - frustum plane top

    • simplified set of frustum properties:

      • ’nearPlane’ (type Float) - frustum plane near

      • ’farPlane’ (type Float) - frustum plane far

      • ’fieldOfView’ (type Float) - frustum field of view in degrees

      • ’aspectRatio’ (type Float) - aspect ratio of frustum width / frustum height Full set of frustum planes properties will be present if the camera is ramses::Orthographic (regardless of which create method was used) or if the camera is ramses::PerspectiveCamera and ramses::LogicEngine::createCameraBindingWithFrustumPlanes was used to create it. Simplified set of frustum properties will be present if the camera is ramses::PerspectiveCamera and ramses::LogicEngine::createCameraBinding was used to create it. Refer to ramses::Camera, ramses::PerspectiveCamera and ramses::OrthographicCamera for the meanings and constraints of all these inputs.

• ramses::LogicNode::getOutputs: always returns nullptr, because a CameraBinding does not have outputs, it implicitly controls the ramses Camera.

Public Functions

ramses::Camera &getRamsesCamera() const

Returns the bound ramses camera.

Returns:

the bound ramses camera

internal::CameraBindingImpl &impl()

Get the internal data for implementation specifics of CameraBinding.

const internal::CameraBindingImpl &impl() const

Get the internal data for implementation specifics of CameraBinding.

class DataArray : public ramses::LogicObject

#include <DataArray.h>

Storage for data - e.g. animation data like keyframes or timestamps.

Public Functions

EPropertyType getDataType() const

Returns the type of data stored in this DataArray.

Returns:

the data type

template<typename T>
const std::vector<T> *getData() const

Returns the data stored in this DataArray. Make sure to use the right template type, query getDataType to see what data type is stored (see also ramses::PropertyTypeToEnum traits and ramses::CanPropertyTypeBeStoredInDataArray). When called with an unsupported type, a compile-time assert is triggered. When called with a mismatching type (e.g. getData<float>() when the type is vec4f) the method returns nullptr.

Returns:

vector of data or nullptr if incorrect template type is provided

size_t getNumElements() const

Returns the number of elements stored in this DataArray.

Returns:

the number of elements

internal::DataArrayImpl &impl()

Get the internal data for implementation specifics of DataArray.

const internal::DataArrayImpl &impl() const

Get the internal data for implementation specifics of DataArray.

class LogicEngine : public ramses::SceneObject

#include <LogicEngine.h>

Central object which creates and manages the lifecycle and execution of scripts, bindings, and all other objects supported by the Ramses Logic library.

• Use the create[Type] methods to create various objects, use destroy() to delete them.

• Use link and unlink to connect data properties between these objects.

• Use update() to trigger the execution of all objects.

Public Functions

template<typename T>
Collection<T> getCollection() const

Returns an iterable ramses::Collection of all instances of T created by this LogicEngine. T must be a concrete logic object type (e.g. ramses::LuaScript) or ramses::LogicObject which will retrieve all logic objects created with this LogicEngine (see ramses::LogicObject::as<Type> to convert to concrete type).

Returns:

an iterable ramses::Collection with all instances of T created by this LogicEngine

template<typename T = LogicObject>
const T *findObject(std::string_view name) const

Returns a pointer to the first occurrence of an object with a given name and type T (ramses::LogicObject by default). T must be a concrete logic object type (e.g. ramses::LuaScript) or ramses::LogicObject which will search any object with given name regardless of its type (see ramses::LogicObject::as<Type> to convert to concrete type). Note that giving a concrete object template type might result in faster search because it is limited to only objects of that type.

Parameters:

name – the name of the logic object to search for

Returns:

a pointer to the logic object, or nullptr if none was found

template<typename T = LogicObject>
T *findObject(std::string_view name)

Returns a pointer to the first occurrence of an object with a given name and type T (ramses::LogicObject by default). T must be a concrete logic object type (e.g. ramses::LuaScript) or ramses::LogicObject which will search any object with given name regardless of its type (see ramses::LogicObject::as<Type> to convert to concrete type). Note that giving a concrete object template type might result in faster search because it is limited to only objects of that type.

Parameters:

name – the name of the logic object to search for

Returns:

a pointer to the logic object, or nullptr if none was found

template<typename T = LogicObject>
T *findObject(sceneObjectId_t id)

Returns a pointer to an object with a given ramses::sceneObjectId_t and type T (ramses::LogicObject by default). T must be a concrete logic object type (e.g. ramses::LuaScript) or ramses::LogicObject which will search any object with given ID regardless of its type (see ramses::LogicObject::as<Type> to convert to concrete type). Note that giving a concrete object template type might result in faster search because it is limited to only objects of that type.

Parameters:

id – The id of the object to find.

Returns:

a pointer to the logic object, or nullptr if none was found

template<typename T = LogicObject>
const T *findObject(sceneObjectId_t id) const

Returns a pointer to an object with a given ramses::sceneObjectId_t and type T (ramses::LogicObject by default). T must be a concrete logic object type (e.g. ramses::LuaScript) or ramses::LogicObject which will search any object with given ID regardless of its type (see ramses::LogicObject::as<Type> to convert to concrete type). Note that giving a concrete object template type might result in faster search because it is limited to only objects of that type.

Parameters:

id – The id of the object to find.

Returns:

a pointer to the logic object, or nullptr if none was found

LuaScript *createLuaScript(std::string_view source, const LuaConfig &config = {}, std::string_view scriptName = "")

Creates a new Lua script from a source string. Refer to the ramses::LuaScript class for requirements which Lua scripts must fulfill in order to be added to the LogicEngine. You can optionally provide Lua module dependencies via the config, they will be accessible under their configured alias name for use by the script. The provided module dependencies must exactly match the declared dependencies in source code (see extractLuaDependencies).

Parameters:

• source – the Lua source code

• config – configuration options, e.g. for module dependencies

• scriptName – name to assign to the script once it’s created

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The script can be destroyed by calling the destroy method

LuaInterface *createLuaInterface(std::string_view source, std::string_view interfaceName, const LuaConfig &config = {})

Creates a new Lua interface from a source string. Refer to the ramses::LuaInterface class for requirements which Lua interface must fulfill in order to be added to the LogicEngine. Note: interfaces must have a non-empty name. ramses::LuaInterface can be created with any non-empty name but if two or more instances share same name there will be a warning during validation (validate) as it is advised for every Lua interface to have a unique name for clear identification from application logic. You can optionally provide Lua module dependencies via the config, they will be accessible under their configured alias name for use in the interface source. The provided module dependencies must exactly match the declared dependencies in source code (see extractLuaDependencies).

Parameters:

• source – the Lua source code

• interfaceName – name to assign to the interface once it’s created. This name must be unique!

• config – configuration options, e.g. for module dependencies

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The interface can be destroyed by calling the destroy method

LuaModule *createLuaModule(std::string_view source, const LuaConfig &config = {}, std::string_view moduleName = "")

Creates a new ramses::LuaModule from Lua source code. LuaModules can be used to share code and data constants across scripts or other modules. See also createLuaScript and ramses::LuaConfig for details. You can optionally provide Lua module dependencies via the config, they will be accessible under their configured alias name for use by the module. The provided module dependencies must exactly match the declared dependencies in source code (see extractLuaDependencies).

Parameters:

• source – module source code

• config – configuration options, e.g. for module dependencies

• moduleName – name to assign to the module once it’s created

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The script can be destroyed by calling the destroy method

bool extractLuaDependencies(std::string_view source, const std::function<void(const std::string&)> &callbackFunc)

Extracts dependencies from a Lua script, module or interface source code so that the corresponding modules can be provided when creating ramses::LuaScript, ramses::LuaModule or ramses::LuaInterface.

Any ramses::LuaScript, ramses::LuaModule or ramses::LuaInterface which has a module dependency, i.e. it requires another ramses::LuaModule for it to work, must explicitly declare these dependencies directly in their source code by calling function ‘modules’ in global space and pass list of module names it depends on, for example:

modules("foo", "bar")
function interface(IN,OUT)
  OUT.x = foo.myType()
end
function run(IN,OUT)
  OUT.x = bar.doSth()
end

The ‘modules’ function does not affect any other part of the source code in any way, it is used only for the purpose of explicit declaration and extraction of its dependencies.

Please note that script runtime errors are ignored during extraction. In case a runtime error prevents the ‘modules’ function to be called, this method will still succeed but will not extract any modules, i.e. will not call callbackFunc. It is therefore highly recommended to put the modules declaration always at the beginning of every script before any other code so it will get executed even if there is runtime error later in the code.

Parameters:

• source – source code of module or script to parse for dependencies

• callbackFunc – function callback will be called for each dependency found

Returns:

true if extraction succeeded (also if no dependencies found) or false if something went wrong. In that case, use ramses::RamsesFramework::getLastError.

NodeBinding *createNodeBinding(ramses::Node &ramsesNode, ramses::ERotationType rotationType = ramses::ERotationType::Euler_XYZ, std::string_view name = "")

Creates a new ramses::NodeBinding which can be used to set the properties of a Ramses Node object. The initial values of the binding’s properties are loaded from the ramsesNode. Rotation values are taken over from the ramsesNode only if the conventions are compatible (see ramses::ERotationType). The creation will fail if provided ramses::Node is not from same ramses::Scene as this LogicEngine instance.

Parameters:

• ramsesNode – the ramses::Node object to control with the binding.

• rotationType – the type of rotation to use (will affect the ‘rotation’ property semantics and type).

• name – a name for the new ramses::NodeBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

AppearanceBinding *createAppearanceBinding(ramses::Appearance &ramsesAppearance, std::string_view name = "")

Creates a new ramses::AppearanceBinding which can be used to set the properties of a Ramses Appearance object. The creation will fail if provided ramses::Appearance is not from same ramses::Scene as this LogicEngine instance.

Parameters:

• ramsesAppearance – the ramses::Appearance object to control with the binding.

• name – a name for the the new ramses::AppearanceBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

CameraBinding *createCameraBinding(ramses::Camera &ramsesCamera, std::string_view name = "")

Creates a new ramses::CameraBinding which can be used to set the properties of a Ramses Camera object. The creation will fail if provided ramses::Camera is not from same ramses::Scene as this LogicEngine instance.

Parameters:

• ramsesCamera – the ramses::Camera object to control with the binding.

• name – a name for the the new ramses::CameraBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

CameraBinding *createCameraBindingWithFrustumPlanes(ramses::Camera &ramsesCamera, std::string_view name = "")

Same as createCameraBinding but the created ramses::CameraBinding will have an input property for each frustum plane also for perspective camera. See ramses::CameraBinding for details. Note that ramses::OrthographicCamera binding will always have frustum planes as properties whether createCameraBinding or createCameraBindingWithFrustumPlanes is used to create it.

Parameters:

• ramsesCamera – the ramses::Camera object to control with the binding.

• name – a name for the the new ramses::CameraBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

RenderPassBinding *createRenderPassBinding(ramses::RenderPass &ramsesRenderPass, std::string_view name = "")

Creates a new ramses::RenderPassBinding which can be used to set the properties of a ramses::RenderPass object. The creation will fail if provided ramses::RenderPass is not from same ramses::Scene as this LogicEngine instance.

Parameters:

• ramsesRenderPass – the ramses::RenderPass object to control with the binding.

• name – a name for the the new ramses::RenderPassBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

RenderGroupBinding *createRenderGroupBinding(ramses::RenderGroup &ramsesRenderGroup, const RenderGroupBindingElements &elements, std::string_view name = "")

Creates a new ramses::RenderGroupBinding which can be used to control some properties of a ramses::RenderGroup object. ramses::RenderGroupBinding can be used to control render order of elements it contains on Ramses side - ramses::MeshNode or ramses::RenderGroup, the elements to control must be provided explicitly at creation time, see ramses::RenderGroupBindingElements and ramses::RenderGroupBinding to learn how these elements form the binding’s input properties. The creation will fail if provided ramses::RenderGroup or the elements are not from same ramses::Scene as this LogicEngine instance.

Parameters:

• ramsesRenderGroup – the ramses::RenderGroup object to control with the binding.

• elements – collection of elements (MeshNode or RenderGroup) to control with this ramses::RenderGroupBinding.

• name – a name for the the new ramses::RenderGroupBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

MeshNodeBinding *createMeshNodeBinding(ramses::MeshNode &ramsesMeshNode, std::string_view name = "")

Creates a new ramses::MeshNodeBinding which can be used to control some properties of a ramses::MeshNode object. The creation will fail if provided ramses::MeshNode is not from same ramses::Scene as this LogicEngine instance.

Parameters:

• ramsesMeshNode – the ramses::MeshNode object to control with the binding.

• name – a name for the the new ramses::MeshNodeBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

SkinBinding *createSkinBinding(const std::vector<const NodeBinding*> &joints, const std::vector<matrix44f> &inverseBindMatrices, AppearanceBinding &appearanceBinding, const ramses::UniformInput &jointMatInput, std::string_view name = {})

Creates a new ramses::SkinBinding which can be used for vertex skinning (bone animations). Refer to ramses::SkinBinding and examples for all the information needed how to use this object.

These conditions must be met in order for the creation to succeed:

• joints must contain at least 1 joint and no null pointers

• inverseBindMatrices must be of equal size as joints (i.e. matrix per joint)

• jointMatInput must point to a valid uniform input of the ramses::Effect used in appearanceBinding

• the shader uniform that jointMatInput points to must be of type array of ramses::EDataType::Matrix44F with number of elements matching number of joints

• jointMatInput must not be bound to any data object in its Ramses appearance The creation will also fail if any of the provided Ramses objects or bindings are not from same ramses::Scene as this LogicEngine instance.

Parameters:

• joints – bindings to Ramses nodes which will act as skeleton nodes.

• inverseBindMatrices – inverse transformation matrices (one for each joint node), values are expected ordered in column-major fashion.

• appearanceBinding – binding to Ramses appearance which specifies the effect/shader for vertex skinning.

• jointMatInput – Ramses appearance uniform input for the resulting joint matrices to be set.

• name – a name for the the new ramses::SkinBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

RenderBufferBinding *createRenderBufferBinding(ramses::RenderBuffer &renderBuffer, std::string_view name = "")

Creates a new ramses::RenderBufferBinding which can be used to change some properties of a ramses::RenderBuffer object. The creation will fail if provided ramses::RenderBuffer is not from same ramses::Scene as this LogicEngine instance.

Parameters:

• renderBuffer – the ramses::RenderBuffer object to control with the binding.

• name – a name for the the new ramses::RenderBufferBinding.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The binding can be destroyed by calling the destroy method

template<typename T>
DataArray *createDataArray(const std::vector<T> &data, std::string_view name = "")

Creates a new ramses::DataArray to store data which can be used with animations. Provided data must not be empty otherwise creation will fail. See ramses::CanPropertyTypeBeStoredInDataArray and ramses::PropertyTypeToEnum to determine supported types that can be used to create a ramses::DataArray. When using std::vector<float> as element data type (corresponds to ramses::EPropertyType::Array), the sizes of all the elements (std::vector<float> instances) must be equal, otherwise creation will fail.

Parameters:

• data – source data to move into ramses::DataArray, must not be empty.

• name – a name for the the new ramses::DataArray.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError.

AnimationNode *createAnimationNode(const AnimationNodeConfig &config, std::string_view name = "")

Creates a new ramses::AnimationNode for animating properties. Refer to ramses::AnimationNode for more information about its use. There must be at least one channel provided in the ramses::AnimationNodeConfig, please see ramses::AnimationChannel requirements for all the data.

Parameters:

• config – list of animation channels to be animated with this animation node and other configuration flags.

• name – a name for the the new ramses::AnimationNode.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError.

TimerNode *createTimerNode(std::string_view name = "")

Creates a new ramses::TimerNode for generate and/or propagate timing information. Refer to ramses::TimerNode for more information about its use.

Parameters:

name – a name for the the new ramses::TimerNode.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError.

AnchorPoint *createAnchorPoint(NodeBinding &nodeBinding, CameraBinding &cameraBinding, std::string_view name = "")

Creates a new ramses::AnchorPoint that can be used to calculate projected coordinates of given ramses::Node when viewed using given ramses::Camera. See ramses::AnchorPoint for more details and usage of this special purpose logic node.

Parameters:

• nodeBinding – binding referencing ramses::Node to use for model transformation when calculating projected coordinates.

• cameraBinding – binding referencing ramses::Camera to use for view and projection transformation when calculating projected coordinates.

• name – a name for the the new ramses::AnchorPoint.

Returns:

a pointer to the created object or nullptr if something went wrong during creation. In that case, use ramses::RamsesFramework::getLastError. The ramses::AnchorPoint can be destroyed by calling the destroy method

bool update()

Updates all ramses::LogicNode’s which were created by this LogicEngine instance. The order in which ramses::LogicNode’s are executed is determined by the links created between them (see link and unlink). ramses::LogicNode’s which don’t have any links between then are executed in arbitrary order, but the order is always the same between two invocations of update without any calls to link or unlink between them. As an optimization ramses::LogicNode’s are only updated, if at least one input of a ramses::LogicNode has changed since the last call to update. If the links between logic nodes create a loop, this method will fail with an error and will not execute any of the logic nodes.

Returns:

true if the update was successful, false otherwise In case of an error, use ramses::RamsesFramework::getLastError.

void enableUpdateReport(bool enable)

Enables collecting of statistics during call to update which can be obtained using getLastUpdateReport. Once enabled every subsequent call to update will be instructed to collect various statistical data which can be useful for profiling and optimizing the network of logic nodes. Note that when enabled there is a slight performance overhead to collect the data, it is recommended to use this only during a development phase. Note that using setStatisticsLoggingRate with EStatisticsLogMode::Detailed will also implicitly enable generating of update report for internal use during periodic statistics logging.

Parameters:

enable – true or false to enable or disable update reports.

LogicEngineReport getLastUpdateReport() const

Returns collection of statistics from last call to update if reporting is enabled (enableUpdateReport). The report contains lists of logic nodes that were executed and not executed and other useful data collected during last update. See ramses::LogicEngineReport for details. The report data is generated if previously enabled using enableUpdateReport and is empty otherwise. The data is only relevant for the last update and is overwritten during next update. Note that if update fails the report contents are undefined.

Attention! The ramses::LogicEngineReport is returned by value and owns all the reported data. Make sure to keep the object as long as its data is referenced.

Returns:

collected statistics from last update.

void setStatisticsLoggingRate(size_t loggingRate, EStatisticsLogMode mode = EStatisticsLogMode::Compact)

Set the logging rate, i.e. how often statistics will be logged. Logging rate of N means every Nth call to update statistics will be logged. The logging rate also determines how many collected sets will be used to calculate min/max and average. These compact statistics include:

• Time since last log in seconds

• Update execution time in microseconds (Avg, Min, Max)

• Time between update calls in microseconds (Avg, Min, Max)

• Count of nodes executed in percentage of total count (Avg, Min, Max)

• Links activated (Avg, Min, Max) The detailed statistics additionally logs slowest nodes and their individual maximum update times during measured period. When loggingRate is set to 0 the logging of statistics is disabled. Note that there is a slight performance overhead for collecting the statistics data, however on most platforms this should be marginal. Note that using EStatisticsLogMode::Detailed will also implicitly enable generating of update report (see enableUpdateReport) for internal use during periodic statistics logging, and vice versa if EStatisticsLogMode::Compact is set it will disable update report generating (even if previously enabled by user).

Parameters:

• loggingRate – rate of N means statistics will be logged every Nth call to update. By default, loggingRate is 60.

• mode – logging mode of the statistics (See EStatisticsLogMode) By default, mode is EStatisticsLogMode::Compact.

bool link(Property &sourceProperty, Property &targetProperty)

Links a property of a ramses::LogicNode to another ramses::Property of another ramses::LogicNode. After linking, calls to update will propagate the value of sourceProperty to the targetProperty. Creating links influences the order in which scripts are executed - if node A provides data to node B, then node A will be executed before node B. A single output property (sourceProperty) can be linked to any number of input properties (targetProperty), but any input property can have at most one link to an output property (links are directional and support a 1-to-N relationships).

The link() method will fail when:

• sourceProperty and targetProperty belong to the same ramses::LogicNode

• sourceProperty is not an output (see ramses::LogicNode::getOutputs())

• targetProperty is not an input (see ramses::LogicNode::getInputs())

• either sourceProperty or targetProperty is not a primitive property (you have to link sub-properties of structs and arrays individually)

Creating links which form a cycle in the node dependency graph will not fail right away but during the next call to update(). Links are directional, it is OK to have A->B, A->C and B->C, but is not OK to have A->B->C->A. Cycles are allowed only under special conditions when using a weak link (see linkWeak).

After calling link, the value of the targetProperty will not change until the next call to update. Creating and destroying links generally has no effect until update is called.

Parameters:

• sourceProperty – the output property which will provide data for targetProperty

• targetProperty – the target property which will receive its value from sourceProperty

Returns:

true if linking was successful, false otherwise. To get more detailed error information use ramses::RamsesFramework::getLastError

bool linkWeak(Property &sourceProperty, Property &targetProperty)

A weak link is for the most part equivalent to link - it has the same requirements and data propagation behavior, but with one crucial difference. Weak link is not considered for node dependency graph (logic node topology) which determines the order of nodes execution during update. This allows to form a cycle using weak link within the dependency graph, which can be helpful when some feedback data is required (e.g. a controller node managing a worker node using normal links, worker node reports progress back to controller via weak link). However there are important things to consider to avoid unexpected problems:

1. The value propagated from a weak link is old, it is the value that was calculated in previous update. Example: consider A->B->C using normal links and a back loop C->A using weak link. When update is called, the nodes are executed exactly in the order defined by normal link dependency: A, B, C (remember that weak links are not considered for execution order). This means however that when A is executed its input value from weak linked C is only from previous update because C is executed last.

2. During first update (after creation or load from file) there is no value applied from weak link, instead the initial input property value will be used at the weak link target. This is a logical consequence of the limitation described above - during first update there was no previous update and therefore no value from weak link.

3. Avoid infinite update loops - update has an optimization to execute only nodes with modified inputs, this can greatly simplify update of complex node hierarchies. When using weak links there is a risk that there will be a never ending need of executions of nodes involved in a node graph cycle. Consider the last node providing new value via weak link to first node, which then generates again new value propagated to the last node, this will result in the need to execute those nodes in all upcoming update calls. Try to avoid such case and if it is not possible at least try to limit this update loop to a minimum of nodes.

Parameters:

• sourceProperty – the output property which will provide data for targetProperty

• targetProperty – the target property which will receive its value from sourceProperty

Returns:

true if linking was successful, false otherwise. To get more detailed error information use ramses::RamsesFramework::getLastError

bool unlink(Property &sourceProperty, Property &targetProperty)

Unlinks two properties which were linked with link. After a link is destroyed, calls to update will no longer propagate the output value from the sourceProperty to the input value of the targetProperty. The value of the targetProperty will remain as it was after the last call to update - it will not be restored to a default value or to any value which was set manually with calls to ramses::Property::set().

Parameters:

• sourceProperty – the output property which is currently linked to targetProperty

• targetProperty – the property which will no longer receive the value from sourceProperty

Returns:

true if unlinking was successful, false otherwise. To get more detailed error information use ramses::RamsesFramework::getLastError.

bool isLinked(const LogicNode &logicNode) const

Checks if an input or output of a given LogicNode is linked to another LogicNode

Parameters:

logicNode – the node to check for linkage.

Returns:

true if the given LogicNode is linked to any other LogicNode, false otherwise.

const std::vector<PropertyLinkConst> &getPropertyLinks() const

Collect and retrieve all existing links between properties of logic nodes. There will be a ramses::PropertyLink in the returned container for every existing link created (using link or linkWeak).

Note that the returned container will not be modified (even if new links are created or unlinked in LogicEngine) until getPropertyLinks is called again.

Returns:

all existing links between properties of logic nodes.

const std::vector<PropertyLink> &getPropertyLinks()

Collect and retrieve all existing links between properties of logic nodes. There will be a ramses::PropertyLink in the returned container for every existing link created (using link or linkWeak).

Note that the returned container will not be modified (even if new links are created or unlinked in LogicEngine) until getPropertyLinks is called again.

Returns:

all existing links between properties of logic nodes.

bool destroy(LogicObject &object)

Destroys an instance of an object created with LogicEngine. All objects created using LogicEngine derive from a base class ramses::LogicObject and can be destroyed using this method.

In case of a ramses::LogicNode and its derived classes, if any links are connected to this ramses::LogicNode, they will be destroyed too. Note that after this call, the execution order of ramses::LogicNode may change! See the docs of link and unlink for more information.

In case of a ramses::DataArray, destroy will fail if it is used in any ramses::AnimationNode’s ramses::AnimationChannel.

In case of a ramses::LuaModule, destroy will fail if it is used in any ramses::LuaScript.

Parameters:

object – the object instance to destroy

Returns:

true if object destroyed, false otherwise. Call ramses::RamsesFramework::getLastError for error details upon failure.

size_t getTotalSerializedSize(ELuaSavingMode luaSavingMode = ELuaSavingMode::SourceAndByteCode) const

Calculates the serialized size of all objects contained in this LogicEngine instance. Note that the returned size will differ from actual size when saved to a file but the difference should be no more than several bytes (file header, meta information, etc.).

Parameters:

luaSavingMode – calculate with Lua code saved as source string, binary or both, see ramses::SaveFileConfig::setLuaSavingMode), default is ramses::ELuaSavingMode::SourceAndByteCode.

Returns:

size in bytes of the serialized LogicEngine.

template<typename T>
size_t getSerializedSize(ELuaSavingMode luaSavingMode = ELuaSavingMode::SourceAndByteCode) const

Calculates the serialized size of all objects of a specific type in this LogicEngine instance. T must be a concrete logic object type (e.g. ramses::LuaScript). For the logic type LogicObject the size of all logic objects will be returned.

Template Parameters:

T – Logic object type to calculate size for

Parameters:

luaSavingMode – calculate with Lua code saved as source string, binary or both, see ramses::SaveFileConfig::setLuaSavingMode), default is ramses::ELuaSavingMode::SourceAndByteCode (relevant only for object types containing Lua code).

Returns:

size in bytes of the serialized objects.

internal::LogicEngineImpl &impl()

Get the internal data for implementation specifics of LogicEngine.

const internal::LogicEngineImpl &impl() const

Get the internal data for implementation specifics of LogicEngine.

Friends

friend class internal::SceneObjectRegistry

class LogicEngineReport

#include <LogicEngineReport.h>

A collection of results from ramses::LogicEngine::update which can be used for debugging or profiling logic node networks.

Can be obtained using ramses::LogicEngine::getLastUpdateReport after an update with enabled reporting (ramses::LogicEngine::enableUpdateReport).

Public Types

using LogicNodeTimed = std::pair<LogicNode*, std::chrono::microseconds>

LogicNode with measured update execution.

Public Functions

const std::vector<LogicNodeTimed> &getNodesExecuted() const

Gets list of logic nodes that were updated and the amount of time it took to execute their update logic. Typically nodes have to be updated due to one of their inputs being ‘dirty’ (modified) or some other internal trigger. The order of the nodes in the list matches the order of their execution, this order is determined by the logic network topology and is deterministic.

Returns:

list of updated nodes with update execution time, sorted by execution order

const std::vector<LogicNode*> &getNodesSkippedExecution() const

List of logic nodes that were not updated because their inputs did not change therefore there was no need to. Similar to getNodesExecuted, the order of the nodes in the list matches the order of their (in this case skipped) execution.

Returns:

list of nodes which did not need update

std::chrono::microseconds getTopologySortExecutionTime() const

Time it took to sort logic nodes by their topology during update. Note that re-sorting is only needed if topology changed (node linked/unlinked), otherwise the result is cached and this should take negligible time.

Returns:

time to sort logic nodes

std::chrono::microseconds getTotalUpdateExecutionTime() const

Time it took to update the whole logic nodes network. This is essentially the same as measuring how long it took to call ramses::LogicEngine::update from application side.

Returns:

time to update all logic nodes

size_t getTotalLinkActivations() const

Obtain the number of links activated during update.

Returns:

the number of links activated during update

LogicEngineReport() noexcept

Default constructor of LogicEngineReport.

explicit LogicEngineReport(std::unique_ptr<internal::LogicEngineReportImpl> impl) noexcept

Constructor of LogicEngineReport. Do not construct, use ramses::LogicEngine::getLastUpdateReport to obtain.

Parameters:

impl – implementation details of the LogicEngineReport

~LogicEngineReport()

Class destructor

LogicEngineReport(const LogicEngineReport&) = delete

Copying disabled, move instead.

LogicEngineReport(LogicEngineReport &&other) noexcept

Move constructor

Parameters:

other – source

LogicEngineReport &operator=(const LogicEngineReport&) = delete

Copying disabled, move instead.

LogicEngineReport &operator=(LogicEngineReport &&other) noexcept

Move assignment

Parameters:

other – source

class LogicNode : public ramses::LogicObject

#include <LogicNode.h>

A base class for multiple logic classes which provides a unified interface to their inputs and outputs.

Some subclasses don’t have inputs or outputs - in that case the getInputs or getOutputs methods respectively will return nullptr. Some subclasses, like the ramses::AppearanceBinding, will have their inputs depending on their current state (in this example the GLSL uniforms of the shader to which the bound ramses Appearance belongs). In those cases, getInputs()/getOutputs() will return a ramses::Property which represents an empty struct (type Struct, but no child properties).

Subclassed by ramses::AnchorPoint, ramses::AnimationNode, ramses::LuaInterface, ramses::LuaScript, ramses::RamsesBinding, ramses::TimerNode

Public Functions

Property *getInputs()

Returns a property of type Struct which holds the inputs of the LogicNode.

Returns the root Property of the LogicNode which contains potentially nested list of properties. Calling ramses::Property::getName() on the returned object will always return “” regardless of the name used in the scripts. This applies only to the root input node, rest of the nodes in the tree structure follow standard behavior. The properties are different for the classes which derive from LogicNode. Look at the documentation of each derived class for more information on the properties.

Returns:

a tree like structure with the inputs of the LogicNode

const Property *getInputs() const

Returns a property of type Struct which holds the inputs of the LogicNode.

Returns the root Property of the LogicNode which contains potentially nested list of properties. Calling ramses::Property::getName() on the returned object will always return “” regardless of the name used in the scripts. This applies only to the root input node, rest of the nodes in the tree structure follow standard behavior. The properties are different for the classes which derive from LogicNode. Look at the documentation of each derived class for more information on the properties.

Returns:

a tree like structure with the inputs of the LogicNode

Property *getOutputs()

Returns a property of type Struct which holds the outputs of the LogicNode

Returns the root Property of the LogicNode which contains potentially nested list of properties. Calling ramses::Property::getName() on the returned object will always return “” regardless of the name used in the scripts. This applies only to the root output node, rest of the nodes in the tree structure follow standard behavior. The properties are different for the classes which derive from LogicNode. Look at the documentation of each derived class for more information on the properties.

Returns:

a tree like structure with the outputs of the LogicNode

const Property *getOutputs() const

Returns a property of type Struct which holds the outputs of the LogicNode

Returns the root Property of the LogicNode which contains potentially nested list of properties. Calling ramses::Property::getName() on the returned object will always return “” regardless of the name used in the scripts. This applies only to the root output node, rest of the nodes in the tree structure follow standard behavior. The properties are different for the classes which derive from LogicNode. Look at the documentation of each derived class for more information on the properties.

Returns:

a tree like structure with the outputs of the LogicNode

internal::LogicNodeImpl &impl()

Get the internal data for implementation specifics of LogicNode.

const internal::LogicNodeImpl &impl() const

Get the internal data for implementation specifics of LogicNode.

class LogicObject : public ramses::SceneObject

#include <LogicObject.h>

A base class for all rlogic API objects.

Subclassed by ramses::DataArray, ramses::LogicNode, ramses::LuaModule

Public Functions

internal::LogicObjectImpl &impl()

Get the internal data for implementation specifics of LogicObject.

const internal::LogicObjectImpl &impl() const

Get the internal data for implementation specifics of LogicObject.

class LuaConfig

#include <LuaConfig.h>

Holds configuration settings for Lua script and module creation. Can be default-constructed, moved and copied.

Public Functions

bool addDependency(std::string_view aliasName, const LuaModule &moduleInstance)

Adds a ramses::LuaModule as a dependency to be added when this config is used for script or module creation. The aliasName can be any valid Lua label which must obey following rules:

• can’t use the same label twice in the same LuaConfig object

• can’t use standard module names (math, string etc.)

The moduleInstance provided can be any module. You can’t reference modules from different ramses::LogicEngine instances and the referenced modules must be from the same instance on which the config is used for script creation.

Parameters:

• aliasName – the alias name under which the dependency will be mapped into the parent script/module

• moduleInstance – the dependency module to map

Returns:

true if the dependency was added successfully, false otherwise In case of an error, check the logs.

bool addStandardModuleDependency(EStandardModule stdModule)

Adds a standard module dependency. The module is mapped under a name as documented in ramses::EStandardModule.

Parameters:

stdModule – the standard module which will be mapped into the parent script/module

Returns:

true if the standard module was added successfully, false otherwise In case of an error, check the logs.

void enableDebugLogFunctions()

Will expose these log functions in Lua: rl_logInfo rl_logWarn rl_logError Each with single string as argument. Call from Lua script or module to any of these will forward the string message to a corresponding internal Ramses Logic logger.

IMPORTANT: These functions are meant for debug/prototype purposes only and attempt to save the project to file (ramses::Scene::saveToFile) with any script or module with these functions enabled will result in failure!

~LuaConfig() noexcept

Destructor of LuaConfig

LuaConfig(const LuaConfig &other)

Copy Constructor of LuaConfig

Parameters:

other – the other LuaConfig to copy from

LuaConfig(LuaConfig &&other) noexcept

Move Constructor of LuaConfig

Parameters:

other – the other LuaConfig to move from

LuaConfig &operator=(const LuaConfig &other)

Assignment operator of LuaConfig

Parameters:

other – the other LuaConfig to copy from

Returns:

self

LuaConfig &operator=(LuaConfig &&other) noexcept

Move assignment operator of LuaConfig

Parameters:

other – the other LuaConfig to move from

Returns:

self

internal::LuaConfigImpl &impl()

Get the internal data for implementation specifics of LuaConfig.

const internal::LuaConfigImpl &impl() const

Get the internal data for implementation specifics of LuaConfig.

class LuaInterface : public ramses::LogicNode

#include <LuaInterface.h>

LuaInterface encapsulates a logic network (whole or its parts) and forms an additional layer to expose only relevant inputs to the user of that network. Those input variables can be used to represent scenes in an abstract way. LuaInterface instances are created by the ramses::LogicEngine class.

A LuaInterface can be created from Lua source code which must fulfill same requirements as ramses::LuaScript, except for the following:

• A Lua interface contains only one global function: interface()

• The interface() function takes only one parameter that represents both inputs and outputs, e.g., interface(INOUT_PARAMS)

Violating any of these requirements will result in an error, which can be obtained by calling ramses::RamsesFramework::getLastError(). For other than interface definition purposes, see ramses::LuaModule and ramses::LuaScript for details.

See also the full documentation at https://ramses-logic.readthedocs.io/en/latest/api.html for more details on Lua and its interaction with C++.

Public Functions

internal::LuaInterfaceImpl &impl()

Get the internal data for implementation specifics of LuaInterface.

const internal::LuaInterfaceImpl &impl() const

Get the internal data for implementation specifics of LuaInterface.

class LuaModule : public ramses::LogicObject

#include <LuaModule.h>

LuaModule represents Lua source code in form of a reusable Lua module which can be used in Lua scripts of one or more ramses::LuaScript instances. Lua modules can be also declared as a dependency to other modules. Lua modules are expected to follow these guidelines https://www.tutorialspoint.com/lua/lua_modules.htm and have some limitations:

• the name of the module given when creating it is only used to differentiate between LuaModule instances on Ramses logic API, not to access them from a script or to resolve a file on a filesystem

• the module is not supposed to be resolved with the ‘require’ keyword in Lua scripts where used (due to security concerns) but must be provided explicitly when creating ramses::LuaScript instance

• modules are read-only in order to prevent data races when accessed from different scripts with undefined order of execution ramses::LuaModule source code is loaded into its own Lua environment and is accessible in other ramses::LuaScript and/or LuaModule instances in their own environments under the alias name given when creating those.

LuaModule can also be used to help providing property types for ramses::LuaScript interface declarations, for example a module with a ‘struct’ type:

local mytypes = {}
function mytypes.mystruct()
    return Type:Struct({
        name = Type:String(),
        address = Type:Struct({
            street = Type:String(),
            number = Type:Int32()
        })
    })
end
return mytypes

And script using above module to define its interface:

modules("mytypes")  -- must declare the dependency explicitly
function interface(IN,OUT)
    IN.input_struct = mytypes.mystruct()
    OUT.output_struct = mytypes.mystruct()
end

The label ‘Type’ is a reserved keyword and must not be overwritten for other purposes (e.g. name of variable or function).

Public Functions

internal::LuaModuleImpl &impl()

Get the internal data for implementation specifics of LuaModule.

const internal::LuaModuleImpl &impl() const

Get the internal data for implementation specifics of LuaModule.

class LuaScript : public ramses::LogicNode

#include <LuaScript.h>

The LuaScript class is the cornerstone of RAMSES Logic as it encapsulates a Lua script and the Lua environment associated with it. LuaScript instances are created by ramses::LogicEngine class.

A LuaScript can be created from Lua source code which must fulfill following requirements:

• valid Lua 5.1 syntax

• contains two global functions - interface(IN,OUT) and run(IN,OUT) with exactly two parameters (for inputs and outputs respectively) and no return values

• declares its inputs and outputs in the interface(IN,OUT) function, and its logic in the run(IN,OUT) function - you can use different names than IN/OUT

• the interface(IN,OUT) function declares zero or more inputs and outputs to the IN and OUT variables passed to the function

• inputs and outputs are declared like this:

  function interface(IN,OUT)
      IN.input_name = Type:T()
      OUT.output_name = Type:T()
  end
  

• T is one of [Int32|Int64|Float|Bool|String|Vec2f|Vec3f|Vec4f|Vec2i|Vec3i|Vec4i|Struct|Array]

• For T=Struct:

  • The first and only argument to the function must be a table

  • The table keys must be strings, and the table values must be again declared with Type:T()

• For T=Array, the function declaration is of the form Type:Array(n, E) where:

  • n is a positive integer

  • E must be declared with Type:T()

  • E can be a Type:Struct(), i.e. arrays of structs are supported

• Each property must have a name (string) - other types like number, bool etc. are not supported as keys

• T can also be defined in a module, see ramses::LuaModule for details

• as a convenience abbreviation, you can use {…} instead of Type:Struct({…}) to declare structs

• You can optionally declare an init() function with no parameters

  • init() is allowed to write data or functions to a predefined GLOBAL table

  • init() will be executed exactly once after loading the script (also when loading from binaries)

  • the data from GLOBAL will be available to the interface() and run() functions

  • no other global data can be read or written in any of the functions or in the global scope of the script

• you may declare module dependencies using the modules() function

  • modules() accepts a vararg of strings for each module

  • the string provided will be the name under which the module will be available in other functions

  • See also ramses::LuaModule for more info on modules and their syntax

Violating any of these requirements will result in an error, which can be obtained by calling ramses::RamsesFramework::getLastError().

See also the full documentation at https://ramses-logic.readthedocs.io/en/latest/api.html for more details on Lua and its interaction with C++.

Public Functions

internal::LuaScriptImpl &impl()

Get the internal data for implementation specifics of LuaScript.

const internal::LuaScriptImpl &impl() const

Get the internal data for implementation specifics of LuaScript.

class MeshNodeBinding : public ramses::RamsesBinding

#include <MeshNodeBinding.h>

The MeshNodeBinding binds to a Ramses object instance of ramses::MeshNode and exposes a set of input properties allowing to control certain states of the MeshNode.

MeshNodeBinding has these input properties: ‘vertexOffset’ (type int32)

• binds to MeshNode’s vertex offset, i.e. start offset into vertex arrays of the mesh (ramses::MeshNode::setStartVertex). ‘indexOffset’ (type int32)

• binds to MeshNode’s index offset, i.e. start offset into indices of the mesh (ramses::MeshNode::setStartIndex). ‘indexCount’ (type int32)

• binds to MeshNode’s index count, i.e. number of indices to use for rendering of the mesh (ramses::MeshNode::setIndexCount). ‘instanceCount’ (type int32)

• binds to MeshNode’s instance count, i.e. number of instances to render when using geometry instancing (ramses::MeshNode::setInstanceCount).

The initial values of the input properties are taken from the bound ramses::MeshNode when the MeshNodeBinding is created.

The MeshNodeBinding class has no output properties (thus ramses::LogicNode::getOutputs() will return nullptr) because the outputs are implicitly forwarded to the bound ramses::MeshNode.

The changes via binding objects are applied to the bound object right away when calling ramses::LogicEngine::update(), however keep in mind that Ramses has a mechanism for bundling scene changes and applying them at once using ramses::Scene::flush, so the changes will be applied all the way only after calling this method on the scene.

Public Functions

const ramses::MeshNode &getRamsesMeshNode() const

Returns the bound Ramses MeshNode.

Returns:

the bound Ramses MeshNode

ramses::MeshNode &getRamsesMeshNode()

Returns the bound Ramses MeshNode.

Returns:

the bound Ramses MeshNode

internal::MeshNodeBindingImpl &impl()

Get the internal data for implementation specifics of MeshNodeBinding.

const internal::MeshNodeBindingImpl &impl() const

Get the internal data for implementation specifics of MeshNodeBinding.

class NodeBinding : public ramses::RamsesBinding

#include <NodeBinding.h>

The NodeBinding is a ramses::RamsesBinding which allows manipulation of a Ramses node. NodeBinding can be created using ramses::LogicEngine::createNodeBinding.

The NodeBinding has a fixed set of inputs which correspond to the properties of a ramses::Node: ‘visibility’ (type bool) - binds to node’s visibility mode to switch between visible and invisible, see also ‘enabled’ input for more options ‘rotation’ (type vec3f, or vec4f in case of quaternion) - binds to node’s rotation, a vec3f represents the Euler angles v[0]:x, v[1]:y, v[2]:z a vec4f represents a quaternion with v[0]:x, v[1]:y, v[2]:z containing the quaternion’s vector component and v[3]:w the quaternion’s scalar component ‘translation’ (type vec3f) - binds to node’s translation ‘scaling’ (type vec3f) - binds to node’s scaling ‘enabled’ (type bool) - binds to node’s visibility mode to be able to switch node to off mode (see ramses::EVisibilityMode). When ‘enabled’ is true (default) the visibility mode is determined by the ‘visibility’ input above. When ‘enabled’ is false, the visibility mode is Off, regardless of the ‘visibility’ input.

The default values of the input properties are taken from the bound ramses::Node provided during construction. This also applies to rotations, if the ramses::ERotationType values of the ramses node match (both are either Quaternion or Euler with the same axis ordering). Otherwise a warning is issued and the rotation values are set to 0.

The NodeBinding class has no output properties (thus getOutputs() will return nullptr) because the outputs are implicitly the properties of the bound Ramses node.

The changes via binding objects are applied to the bound object right away when calling ramses::LogicEngine::update(), however keep in mind that Ramses has a mechanism for bundling scene changes and applying them at once using ramses::Scene::flush, so the changes will be applied all the way only after calling this method on the scene.

Note

Not all states of the #ramses::Node must be managed via #NodeBinding, input properties which are not modified via #NodeBinding (i.e. user never set a value explicitly nor linked the input) will not alter the corresponding Ramses object state. This allows the user code to control some states via Ramses logic nodes and some directly using Ramses object.

Public Functions

ramses::Node &getRamsesNode() const

Returns the bound ramses node.

Returns:

the bound ramses node

ramses::ERotationType getRotationType() const

Returns the statically configured rotation type for the node rotation property.

Returns:

the currently used rotation type

internal::NodeBindingImpl &impl()

Get the internal data for implementation specifics of NodeBinding.

const internal::NodeBindingImpl &impl() const

Get the internal data for implementation specifics of NodeBinding.

class Property

#include <Property.h>

Represents a generic property slot of the ramses::LogicNode and its derived classes. Properties can have primitive types (string, integer, etc.) or complex types (structs, arrays). Complex types can have “children”, i.e. nested properties: named fields (structs), or indexed fields (arrays).

Public Functions

EPropertyType getType() const

Returns the type of this Property

Returns:

the type of this Property

std::string_view getName() const

Returns the name of this Property. Note that not all properties have a name - for example an array element does not have a name. In that case the result will be an empty string view. Struct fields always have a non-empty name.

Returns:

the name of this Property

size_t getChildCount() const

Returns the amount of available child (nested) properties. If the Property is of type ramses::EPropertyType::Struct, the returned number will correspond to the number of named properties of the struct. If the Property is of type ramses::EPropertyType::Array, the method will return the array size. For all other property types getChildCount returns zero.

Returns:

the number of nested properties.

bool hasChild(std::string_view name) const

Return whether the ramses::Property has a child with the given name

Parameters:

name – the name of the child that should be checked for existence

Returns:

whether the child with the given name exists

const Property *getChild(size_t index) const

Returns the child property with the given index. index must be < getChildCount().

This method can be used to get nested properties of structs and arrays. For primitive types this will always return nullptr.

Note that array indexing in getChild follows C++ conventions and not Lua conventions! Inside the Lua scripts, you can and must use Lua conventions when indexing arrays (start at 1, end at N) while in C++ you must use [0, N-1].

Struct properties can also be retrieved by index. The ordering is not guaranteed to match the order of declaration inside Lua scripts (Lua explicitly warns to not rely on ordering of named table entries!). However, once a script is created, the index will not change, i.e. it is permitted that user code caches the property index for faster future access.

Parameters:

index – [in] zero based index of child property to retrieve

Returns:

the child with the given index, or nullptr if the property is primitive or the index is out of range

Property *getChild(size_t index)

Returns the child property with the given index. index must be < getChildCount().

This method can be used to get nested properties of structs and arrays. For primitive types this will always return nullptr.

Note that array indexing in getChild follows C++ conventions and not Lua conventions! Inside the Lua scripts, you can and must use Lua conventions when indexing arrays (start at 1, end at N) while in C++ you must use [0, N-1].

Struct properties can also be retrieved by index. The ordering is not guaranteed to match the order of declaration inside Lua scripts (Lua explicitly warns to not rely on ordering of named table entries!). However, once a script is created, the index will not change, i.e. it is permitted that user code caches the property index for faster future access.

Parameters:

index – [in] zero based index of child property to retrieve

Returns:

the child with the given index, or nullptr if the property is primitive or the index is out of range

Property *getChild(std::string_view name)

Searches for a child with the given name. Only properties of type ramses::EPropertyType::Struct can return a child by name. In case of a primitive property or array this method will return nullptr.

Note that this method may be slower than getChild(size_t index) as it must do a string-based search.

Parameters:

name – [in] name of child property to retrieve

Returns:

the child with the given name, or nullptr if property is not of type ramses::EPropertyType::Struct

const Property *getChild(std::string_view name) const

Searches for a child with the given name. Only properties of type ramses::EPropertyType::Struct can return a child by name. In case of a primitive property or array this method will return nullptr.

Note that this method may be slower than getChild(size_t index) as it must do a string-based search.

Parameters:

name – [in] name of child property to retrieve

Returns:

the child with the given name, or nullptr if property is not of type ramses::EPropertyType::Struct

template<typename T>
std::optional<T> get() const

Returns the value of this property. The supported template types are defined by ramses::IsPrimitiveProperty where IsPrimitiveProperty<T>::value == true for a type T.

Attention! We recommend always specifying the template argument T explicitly, and don’t rely on the compiler’s type deduction! If T is not one of the supported types, a static_assert will be triggered!

Returns nullopt if the template type T does not match the internal type of the property.

Returns:

the value of this Property as std::optional or std::nullopt if T does not match.

template<typename T>
bool set(T value)

Sets the value of this Property. Same rules apply to template parameter T as in get()

Attention! We recommend always specifying the template argument T explicitly, and don’t rely on the compiler’s type deduction! If T is not one of the supported types, a static_assert will be triggered!

set() will report an error if the Property is linked. Use hasIncomingLink() to check in advance.

Parameters:

value – the value to set for this Property

Returns:

true if setting the value was successful, false otherwise.

bool isLinked() const

Checks if this property is linked to a property of another node.

Property can be either on inputs side or outputs side of a node (or both in case of ramses::LuaInterface), which defines what type of link is applicable - an incoming or outgoing. This query checks for any links, regardless of data flow direction. See hasIncomingLink() hasOutgoingLink() for dedicated checks

Returns:

true if the property is linked, false otherwise.

bool hasIncomingLink() const

Checks if there is any incoming link to this property, i.e. data is flowing to it from another node’s property. There can be only one incoming link per input property.

Returns:

true if the property is an input and is linked, false otherwise.

bool hasOutgoingLink() const

Checks if there is any outgoing link from this property, i.e. data is flowing from it to another node’s property. There can be multiple outgoing links per output property.

Returns:

true if the property is an output and is linked, false otherwise.

std::optional<PropertyLinkConst> getIncomingLink() const

Returns information about the incoming link to this property, namely which property is the source of the link. Only certain properties can have an incoming link, see ramses::LogicEngine::link for details.

Returns:

incoming link data or std::nullopt if there is no link.

std::optional<PropertyLink> getIncomingLink()

Returns information about the incoming link to this property, namely which property is the source of the link. Only certain properties can have an incoming link, see ramses::LogicEngine::link for details.

Returns:

incoming link data or std::nullopt if there is no link.

size_t getOutgoingLinksCount() const

Returns the number of outgoing links from this property. Only certain properties can have outgoing links, see ramses::LogicEngine::link for details.

Returns:

number of outgoing links from this property.

std::optional<PropertyLinkConst> getOutgoingLink(size_t index) const

Returns information about the outgoing link from this property, namely which property is the target of the link with given index. Use getOutgoingLinksCount to query how many outgoing links there are. Only certain properties can have outgoing links, see ramses::LogicEngine::link for details.

Parameters:

index – [in] zero based index of outgoing link to retrieve

Returns:

outgoing link data or std::nullopt if there is no link with given index.

std::optional<PropertyLink> getOutgoingLink(size_t index)

Returns information about the outgoing link from this property, namely which property is the target of the link with given index. Use getOutgoingLinksCount to query how many outgoing links there are. Only certain properties can have outgoing links, see ramses::LogicEngine::link for details.

Parameters:

index – [in] zero based index of outgoing link to retrieve

Returns:

outgoing link data or std::nullopt if there is no link with given index.

const LogicNode &getOwningLogicNode() const

Get ramses::LogicNode that owns this property. Every property is owned by a ramses::LogicNode and represents either its input or output.

Returns:

ramses::LogicNode that owns this property.

LogicNode &getOwningLogicNode()

Get ramses::LogicNode that owns this property. Every property is owned by a ramses::LogicNode and represents either its input or output.

Returns:

ramses::LogicNode that owns this property.

internal::PropertyImpl &impl()

Get the internal data for implementation specifics of Property.

const internal::PropertyImpl &impl() const

Get the internal data for implementation specifics of Property.

Property(const Property &other) = delete

Copy Constructor of Property is deleted because properties are not supposed to be copied

Parameters:

other – property to copy from

Property(Property &&other) = delete

Move Constructor of Property is deleted because properties are not supposed to be moved

Parameters:

other – property to move from

Property &operator=(const Property &other) = delete

Assignment operator of Property is deleted because properties are not supposed to be copied

Parameters:

other – property to assign from

Property &operator=(Property &&other) = delete

Move assignment operator of Property is deleted because properties are not supposed to be moved

Parameters:

other – property to move from

struct PropertyLink

#include <PropertyLink.h>

PropertyLink describes a data link between two properties, each belonging to a ramses::LogicNode. Data flows always from source (some ramses::LogicNode’s output) to target (another ramses::LogicNode’s input), see ramses::LogicEngine::link and ramses::LogicEngine::update for more details. PropertLink can be obtained using ramses::Property::getIncomingLink, ramses::Property::getOutgoingLink or ramses::LogicEngine::getPropertyLinks.

Public Members

Property *source = nullptr

data flow source (some ramses::LogicNode’s output)

Property *target = nullptr

data flow target (another ramses::LogicNode’s input)

bool isWeakLink = false

true if this is a weak link - see ramses::LogicEngine::linkWeak

class RamsesBinding : public ramses::LogicNode

#include <RamsesBinding.h>

RamsesBinding is a shared base class for bindings to Ramses objects. For details on each type of binding, look at the derived classes.

Subclassed by ramses::AppearanceBinding, ramses::CameraBinding, ramses::MeshNodeBinding, ramses::NodeBinding, ramses::RenderBufferBinding, ramses::RenderGroupBinding, ramses::RenderPassBinding, ramses::SkinBinding

class RenderBufferBinding : public ramses::RamsesBinding

#include <RenderBufferBinding.h>

RenderBufferBinding binds to a Ramses object instance of ramses::RenderBuffer and exposes a set of input properties allowing to change some parameters of ramses::RenderBuffer.

Important note: ramses::RenderBuffer (unlike most other scene objects that can be bound to logic node network) is a static object in the sense that once it is allocated on Ramses renderer side it cannot be changed. This means that RenderBufferBinding can be effectively used to change properties only BEFORE the render buffer is allocated on renderer (concretely before the scene is in state ramses::RendererSceneState::Ready). Note that changing its properties after this moment will not produce any API or runtime errors but renderer will ignore them and log an error. It is recommended to study the RenderBufferBinding example before using it.

RenderBufferBinding has these input properties: ‘width’ (type int32)

• binds to RenderBuffer’s resolution width, overwriting the one which was used when creating it. ‘height’ (type int32)

• binds to RenderBuffer’s resolution height, overwriting the one which was used when creating it. ‘sampleCount’ (type int32)

• binds to RenderBuffer’s sample count used for multisampling, overwriting the one which was used when creating it.

The initial values of the input properties are taken from the bound ramses::RenderBuffer.

The RenderBufferBinding class has no output properties (thus ramses::LogicNode::getOutputs() will return nullptr) because the outputs are implicitly forwarded to the bound ramses::RenderBuffer.

The changes via binding objects are applied to the bound object right away when calling ramses::LogicEngine::update, however keep in mind that Ramses has a mechanism for bundling scene changes and applying them at once using ramses::Scene::flush, so the changes will be applied all the way only after calling this method on the scene.

Possible errors:

• ramses::LogicEngine::update will fail to update RenderBufferBinding if:

  • any input negative

  • ’width’ or ‘height’ is zero

• ramses::Scene::flush can fail as a result of changing ramses::RenderBuffer parameters in ramses::Scene:

  • if ramses::RenderBuffer is used in a ramses::RenderTarget and becomes not compatible (different size or sample count) with other buffers in that render target

  • if ramses::RenderBuffer is used as source/destination in a ramses::BlitPass and becomes out of bounds for the pass’s blitting region

• renderer will produce an error log if a ramses::RenderBuffer change comes after it was already allocated (see above for details)

Public Functions

const ramses::RenderBuffer &getRenderBuffer() const

Returns the bound ramses::RenderBuffer.

Returns:

the bound ramses::RenderBuffer

ramses::RenderBuffer &getRenderBuffer()

Returns the bound ramses::RenderBuffer.

Returns:

the bound ramses::RenderBuffer

internal::RenderBufferBindingImpl &impl()

Get the internal data for implementation specifics of RenderBufferBinding.

const internal::RenderBufferBindingImpl &impl() const

Get the internal data for implementation specifics of RenderBufferBinding.

class RenderGroupBinding : public ramses::RamsesBinding

#include <RenderGroupBinding.h>

RenderGroupBinding binds to a Ramses object instance of ramses::RenderGroup. RenderGroupBinding allows controlling the rendering order of selected elements contained in the ramses::RenderGroup - these can be ramses::MeshNode and other (nested) ramses::RenderGroup objects.

RenderGroupBinding is initialized with a ramses::RenderGroup and a set of elements to expose for render order control through the binding’s input properties. Not all the elements contained in the ramses::RenderGroup have to be provided, the binding can be used to control only a subset of the elements in the render group. The set of provided elements is then static for the lifetime of the RenderGroupBinding.

It is not possible to add or remove elements from the bound ramses::RenderGroup using this binding and this binding will not reflect changes made to the ramses::RenderGroup via its Ramses API. Therefore it is important to keep the binding valid with respect to the ramses::RenderGroup it is bound to, for example:

• An element is added to the bound ramses::RenderGroup via Ramses API - the binding with its elements is valid and can be used but the newly added element will not be known to it (cannot control its render order).

• An element is removed from the bound ramses::RenderGroup via Ramses API - if the removed element was part of the provided initial set at construction of the binding, the binding is invalidated and should not be used because any attempt to change render order of the removed element will result in update fail. If RenderGroupBinding gets invalidated it needs to be destroyed and recreated with a valid set of elements contained in the render group. In this case property links (if any) get destroyed with the binding and need to be re-created.

When RenderGroupBinding is created using ramses::LogicEngine::createRenderGroupBinding it will create property inputs based on the provided set of elements (see ramses::RenderGroupBindingElements): ‘renderOrders’ (type struct) - contains all the elements provided as children: [element1Name] (type int32) - binds to render order of that element within the bound ramses::RenderGroup … [elementNName] (type int32) The property name for each element can be specified when adding the element using ramses::RenderGroupBindingElements::addElement. Note that the order of the render order input properties exactly matches the order of adding elements via ramses::RenderGroupBindingElements::addElement.

The render order is directly forwarded to Ramses and follows Ramses behavior of ordering, i.e. element with lower render order value gets rendered before element with higher value. If two elements have same number (default) their render order is not defined and the Ramses renderer decides their order based on its optimization criteria, it is therefore recommended to explicitly specify render order only if needed.

The initial render order values of the input properties are taken from the bound ramses::RenderGroup’s elements provided during construction.

The RenderGroupBinding class has no output properties (thus ramses::LogicNode::getOutputs() will return nullptr) because the outputs are implicitly forwarded to the bound ramses::RenderGroup.

The changes via binding objects are applied to the bound object right away when calling ramses::LogicEngine::update(), however keep in mind that Ramses has a mechanism for bundling scene changes and applying them at once using ramses::Scene::flush, so the changes will be applied all the way only after calling this method on the scene.

Public Functions

const ramses::RenderGroup &getRamsesRenderGroup() const

Returns the bound ramses render group.

Returns:

the bound ramses render group

ramses::RenderGroup &getRamsesRenderGroup()

Returns the bound ramses render group.

Returns:

the bound ramses render group

internal::RenderGroupBindingImpl &impl()

Get the internal data for implementation specifics of RenderGroupBinding.

const internal::RenderGroupBindingImpl &impl() const

Get the internal data for implementation specifics of RenderGroupBinding.

class RenderGroupBindingElements

#include <RenderGroupBindingElements.h>

RenderGroupBindingElements is a helper class holding a set of references to elements to be provided when constructing ramses::RenderGroupBinding. These elements are either ramses::MeshNode or ramses::RenderGroup.

Note that ramses::RenderGroup can contain other (nested) ramses::RenderGroup objects, in such case the parent ramses::RenderGroup corresponds to the ramses::RenderGroupBinding to be created and the nested ramses::RenderGroup is the element provided here.

Public Functions

RenderGroupBindingElements() noexcept

Constructor of RenderGroupBindingElements.

~RenderGroupBindingElements() noexcept

Destructor of RenderGroupBindingElements.

RenderGroupBindingElements(const RenderGroupBindingElements &other)

Copy constructor.

RenderGroupBindingElements(RenderGroupBindingElements &&other) noexcept

Move constructor.

RenderGroupBindingElements &operator=(const RenderGroupBindingElements &other)

Assignment operator.

RenderGroupBindingElements &operator=(RenderGroupBindingElements &&other) noexcept

Move assignment operator.

bool addElement(const ramses::MeshNode &meshNode, std::string_view elementName = {})

Add ramses::MeshNode element to control its render order when provided to ramses::RenderGroupBinding. Will fail if given element is already contained.

Parameters:

• meshNode – ramses::MeshNode element to add to be exposed for render order control.

• elementName – This name will be used to name the input property in the created ramses::RenderGroupBinding. If none provided, name of the ramses::MeshNode will be used.

Returns:

true if successful, false otherwise.

bool addElement(const ramses::RenderGroup &nestedRenderGroup, std::string_view elementName = {})

Add ramses::RenderGroup element to control its render order when provided to ramses::RenderGroupBinding. Will fail if given element is already contained.

Parameters:

• nestedRenderGroup – ramses::RenderGroup element to add to be exposed for render order control.

• elementName – This name will be used to name the input property in the created ramses::RenderGroupBinding. If none provided, name of the ramses::RenderGroup will be used.

Returns:

true if successful, false otherwise.

internal::RenderGroupBindingElementsImpl &impl()

Get the internal data for implementation specifics of RenderGroupBindingElements.

const internal::RenderGroupBindingElementsImpl &impl() const

Get the internal data for implementation specifics of RenderGroupBindingElements.

class RenderPassBinding : public ramses::RamsesBinding

#include <RenderPassBinding.h>

RenderPassBinding binds to a Ramses object instance like other types derived from ramses::RamsesBinding, in this case it binds to a ramses::RenderPass. RenderPassBinding can be created using ramses::LogicEngine::createRenderPassBinding after providing an instance of a ramses::RenderPass.

The RenderPassBinding has a fixed set of inputs which correspond to some of the parameters in ramses::RenderPass: ‘enabled’ (type bool) - binds to enable/disable state (see ramses::RenderPass::setEnabled) ‘renderOrder’ (type int32) - binds to render order (see ramses::RenderPass::setRenderOrder) ‘clearColor’ (type vec4f) - binds to color used when clearing render pass (see ramses::RenderPass::setClearColor) ‘renderOnce’ (type bool) - binds to render once on/off state (see ramses::RenderPass::setRenderOnce)

The initial values of the input properties are taken from the bound ramses::RenderPass provided during construction.

The RenderPassBinding class has no output properties (thus ramses::LogicNode::getOutputs() will return nullptr) because the outputs are implicitly the properties of the bound ramses::RenderPass.

The changes via binding objects are applied to the bound object right away when calling ramses::LogicEngine::update(), however keep in mind that Ramses has a mechanism for bundling scene changes and applying them at once using ramses::Scene::flush, so the changes will be applied all the way only after calling this method on the scene.

Note

Not all states of the #ramses::RenderPass must be managed via #RenderPassBinding, input properties which are not modified via #RenderPassBinding (i.e. user never set a value explicitly nor linked the input) will not alter the corresponding Ramses object state. This allows the user code to control some states via Ramses logic nodes and some directly using Ramses object.

Public Functions

const ramses::RenderPass &getRamsesRenderPass() const

Returns the bound ramses render pass.

Returns:

the bound ramses render pass

ramses::RenderPass &getRamsesRenderPass()

Returns the bound ramses render pass.

Returns:

the bound ramses render pass

internal::RenderPassBindingImpl &impl()

Get the internal data for implementation specifics of RenderPassBinding.

const internal::RenderPassBindingImpl &impl() const

Get the internal data for implementation specifics of RenderPassBinding.

class SkinBinding : public ramses::RamsesBinding

#include <SkinBinding.h>

SkinBinding is a special kind of binding which holds all the data needed to calculate vertex skinning matrices which are then set on every update to the bound appearance using the provided uniform input. The data required for vertex skinning are:

• joint nodes (also referred to as skeleton nodes) - these are transformation nodes which are typically animated as part of the skeleton structure.

• inverse bind matrices - inverse transformation matrix for each joint node, these are static for the lifecycle of the SkinBinding.

• ramses::AppearanceBinding - binds to ramses::Appearance with an ramses::Effect specifying a vertex shader which is expected to apply the final stage of vertex skinning calculation using the joint matrices calculated in this SkinBinding.

• ramses::UniformInput - specifies a vertex shader input (interface to the shader) where the joint matrices are expected. For more details on how this data is used please see the GLTF Skins tutorial https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_020_Skins.md the GLTF specification was used as reference for the SkinBinding implementation in expectation to support most skinning use cases.

Even though the SkinBinding is a ramses::LogicNode it does not have any input nor output properties. The joint matrices (output data) are internally passed to the ramses::Appearance and are therefore not exposed as output properties. Also all the input data described above is statically referenced and not exposed as input properties.

Performance remark: Unlike other logic nodes SkinBinding does not use dirtiness mechanism monitoring the input data which then calculates the output data only if anything changed. SkinBinding depends on Ramses nodes which cannot be easily monitored and therefore it has to be updated every time ramses::LogicEngine::update is called. For this reason it is highly recommended to keep the number of SkinBindings to a necessary minimum.

The changes via binding objects are applied to the bound objects right away when calling ramses::LogicEngine::update(), however keep in mind that Ramses has a mechanism for bundling scene changes and applying them at once using ramses::Scene::flush, so the changes will be applied all the way only after calling this method on the ramses scene.

Public Functions

const AppearanceBinding &getAppearanceBinding() const

Returns the appearance binding that this skin is bound to.

Returns:

the appearance binding that this skin is bound to

const ramses::UniformInput &getAppearanceUniformInput() const

Returns the uniform input used to set joint matrices to the bound appearance.

Returns:

the uniform input used to set joint matrices to the bound appearance

internal::SkinBindingImpl &impl()

Get the internal data for implementation specifics of SkinBinding.

const internal::SkinBindingImpl &impl() const

Get the internal data for implementation specifics of SkinBinding.

class TimerNode : public ramses::LogicNode

#include <TimerNode.h>

Timer node can be used to provide timing information to animation nodes (ramses::AnimationNode) or any other logic nodes.

• Property inputs:

  • ticker_us (int64) - (optional) user provided ticker in microseconds (by default, see below to learn how to use arbitrary time units).

    • if the input is 0 (default) then this TimerNode uses system clock to generate ticker by itself, this is recommended for simple use cases when application does not need more advanced timing control.

• Property outputs:

  • ticker_us (int64) - in auto-generate mode (‘ticker_us’ input stays 0) this will output system clock time since epoch in microseconds

    • in case of user provided ticker (non-zero ‘ticker_us’ input) this output will contain the same value (user ticker is just passed through, this way time units are user defined).

Timer node works in one of two modes - it generates ticker by itself or uses user provided ticker. This allows quick and easy switch between stages of the development, e.g. prototyping, testing or production, where for some use cases auto-generated time is desired and other require well specified timing provided by application. Due to the auto-generate mode both the input and output has defined time units, however timer node can also be used in a fully time unit agnostic mode, see inputs/outputs description above for details. Note that unlike other logic nodes a TimerNode is always updated on every ramses::LogicEngine::update call regardless of if any of its inputs were modified or not.

Public Functions

internal::TimerNodeImpl &impl()

Get the internal data for implementation specifics of TimerNode.

const internal::TimerNodeImpl &impl() const

Get the internal data for implementation specifics of TimerNode.