ernie-renderer 0.2.0.dev40__tar.gz → 0.2.0.dev45__tar.gz

{ernie_renderer-0.2.0.dev40 → ernie_renderer-0.2.0.dev45}/.github/workflows/ci.yml

@@ -134,7 +134,7 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
-      - run: python -m pip install pytest
+      - run: python -m pip install pytest jsonschema
       - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: build-${{ matrix.os }}
@@ -213,8 +213,10 @@ jobs:
           path: coverage
           retention-days: 14
 
-  # The documentation, built strictly so broken links and warnings fail.
+  # The documentation, built strictly so broken links and warnings fail, with the schema reference
+  # pages and the scene files' JSON Schema generated by the Linux build.
   docs:
+    needs: build
     runs-on: ubuntu-24.04
     timeout-minutes: 10
     steps:
@@ -222,6 +224,14 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: build-ubuntu-24.04
+      - name: Generate the schema reference
+        run: |
+          tar -xf build-ci.tar
+          build/ci/bin/ernie schema --json-schema docs/schema/ernie-scene.schema.json \
+            --markdown docs/reference
       - run: python -m pip install -r docs/requirements.txt
       - run: mkdocs build --strict
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2

{ernie_renderer-0.2.0.dev40 → ernie_renderer-0.2.0.dev45}/.gitignore

@@ -7,6 +7,9 @@ build/
 dist/
 site/
 .deps/
+# Generated by `ernie schema` before the docs build
+/docs/reference/
+/docs/schema/
 *.egg-info/
 __pycache__/
 .venv/

{ernie_renderer-0.2.0.dev40 → ernie_renderer-0.2.0.dev45}/CMakeLists.txt

@@ -15,7 +15,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev40" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev45" CACHE STRING "Pre-release suffix of Ernie's version")
 set(ERNIE_VERSION "${PROJECT_VERSION}${ERNIE_VERSION_SUFFIX}")
 
 option(ERNIE_BUILD_TESTS "Build Ernie's tests" OFF)

