ernie-renderer 0.2.0.dev149__tar.gz → 0.2.0.dev151__tar.gz

{ernie_renderer-0.2.0.dev149 → ernie_renderer-0.2.0.dev151}/CMakeLists.txt

@@ -15,7 +15,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev149" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev151" 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.dev149 → ernie_renderer-0.2.0.dev151}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev149
+Version: 0.2.0.dev151
 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.dev149 → ernie_renderer-0.2.0.dev151}/benchmarks/CMakeLists.txt

@@ -3,6 +3,7 @@ add_executable(
     ernie_benchmarks
     main.cpp
     device/pose_step.cpp
+    render/batch_step.cpp
     render/transform_graph.cpp
     scene/extents.cpp
     scene/storage.cpp

ernie_renderer-0.2.0.dev151/benchmarks/render/batch_step.cpp

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file batch_step.cpp
+/// @brief Batched rendering as reinforcement learning uses it, after Madrona's procedural benchmark
+/// scenes: thousands of worlds, each a few shapes over a shared ground, a 64 x 64 camera a world
+/// rendering colour and depth, every view in one dispatch. Reports views a second.
+#include "benchmarks/bench.h"
+#include "ernie/device/context.h"
+#include "ernie/render/renderer.h"
+#include "ernie/scene/schema/camera.h"
+#include "ernie/scene/schema/geom.h"
+#include "ernie/scene/schema/planet.h"
+#include "ernie/scene/schema/render.h"
+#include "ernie/scene/tokens.h"
+#include "ernie/scene/xform.h"
+#include "ernie/util/profiler.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <memory>
+#include <random>
+#include <string>
+#include <vector>
+
+namespace ernie::bench {
+namespace {
+
+constexpr int kShapesPerWorld = 8;
+
+/// @brief A scene of `worlds` worlds side by side, each with shapes scattered in front of its
+/// camera, and the products rendering every camera's colour and depth at `size` pixels.
+void BuildWorlds(Scene& scene, int worlds, glm::uvec2 size) {
+    GroundPlane::Define(scene, "/Ground");
+    const std::vector<Path> vars{Path("/Render/Vars/Colour"), Path("/Render/Vars/Depth")};
+    RenderVar::Define(scene, vars[0]).SetSourceName(std::string(render_vars::kLdrColor));
+    RenderVar::Define(scene, vars[1]).SetSourceName(std::string(render_vars::kDistanceToCamera));
+    std::mt19937 random(7);
+    std::uniform_real_distribution<double> spread(-2.0, 2.0);
+    std::vector<Path> products;
+    for (int world = 0; world < worlds; ++world) {
+        const std::string root = "/World" + std::to_string(world);
+        Xform::Define(scene, root).SetWorld(world);
+        for (int shape = 0; shape < kShapesPerWorld; ++shape) {
+            const std::string path = root + "/Shape" + std::to_string(shape);
+            if (shape % 2 == 0) {
+                Sphere::Define(scene, path).SetRadius(0.4);
+            } else {
+                Cube::Define(scene, path).SetSize(0.7);
+            }
+            SetXform(scene, path,
+                     {.translate = glm::dvec3(spread(random), 5.0 + spread(random),
+                                              0.5 + 0.2 * spread(random))});
+        }
+        const std::string camera = root + "/Camera";
+        Camera::Define(scene, camera).SetHorizontalAperture(0.036).SetVerticalAperture(0.036);
+        scene.Set(camera, tokens::kTransform,
+                  LookAtTransform({0.0, 0.0, 1.5}, {0.0, 5.0, 0.5}, {0.0, 0.0, 1.0}));
+        products.emplace_back("/Render/View" + std::to_string(world));
+        RenderProduct::Define(scene, products.back())
+            .SetCamera(camera)
+            .SetResolution(glm::dvec2(size))
+            .SetOrderedVars(vars);
+    }
+    RenderSettings::Define(scene, "/Render/Settings").SetProducts(products);
+}
+
+Timing StepWorlds(int worlds, glm::uvec2 size, double targetMs) {
+    std::unique_ptr<Renderer> renderer;
+    try {
+        renderer = std::make_unique<Renderer>();
+    } catch (const std::exception& error) {
+        std::printf("skipped: %s\n", error.what());
+        return {0.0, targetMs};
+    }
+    Scene scene;
+    BuildWorlds(scene, worlds, size);
+    // The first step builds every bottom level; later ones rebuild only the top levels.
+    renderer->Step(scene);
+    renderer->Context().WaitIdle();
+    const double host = Fastest([] {}, [&] { renderer->Step(scene); });
+    renderer->Context().WaitIdle();
+    const double ms = Fastest([] {},
+                              [&] {
+                                  renderer->Step(scene);
+                                  renderer->Context().WaitIdle();
+                              });
+    const double pixels = static_cast<double>(worlds) * size.x * size.y;
+    std::printf("  %d views of %u x %u: %.0f views, %.2f gigapixels a second, %.2f ms submitting, "
+                "on %s\n",
+                worlds, size.x, size.y, 1000.0 * worlds / ms, pixels / ms / 1e6, host,
+                renderer->Context().Info().name.c_str());
+    if (std::getenv("ERNIE_BENCH_PROFILE") != nullptr) {
+        profiler::SetEnabled(true);
+        profiler::SetGpuEnabled(false);
+        for (int step = 0; step < 8; ++step) {
+            profiler::BeginFrame();
+            renderer->Step(scene);
+            renderer->Context().WaitIdle();
+        }
+        profiler::BeginFrame();
+        const std::vector<profiler::Frame> frames = profiler::Frames();
+        std::printf("%s", profiler::ReportText(profiler::Summarize(frames, profiler::ThreadNames()),
+                                               {.depth = 4, .minMs = 0.1, .byTime = true})
+                              .c_str());
+        profiler::SetEnabled(false);
+    }
+    return {ms, targetMs};
+}
+
+/// Registers a step of `worlds` views of `side` x `side` pixels.
+bool RegisterBatch(int worlds, std::uint32_t side, double targetMs) {
+    return Register("render.batch_step." + std::to_string(worlds) + "_worlds_" +
+                        std::to_string(side) + "x" + std::to_string(side),
+                    [=] { return StepWorlds(worlds, glm::uvec2(side), targetMs); });
+}
+
+// Madrona's benchmark resolutions, then beyond, at 1024 worlds; and many worlds at 64 x 64.
+const bool kBatches = RegisterBatch(1024, 64, 5.0) && RegisterBatch(1024, 128, 15.0) &&
+                      RegisterBatch(1024, 256, 50.0) && RegisterBatch(1024, 512, 200.0) &&
+                      RegisterBatch(4096, 64, 20.0);
+
+}  // namespace
+}  // namespace ernie::bench

{ernie_renderer-0.2.0.dev149 → ernie_renderer-0.2.0.dev151}/ernie/device/queue.cpp

@@ -97,10 +97,54 @@ Queue::~Queue() {
     vkDestroyCommandPool(device_, pool_, nullptr);
 }
 
+Recording::~Recording() {
+    queue_.GiveBack(commands_, last_);
+}
+
 Ticket Queue::Submit(const std::function<void(VkCommandBuffer)>& record,
                      std::span<const Ticket> waits, BinarySemaphores binary) {
     // One recording at a time: the command pool is not thread-safe.
     const std::lock_guard recording(recording_);
+    const std::vector<VkSemaphoreSubmitInfo> waitInfos = WaitInfos(waits, binary);
+    const VkCommandBuffer commands =
+        RecordBuffer(record, VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT);
+    const std::lock_guard lock(mutex_);
+    try {
+        const Ticket ticket = SubmitBuffer(commands, waitInfos, binary);
+        inFlight_.emplace_back(commands, ticket.value);
+        return ticket;
+    } catch (...) {
+        free_.push_back(commands);
+        throw;
+    }
+}
+
+std::unique_ptr<Recording> Queue::Record(const std::function<void(VkCommandBuffer)>& record) {
+    const std::lock_guard recording(recording_);
+    // Simultaneous use, so a replay may be submitted before the last has finished.
+    return std::unique_ptr<Recording>(
+        new Recording(*this, RecordBuffer(record, VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT)));
+}
+
+Ticket Queue::Submit(Recording& recorded, std::span<const Ticket> waits, BinarySemaphores binary) {
+    if (&recorded.queue_ != this) {
+        throw DeviceError(DeviceErrorKind::Failed,
+                          name_ + " cannot submit another queue's recording");
+    }
+    const std::vector<VkSemaphoreSubmitInfo> waitInfos = WaitInfos(waits, binary);
+    const std::lock_guard lock(mutex_);
+    const Ticket ticket = SubmitBuffer(recorded.commands_, waitInfos, binary);
+    recorded.last_ = ticket.value;
+    return ticket;
+}
+
+void Queue::GiveBack(VkCommandBuffer commands, std::uint64_t last) {
+    const std::lock_guard lock(mutex_);
+    inFlight_.emplace_back(commands, last);
+}
+
+std::vector<VkSemaphoreSubmitInfo> Queue::WaitInfos(std::span<const Ticket> waits,
+                                                    BinarySemaphores binary) const {
     std::vector<VkSemaphoreSubmitInfo> waitInfos;
     for (const Ticket& wait : waits) {
         if (wait.timeline == nullptr) {
@@ -124,7 +168,11 @@ Ticket Queue::Submit(const std::function<void(VkCommandBuffer)>& record,
                              .semaphore = binary.wait,
                              .stageMask = VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT});
     }
+    return waitInfos;
+}
 
+VkCommandBuffer Queue::RecordBuffer(const std::function<void(VkCommandBuffer)>& record,
+                                    VkCommandBufferUsageFlags usage) {
     std::unique_lock lock(mutex_);
     Recycle();
     VkCommandBuffer commands = VK_NULL_HANDLE;
@@ -145,7 +193,7 @@ Ticket Queue::Submit(const std::function<void(VkCommandBuffer)>& record,
     CheckVk(vkResetCommandBuffer(commands, 0),
             [&] { return "Resetting " + name_ + "'s command buffer"; });
     const VkCommandBufferBeginInfo begin{.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO,
-                                         .flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT};
+                                         .flags = usage};
     try {
         CheckVk(vkBeginCommandBuffer(commands, &begin), [&] { return "Recording on " + name_; });
         record(commands);
@@ -156,8 +204,12 @@ Ticket Queue::Submit(const std::function<void(VkCommandBuffer)>& record,
         free_.push_back(commands);
         throw;
     }
+    return commands;
+}
 
-    lock.lock();
+Ticket Queue::SubmitBuffer(VkCommandBuffer commands,
+                           const std::vector<VkSemaphoreSubmitInfo>& waitInfos,
+                           BinarySemaphores binary) {
     const std::uint64_t value = submitted_ + 1;
     const VkCommandBufferSubmitInfo commandInfo{
         .sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO, .commandBuffer = commands};
@@ -177,13 +229,9 @@ Ticket Queue::Submit(const std::function<void(VkCommandBuffer)>& record,
         .pCommandBufferInfos = &commandInfo,
         .signalSemaphoreInfoCount = binary.signal != VK_NULL_HANDLE ? 2u : 1u,
         .pSignalSemaphoreInfos = signals.data()};
-    const VkResult submitted = vkQueueSubmit2(queue_, 1, &submit, VK_NULL_HANDLE);
-    if (submitted < VK_SUCCESS) {
-        free_.push_back(commands);
-    }
-    CheckVk(submitted, [&] { return "Submitting to " + name_; });
+    CheckVk(vkQueueSubmit2(queue_, 1, &submit, VK_NULL_HANDLE),
+            [&] { return "Submitting to " + name_; });
     submitted_ = value;
-    inFlight_.emplace_back(commands, value);
     return timeline_.At(value);
 }
 

{ernie_renderer-0.2.0.dev149 → ernie_renderer-0.2.0.dev151}/ernie/device/queue.h

@@ -9,6 +9,7 @@
 
 #include <cstdint>
 #include <functional>
+#include <memory>
 #include <mutex>
 #include <span>
 #include <string>
@@ -81,6 +82,26 @@ struct BinarySemaphores {
     VkSemaphore signal = VK_NULL_HANDLE;
 };
 
+class Queue;
+
+/// @brief Commands recorded once and submitted again and again, as a captured frame is replayed.
+/// Its command buffer goes back to its queue once its last submission is done.
+class Recording {
+  public:
+    ~Recording();
+    Recording(const Recording&) = delete;
+    Recording& operator=(const Recording&) = delete;
+
+  private:
+    friend class Queue;
+    Recording(Queue& queue, VkCommandBuffer commands) : queue_(queue), commands_(commands) {}
+
+    Queue& queue_;
+    VkCommandBuffer commands_;
+    /// The timeline value of its latest submission; 0 before its first.
+    std::uint64_t last_ = 0;
+};
+
 /// @brief A queue of one family. Submissions take a recording function and return a ticket on the
 /// queue's timeline; command buffers are recycled once their tickets complete. Any thread may
 /// submit, one recording at a time, and test or wait on tickets.
@@ -97,6 +118,13 @@ class Queue {
     /// @throws DeviceError if a wait is another device's, or submission fails.
     Ticket Submit(const std::function<void(VkCommandBuffer)>& record,
                   std::span<const Ticket> waits = {}, BinarySemaphores binary = {});
+    /// @brief Records commands to submit any number of times. Submissions may overlap: what one
+    /// must see of the last, it waits for.
+    std::unique_ptr<Recording> Record(const std::function<void(VkCommandBuffer)>& record);
+    /// @brief Submits a recording once `waits` are done.
+    /// @throws DeviceError for another queue's recording, as `Submit`.
+    Ticket Submit(Recording& recorded, std::span<const Ticket> waits = {},
+                  BinarySemaphores binary = {});
     /// @return The ticket of the latest submission: waiting on it waits for all of them.
     Ticket Last() const;
     /// @brief Presents swapchain images, between submissions from any thread.
@@ -124,8 +152,21 @@ class Queue {
     }
 
   private:
+    friend class Recording;
+
     /// Moves finished command buffers to the free list.
     void Recycle();
+    std::vector<VkSemaphoreSubmitInfo> WaitInfos(std::span<const Ticket> waits,
+                                                 BinarySemaphores binary) const;
+    /// @return A free command buffer with `record`'s commands.
+    VkCommandBuffer RecordBuffer(const std::function<void(VkCommandBuffer)>& record,
+                                 VkCommandBufferUsageFlags usage);
+    /// Submits a recorded buffer, with `mutex_` held.
+    Ticket SubmitBuffer(VkCommandBuffer commands,
+                        const std::vector<VkSemaphoreSubmitInfo>& waitInfos,
+                        BinarySemaphores binary);
+    /// Takes a recording's buffer back, to recycle once `last` is reached.
+    void GiveBack(VkCommandBuffer commands, std::uint64_t last);
 
     VkDevice device_;
     std::uint32_t family_;

{ernie_renderer-0.2.0.dev149 → ernie_renderer-0.2.0.dev151}/ernie/graph/graph.cpp

@@ -160,6 +160,10 @@ void PassBuilder::NeverCull() {
     graph_.passes_[pass_].neverCull = true;
 }
 
+void PassBuilder::OneShot() {
+    graph_.passes_[pass_].oneShot = true;
+}
+
 void PassContext::Check(std::uint32_t id) const {
     const Graph::Pass& pass = graph_.passes_[pass_];
     if (std::ranges::none_of(
@@ -470,13 +474,21 @@ void Graph::RecordPass(VkCommandBuffer commands, std::uint32_t order, std::uint3
         scope = scopes_[scope].parent;
     }
     if (scope != kNoScope && scopes_[scope].depth == depth) {
-        ERNIE_GPU_ZONE(context_, commands, scopes_[scope].name.c_str());
+        std::optional<GpuZone> zone;
+        if (timed_) {
+            zone.emplace(context_, commands, scopes_[scope].name.c_str());
+        }
         RecordPass(commands, order, depth + 1);
         return;
     }
     ERNIE_ZONE("Record a pass");
     ERNIE_ZONE_TEXT(pass.name);
-    ERNIE_GPU_ZONE(context_, commands, pass.name.c_str());
+    // Ernie's own reports name each pass by a zone of its own.
+    const profiler::ScopedZone named(profiler::Enabled() ? profiler::Intern(pass.name) : "");
+    std::optional<GpuZone> zone;
+    if (timed_) {
+        zone.emplace(context_, commands, pass.name.c_str());
+    }
     Record(commands, dependencies_.passes[order]);
     if (fullBarriers_) {
         ernie::Barrier(commands, VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT, VK_ACCESS_2_MEMORY_WRITE_BIT,
@@ -529,6 +541,67 @@ Ticket Graph::Execute(Queue& queue, std::span<const Ticket> waits, BinarySemapho
     return ticket;
 }
 
+bool Graph::Capturable() {
+    Compile();
+    return std::ranges::none_of(live_, [&](std::uint32_t p) { return passes_[p].oneShot; });
+}
+
+std::unique_ptr<CapturedGraph> Graph::Capture(Queue& queue) {
+    if (executed_) {
+        throw std::logic_error("A frame graph executes or is captured once");
+    }
+    if (!Capturable()) {
+        throw std::logic_error("A frame graph with one-shot passes cannot be captured");
+    }
+    executed_ = true;
+    timed_ = false;
+    auto captured = std::unique_ptr<CapturedGraph>(new CapturedGraph(context_, pool_, queue));
+    captured->recording_ = queue.Record([&](VkCommandBuffer commands) {
+        for (std::uint32_t order = 0; order < live_.size(); ++order) {
+            RecordPass(commands, order);
+        }
+        Record(commands, dependencies_.after);
+    });
+    // The transients stay leased to the capture, which gives them back.
+    for (Resource& resource : resources_) {
+        if (resource.imported) {
+            continue;
+        }
+        if (resource.deviceImage != nullptr) {
+            captured->firstWaits_.push_back(resource.deviceImage->Ready());
+            captured->images_.push_back(std::exchange(resource.deviceImage, nullptr));
+        }
+        if (resource.slice.buffer != nullptr) {
+            captured->ranges_.push_back(resource.range);
+            resource.slice = {};
+        }
+    }
+    leased_ = false;
+    captured->kept_ = std::move(kept_);
+    kept_.clear();
+    return captured;
+}
+
+CapturedGraph::~CapturedGraph() {
+    // The pool takes leases back once every queue's work so far, the last submission's, is done.
+    for (const DeviceImage* image : images_) {
+        pool_.Release(*image);
+    }
+    for (const BufferRange& range : ranges_) {
+        pool_.Release(range);
+    }
+    for (std::shared_ptr<const void>& object : kept_) {
+        context_.Retire(std::move(object));
+    }
+}
+
+Ticket CapturedGraph::Submit(std::span<const Ticket> waits) {
+    std::vector<Ticket> after(waits.begin(), waits.end());
+    after.insert(after.end(), firstWaits_.begin(), firstWaits_.end());
+    firstWaits_.clear();
+    return queue_.Submit(*recording_, after);
+}
+
 std::vector<std::string> Graph::ExecutedPasses() const {
     std::vector<std::string> names;
     for (const std::uint32_t p : live_) {
@@ -578,6 +651,7 @@ void AddUploadPass(Graph& graph, std::string_view name, Uploader& uploader,
     graph.Add(
         name, Kind::Copy,
         [&](PassBuilder& pass) {
+            pass.OneShot();
             for (Buffer& target : targets) {
                 if (target.Valid()) {
                     target = pass.Write(target, Use::CopyDst);

{ernie_renderer-0.2.0.dev149 → ernie_renderer-0.2.0.dev151}/ernie/graph/graph.h

@@ -100,6 +100,7 @@ struct BufferSlice {
 };
 
 class Graph;
+class CapturedGraph;
 
 /// @brief Declares one pass's accesses during setup.
 class PassBuilder {
@@ -128,6 +129,9 @@ class PassBuilder {
     Acceleration Read(Acceleration structure, Use use = Use::Trace);
     /// @brief Keeps the pass though nothing reads what it writes, as for one the host reads.
     void NeverCull();
+    /// @brief Marks the pass as recording this frame's data, as an upload's or a build of new
+    /// geometry does: a graph with one is not captured to replay (`Graph::Capturable`).
+    void OneShot();
 
   private:
     friend class Graph;
@@ -242,6 +246,14 @@ class Graph {
     /// @return The ticket of the graph's work, which CUDA can wait on too.
     /// @throws GraphError as `Compile`; std::logic_error if executed already.
     Ticket Execute(Queue& queue, std::span<const Ticket> waits = {}, BinarySemaphores binary = {});
+    /// @return Whether the graph can be captured: it has no one-shot pass. Compiles it.
+    bool Capturable();
+    /// @brief Records every kept pass once, for submitting again and again while what the passes
+    /// record stays as it was: the same resources, laid out as now. The capture keeps the
+    /// transients and the objects passes keep. Passes are not timed on the GPU.
+    /// @return The capture, not yet submitted.
+    /// @throws std::logic_error unless `Capturable`, or if executed or captured already.
+    std::unique_ptr<CapturedGraph> Capture(Queue& queue);
 
     /// @brief Adds a full barrier before every pass; on by default with
     /// ERNIE_GRAPH_FULL_BARRIERS=1.
@@ -296,6 +308,7 @@ class Graph {
         /// The innermost scope it was added in.
         std::uint32_t scope = kNoScope;
         bool neverCull = false;
+        bool oneShot = false;
     };
     struct ScopeNode {
         std::string name;
@@ -330,6 +343,36 @@ class Graph {
     bool leased_ = false;
     bool fullBarriers_ = false;
     bool flushEachPass_ = false;
+    /// Whether passes record GPU timing zones, which a capture cannot replay.
+    bool timed_ = true;
+};
+
+/// @brief A graph's commands recorded once and submitted per frame, while the transients they use
+/// stay leased to it. Releasing it gives them back once its last submission is done.
+class CapturedGraph {
+  public:
+    ~CapturedGraph();
+    CapturedGraph(const CapturedGraph&) = delete;
+    CapturedGraph& operator=(const CapturedGraph&) = delete;
+
+    /// @brief Submits the commands after `waits`; the first submission also waits for transient
+    /// images new to the pool.
+    /// @return The submission's ticket.
+    Ticket Submit(std::span<const Ticket> waits = {});
+
+  private:
+    friend class Graph;
+    CapturedGraph(DeviceContext& context, TransientPool& pool, Queue& queue)
+        : context_(context), pool_(pool), queue_(queue) {}
+
+    DeviceContext& context_;
+    TransientPool& pool_;
+    Queue& queue_;
+    std::unique_ptr<Recording> recording_;
+    std::vector<Ticket> firstWaits_;
+    std::vector<const DeviceImage*> images_;
+    std::vector<BufferRange> ranges_;
+    std::vector<std::shared_ptr<const void>> kept_;
 };
 
 /// @brief Adds a copy pass recording what `uploader` staged into `targets`, which later passes then

{ernie_renderer-0.2.0.dev149 → ernie_renderer-0.2.0.dev151}/ernie/python/render.cpp

@@ -116,12 +116,19 @@ void BindRender(nb::module_& module) {
                                "rendering the same scene again costs only what changed.")
         .def(
             "__init__",
-            [](PythonRenderer* self, const std::string& device, bool validation) {
-                new (self)
-                    PythonRenderer(RendererOptions{.device = device, .validation = validation});
+            [](PythonRenderer* self, const std::string& device, bool validation,
+               std::uint32_t worlds, std::uint32_t instancesPerWorld, std::uint32_t views) {
+                new (self) PythonRenderer(RendererOptions{
+                    .device = device,
+                    .validation = validation,
+                    .capacities = {
+                        .worlds = worlds, .instancesPerWorld = instancesPerWorld, .views = views}});
             },
             nb::kw_only(), nb::arg("device") = "", nb::arg("validation") = false,
-            "Opens a device that ray traces: by UUID or part of its name, or the best one.")
+            nb::arg("worlds") = 0, nb::arg("instances_per_world") = 0, nb::arg("views") = 0,
+            "Opens a device that ray traces: by UUID or part of its name, or the best one. "
+            "worlds, instances_per_world and views declare the most the scene holds, laid out "
+            "once; a scene beyond them raises. 0 is as many as there are.")
         .def(
             "render",
             [](PythonRenderer& self, Scene& scene) { return ToNumpy(self.renderer.Render(scene)); },
@@ -138,12 +145,12 @@ void BindRender(nb::module_& module) {
             "and vars in one dispatch, and returns the RenderBatches without waiting: their vars "
             "are device columns that torch.from_dlpack views in place, or read() copies.")
         .def(
-            "bind_transform_op",
+            "bind_column",
             [](nb::object self, Scene& scene, const std::string& prim,
                const std::string& attribute) {
                 auto& renderer = nb::cast<PythonRenderer&>(self);
                 const DeviceColumn& bound =
-                    renderer.renderer.BindTransformOp(scene, Path(prim), attribute);
+                    renderer.renderer.BindColumn(scene, Path(prim), attribute);
                 auto* column = new Column(renderer.Pair(), bound, {}, Ticket{});
                 column->keeper = self;
                 nb::object handle = nb::cast(column, nb::rv_policy::take_ownership);
@@ -151,10 +158,10 @@ void BindRender(nb::module_& module) {
                 return handle;
             },
             nb::arg("scene"), nb::arg("prim"), nb::arg("attribute"),
-            "Hands a transform op (such as xformOp:translate) of every prim in the prim's bucket "
-            "to the device: returns its DeviceColumn, a row a prim in the bucket's order, which "
-            "PyTorch or Warp write in place; call ready(stream) after writing, and the next step "
-            "renders the new poses with no copy through the host.");
+            "Hands a transform op (such as xformOp:translate) or primvars:displayColor of every "
+            "prim in the prim's bucket to the device: returns its DeviceColumn, a row a prim in "
+            "the bucket's order, which PyTorch or Warp write in place; call ready(stream) after "
+            "writing, and the next step renders the new values with no copy through the host.");
 }
 
 }  // namespace ernie::python

{ernie_renderer-0.2.0.dev149 → ernie_renderer-0.2.0.dev151}/ernie/render/device_scene.cpp

@@ -9,10 +9,10 @@
 namespace ernie {
 
 DeviceScene::DeviceScene(DeviceContext& context, Arenas& arenas, const Scene& scene,
-                         const ShaderCompiler& compiler)
-    : context_(context), pool_(context), columns_(context, arenas, scene),
+                         const ShaderCompiler& compiler, WorldCapacities capacities)
+    : context_(context), scene_(scene), pool_(context), columns_(context, arenas, scene),
       transforms_(context, arenas, scene, compiler), geometry_(context, arenas, scene),
-      instances_(context, arenas) {
+      instances_(context, arenas, scene, compiler, capacities) {
     if (context.Capabilities().rayQuery) {
         tracer_ = std::make_unique<RayTracer>(context, arenas, compiler, geometry_);
     }
@@ -30,7 +30,37 @@ bool DeviceScene::Follow(const glm::dvec3& viewpoint) {
 Ticket DeviceScene::Execute(const std::function<void(graph::Graph&)>& passes,
                             std::span<const Ticket> waits, BinarySemaphores binary) {
     ERNIE_ZONE("Run a frame");
+    captured_.reset();
     graph::Graph graph(context_, pool_);
+    AddFrame(graph, passes);
+    return graph.Execute(context_.Main(), waits, binary);
+}
+
+Ticket DeviceScene::Step(const std::function<void(graph::Graph&)>& passes, std::uint64_t key,
+                         std::span<const Ticket> waits) {
+    const CaptureKey now{scene_.Store().Version(), transforms_.Origin(), key};
+    replayed_ = captured_ && now == capturedKey_ && Settled();
+    if (replayed_) {
+        ERNIE_ZONE("Replay a frame");
+        return captured_->Submit(waits);
+    }
+    ERNIE_ZONE("Run a frame");
+    captured_.reset();
+    graph::Graph graph(context_, pool_);
+    AddFrame(graph, passes);
+    if (!Settled() || !graph.Capturable()) {
+        return graph.Execute(context_.Main(), waits);
+    }
+    captured_ = graph.Capture(context_.Main());
+    capturedKey_ = now;
+    return captured_->Submit(waits);
+}
+
+bool DeviceScene::Settled() const {
+    return !tracer_ || tracer_->Bottoms().Idle();
+}
+
+void DeviceScene::AddFrame(graph::Graph& graph, const std::function<void(graph::Graph&)>& passes) {
     columns_.AddSync(graph);
     transforms_.AddUpdate(graph);
     const GeometryPool::Changes changes = geometry_.Update();
@@ -43,7 +73,6 @@ Ticket DeviceScene::Execute(const std::function<void(graph::Graph&)>& passes,
     if (passes) {
         passes(graph);
     }
-    return graph.Execute(context_.Main(), waits, binary);
 }
 
 }  // namespace ernie