Oss release master created 2021-07-14-13-23

see CHANGELOG.md for details

Original commit sha: 51e5ec514e6e80dd4cfe03c0f8db56966ebd630d

Co-authored-by: Daniel Haas <25718295+bojackHaasman@users.noreply.github.com>
Co-authored-by: Tobias Hammer <tohammer@users.noreply.github.com>
Co-authored-by: Bernhard Kisslinger <65217745+bkisslinger@users.noreply.github.com>
Co-authored-by: Violin Yanev <violinyanev@users.noreply.github.com>

.clang-tidy

@@ -223,6 +223,7 @@ Checks:
     cppcoreguidelines-pro-type-vararg,
     cppcoreguidelines-slicing,
     cppcoreguidelines-special-member-functions,
+    cppcoreguidelines-avoid-non-const-global-variables,
 
     # We are not using Darwin
     #darwin-*,

CHANGELOG.md

@@ -1,5 +1,31 @@
 # master
 
+# v0.7.0
+
+**Features**
+
+* Struct properties from Lua are now sorted in ascending lexicographic order
+* Loading from file or buffer data handles most error cases gracefully, and handles more error cases
+    * Ramses object type mismatches after loading result in errors
+    * Appearances must be from the same base effect after loading
+    * Corrupted data results in graceful errors, not in crashes and undefined behavior
+
+**Breaking changes**
+
+* Ramses Bindings are now statically attached to their Ramses object
+    * Ramses object is provided as reference during construction of the binding
+    * Can't be changed or set to nullptr
+    * Fixes bug when ramses object was re-set and links were not automatically removed (can not happen now by design)
+    * Binding input values are initialized with the values from the bound ramses object (all except appearance)
+    * See reworked documentation for more details
+* Renamed Camera binding inputs to have shorter names
+    * See class docs for new names: https://ramses-logic.readthedocs.io/en/latest/api.html#_CPPv4N6rlogic19RamsesCameraBindingE
+    * Reason: shorter strings are faster to resolve and easier to read
+* Bindings receive their input values from Ramses (after construction and after loading from file/memory)
+    * This is more consistent and eliminates data race conditions
+* New serialization format (must re-export binary files to use this version of the logic engine)
+    * This is a preparation for the first LTS version of the logic engine (API, ABI and file format)
+
 # v0.6.2
 
 **Features**

CMakeLists.txt

@@ -14,8 +14,8 @@ cmake_minimum_required(VERSION 3.13)
 #==========================================================================
 
 set(RLOGIC_VERSION_MAJOR 0)
-set(RLOGIC_VERSION_MINOR 6)
-set(RLOGIC_VERSION_PATCH 2)
+set(RLOGIC_VERSION_MINOR 7)
+set(RLOGIC_VERSION_PATCH 0)
 
 set(RLOGIC_VERSION ${RLOGIC_VERSION_MAJOR}.${RLOGIC_VERSION_MINOR}.${RLOGIC_VERSION_PATCH})
 set(ramses-logic_VERSION "${RLOGIC_VERSION}" CACHE STRING "Ramses Logic version" FORCE)
