hyperverse 0.0.1__py3-none-any.whl

hyperdrone/_vendor/rl-tools/include/rl_tools/rendering/raytracing/operations_cpu_mux.h

@@ -0,0 +1,31 @@
+#include "../../version.h"
+#include "../../rl_tools.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RENDERING_RAYTRACING_OPERATIONS_CPU_MUX_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RENDERING_RAYTRACING_OPERATIONS_CPU_MUX_H
+
+// backend contract: renderer.h maps the same macro to backends::Default (the Renderer/AssetLibrary
+// template default), and the selected header provides, in namespace rl_tools for that tag:
+//   types: backends::{RendererState, LibraryState, SceneState}<BACKEND, SPEC> specializations
+//   verbs on Renderer<SPEC, BACKEND>: malloc, init(device, renderer, scene, pool, metadata), free,
+//          synchronize, generate_probe_directions, {render, probe, update, advance_flow}_{launch, sync}
+//   copy(...) with backends::Device<BACKEND> as source or destination
+//   optional: device_name; AssetLibrary malloc/free/init overloads for cross-renderer sharing (OptiX)
+// It includes operations_cpu_common.h (backend-independent host verbs) first and
+// operations_cpu_post.h last, which derives the blocking composites (render = render_launch +
+// render_sync, ...), the library/Bundle init overloads and the non-sharing library fallbacks.
+#if defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_METAL)
+    #include "backends/metal/operations_cpu.h"
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_OPTIX)
+    #include "backends/optix/operations_cuda.h"
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_VULKAN)
+    #include "backends/vulkan/operations_cpu.h"
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_WEBGPU)
+    #include "backends/webgpu/operations_cpu.h"
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_GENERIC)
+    #include "backends/generic/operations_cpu.h"
+#else
+    #error "RLtools raytracing: no backend configured (RL_TOOLS_RENDERING_RAYTRACING_BACKEND_OPTIX, RL_TOOLS_RENDERING_RAYTRACING_BACKEND_METAL, RL_TOOLS_RENDERING_RAYTRACING_BACKEND_VULKAN, RL_TOOLS_RENDERING_RAYTRACING_BACKEND_WEBGPU, or RL_TOOLS_RENDERING_RAYTRACING_BACKEND_GENERIC)"
+#endif
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/rendering/raytracing/operations_cpu_post.h

