ramses 28.0.0

CMakeLists.txt

@@ -11,7 +11,7 @@ CMAKE_MINIMUM_REQUIRED(VERSION 3.13)
 set(RAMSES_VERSION_MAJOR 28)
 set(RAMSES_VERSION_MINOR 0)
 set(RAMSES_VERSION_PATCH 0)
-set(RAMSES_VERSION_POSTFIX "-rc5")
+set(RAMSES_VERSION_POSTFIX "")
 set(RAMSES_VERSION "${RAMSES_VERSION_MAJOR}.${RAMSES_VERSION_MINOR}.${RAMSES_VERSION_PATCH}${RAMSES_VERSION_POSTFIX}")
 
 project(ramses-sdk

doc/sphinx/classes/index.rst

@@ -1,6 +1,6 @@
 ..
     -------------------------------------------------------------------------
-    Copyright (C) 2021 BMW AG
+    Copyright (C) 2023 BMW AG
     -------------------------------------------------------------------------
     This Source Code Form is subject to the terms of the Mozilla Public
     License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -35,11 +35,9 @@ Class Index
 
     logic
 
-
 .. toctree::
     :maxdepth: 3
     :caption: Ramses Utils
 
     utils
 
-

doc/sphinx/viewer.rst

@@ -105,28 +105,47 @@ Options
 Lua configuration API
 ==============================================
 
-The :program:`ramses-viewer` exposes a lua module ``rlogic`` that allows to interact with the viewer's
-logic engine instance. ``rlogic`` mimics the Ramses Logic C++ API and provides some extra interfaces to take
-screenshots and define interactive views.
+The :program:`ramses-viewer` exposes a lua module ``R`` that allows to interact with the scene's
+logic engine instance(s). It also provides interfaces to take screenshots and define interactive views.
 
 --------------------------------------------------
-Logic Nodes
+Logic Engine
 --------------------------------------------------
 
-The module ``rlogic`` provides members to access all Logic Node types:
-
-* ``rlogic.interfaces`` (:cpp:class:`ramses::LuaInterface`)
-* ``rlogic.scripts`` (:cpp:class:`ramses::LuaScript`)
-* ``rlogic.animationNodes`` (:cpp:class:`ramses::AnimationNode`)
-* ``rlogic.timerNodes`` (:cpp:class:`ramses::TimerNode`)
-* ``rlogic.nodeBindings`` (:cpp:class:`ramses::NodeBinding`)
-* ``rlogic.appearanceBindings`` (:cpp:class:`ramses::AppearanceBinding`)
-* ``rlogic.cameraBindings`` (:cpp:class:`ramses::CameraBinding`)
-* ``rlogic.renderPassBindings`` (:cpp:class:`ramses::RenderPassBinding`)
-* ``rlogic.renderGroupBindings`` (:cpp:class:`ramses::RenderGroupBinding`)
-* ``rlogic.meshNodeBindings`` (:cpp:class:`ramses::MeshNodeBinding`)
-* ``rlogic.anchorPoints`` (:cpp:class:`ramses::AnchorPoint`)
-* ``rlogic.skinBindings`` (:cpp:class:`ramses::SkinBinding`)
+``R.logic`` provides access to the scene's logic engines. They can be found by name or scene object id.
+Alternatively all logic engine instances can be returned.
+
+Example:
+
+.. code-block:: lua
+
+    -- returns all LogicEngines (also convenient if there's only 1 logic engine)
+    -- there's no guarantee for a specific order
+    engine0, engine1 = R.logic()
+
+    -- returns the LogicEngine with the name `foo` or nil if it does not exist
+    R.logic["foo"]
+
+    -- returns the LogicEngine with the scene object id `42` or nil if it does not exist
+    R.logic[42]
+
+Logic Nodes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Logic Engine object has members to access all Logic Node types:
+
+* ``R.logic().interfaces`` (:cpp:class:`ramses::LuaInterface`)
+* ``R.logic().scripts`` (:cpp:class:`ramses::LuaScript`)
+* ``R.logic().animationNodes`` (:cpp:class:`ramses::AnimationNode`)
+* ``R.logic().timerNodes`` (:cpp:class:`ramses::TimerNode`)
+* ``R.logic().nodeBindings`` (:cpp:class:`ramses::NodeBinding`)
+* ``R.logic().appearanceBindings`` (:cpp:class:`ramses::AppearanceBinding`)
+* ``R.logic().cameraBindings`` (:cpp:class:`ramses::CameraBinding`)
+* ``R.logic().renderPassBindings`` (:cpp:class:`ramses::RenderPassBinding`)
+* ``R.logic().renderGroupBindings`` (:cpp:class:`ramses::RenderGroupBinding`)
+* ``R.logic().meshNodeBindings`` (:cpp:class:`ramses::MeshNodeBinding`)
+* ``R.logic().anchorPoints`` (:cpp:class:`ramses::AnchorPoint`)
+* ``R.logic().skinBindings`` (:cpp:class:`ramses::SkinBinding`)
 
 The Logic Node instances can be either found by name or by object id.
 Alternatively the node list can be iterated.
@@ -136,26 +155,26 @@ Example:
 .. code-block:: lua
 
     -- returns the LuaScript node with the name `foo` or nil if it does not exist
-    rlogic.scripts.foo
+    R.logic().scripts.foo
 
     -- returns the LuaScript node with the object id `42` or nil if it does not exist
-    rlogic.scripts[42]
+    R.logic().scripts[42]
 
     -- returns the LuaScript node with the name `name with spaces` or nil if it does not exist
-    rlogic.scripts["name with spaces"]
+    R.logic().scripts["name with spaces"]
 
     -- iterates through all LuaScript instances
-    for script in rlogic.scripts() do
+    for script in R.logic().scripts() do
         print(script)
     end
 
 .. note::
-    Ramses Logic does not guarantee unique names.
+    Ramses does not guarantee unique names.
     Also empty names are possible.
 
---------------------------------------------------
+
 Logic Properties
---------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Logic Nodes own Logic Properties. They are accessed like this:
 
@@ -167,25 +186,42 @@ Example:
 
 .. code-block:: lua
 
-    rlogic.scripts.foo.IN.integerProperty.value = 6
-    rlogic.scripts.foo.IN.stringProperty.value = "Hello World"
-    rlogic.scripts.foo.IN.structProperty.vec3iChild.value = { 42, 44, 0 }
-    rlogic.scripts.foo.IN.arrayProperty[1].integerChild.value = 5
+    R.logic().scripts.foo.IN.integerProperty.value = 6
+    R.logic().scripts.foo.IN.stringProperty.value = "Hello World"
+    R.logic().scripts.foo.IN.structProperty.vec3iChild.value = { 42, 44, 0 }
+    R.logic().scripts.foo.IN.arrayProperty[1].integerChild.value = 5
 
     -- returns the property's value
-    rlogic.scripts.foo.IN.integerProperty.value
+    R.logic().scripts.foo.IN.integerProperty.value
     -- returns the property object
-    rlogic.scripts.foo.IN.integerProperty
+    R.logic().scripts.foo.IN.integerProperty
 
 .. note::
     Properties can be readonly if they are output properties or linked to an output property.
     Trying to set values to them will cause a runtime error.
 
+
+Logic Engine Update
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The logic engine is automatically updated (:cpp:func:`ramses::LogicEngine::update()`) before
+a new frame is drawn or before a screenshot is stored.
+In batch mode (:option:`ramses-viewer --exec` :option:`ramses-viewer --exec-lua`) it's sometimes useful to explicitly update
+the logic engine state by calling ``R.logic().update()``:
+
+.. code-block:: lua
+
+    R.logic().scripts.foo.IN.color.value = "red"
+    R.logic().update()
+    if not R.logic().scripts.foo.OUT.color.value == {255, 0, 0} then
+        error("unexpected value")
+    end
+
 --------------------------------------------------
 Views
 --------------------------------------------------
 
-``rlogic.views`` can be used to demonstrate typical scene configurations to the user.
+``R.views`` can be used to demonstrate typical scene configurations to the user.
 If the lua script defines views, the user can simply switch between them in the UI
 and does not need to know how to configure all the corresponding properties.
 
@@ -235,41 +271,24 @@ Example:
     }
 
     -- assigns the view list
-    rlogic.views = {simpleView, animatedView, interactiveView}
+    R.views = {simpleView, animatedView, interactiveView}
 
 --------------------------------------------------
 Screenshots
 --------------------------------------------------
 
-Screenshots can be taken by the ``rlogic.screenshot(filename)`` function.
+Screenshots can be taken by the ``R.screenshot(filename)`` function.
 The :program:`ramses-viewer` will implicitly update the logic state before.
 
 .. code-block:: lua
 
-    rlogic.scripts.foo.IN.color.value = "red"
-    rlogic.screenshot(foo_red.png)
-    rlogic.scripts.foo.IN.color.value = "green"
-    rlogic.screenshot(foo_green.png)
+    R.logic().scripts.foo.IN.color.value = "red"
+    R.screenshot(foo_red.png)
+    R.logic().scripts.foo.IN.color.value = "green"
+    R.screenshot(foo_green.png)
 
 .. note::
 
     To exclude the Viewer's UI from the screenshot you can set the :option:`ramses-viewer --gui` to either `on` or `off`.
     In `on` mode the Viewer creates an offscreen buffer for the scene.
     That's why the screenshot's size is independent of the window size and does not contain the Viewer's UI.
-
---------------------------------------------------
-Logic Engine Update
---------------------------------------------------
-
-The logic engine is automatically updated (:cpp:func:`ramses::LogicEngine::update()`) before
-a new frame is drawn or before a screenshot is stored.
-In batch mode (:option:`ramses-viewer --exec` :option:`ramses-viewer --exec-lua`) it's sometimes useful to explicitly update
-the logic engine state by calling ``rlogic.update()``:
-
-.. code-block:: lua
-
-    rlogic.scripts.foo.IN.color.value = "red"
-    rlogic.update()
-    if not rlogic.scripts.foo.OUT.color.value == {255, 0, 0} then
-        error("unexpected value")
-    end

external/CMakeLists.txt

@@ -313,6 +313,11 @@ if(ramses-sdk_BUILD_TOOLS)
                                 imgui/*.cpp
                                 imgui/misc/cpp/*.cpp
         )
+
+    add_executable(imgui_binary_to_compressed EXCLUDE_FROM_ALL
+        imgui/misc/fonts/binary_to_compressed_c.cpp
+        )
+    folderizeTarget(imgui_binary_to_compressed)
 endif()
 
 

include/ramses/client/ArrayBuffer.h

@@ -1,5 +1,5 @@
 //  -------------------------------------------------------------------------
-//  Copyright (C) 2017 BMW Car IT GmbH
+//  Copyright (C) 2023 BMW AG
 //  -------------------------------------------------------------------------
 //  This Source Code Form is subject to the terms of the Mozilla Public
 //  License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -20,14 +20,14 @@ namespace ramses
     }
 
     /**
-     * @ingroup CoreAPI
      * @brief The ArrayBuffer is a data object used to provide vertex or index data to #ramses::Geometry::setInputBuffer
      *        and #ramses::Geometry::setIndices. The buffer data of an ArrayBuffer is not filled initially and can be fully
-     *        or partially updated in between scene flushes.
+     *        or partially updated between scene flushes.
      *
      * @details If an #ArrayBuffer object is created with type #ramses::EDataType::ByteBlob then an element
      *          is defined as one byte, rather than a logical vertex element. Hence, all functions of #ArrayBuffer
      *          referring to element refer to a single byte within byte array.
+     * @ingroup CoreAPI
      */
     class RAMSES_API ArrayBuffer : public SceneObject
     {

include/ramses/client/ArrayResource.h

@@ -1,5 +1,5 @@
 //  -------------------------------------------------------------------------
-//  Copyright (C) 2020 BMW AG
+//  Copyright (C) 2023 BMW AG
 //  -------------------------------------------------------------------------
 //  This Source Code Form is subject to the terms of the Mozilla Public
 //  License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -19,13 +19,13 @@ namespace ramses
     }
 
     /**
-    * @ingroup CoreAPI
     * @brief The #ArrayResource stores a data array of a given type. The data is immutable.
-    *        The resource can be used as input for a #ramses::Geometry.
+    *        The resource can be used as an input for a #ramses::Geometry.
     *
     * @details If an #ArrayResource object is created with type #ramses::EDataType::ByteBlob then an element
     *          is defined as one byte, rather than a logical vertex element. Hence, number of elements is
-    *          the same as size in bytes.
+    *          the same as the size in bytes.
+    * @ingroup CoreAPI
     */
     class RAMSES_API ArrayResource : public Resource
     {

include/ramses/client/AttributeInput.h

@@ -1,5 +1,5 @@
 //  -------------------------------------------------------------------------
-//  Copyright (C) 2014 BMW Car IT GmbH
+//  Copyright (C) 2023 BMW AG
 //  -------------------------------------------------------------------------
 //  This Source Code Form is subject to the terms of the Mozilla Public
 //  License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -19,8 +19,8 @@ namespace ramses
     }
 
     /**
+    * @brief The AttributeInput is a description of an attribute effect input.
     * @ingroup CoreAPI
-    * @brief The AttributeInput is a description of an attribute effect input
     */
     class RAMSES_API AttributeInput : public EffectInput
     {

include/ramses/client/BlitPass.h

@@ -1,5 +1,5 @@
 //  -------------------------------------------------------------------------
-//  Copyright (C) 2017 BMW Car IT GmbH
+//  Copyright (C) 2023 BMW AG
 //  -------------------------------------------------------------------------
 //  This Source Code Form is subject to the terms of the Mozilla Public
 //  License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -20,11 +20,11 @@ namespace ramses
     class RenderBuffer;
 
     /**
-     * @ingroup CoreAPI
      * @brief The BlitPass blits contents of one RendeBuffer to another. The source and destination
-     * RenderBuffer objects must have same type, format and dimensions. BlitPass objects are ordered together
+     * RenderBuffer objects must have the same type, format and dimensions. BlitPass objects are ordered
      * using a render order, which is also shared with RenderPass objects, i.e, BlitPass and RenderPass objects
      * can all be ordered relative to each other.
+     * @ingroup CoreAPI
      */
     class RAMSES_API BlitPass : public SceneObject
     {

include/ramses/client/Camera.h

@@ -1,5 +1,5 @@
 //  -------------------------------------------------------------------------
-//  Copyright (C) 2014 BMW Car IT GmbH
+//  Copyright (C) 2023 BMW AG
 //  -------------------------------------------------------------------------
 //  This Source Code Form is subject to the terms of the Mozilla Public
 //  License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -20,10 +20,10 @@ namespace ramses
     class DataObject;
 
     /**
-    * @ingroup CoreAPI
     * @brief   The #Camera base class is part of a scene and defines a view into the scene
     *          defined by the client application. It is also a #Node with transformation.
-    * @details A valid camera for rendering must have viewport and frustum set.
+    * @details A valid camera for rendering must have a viewport and a frustum set.
+    * @ingroup CoreAPI
     */
     class RAMSES_API Camera : public Node
     {

include/ramses/client/ClientObject.h

@@ -1,5 +1,5 @@
 //  -------------------------------------------------------------------------
-//  Copyright (C) 2014 BMW Car IT GmbH
+//  Copyright (C) 2023 BMW AG
 //  -------------------------------------------------------------------------
 //  This Source Code Form is subject to the terms of the Mozilla Public
 //  License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -18,8 +18,8 @@ namespace ramses
     }
 
     /**
-   * @ingroup CoreAPI
     * @brief The ClientObject is a base class for all client API objects owned by a RamsesClient.
+    * @ingroup CoreAPI
     */
     class RAMSES_API ClientObject : public RamsesObject
     {

include/ramses/client/DataObject.h

@@ -1,5 +1,5 @@
 //  -------------------------------------------------------------------------
-//  Copyright (C) 2016 BMW Car IT GmbH
+//  Copyright (C) 2023 BMW AG
 //  -------------------------------------------------------------------------
 //  This Source Code Form is subject to the terms of the Mozilla Public
 //  License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -20,17 +20,17 @@ namespace ramses
     }
 
     /**
-    * @ingroup CoreAPI
     * @brief   The DataObject is a data container for storing data within a scene.
     * @details The DataObject can be bound to some inputs of some object types
     *          (e.g. #ramses::Appearance::bindInput or #ramses::Camera::bindViewportOffset).
     *          When a data object is bound to an input the data object value overrides whatever was previously
     *          set to that input using its direct setter.
     *          A single #DataObject can be bound to multiple inputs (also to other #ramses::RamsesObject types
-    *          where applicable) providing a way to distribute value across instances/inputs.
+    *          where applicable) providing a way to distribute a value across instances/inputs.
     *          Using #DataObject also allows use of data linking across scenes between data object provider and consumer
     *          (#ramses::Scene::createDataProvider and #ramses::Scene::createDataConsumer) see SDK examples for typical use cases.
     *          A value set to a #DataObject is then propagated everywhere it is bound to and it is linked to.
+    * @ingroup CoreAPI
     */
     class RAMSES_API DataObject : public SceneObject
     {