@@ -45,8 +45,8 @@ option(ramses-logic_ENABLE_INSTALL "Enable/disable installation of Ramses Logic"
 option(ramses-logic_BUILD_WITH_LTO "Build all targets with link time optimization enabled (not supported on all platforms)" OFF)
 option(ramses-logic_WARNINGS_AS_ERRORS "Treat warnings as errors when compiling" ON)
 option(ramses-logic_FORCE_BUILD_TESTS "Force build tests, even if built as a submodule" OFF)
+option(ramses-logic_FORCE_BUILD_DOCS "Abort build if documentation dependencies not found(doxygen, sphinx, breathe and the rtd theme for sphinx)" OFF)
 option(ramses-logic_BUILD_EXAMPLES "Build examples" ON)
-option(ramses-logic_BUILD_DOCS "Build documentation (ON/OFF). Requires doxygen, sphinx, breathe and the rtd theme for sphinx" OFF)
 option(ramses-logic_ENABLE_FLATBUFFERS_GENERATION "Create target to generate flatbuffers serialization files (ON/OFF)" ON)
 option(ramses-logic_ENABLE_TEST_COVERAGE "Enable test coverage - works on clang only (ON/OFF)" OFF)
 option(ramses-logic_ENABLE_CODE_STYLE "Enable code style checker target (requires python3.6+)" ON)
@@ -233,9 +233,7 @@ endif()
 # build and install documentation
 #==========================================================================
 
-if(ramses-logic_BUILD_DOCS)
-    add_subdirectory(doc)
-endif()
+add_subdirectory(doc)
 
 if(ramses-logic_ENABLE_INSTALL)
     install(FILES       README.md CHANGELOG.md LICENSE.txt

README.md

@@ -3,13 +3,13 @@
 
 [![build status](https://github.com/GENIVI/ramses-logic/workflows/CMake/badge.svg?branch=master)](https://github.com/GENIVI/ramses-logic/actions?query=branch%3Amaster) [![docs status](https://readthedocs.org/projects/ramses-logic/badge/?style=flat)](https://ramses-logic.readthedocs.io/en/latest/)
 
-`RAMSES logic` extends the [RAMSES rendering ecosystem](https://github.com/GENIVI/ramses) with scripting support based on
+`RAMSES logic` extends the [RAMSES rendering ecosystem](https://ramses-sdk.readthedocs.io/) with scripting support based on
 [Lua](https://github.com/lua/lua). `RAMSES` is designed to be minimalistic and closely aligned to OpenGL, which can be a
 limitation for more complex applications. `RAMSES logic` addresses this limitation by providing a runtime library which can
 load and run `Lua` scripts and provides a standard set of tools to let these scripts interact between each other and control
 a sophisticated `RAMSES` scene.
 
-You can find the full documentation of `RAMSES logic` [here](https://ramses-logic.readthedocs.io/en/latest).
+You can find the full documentation of `RAMSES logic` [here](https://ramses-logic.readthedocs.io/).
 
 # Build
 

benchmarks/serialization.cpp

@@ -0,0 +1,92 @@
+//  -------------------------------------------------------------------------
+//  Copyright (C) 2021 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
+//  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//  -------------------------------------------------------------------------
+
+#include "benchmark/benchmark.h"
+
+#include "ramses-logic/LogicEngine.h"
+#include "ramses-logic/Property.h"
+
+#include "fmt/format.h"
+#include <fstream>
+
+namespace rlogic
+{
+    static std::vector<char> CreateLargeLogicEngineBuffer(std::string_view fileName, int64_t scriptCount)
+    {
+        LogicEngine logicEngine;
+
+        const std::string scriptSrc = R"(
+            function interface()
+                for i = 0,20,1 do
+                    IN["dest"..tostring(i)] = INT
+                    OUT["src"..tostring(i)] = INT
+                end
+            end
+            function run()
+            end
+        )";
+
+        std::vector<LuaScript*> scripts(scriptCount);
+        for (int64_t i = 0; i < scriptCount; ++i)
+        {
+            scripts[i] = logicEngine.createLuaScriptFromSource(scriptSrc);
+
+            if (i >= 1)
+            {
+                for (int64_t link = 0; link < 20; ++link)
+                {
+                    auto target = scripts[i]->getInputs()->getChild(fmt::format("dest{}", link));
+                    auto src = scripts[i - 1]->getOutputs()->getChild(fmt::format("src{}", link));
+                    logicEngine.link(*src, *target);
+                }
+            }
+        }
+
+        logicEngine.saveToFile(fileName);
+
+        std::ifstream fileStream(std::string(fileName), std::ifstream::binary);
+        fileStream.seekg(0, std::ios::end);
+        std::vector<char> byteBuffer(static_cast<size_t>(fileStream.tellg()));
+        fileStream.seekg(0, std::ios::beg);
+        fileStream.read(byteBuffer.data(), byteBuffer.size());
+        return byteBuffer;
+    }
+
+    static void BM_LoadFromBuffer_WithVerifier(benchmark::State& state)
+    {
+        const int64_t scriptCount = state.range(0);
+
+        const std::vector<char> buffer = CreateLargeLogicEngineBuffer("largeFile.bin", scriptCount);
+
+        for (auto _ : state) // NOLINT(clang-analyzer-deadcode.DeadStores) False positive
+        {
+            LogicEngine logicEngine;
+            logicEngine.loadFromBuffer(buffer.data(), buffer.size(), nullptr, true);
+        }
+    }
+
+    // ARG: script count
+    BENCHMARK(BM_LoadFromBuffer_WithVerifier)->Arg(8)->Arg(32)->Arg(128)->Unit(benchmark::kMicrosecond);
+
+    static void BM_LoadFromBuffer_WithoutVerifier(benchmark::State& state)
+    {
+        const int64_t scriptCount = state.range(0);
+
+        const std::vector<char> buffer = CreateLargeLogicEngineBuffer("largeFile.bin", scriptCount);
+
+        for (auto _ : state) // NOLINT(clang-analyzer-deadcode.DeadStores) False positive
+        {
+            LogicEngine logicEngine;
+            logicEngine.loadFromBuffer(buffer.data(), buffer.size(), nullptr, false);
+        }
+    }
+
+    // ARG: script count
+    BENCHMARK(BM_LoadFromBuffer_WithoutVerifier)->Arg(8)->Arg(32)->Arg(128)->Unit(benchmark::kMicrosecond);
+}
+

ci/docker/image/DOCKER_TAG

@@ -1 +1 @@
-07be371ba5e5
+07be371ce5e5

ci/docker/runtime-files/bashrc

@@ -25,7 +25,7 @@ _buildsh_complete()
     cur=${COMP_WORDS[COMP_CWORD]}
     case "$COMP_CWORD" in
         1)
-            COMPREPLY=( $(compgen -W "L64_GCC L64_GCCv7 L64_LLVM CHECK_FLATBUF_GEN TEST_COVERAGE DOC_PACKAGE CLANG_TIDY THREAD_SANITIZER ADDRESS_SANITIZER UB_SANITIZER L64_GCC_LTO ANDROID_LIB_x86 ANDROID_LIB_x86_64 ANDROID_LIB_arm64-v8a ANDROID_LIB_armeabi-v7a L64_LLVM_COVERAGE L64_LLVM_SHUFFLE" -- $cur) )
+            COMPREPLY=( $(compgen -W "L64_GCC L64_GCCv7 L64_LLVM CHECK_FLATBUF_GEN TEST_COVERAGE CLANG_TIDY THREAD_SANITIZER ADDRESS_SANITIZER UB_SANITIZER L64_GCC_LTO ANDROID_LIB_x86 ANDROID_LIB_x86_64 ANDROID_LIB_arm64-v8a ANDROID_LIB_armeabi-v7a L64_LLVM_COVERAGE L64_LLVM_SHUFFLE" -- $cur) )
             ;;
         2)
             COMPREPLY=( $(compgen -W "Debug Release RelWithDebInfo" -- $cur) )

ci/docker/runtime-files/build.sh

@@ -6,7 +6,7 @@
 #  file, You can obtain one at https://mozilla.org/MPL/2.0/.
 #  -------------------------------------------------------------------------
 
-TARGETS="L64_GCC L64_GCCv7 L64_LLVM CHECK_FLATBUF_GEN  TEST_COVERAGE DOC_PACKAGE CLANG_TIDY THREAD_SANITIZER ADDRESS_SANITIZER UB_SANITIZER L64_GCC_LTO ANDROID_LIB_x86 ANDROID_LIB_x86_64 ANDROID_LIB_arm64-v8a ANDROID_LIB_armeabi-v7a L64_LLVM_COVERAGE L64_LLVM_SHUFFLE"
+TARGETS="L64_GCC L64_GCCv7 L64_LLVM CHECK_FLATBUF_GEN  TEST_COVERAGE CLANG_TIDY THREAD_SANITIZER ADDRESS_SANITIZER UB_SANITIZER L64_GCC_LTO ANDROID_LIB_x86 ANDROID_LIB_x86_64 ANDROID_LIB_arm64-v8a ANDROID_LIB_armeabi-v7a L64_LLVM_COVERAGE L64_LLVM_SHUFFLE"
 
 # preset defaults
 CONFIG=Release
@@ -59,8 +59,6 @@ case $TARGET in
              TOOLCHAIN=$RL_SRC/cmake/toolchain/Linux_X86_64_llvm.toolchain
              CONFIG=Debug
              ;;
-    DOC_PACKAGE)
-             ;;
     CLANG_TIDY)
              TOOLCHAIN=$RL_SRC/cmake/toolchain/Linux_X86_64_llvm.toolchain
              CONFIG=Debug
@@ -128,29 +126,6 @@ if [ "$TARGET" = "ANDROID_LIB_x86" ] || [ "$TARGET" = "ANDROID_LIB_x86_64" ] ||
         cp $BUILD_DIR/*.tar.gz $PACKAGE_DIR
     fi
 
-elif [ "$TARGET" = "DOC_PACKAGE" ]; then
-    cmake \
-        -G"Ninja"                       \
-        -Dramses-logic_BUILD_DOCS=ON    \
-        $RL_SRC
-
-    ninja rlogic-sphinx
-
-    # Obtain project version
-    pushd $RL_SRC
-    VERSION_MAJOR=`cat CMakeLists.txt | grep "set(RLOGIC_VERSION_MAJOR" | sed 's/^[^0-9]*\([0-9]*\).*$/\1/'`
-    VERSION_MINOR=`cat CMakeLists.txt | grep "set(RLOGIC_VERSION_MINOR" | sed 's/^[^0-9]*\([0-9]*\).*$/\1/'`
-    VERSION_PATCH=`cat CMakeLists.txt | grep "set(RLOGIC_VERSION_PATCH" | sed 's/^[^0-9]*\([0-9]*\).*$/\1/'`
-    GIT_COMMIT_HASH=`git rev-parse --short HEAD`
-    popd
-
-    VERSION_NAME="$VERSION_MAJOR.$VERSION_MINOR.$VERSION_PATCH-sha-$GIT_COMMIT_HASH"
-
-    pushd $BUILD_DIR/sphinx
-    DOC_PACKAGE_NAME=RAMSES_Logic_docs_$VERSION_NAME.tar.gz
-    tar cfz $PACKAGE_DIR/$DOC_PACKAGE_NAME *
-    popd
-
 elif [ "$TARGET" = "CLANG_TIDY" ]; then
 
     cmake \
@@ -272,7 +247,7 @@ else
         -DCMAKE_BUILD_TYPE=$CONFIG \
         -DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN \
         -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR \
-        -Dramses-logic_BUILD_DOCS=$BUILD_DOCS \
+        -Dramses-logic_FORCE_BUILD_DOCS=$BUILD_DOCS \
         -Dramses-logic_BUILD_WITH_LTO=${ENABLE_LTO} \
         -Dramses-logic_ENABLE_FLATBUFFERS_GENERATION=OFF \
         -Dramses-logic_ENABLE_TEST_COVERAGE=${ENABLE_COVERAGE} \
@@ -322,7 +297,7 @@ else
 
 fi
 
-if [ "$BUILD_PACKAGE" = True ] && [ "$TARGET" != "DOC_PACKAGE" ]; then
+if [ "$BUILD_PACKAGE" = True ]; then
      cp $BUILD_DIR/*.tar.gz $PACKAGE_DIR
 fi
 

cmake/flatbuffersGeneration.cmake

@@ -33,7 +33,7 @@ set(flatbuffers_output_dir "${PROJECT_SOURCE_DIR}/lib/flatbuffers/generated")
 # create list of *_gen.h out of *.fbs file list
 foreach(schema ${flatbuffers_schemas})
     get_filename_component(filename ${schema} NAME_WE)
-    list(APPEND generated_headers "${flatbuffers_output_dir}/${filename}_gen.h")
+    list(APPEND generated_headers "${flatbuffers_output_dir}/${filename}Gen.h")
 endforeach()
 
 # TODO Violin/Tobias investigate the "--conform" option of flatc - looks very promising
@@ -55,7 +55,7 @@ add_custom_command(
     COMMAND $<TARGET_FILE:flatc>
         -o ${flatbuffers_output_dir}/
         --cpp ${flatbuffers_schemas}
-        --filename-suffix _gen
+        --filename-suffix Gen
         --filename-ext h
         --scoped-enums
         --no-prefix

doc/CMakeLists.txt

@@ -6,9 +6,27 @@
 #  file, You can obtain one at https://mozilla.org/MPL/2.0/.
 #  -------------------------------------------------------------------------
 
+if(ramses-logic_FORCE_BUILD_DOCS)
+    set(PACKAGE_FIND_MODE REQUIRED)
+    set(DOCS_ERROR_TYPE FATAL_ERROR)
+else()
+    set(PACKAGE_FIND_MODE QUIET)
+    set(DOCS_ERROR_TYPE STATUS)
+endif()
+
 # error if doxygen not found
-find_package(Doxygen QUIET REQUIRED)
-find_package(Sphinx QUIET REQUIRED)
+find_package(Doxygen ${PACKAGE_FIND_MODE})
+
+if (NOT DOXYGEN_FOUND)
+    message(${DOCS_ERROR_TYPE} "Doxygen was not found on this system. Documentation generation was disabled.")
+    return()
+endif()
+
+find_package(Sphinx ${PACKAGE_FIND_MODE})
+if (NOT SPHINX_FOUND)
+    message(${DOCS_ERROR_TYPE} "Sphinx was not found on this system. Documentation generation was disabled.")
+    return()
+endif()
 
 # only used to set as dependency for docs build (so that docs are rebuilt in developer mode
 # when an API file is changed)

doc/sphinx/api.rst

@@ -33,7 +33,9 @@ The greyed-out slots in the image above represent input properties which are nei
 have a statically configured value. In bindings, this denotes that the corresponding ``Ramses`` property
 is not being updated by the ``Logic Engine`` (see also :ref:`next section <Data Flow>`). In scripts, these
 properties will receive a default value at runtime (0, 0.0f, "", true etc.) unless explicitly set by the application
-logic. Usually, script inputs without a configured value or a link to other output are considered the ``interface``
+logic. Bindings' input values are initialized with the values of the bound `Ramses` object, for all bindings except
+:class:`rlogic::RamsesAppearanceBinding`.
+Usually, script inputs without a configured value or a link to other output are considered the ``interface``
 of the logic network towards a runtime application, and their values are supposed to be explicitly set at runtime.
 
 .. note::
@@ -81,8 +83,7 @@ you should never set the ``visibility`` property of a Binding object, instead se
 
 The ``Logic Engine`` can be also serialized and deserialized into binary files for fast loading.
 The above data flow rules still apply as if all the scripts and binding objects were just created. The first call to
-:func:`rlogic::LogicEngine::update` after loading from file will execute all scripts. Bindings will only be executed if
-some or all of their inputs are linked to a script output. Binding values will only be passed further to ``Ramses``
+:func:`rlogic::LogicEngine::update` after loading from file will execute all scripts. Binding values will only be passed further to ``Ramses``
 if their values were modified, e.g. by a link which produced a different value than before saving, or if the application
 called :func:`rlogic::Property::set` explicitly on any of the bindings' input properties. For more details on saving and loading,
 see the :ref:`section further down <Saving/Loading from file>`.
@@ -262,6 +263,12 @@ The reason for that is two-fold:
 The `section on data flow <Data Flow>`_ describes how data is passed throughout the network of logic nodes and when
 bound Ramses objects are updated and when not.
 
+.. note::
+
+    Binding input values are initialized with the same values as the `Ramses` objects they "bind". The only
+    exception to this are Appearance bindings - extracting all data from Ramses Appearances would incur performance
+    costs not worth the convenience.
+
 
 =========================
 Error handling

doc/sphinx/build.rst

@@ -122,11 +122,6 @@ things can be enabled using following CMake options:
     * default: OFF
     * enables clang's options to generate code coverage from test executables
 
-* -Dramses-logic_BUILD_DOCS
-    * options: ON/OFF
-    * default: OFF
-    * builds these documentation pages. Requires `sphinx <https://www.sphinx-doc.org/>`_, `breathe <https://breathe.readthedocs.io/>`_ and the `rtd documentation theme <https://github.com/readthedocs/sphinx_rtd_theme>`_ by sphinx.
-
 * -Dramses-logic_BUILD_WITH_LTO
     * options: ON/OFF
     * default: OFF

doc/sphinx/lua_syntax.rst

@@ -264,6 +264,15 @@ Additional Lua syntax specifics
 type system and memory management. This is mostly transparent to the user, but there are some noteworthy
 special cases worth explaining.
 
+-----------------------------------------------------
+Userdata vs. table
+-----------------------------------------------------
+
+The properties declared in the IN and OUT objects are stored as so-called `usertype` Lua objects, not standard tables.
+`Userdata` are C++ objects which are exposed to the Lua script. This limits the operations possible with
+those types - only the `index`, `newIndex` and for some containers the size (`#` operator) are supported.
+Using other Lua operations (e.g. pairs/ipairs) will result in errors.
+
 -----------------------------------------------------
 Vec2/3/4 types
 -----------------------------------------------------

examples/04_ramses_scene/main.cpp

@@ -69,13 +69,7 @@ int main(int argc, char* argv[])
      * Create a binding object which serves as a bridge between logic scripts and animations on one end
      * and a Ramses scene on the other end
      */
-    rlogic::RamsesNodeBinding* nodeBinding = logicEngine.createRamsesNodeBinding("binding to triangle mesh node");
-
-    /**
-     * Connect the binding object to the Ramses node we created above. This will cause the LogicEngine
-     * to overwrite the properties of the linked Ramses node whenever this RamsesNodeBinding is updated.
-     */
-    nodeBinding->setRamsesNode(triangleNode);
+    rlogic::RamsesNodeBinding* nodeBinding = logicEngine.createRamsesNodeBinding(*triangleNode, "binding to triangle mesh node");
 
     /**
      * Create a simple script which takes the current time in milliseconds