{ernie_renderer-0.2.0.dev40 → ernie_renderer-0.2.0.dev45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev40
+Version: 0.2.0.dev45
 Summary: Efficient Renderer for Natural and Interplanetary Environments: a physically based, spectral Vulkan ray tracer
 Author: Alex Maietta
 License-Expression: BSD-3-Clause

{ernie_renderer-0.2.0.dev40 → ernie_renderer-0.2.0.dev45}/benchmarks/scene/extents.cpp

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: BSD-3-Clause
 /// @file extents.cpp
-/// @brief Cached extents at 100,000 prims: the first update, and one edit's.
+/// @brief Scene updates at 100,000 prims: the first, one edit's, and one inherited edit's.
 #include "benchmarks/bench.h"
 #include "ernie/scene/schemas/geom.h"
 
@@ -21,20 +21,35 @@ std::unique_ptr<Scene> MakeSpheres() {
     return scene;
 }
 
-const bool kFirstUpdate = Register("scene.extents.first_update_100k", [] {
+const bool kFirstUpdate = Register("scene.update.first_100k", [] {
     std::unique_ptr<Scene> scene;
-    return Timing{Fastest([&] { scene = MakeSpheres(); }, [&] { scene->UpdateExtents(); }), 10.0};
+    return Timing{Fastest([&] { scene = MakeSpheres(); }, [&] { scene->Update(); }), 10.0};
 });
 
-const bool kOneEdit = Register("scene.extents.update_after_one_edit_of_100k", [] {
+const bool kOneEdit = Register("scene.update.after_one_edit_of_100k", [] {
     std::unique_ptr<Scene> scene = MakeSpheres();
-    scene->UpdateExtents();
+    scene->Update();
     const PrimId ball = *scene->Find("/World/Ball_54321");
     double radius = 1.0;
     const double ms = Fastest([&] { scene->Set(ball, Sphere::kRadius, radius += 1.0); },
-                              [&] { scene->UpdateExtents(); });
+                              [&] { scene->Update(); });
     return Timing{ms, 1.0};
 });
 
+const bool kInheritedEdit = Register("scene.update.after_hiding_the_parent_of_100k", [] {
+    std::unique_ptr<Scene> scene = MakeSpheres();
+    scene->Define("/World", "Xform");
+    scene->Update();
+    const PrimId world = *scene->Find("/World");
+    bool hidden = false;
+    const double ms = Fastest(
+        [&] {
+            hidden = !hidden;
+            scene->Set(world, Imageable::kVisibility, hidden ? "invisible" : "inherited");
+        },
+        [&] { scene->Update(); });
+    return Timing{ms, 10.0};
+});
+
 }  // namespace
 }  // namespace ernie::bench

ernie_renderer-0.2.0.dev45/docs/README.md

@@ -0,0 +1,10 @@
+# Docs
+
+The schema reference pages and the scene files' JSON Schema are generated from the schema registry by a build of `ernie`, before the site is built:
+
+```sh
+ernie schema --json-schema docs/schema/ernie-scene.schema.json --markdown docs/reference
+python -m pip install -r docs/requirements.txt
+mkdocs serve # live preview at http://127.0.0.1:8000
+mkdocs build # static site in site/
+```

ernie_renderer-0.2.0.dev45/ernie/app/main.cpp

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file main.cpp
+/// @brief The ernie program.
+#include "ernie/device/vulkan_devices.h"
+#include "ernie/scene/reference.h"
+#include "ernie/util/file.h"
+#include "ernie/util/version.h"
+
+#include <cstdio>
+#include <exception>
+#include <filesystem>
+#include <string_view>
+#include <vector>
+
+namespace {
+
+namespace fs = std::filesystem;
+
+void PrintUsage() {
+    std::puts("Usage: ernie [--version] [--devices] [--help]\n"
+              "       ernie schema [--json-schema FILE] [--markdown DIR] [--usda DIR]\n"
+              "       ernie validate SCENE.json...");
+}
+
+int PrintDevices() {
+    for (const ernie::VulkanDeviceInfo& device : ernie::ListVulkanDevices()) {
+        std::printf("%s (%s, Vulkan %u.%u%s)\n", device.name.c_str(), ernie::ToString(device.type),
+                    device.apiMajor, device.apiMinor, device.rayQuery ? ", ray queries" : "");
+    }
+    return 0;
+}
+
+void Write(const fs::path& path, std::string_view text) {
+    if (path.has_parent_path()) {
+        fs::create_directories(path.parent_path());
+    }
+    ernie::WriteTextFile(path, text);
+}
+
+/// Writes the views of the schema registry that `arguments` ask for.
+int Schema(const std::vector<std::string_view>& arguments) {
+    if (arguments.empty() || arguments.size() % 2 != 0) {
+        PrintUsage();
+        return 2;
+    }
+    for (std::size_t i = 0; i < arguments.size(); i += 2) {
+        const fs::path out(arguments[i + 1]);
+        if (arguments[i] == "--json-schema") {
+            Write(out, ernie::SceneJsonSchema());
+        } else if (arguments[i] == "--markdown") {
+            for (const ernie::SchemaFamily& family : ernie::SchemaFamilies()) {
+                Write(out / (std::string(family.name) + ".md"), ernie::ReferencePage(family));
+            }
+        } else if (arguments[i] == "--usda") {
+            const ernie::UsdSchemaPlugin plugin = ernie::ErnieUsdSchemaPlugin();
+            Write(out / "generatedSchema.usda", plugin.generatedSchema);
+            Write(out / "plugInfo.json", plugin.plugInfo);
+        } else {
+            PrintUsage();
+            return 2;
+        }
+    }
+    return 0;
+}
+
+/// Prints every problem of the scene files; fails if any has one.
+int Validate(const std::vector<std::string_view>& files) {
+    if (files.empty()) {
+        PrintUsage();
+        return 2;
+    }
+    int status = 0;
+    for (const std::string_view file : files) {
+        for (const ernie::SceneProblem& problem :
+             ernie::ValidateScene(ernie::ReadTextFile(fs::path(file)))) {
+            std::printf("%.*s: %s\n", static_cast<int>(file.size()), file.data(),
+                        problem.Message().c_str());
+            status = 1;
+        }
+    }
+    return status;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    const std::string_view option = argc > 1 ? argv[1] : "--help";
+    const std::vector<std::string_view> rest(argv + std::min(argc, 2), argv + argc);
+    try {
+        if (option == "--version") {
+            std::printf("ernie %.*s\n", static_cast<int>(ernie::Version().size()),
+                        ernie::Version().data());
+            return 0;
+        }
+        if (option == "--devices") {
+            return PrintDevices();
+        }
+        if (option == "schema") {
+            return Schema(rest);
+        }
+        if (option == "validate") {
+            return Validate(rest);
+        }
+        PrintUsage();
+        return option == "--help" ? 0 : 2;
+    } catch (const std::exception& error) {
+        std::fprintf(stderr, "ernie: %s\n", error.what());
+        return 1;
+    }
+}

{ernie_renderer-0.2.0.dev40 → ernie_renderer-0.2.0.dev45}/ernie/scene/CMakeLists.txt

@@ -3,10 +3,16 @@ add_library(
     ernie_scene
     OBJECT
     extent_cache.cpp
+    holder_index.cpp
+    inherit.cpp
+    json.cpp
     path.cpp
+    reference.cpp
     schema.cpp
     scene.cpp
     storage.cpp
+    usd_plugin.cpp
+    validate.cpp
     view.cpp
     xform.cpp
     schemas/camera.cpp
@@ -22,4 +28,8 @@ add_library(
     schemas/shade.cpp
     schemas/vol.cpp
 )
-target_link_libraries(ernie_scene PUBLIC ernie_physics ernie_io PRIVATE ernie_build_options)
+target_link_libraries(
+    ernie_scene
+    PUBLIC ernie_physics ernie_io
+    PRIVATE ernie_json ernie_build_options
+)

ernie_renderer-0.2.0.dev45/ernie/scene/holder_index.cpp

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file holder_index.cpp
+/// @brief Re-indexing changed relationship cells, and finding a target's live holders.
+#include "ernie/scene/holder_index.h"
+
+#include <algorithm>
+#include <unordered_set>
+
+namespace ernie {
+namespace {
+
+bool IsRelationship(ColumnType type) {
+    return type == ColumnType::Relationship || type == ColumnType::Relationships;
+}
+
+/// @return The targets of a relationship cell, without the unset one.
+std::vector<PathId> Targets(const PrimStore& store, BucketId bucket, const Column& column,
+                            std::uint32_t row) {
+    std::vector<PathId> targets;
+    if (column.values->Type() == ColumnType::Relationship) {
+        targets.push_back(store.Read<Target>(bucket, column.attribute)[row].path);
+    } else {
+        for (const Target target : store.Read<std::vector<Target>>(bucket, column.attribute)[row]) {
+            targets.push_back(target.path);
+        }
+    }
+    std::erase(targets, kNoPath);
+    return targets;
+}
+
+}  // namespace
+
+void HolderIndex::Update(const PrimStore& store) {
+    const ChangeSet changes = store.ChangesSince(cursor_);
+    for (const ChangeSet::Values& values : changes.values) {
+        const Bucket& bucket = store.GetBucket(values.bucket);
+        const Column& column = *bucket.Find(values.attribute);
+        if (!IsRelationship(column.values->Type())) {
+            continue;
+        }
+        for (const RowRange range : values.rows) {
+            for (std::uint32_t row = range.begin; row < std::min(range.end, bucket.Rows()); ++row) {
+                Index(bucket.prims[row], values.attribute,
+                      Targets(store, values.bucket, column, row));
+            }
+        }
+    }
+    // A bucket too far behind to replay reports every row of every column, as a fresh one does.
+    for (const BucketId id : changes.resets) {
+        const Bucket& bucket = store.GetBucket(id);
+        for (const Column& column : bucket.columns) {
+            for (std::uint32_t row = 0;
+                 IsRelationship(column.values->Type()) && row < bucket.Rows(); ++row) {
+                Index(bucket.prims[row], column.attribute, Targets(store, id, column, row));
+            }
+        }
+    }
+    cursor_ = changes.version;
+}
+
+void HolderIndex::Index(PrimId prim, AttributeId attribute, std::vector<PathId> targets) {
+    const Cell cell = Key(prim, attribute);
+    const auto found = targets_.find(cell);
+    if (found != targets_.end()) {
+        for (const PathId old : found->second) {
+            holders_[old].erase(cell);
+        }
+    }
+    for (const PathId target : targets) {
+        holders_[target][cell] = prim.generation;
+    }
+    if (!targets.empty()) {
+        targets_[cell] = std::move(targets);
+    } else if (found != targets_.end()) {
+        targets_.erase(found);
+    }
+}
+
+std::vector<PrimId> HolderIndex::Find(const PrimStore& store, PathId target) const {
+    std::vector<PrimId> found;
+    const auto holders = holders_.find(target);
+    if (holders == holders_.end()) {
+        return found;
+    }
+    std::unordered_set<std::uint32_t> slots;
+    for (const auto& [cell, generation] : holders->second) {
+        const PrimId prim{static_cast<std::uint32_t>(cell >> 32), generation};
+        // Cells of removed prims, or of prims since moved to a bucket without the attribute, stay
+        // until their slot's next prim writes them.
+        if (Holds(store, prim, static_cast<AttributeId>(cell), target) &&
+            slots.insert(prim.slot).second) {
+            found.push_back(prim);
+        }
+    }
+    return found;
+}
+
+bool HolderIndex::Holds(const PrimStore& store, PrimId prim, AttributeId attribute, PathId target) {
+    if (!store.Alive(prim)) {
+        return false;
+    }
+    const BucketId bucket = store.PrimBucket(prim);
+    const Column* column = store.GetBucket(bucket).Find(attribute);
+    if (column == nullptr || !IsRelationship(column->values->Type())) {
+        return false;
+    }
+    const std::vector<PathId> targets = Targets(store, bucket, *column, store.PrimRow(prim));
+    return std::ranges::find(targets, target) != targets.end();
+}
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev45/ernie/scene/holder_index.h

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file holder_index.h
+/// @brief The reverse index of relationships: which prims target each path.
+#pragma once
+
+#include "ernie/scene/storage.h"
+
+#include <cstdint>
+#include <unordered_map>
+#include <vector>
+
+namespace ernie {
+
+/// @brief Which prims' relationships target each path, kept up to date from the store's changes,
+/// so an edit to a target reaches its holders: a prototype its instancers, a material the prims
+/// bound to it (through their resolved bindings), a body its terrains.
+class HolderIndex {
+  public:
+    /// Re-indexes the relationship cells that changed since the last update.
+    void Update(const PrimStore& store);
+    /// @return The live prims with a relationship targeting `target`, each once.
+    std::vector<PrimId> Find(const PrimStore& store, PathId target) const;
+
+  private:
+    /// A relationship cell: the prim's slot and the attribute, packed.
+    using Cell = std::uint64_t;
+    static Cell Key(PrimId prim, AttributeId attribute) {
+        return (std::uint64_t{prim.slot} << 32) | attribute;
+    }
+
+    void Index(PrimId prim, AttributeId attribute, std::vector<PathId> targets);
+    /// @return Whether the prim is alive and its relationship still targets `target`.
+    static bool Holds(const PrimStore& store, PrimId prim, AttributeId attribute, PathId target);
+
+    /// Each target's holding cells, with the generation of the prim that wrote them.
+    std::unordered_map<PathId, std::unordered_map<Cell, std::uint32_t>> holders_;
+    /// Each cell's targets, to unindex them when it changes.
+    std::unordered_map<Cell, std::vector<PathId>> targets_;
+    std::uint64_t cursor_ = 0;
+};
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev45/ernie/scene/inherit.cpp

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file inherit.cpp
+/// @brief Resolving inherited attributes from the nearest authoring ancestor into their resolved
+/// columns, for only the subtrees whose authored values or prims changed.
+#include "ernie/scene/convert.h"
+#include "ernie/scene/scene.h"
+
+#include <algorithm>
+#include <concepts>
+#include <limits>
+
+namespace ernie {
+
+void Scene::Resolve() {
+    const ChangeSet changes = store_.ChangesSince(resolved_);
+    for (const AttributeDef* def : InheritedAttributes()) {
+        const AttributeId attribute = store_.Tokens().Intern(def->name);
+        const AttributeId resolved = store_.Tokens().Intern(ResolvedName(def->name));
+        WithColumnType(def->type, [&]<typename T>(std::type_identity<T>) {
+            if constexpr (std::equality_comparable<T> && !std::same_as<T, Tensor>) {
+                const T fallback = ToElement<T>(store_.Paths(), def->fallback).value_or(T{});
+                BitSet roots = ResolveRoots(changes, attribute);
+                std::vector<PathId> order;
+                roots.ForEachRun([&](std::size_t begin, std::size_t end) {
+                    for (std::size_t path = begin; path < end; ++path) {
+                        order.push_back(static_cast<PathId>(path));
+                    }
+                });
+                // Ancestors intern first, so most roots are reached from one above them.
+                for (const PathId root : order) {
+                    if (roots.Test(root)) {
+                        ResolveSubtree<T>(root, attribute, resolved, fallback, roots);
+                    }
+                }
+            }
+        });
+    }
+    // Its own writes are to resolved columns, which no resolve reads.
+    resolved_ = store_.Version();
+}
+
+BitSet Scene::ResolveRoots(const ChangeSet& changes, AttributeId attribute) const {
+    BitSet roots;
+    roots.Resize(store_.Paths().Size());
+    const auto add = [&](BucketId bucket, std::uint32_t begin, std::uint32_t end) {
+        const Bucket& rows = store_.GetBucket(bucket);
+        for (std::uint32_t row = begin; row < std::min(end, rows.Rows()); ++row) {
+            roots.Set(store_.PrimPath(rows.prims[row]));
+        }
+    };
+    for (const BucketId bucket : changes.resets) {
+        add(bucket, 0, std::numeric_limits<std::uint32_t>::max());
+    }
+    for (const ChangeSet::Rows& rows : changes.rows) {
+        if (rows.change.kind == StructuralChange::Kind::Added) {
+            add(rows.bucket, rows.change.row, rows.change.row + rows.change.count);
+        }
+    }
+    for (const ChangeSet::Values& values : changes.values) {
+        if (values.attribute == attribute) {
+            for (const RowRange range : values.rows) {
+                add(values.bucket, range.begin, range.end);
+            }
+        }
+    }
+    return roots;
+}
+
+template <typename T> const T* Scene::Inheritable(PrimId prim, AttributeId attribute) const {
+    const BucketId bucket = store_.PrimBucket(prim);
+    const Column* column = store_.GetBucket(bucket).Find(attribute);
+    const std::uint32_t row = store_.PrimRow(prim);
+    if (column == nullptr || !column->authored.Test(row) ||
+        column->values->Type() != kColumnType<T>) {
+        return nullptr;
+    }
+    const T* own = &store_.Read<T>(bucket, attribute)[row];
+    if constexpr (std::same_as<T, Token>) {
+        return *own == inherited_ ? nullptr : own;
+    }
+    return own;
+}
+
+template <typename T> T Scene::Above(PathId path, AttributeId attribute, const T& fallback) const {
+    const PathTable& paths = store_.Paths();
+    for (PathId above = paths.Parent(path); above != kRootPath; above = paths.Parent(above)) {
+        const std::optional<PrimId> prim = store_.Find(above);
+        if (const T* own = prim ? Inheritable<T>(*prim, attribute) : nullptr) {
+            return *own;
+        }
+    }
+    return fallback;
+}
+
+template <typename T>
+void Scene::ResolveSubtree(PathId root, AttributeId attribute, AttributeId resolved,
+                           const T& fallback, BitSet& roots) {
+    std::vector<std::pair<PathId, T>> pending{{root, Above<T>(root, attribute, fallback)}};
+    while (!pending.empty()) {
+        const auto [path, above] = std::move(pending.back());
+        pending.pop_back();
+        const std::optional<PrimId> prim = store_.Find(path);
+        if (!prim) {
+            continue;
+        }
+        const bool isRoot = roots.Test(path);
+        roots.Set(path, false);
+        const T* own = Inheritable<T>(*prim, attribute);
+        const T value = own != nullptr ? *own : above;
+        // Prims without the column (typeless ones, materials) pass the value through.
+        const bool stored = store_.GetBucket(store_.PrimBucket(*prim)).Find(resolved) != nullptr;
+        // An unchanged prim's descendants are unchanged too, unless they are roots themselves.
+        if (store_.Derive(*prim, resolved, value) || isRoot || !stored) {
+            store_.Paths().ForEachChild(path,
+                                        [&](PathId child) { pending.emplace_back(child, value); });
+        }
+    }
+}
+
+}  // namespace ernie