@@ -0,0 +1,85 @@
+#include "../../version.h"
+#include "../../rl_tools.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RENDERING_RAYTRACING_OPERATIONS_CPU_POST_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RENDERING_RAYTRACING_OPERATIONS_CPU_POST_H
+
+#include "renderer.h"
+
+// backend-generic wrappers over each backend's 5-arg init(device, renderer, scene, pool,
+// metadata): included at the BOTTOM of every backend operations header so the forwarded-to
+// overloads are visible at the wrappers' definition context (the verbs live in plain rl_tools,
+// which argument-dependent lookup at the point of instantiation never associates)
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools {
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void init(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer, rendering::raytracing::AssetLibrary<SPEC, BACKEND>& library, typename SPEC::TI scene_id){
+        init(device, renderer, library.scenes[scene_id], library.pool, library.metadata[scene_id]);
+    }
+
+    template <typename DEVICE, typename SPEC, typename BACKEND, typename T>
+    void init(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer, const rendering::Bundle<T>& bundle, const rendering::raytracing::AssetPool& pool){
+        init(device, renderer, bundle.scene, pool, bundle.metadata);
+    }
+
+    template <typename DEVICE, typename SPEC, typename BACKEND, typename T>
+    void init(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer, const rendering::Bundle<T>& bundle){
+        static const rendering::raytracing::AssetPool empty_pool{};
+        init(device, renderer, bundle.scene, empty_pool, bundle.metadata);
+    }
+
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void render(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer){
+        render_launch(device, renderer);
+        render_sync(device, renderer);
+    }
+
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void probe(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer){
+        probe_launch(device, renderer);
+        probe_sync(device, renderer);
+    }
+
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void update(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer){
+        update_launch(device, renderer);
+        update_sync(device, renderer);
+    }
+
+    // flow: the previous instant becomes the current one (cameras -> cameras_previous,
+    // transforms -> transforms_previous, pending host rows alike); call after a frame's render
+    // and before the next frame's writes
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void advance_flow(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer){
+        advance_flow_launch(device, renderer);
+        advance_flow_sync(device, renderer);
+    }
+
+    // shared-asset-library fallbacks for backends without cross-renderer sharing: the library is
+    // empty and every renderer builds its own copy — the API stays uniform. A backend with real
+    // sharing (OptiX) declares its own overloads, which win by partial ordering.
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void malloc(DEVICE& device, rendering::raytracing::AssetLibrary<SPEC, BACKEND>& library){
+        library.backend = new rendering::raytracing::backends::LibraryState<BACKEND, SPEC>{};
+    }
+
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void free(DEVICE& device, rendering::raytracing::AssetLibrary<SPEC, BACKEND>& library){
+        for(auto* assets : library.assets){
+            delete assets;
+        }
+        library.assets.clear();
+        library.scenes.clear();
+        library.metadata.clear();
+        delete library.backend;
+        library.backend = nullptr;
+    }
+
+    template <typename DEVICE, typename SPEC, typename BACKEND>
+    void malloc(DEVICE& device, rendering::raytracing::Renderer<SPEC, BACKEND>& renderer, rendering::raytracing::AssetLibrary<SPEC, BACKEND>& library){
+        malloc(device, renderer);
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/rendering/raytracing/renderer.h

@@ -0,0 +1,478 @@
+#include "../../version.h"
+#include "../../rl_tools.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RENDERING_RAYTRACING_RENDERER_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RENDERING_RAYTRACING_RENDERER_H
+
+#include "types.h"
+#include "scene.h"
+#include "../../containers/tensor/tensor.h"
+
+#include <vector>
+#include <deque>
+#include <cstdint>
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools {
+    namespace rendering::raytracing{
+
+        using BasicShading = Medium;
+        using HighFidelityShading = High;
+        using VeryHighFidelityShading = VeryHigh;
+        using FastFlatShading = Low;
+
+        namespace config{
+            // Fringe defaults only: the required geometry — CAM_WIDTH, CAM_HEIGHT, NUM_CAMERAS,
+            // NUM_PROBES — is deliberately absent from this base, so a missing (or misspelled)
+            // required member fails to compile instead of silently falling back to a default.
+            template <typename T_T, typename T_TI>
+            struct Default{
+                using T = T_T;
+                using TI = T_TI;
+                using SHADING = Medium;
+                static constexpr bool OUTPUT_RGB = true;
+                static constexpr bool OUTPUT_DEPTH = false;
+                // segmentation writes one uint32 instance index per pixel (miss = 0xFFFFFFFF),
+                // always single-sample from the shutter-close camera: labels cannot be averaged,
+                // so anti-aliasing and motion-blur settings do not apply to it
+                static constexpr bool OUTPUT_SEGMENTATION = false;
+                static constexpr bool SEMANTIC_SEGMENTATION = false;
+                // normals writes the world-frame (FLU) geometric unit normal of the hit surface,
+                // oriented against the ray, as float3 per pixel (miss = 0,0,0); like segmentation
+                // it is always single-sample from the shutter-close camera: unit normals cannot
+                // be averaged, so anti-aliasing and motion-blur settings do not apply to it
+                static constexpr bool OUTPUT_NORMALS = false;
+                // flow relates the current instant (cameras/transforms) to the previous instant
+                // (cameras_previous/transforms_previous): per pixel of the current image, the
+                // displacement to its correspondence in the previous image in pixels
+                // (p_previous - p_current, float2) plus a FlowStatus code. The hit point is
+                // carried to the previous instant by its instance's rigid motion, projected
+                // through the previous camera, and tested for visibility against the previous
+                // instant's scene. Always single-sample from pixel centres, like segmentation.
+                static constexpr bool OUTPUT_FLOW = false;
+                // forward flow: the same pass from the previous image to the current one, on the
+                // previous grid (q_current - q_previous). Requires OUTPUT_FLOW.
+                static constexpr bool OUTPUT_FLOW_FORWARD = false;
+                static constexpr bool ENABLE_MOTION_BLUR = false;
+                static constexpr T_TI MOTION_BLUR_SAMPLES = 1;
+                // dynamic motion blur renders MOTION_BLUR_SAMPLES sequential passes per frame,
+                // rebuilding the overlay acceleration structures from per-sample transforms
+                // (transforms_motion) between passes and accumulating linear radiance on the
+                // device — overlays blur, not just the camera. Requires motion blur + overlays.
+                static constexpr bool ENABLE_DYNAMIC_MOTION_BLUR = false;
+                static constexpr bool ENABLE_ANTI_ALIASING = false;
+                static constexpr T_TI ANTI_ALIASING_GRID_SIZE = 1;
+                static constexpr T_TI NUM_OVERLAYS = 0;
+                static constexpr T_TI MAX_OVERLAY_INSTANCES = 0;
+                static constexpr T_TI MAX_OVERLAYS_PER_CAMERA = 0;
+                // spec-driven observation output: the RGB ray gen writes OBSERVATION_T pixels
+                // ([0,1] linear or sRGB per SHADING) directly — no format-conversion pass. The
+                // packed frame buffer remains the video/golden output.
+                static constexpr bool OUTPUT_OBSERVATION = false;
+                using OBSERVATION_T = float;
+            };
+        }
+
+        template <typename T_CONFIG>
+        struct Specification{
+            using CONFIG = T_CONFIG;
+            using T = typename CONFIG::T;
+            using TI = typename CONFIG::TI;
+            using SHADING = typename CONFIG::SHADING;
+            static constexpr bool HAS_RGB = CONFIG::OUTPUT_RGB;
+            static constexpr bool HAS_DEPTH = CONFIG::OUTPUT_DEPTH;
+            static constexpr bool HAS_SEGMENTATION = CONFIG::OUTPUT_SEGMENTATION;
+            static constexpr bool HAS_NORMALS = CONFIG::OUTPUT_NORMALS;
+            static constexpr bool HAS_FLOW = CONFIG::OUTPUT_FLOW;
+            static constexpr bool HAS_FLOW_FORWARD = CONFIG::OUTPUT_FLOW_FORWARD;
+            static_assert(!HAS_FLOW_FORWARD || HAS_FLOW, "OUTPUT_FLOW_FORWARD requires OUTPUT_FLOW");
+            static constexpr bool ENABLE_DEPTH = HAS_DEPTH;
+            static constexpr bool ENABLE_RGB = HAS_RGB;
+            static constexpr TI CAM_WIDTH = CONFIG::CAM_WIDTH;
+            static constexpr TI CAM_HEIGHT = CONFIG::CAM_HEIGHT;
+            static constexpr TI NUM_CAMERAS = CONFIG::NUM_CAMERAS;
+            static constexpr TI NUM_PROBES = CONFIG::NUM_PROBES;
+            static_assert(CAM_WIDTH > 0 && CAM_HEIGHT > 0 && NUM_CAMERAS > 0, "camera geometry must be nonzero");
+            static_assert(HAS_RGB || HAS_DEPTH || HAS_SEGMENTATION || HAS_NORMALS || HAS_FLOW || NUM_PROBES > 0, "the renderer must produce at least one output (an image target or collision probes)");
+            static constexpr TI MOTION_BLUR_SAMPLES = CONFIG::MOTION_BLUR_SAMPLES;
+            static constexpr bool ENABLE_MOTION_BLUR = CONFIG::ENABLE_MOTION_BLUR && MOTION_BLUR_SAMPLES > 1;
+            static constexpr bool HAS_CAMERA_PAIR = ENABLE_MOTION_BLUR;
+            static_assert(MOTION_BLUR_SAMPLES >= 1, "MOTION_BLUR_SAMPLES must be at least 1");
+            static_assert(!ENABLE_MOTION_BLUR || MOTION_BLUR_SAMPLES == 2 || MOTION_BLUR_SAMPLES == 4 || MOTION_BLUR_SAMPLES == 8 || MOTION_BLUR_SAMPLES == 16 || MOTION_BLUR_SAMPLES == 32, "MOTION_BLUR_SAMPLES must be one of 2, 4, 8, 16, or 32");
+            static constexpr TI ANTI_ALIASING_GRID_SIZE = CONFIG::ANTI_ALIASING_GRID_SIZE;
+            static constexpr bool ENABLE_ANTI_ALIASING = CONFIG::ENABLE_ANTI_ALIASING && ANTI_ALIASING_GRID_SIZE > 1;
+            static constexpr TI ANTI_ALIASING_SAMPLES = ENABLE_ANTI_ALIASING ? ANTI_ALIASING_GRID_SIZE * ANTI_ALIASING_GRID_SIZE : 1;
+            static constexpr TI RGB_SAMPLES = (ENABLE_MOTION_BLUR ? MOTION_BLUR_SAMPLES : 1) * ANTI_ALIASING_SAMPLES;
+            static constexpr TI DEPTH_SAMPLES = RGB_SAMPLES;
+            static_assert(ANTI_ALIASING_GRID_SIZE >= 1, "ANTI_ALIASING_GRID_SIZE must be at least 1");
+            static_assert(!ENABLE_ANTI_ALIASING || ANTI_ALIASING_GRID_SIZE == 2 || ANTI_ALIASING_GRID_SIZE == 3 || ANTI_ALIASING_GRID_SIZE == 4, "ANTI_ALIASING_GRID_SIZE must be one of 2, 3, or 4");
+            static constexpr TI GRID_COLS = [](){
+                TI cols = 1;
+                while(cols * cols < NUM_CAMERAS) cols++;
+                return cols;
+            }();
+            static constexpr TI GRID_ROWS = (NUM_CAMERAS + GRID_COLS - 1) / GRID_COLS;
+            static constexpr TI FB_WIDTH = GRID_COLS * CAM_WIDTH;
+            static constexpr TI FB_HEIGHT = GRID_ROWS * CAM_HEIGHT;
+            static constexpr TI CAM_PIXELS = CAM_WIDTH * CAM_HEIGHT;
+            // dynamic overlays: per-camera dynamic content composed onto the static shared world
+            static constexpr TI NUM_OVERLAYS = CONFIG::NUM_OVERLAYS;
+            static constexpr TI MAX_OVERLAY_INSTANCES = CONFIG::MAX_OVERLAY_INSTANCES;
+            static constexpr TI MAX_OVERLAYS_PER_CAMERA = CONFIG::MAX_OVERLAYS_PER_CAMERA;
+            static constexpr bool ENABLE_OVERLAYS = NUM_OVERLAYS > 0 && MAX_OVERLAY_INSTANCES > 0 && MAX_OVERLAYS_PER_CAMERA > 0;
+            static constexpr bool SEMANTIC_SEGMENTATION = CONFIG::SEMANTIC_SEGMENTATION; // segmentation output carries Object::segmentation_class instead of the instance id
+            static_assert(!SEMANTIC_SEGMENTATION || HAS_SEGMENTATION, "SEMANTIC_SEGMENTATION requires OUTPUT_SEGMENTATION");
+            static_assert(ENABLE_OVERLAYS || (NUM_OVERLAYS == 0 && MAX_OVERLAY_INSTANCES == 0 && MAX_OVERLAYS_PER_CAMERA == 0), "overlay constants must be all zero (disabled) or all nonzero");
+            static constexpr bool ENABLE_DYNAMIC_MOTION_BLUR = CONFIG::ENABLE_DYNAMIC_MOTION_BLUR && ENABLE_MOTION_BLUR && ENABLE_OVERLAYS;
+            static_assert(!CONFIG::ENABLE_DYNAMIC_MOTION_BLUR || (ENABLE_MOTION_BLUR && ENABLE_OVERLAYS), "ENABLE_DYNAMIC_MOTION_BLUR requires ENABLE_MOTION_BLUR (MOTION_BLUR_SAMPLES > 1) and overlays");
+            static constexpr bool HAS_FLOW_OVERLAYS = HAS_FLOW && ENABLE_OVERLAYS;
+            static constexpr bool HAS_OBSERVATION = CONFIG::OUTPUT_OBSERVATION;
+            using OBSERVATION_T = typename CONFIG::OBSERVATION_T;
+            static constexpr TI OBSERVATION_CHANNELS = 3;
+            static_assert(!HAS_OBSERVATION || HAS_RGB, "OUTPUT_OBSERVATION requires OUTPUT_RGB (the RGB ray gen writes it)");
+        };
+
+        namespace backends {
+            struct None {};
+            struct Generic {};
+            struct Optix {};
+            struct Metal {};
+            struct Vulkan {};
+            struct Webgpu {};
+
+            template <typename T_BACKEND>
+            struct Name;
+            template <> struct Name<None>    { static constexpr const char* VALUE = "none"; };
+            template <> struct Name<Generic> { static constexpr const char* VALUE = "generic"; };
+            template <> struct Name<Optix>   { static constexpr const char* VALUE = "optix"; };
+            template <> struct Name<Metal>   { static constexpr const char* VALUE = "metal"; };
+            template <> struct Name<Vulkan>  { static constexpr const char* VALUE = "vulkan"; };
+            template <> struct Name<Webgpu>  { static constexpr const char* VALUE = "webgpu"; };
+
+            template <typename T_BACKEND>
+            constexpr const char* name(){
+                return Name<T_BACKEND>::VALUE;
+            }
+
+#if defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_METAL)
+            using Default = Metal;
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_OPTIX)
+            using Default = Optix;
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_VULKAN)
+            using Default = Vulkan;
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_WEBGPU)
+            using Default = Webgpu;
+#elif defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_GENERIC)
+            using Default = Generic;
+#else
+            using Default = None;
+#endif
+
+            template <typename T_BACKEND, typename T_SPEC>
+            struct RendererState;
+
+            template <typename T_BACKEND, typename T_SPEC>
+            struct LibraryState;
+
+            template <typename T_BACKEND, typename T_SPEC>
+            struct SceneState;
+
+            namespace optix { struct State; }
+            namespace metal { struct Context; }
+            namespace vulkan { struct Context; }
+            namespace webgpu { struct Context; }
+            // renderer.device: memory-domain handle for tensor copies at readback/upload
+            // boundaries — copy(renderer.device, device, ...) dispatches on the backend residency
+            // and orders the copy after the renderer's in-flight work; backend selection for the
+            // verbs stays the Renderer's template argument
+            template <typename T_BACKEND>
+            struct Device {
+                using index_t = size_t;
+            };
+            template <>
+            struct Device<Optix>{
+                using index_t = size_t;
+                optix::State* state = nullptr;
+            };
+            template <>
+            struct Device<Metal>{
+                using index_t = size_t;
+                metal::Context* context = nullptr;
+            };
+            template <>
+            struct Device<Vulkan>{
+                using index_t = size_t;
+                vulkan::Context* context = nullptr;
+            };
+            template <>
+            struct Device<Webgpu>{
+                using index_t = size_t;
+                webgpu::Context* context = nullptr;
+            };
+        }
+
+        namespace device {
+            template <typename T_RENDERING_DEVICE>
+            struct Extension {
+                using RENDERING_DEVICE = T_RENDERING_DEVICE;
+                RENDERING_DEVICE rendering;
+            };
+
+            template <typename T_BASE_SPEC, typename T_RENDERING_DEVICE>
+            struct Specification: T_BASE_SPEC {
+                using DEVICE_EXTENSION = Extension<T_RENDERING_DEVICE>;
+            };
+
+            template <typename DEVICE, typename = void>
+            struct HasRendering: utils::typing::false_type {};
+            template <typename DEVICE>
+            struct HasRendering<DEVICE, utils::typing::void_t<decltype(utils::typing::declared_lvalue<DEVICE>().rendering)>>: utils::typing::true_type {};
+        }
+
+        // shared scene store: renderers malloc'd against a library share one backend context and
+        // one geometry/texture/BLAS build per unique scene — init(device, renderer, library,
+        // path) deduplicates by file content hash and returns the unique-scene index, so callers
+        // key their own per-scene data off it. The library owns the host scenes its builds
+        // reference (deque: stable addresses). On backends without cross-renderer sharing
+        // (generic/Metal/Vulkan) each renderer still builds its own device copy — the caller
+        // code is uniform, the sharing is a backend property.
+        template <typename T_SPEC, typename T_BACKEND = backends::Default>
+        struct AssetLibrary {
+            using SPEC = T_SPEC;
+            using BACKEND = T_BACKEND;
+            using TI = typename SPEC::TI;
+            using BACKEND_STATE = backends::LibraryState<BACKEND, SPEC>;
+            using SCENE_STATE = backends::SceneState<BACKEND, SPEC>;
+            BACKEND_STATE* backend = nullptr;
+            std::deque<Scene> scenes;
+            std::deque<SCENE_STATE*> assets;
+            std::vector<SceneMetadata<typename SPEC::T>> metadata;
+            AssetPool pool;
+        };
+
+        template <typename T_SPEC, bool T_HAS_CAMERA_PAIR>
+        struct CameraPairRendererStorage {};
+
+        template <typename T_SPEC>
+        struct CameraPairRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using T = typename SPEC::T;
+            using TI = typename SPEC::TI;
+            using CAMERA_TENSOR_SPEC = tensor::Specification<Camera<T>, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS>, true>;
+            Tensor<CAMERA_TENSOR_SPEC> cameras_open;
+        };
+
+        template <typename T_SPEC, bool T_HAS_RGB>
+        struct RGBRendererStorage {};
+
+        template <typename T_SPEC>
+        struct RGBRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            using FB_TENSOR_SPEC = tensor::Specification<uint32_t, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH>, true>;
+            Tensor<FB_TENSOR_SPEC> frame_buffer;
+        };
+
+        template <typename T_SPEC, bool T_HAS_DEPTH>
+        struct DepthRendererStorage {};
+
+        template <typename T_SPEC>
+        struct DepthRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using T = typename SPEC::T;
+            using TI = typename SPEC::TI;
+            using DEPTH_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH>, true>;
+            Tensor<DEPTH_TENSOR_SPEC> depth_buffer;
+        };
+
+        template <typename T_SPEC, bool T_HAS_SEGMENTATION>
+        struct SegmentationRendererStorage {};
+
+        template <typename T_SPEC>
+        struct SegmentationRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            using SEGMENTATION_TENSOR_SPEC = tensor::Specification<uint32_t, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH>, true>;
+            Tensor<SEGMENTATION_TENSOR_SPEC> segmentation_buffer;
+        };
+
+        template <typename T_SPEC, bool T_HAS_NORMALS>
+        struct NormalsRendererStorage {};
+
+        template <typename T_SPEC>
+        struct NormalsRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            using NORMALS_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH, 3>, true>;
+            Tensor<NORMALS_TENSOR_SPEC> normals_buffer;
+        };
+
+        template <typename T_SPEC, bool T_HAS_FLOW>
+        struct FlowRendererStorage {};
+
+        template <typename T_SPEC>
+        struct FlowRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using T = typename SPEC::T;
+            using TI = typename SPEC::TI;
+            // the previous instant's cameras: producer input with the residency and ownership of
+            // cameras; advance_flow snapshots cameras into it
+            using CAMERA_TENSOR_SPEC = tensor::Specification<Camera<T>, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS>, true>;
+            Tensor<CAMERA_TENSOR_SPEC> cameras_previous;
+            using FLOW_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH, 2>, true>;
+            Tensor<FLOW_TENSOR_SPEC> flow_buffer;
+            using FLOW_STATUS_TENSOR_SPEC = tensor::Specification<uint32_t, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH>, true>;
+            Tensor<FLOW_STATUS_TENSOR_SPEC> flow_status_buffer;
+        };
+
+        template <typename T_SPEC, bool T_HAS_FLOW_FORWARD>
+        struct FlowForwardRendererStorage {};
+
+        template <typename T_SPEC>
+        struct FlowForwardRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            using FLOW_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH, 2>, true>;
+            Tensor<FLOW_TENSOR_SPEC> flow_forward_buffer;
+            using FLOW_STATUS_TENSOR_SPEC = tensor::Specification<uint32_t, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH>, true>;
+            Tensor<FLOW_STATUS_TENSOR_SPEC> flow_forward_status_buffer;
+        };
+
+        template <typename T_SPEC, bool T_HAS_FLOW_OVERLAYS>
+        struct FlowOverlayRendererStorage {};
+
+        template <typename T_SPEC>
+        struct FlowOverlayRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            // the previous instant's overlay poses: same layout, residency and ownership contract
+            // as transforms. advance_flow snapshots transforms into it (resident rows in the
+            // backend's memory domain, rows the host has not yet published through the staging
+            // mirror); update() composes the per-slot flow deltas from the two instants and
+            // builds the previous instant's overlay acceleration structures the visibility rays
+            // traverse.
+            using TRANSFORMS_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_OVERLAYS, SPEC::MAX_OVERLAY_INSTANCES, 12>, true>;
+            Tensor<TRANSFORMS_TENSOR_SPEC> transforms_previous;
+            std::vector<float> transforms_previous_staging;
+            bool transforms_previous_pending[SPEC::NUM_OVERLAYS * SPEC::MAX_OVERLAY_INSTANCES] = {};
+        };
+
+        template <typename T_SPEC, bool T_HAS_OBSERVATION>
+        struct ObservationRendererStorage {};
+
+        template <typename T_SPEC>
+        struct ObservationRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            using OBSERVATION_TENSOR_SPEC = tensor::Specification<typename SPEC::OBSERVATION_T, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH, SPEC::OBSERVATION_CHANNELS>, true>;
+            Tensor<OBSERVATION_TENSOR_SPEC> observation;
+        };
+
+        template <typename T_SPEC, bool T_ENABLE_OVERLAYS>
+        struct OverlayRendererStorage {};
+
+        template <typename T_SPEC>
+        struct OverlayRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            static constexpr TI INVALID_OVERLAY = ~(TI)0;
+
+            struct OverlaySlot {
+                TI object = 0;          // global object index (scene objects + pool objects)
+                float rest[12];         // part -> assembly frame captured at spawn; the whole-assembly verbs compose pose ∘ rest
+                bool active = false;
+            };
+            struct OverlayState {
+                OverlaySlot slots[SPEC::MAX_OVERLAY_INSTANCES];
+                bool dirty = false;     // active/object changed since the last update
+            };
+            // pool assemblies flattened at init so spawn needs no pool access in the hot path
+            struct AssetRecord {
+                TI first_part;          // into asset_part_objects/asset_part_transforms
+                TI num_parts;
+            };
+            OverlayState overlays[SPEC::NUM_OVERLAYS];
+            // geometry-to-world transform per slot [o][s], consumed by update(): backend-native
+            // residency (device memory on OptiX), accessed via transforms(device, renderer).
+            // Producers write it in place; the host verbs write the staging mirror and mark their
+            // rows pending, and update() publishes exactly those rows — a row belongs to whoever
+            // wrote it last.
+            using TRANSFORMS_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_OVERLAYS, SPEC::MAX_OVERLAY_INSTANCES, 12>, true>;
+            Tensor<TRANSFORMS_TENSOR_SPEC> transforms;
+            std::vector<float> transforms_staging;
+            bool transforms_pending[SPEC::NUM_OVERLAYS * SPEC::MAX_OVERLAY_INSTANCES] = {};
+            TI attachments[SPEC::NUM_CAMERAS * SPEC::MAX_OVERLAYS_PER_CAMERA];
+            bool attachments_dirty = false;
+            // the flattened pool tables live on the renderer (not in backend state) because the
+            // backend-independent host verbs (spawn, set_transform) consume them
+            std::vector<AssetRecord> assets;
+            std::vector<TI> asset_part_objects;      // global object index per part
+            std::vector<float> asset_part_transforms; // 12 per part, assembly-local
+        };
+
+        template <typename T_SPEC, bool T_ENABLE_DYNAMIC_MOTION_BLUR>
+        struct DynamicMotionBlurRendererStorage {};
+
+        template <typename T_SPEC>
+        struct DynamicMotionBlurRendererStorage<T_SPEC, true> {
+            using SPEC = T_SPEC;
+            using TI = typename SPEC::TI;
+            // per-sample overlay transform input consumed by the dynamic-motion-blur render loop:
+            // sample-major so slab s (base + s * NUM_OVERLAYS * MAX_OVERLAY_INSTANCES * 12) has
+            // the exact layout of the transforms tensor and feeds the same build path, under the
+            // same staging and ownership contract
+            using TRANSFORMS_MOTION_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::MOTION_BLUR_SAMPLES, SPEC::NUM_OVERLAYS, SPEC::MAX_OVERLAY_INSTANCES, 12>, true>;
+            Tensor<TRANSFORMS_MOTION_TENSOR_SPEC> transforms_motion;
+            std::vector<float> transforms_motion_staging;
+            bool transforms_motion_pending[SPEC::NUM_OVERLAYS * SPEC::MAX_OVERLAY_INSTANCES] = {};
+            // linear-radiance accumulators, resolved into the packed frame buffer / depth buffer
+            // after the last sample pass; allocated only for the enabled outputs
+            using RGB_ACCUMULATOR_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH, 3>, true>;
+            Tensor<RGB_ACCUMULATOR_TENSOR_SPEC> rgb_accumulator;
+            using DEPTH_ACCUMULATOR_TENSOR_SPEC = tensor::Specification<float, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::CAM_HEIGHT, SPEC::CAM_WIDTH>, true>;
+            Tensor<DEPTH_ACCUMULATOR_TENSOR_SPEC> depth_accumulator;
+        };
+
+        template <typename T_SPEC, typename T_BACKEND = backends::Default>
+        struct Renderer: CameraPairRendererStorage<T_SPEC, T_SPEC::HAS_CAMERA_PAIR>, RGBRendererStorage<T_SPEC, T_SPEC::HAS_RGB>, DepthRendererStorage<T_SPEC, T_SPEC::HAS_DEPTH>, SegmentationRendererStorage<T_SPEC, T_SPEC::HAS_SEGMENTATION>, NormalsRendererStorage<T_SPEC, T_SPEC::HAS_NORMALS>, FlowRendererStorage<T_SPEC, T_SPEC::HAS_FLOW>, FlowForwardRendererStorage<T_SPEC, T_SPEC::HAS_FLOW_FORWARD>, FlowOverlayRendererStorage<T_SPEC, T_SPEC::HAS_FLOW_OVERLAYS>, ObservationRendererStorage<T_SPEC, T_SPEC::HAS_OBSERVATION>, OverlayRendererStorage<T_SPEC, T_SPEC::ENABLE_OVERLAYS>, DynamicMotionBlurRendererStorage<T_SPEC, T_SPEC::ENABLE_DYNAMIC_MOTION_BLUR>{
+            using SPEC = T_SPEC;
+            using BACKEND = T_BACKEND;
+            using BACKEND_STATE = backends::RendererState<BACKEND, SPEC>;
+            using T = typename SPEC::T;
+            using TI = typename SPEC::TI;
+
+            // camera input consumed directly by render/probe: backend-native residency (device
+            // memory on OptiX, host on generic, shared/mapped on Metal/Vulkan) — access via
+            // cameras(device, renderer); under motion blur this is the shutter-close camera and
+            // cameras_open holds the shutter-open pose (see cameras_open/cameras_close accessors)
+            using CAMERA_TENSOR_SPEC = tensor::Specification<Camera<T>, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS>, true>;
+            Tensor<CAMERA_TENSOR_SPEC> cameras;
+
+            using COLLISION_TENSOR_SPEC = tensor::Specification<CollisionResult, TI, tensor::Shape<TI, SPEC::NUM_CAMERAS, SPEC::NUM_PROBES>, true>;
+            Tensor<COLLISION_TENSOR_SPEC> collision_results;
+
+            // loader-authoritative (SceneMetadata): probe ray budget and depth miss sentinel
+            T max_ray_length = 0;
+            // resolved Scene::Environment (background pair + ambient), staged into the backend
+            // launch params; set by init
+            T ambient_color[3] = {0, 0, 0};
+            T miss_color_0[3] = {0, 0, 0};
+            T miss_color_1[3] = {0, 0, 0};
+
+            backends::Device<BACKEND> device;
+            BACKEND_STATE* backend = nullptr;
+        };
+    }
+    template <typename DEVICE>
+    auto& get_rendering_device(DEVICE& device){
+        if constexpr(rendering::raytracing::device::HasRendering<DEVICE>::value){
+            return device.rendering;
+        }
+        else{
+            return device;
+        }
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif