hyperdrone 0.1.0__py3-none-any.whl

hyperdrone/_vendor/rl-tools/include/rl_tools/random/operations_generic.h

@@ -0,0 +1,133 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_UTILS_RANDOM_OPERATIONS_GENERIC_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_UTILS_RANDOM_OPERATIONS_GENERIC_H
+
+
+#include "../utils/generic/typing.h"
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void malloc(const DEVICE& dev, devices::generic::random::ENGINE<SPEC>& rng){}
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void free(const DEVICE& dev, devices::generic::random::ENGINE<SPEC>& rng){}
+    template <template <typename DEV_SPEC> typename DEVICE, typename DEV_SPEC, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void init(const DEVICE<DEV_SPEC>& dev, devices::generic::random::ENGINE<SPEC>& rng, typename DEV_SPEC::MATH::index_t seed = 1){
+        rng.state = 0b10101010101010101010101010101010 + seed;
+    }
+    namespace random{
+        namespace generic{
+            template <typename MATH_DEV>
+            RL_TOOLS_FUNCTION_PLACEMENT constexpr typename MATH_DEV::index_t next_max(const devices::random::Generic<MATH_DEV>& dev){
+                return MATH_DEV::MAX_INDEX;
+            }
+            template<typename MATH_DEV, typename RNG>
+            RL_TOOLS_FUNCTION_PLACEMENT void next(const devices::random::Generic<MATH_DEV>& dev, RNG& rng){
+                // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+                rng.state ^= (rng.state << 13);
+                rng.state ^= (rng.state >> 17);
+                rng.state ^= (rng.state << 5);
+            }
+        }
+
+//    template <typename MATH_DEV, typename TI, typename RNG>
+//    auto split(const devices::random::Generic<MATH_DEV>& dev, TI split_id, RNG& rng){
+//        // this operation should not alter the state of rng
+//        RNG rng_copy = rng;
+//        auto next_value = generic::next(dev, rng_copy);
+//        return default_engine(dev, next_value + split_id);
+//    }
+
+        template<typename MATH_DEV, typename T, typename RNG>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_int_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, RNG& rng){
+            // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+            using TI = typename MATH_DEV::index_t;
+            TI range = static_cast<typename MATH_DEV::index_t>(high - low) + 1;
+            generic::next(dev, rng);
+            TI r = rng.state % range;
+            return static_cast<T>(r) + low;
+        }
+        template<typename MATH_DEV, typename T, typename RNG>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_real_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, RNG& rng){
+            // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+            static_assert(utils::typing::is_same_v<T, double> || utils::typing::is_same_v<T, float>);
+            generic::next(dev, rng);
+            constexpr auto rng_max = static_cast<decltype(rng.state)>(-1);
+            return (rng.state / static_cast<T>(rng_max)) * (high - low) + low;
+        }
+        namespace normal_distribution{
+            template<typename MATH_DEV, typename T, typename RNG>
+            RL_TOOLS_FUNCTION_PLACEMENT T sample(const devices::random::Generic<MATH_DEV>& dev, T mean, T std, RNG& rng){
+                // static_assert(utils::typing::is_same_v<typename RNG::STATE_TYPE, typename MATH_DEV::index_t>);
+                static_assert(utils::typing::is_same_v<T, double> || utils::typing::is_same_v<T, float>);
+                constexpr auto rng_max = static_cast<decltype(rng.state)>(-1);
+                generic::next(dev, rng);
+                T u1 = rng.state / static_cast<T>(rng_max);
+                generic::next(dev, rng);
+                T u2 = rng.state / static_cast<T>(rng_max);
+                T x = math::sqrt(MATH_DEV{}, -2.0 * math::log(MATH_DEV{}, u1));
+                T y = 2.0 * math::PI<T> * u2;
+                T z = x * math::cos(MATH_DEV{}, y);
+                return z * std + mean;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T log_prob(const RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                static_assert(utils::typing::is_same_v<T, float> || utils::typing::is_same_v<T, double>);
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T neg_log_sqrt_pi = -0.5 * math::log(MATH_DEV{}, 2 * math::PI<T>);
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return neg_log_sqrt_pi - log_std - 0.5 * pre_square * pre_square;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T d_log_prob_d_mean(RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return pre_square / std;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T d_log_prob_d_log_std(RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return - 1 + pre_square * pre_square;
+            }
+            template<typename RANDOM_DEVICE, typename T>
+            RL_TOOLS_FUNCTION_PLACEMENT T d_log_prob_d_sample(RANDOM_DEVICE& dev, T mean, T log_std, T value){
+                using MATH_DEV = typename RANDOM_DEVICE::MATH_DEVICE;
+                T diff = (value - mean);
+                T std = math::exp(MATH_DEV{}, log_std);
+                T pre_square = diff/std;
+                return - pre_square / std;
+            }
+        }
+    }
+    // Convenience overloads: scalar random calls on ArrayENGINE delegate to engine 0
+    namespace random{
+        template<typename MATH_DEV, typename T, typename SPEC>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_real_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, devices::generic::random::ArrayENGINE<SPEC>& rng){
+            auto& rng_state = get(rng.states, 0, 0);
+            return uniform_real_distribution(dev, low, high, rng_state);
+        }
+        template<typename MATH_DEV, typename T, typename SPEC>
+        RL_TOOLS_FUNCTION_PLACEMENT T uniform_int_distribution(const devices::random::Generic<MATH_DEV>& dev, T low, T high, devices::generic::random::ArrayENGINE<SPEC>& rng){
+            auto& rng_state = get(rng.states, 0, 0);
+            return uniform_int_distribution(dev, low, high, rng_state);
+        }
+        namespace normal_distribution{
+            template<typename MATH_DEV, typename T, typename SPEC>
+            RL_TOOLS_FUNCTION_PLACEMENT T sample(const devices::random::Generic<MATH_DEV>& dev, T mean, T std, devices::generic::random::ArrayENGINE<SPEC>& rng){
+                auto& rng_state = get(rng.states, 0, 0);
+                return sample(dev, mean, std, rng_state);
+            }
+        }
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/random/operations_generic_array.h

@@ -0,0 +1,64 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RANDOM_OPERATIONS_GENERIC_ARRAY_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RANDOM_OPERATIONS_GENERIC_ARRAY_H
+
+#include "../containers/matrix/matrix.h"
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools::devices::generic::random{
+    // PortableState and ArrayENGINE forward-declared in devices/devices.h
+    template <typename T_TI, T_TI T_NUM_RNGS, bool T_DYNAMIC_ALLOCATION>
+    struct ArraySpecification{
+        using TI = T_TI;
+        static constexpr TI NUM_RNGS = T_NUM_RNGS;
+        static constexpr bool DYNAMIC_ALLOCATION = T_DYNAMIC_ALLOCATION;
+    };
+    template <typename T_SPEC>
+    struct ArrayENGINE{
+        using SPEC = T_SPEC;
+        using TI = typename SPEC::TI;
+        static constexpr TI NUM_RNGS = SPEC::NUM_RNGS;
+        Matrix<matrix::Specification<PortableState, TI, 1, NUM_RNGS, SPEC::DYNAMIC_ALLOCATION>> states;
+    };
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void malloc(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& rng){
+        malloc(device, rng.states);
+    }
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void free(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& rng){
+        free(device, rng.states);
+    }
+    template <typename DEVICE, typename SPEC>
+    RL_TOOLS_FUNCTION_PLACEMENT void init(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& rng, unsigned int seed = 1){
+        using TI = typename SPEC::TI;
+        for(TI i = 0; i < SPEC::NUM_RNGS; i++){
+            devices::generic::random::PortableState element;
+            element.state = 0b10101010101010101010101010101010 + seed + static_cast<unsigned int>(i);
+            set(rng.states, 0, i, element);
+        }
+    }
+    template <typename DEVICE_SRC, typename DEVICE_DST, typename SPEC>
+    void copy(DEVICE_SRC& device_src, DEVICE_DST& device_dst, const devices::generic::random::ArrayENGINE<SPEC>& src, devices::generic::random::ArrayENGINE<SPEC>& dst){
+        copy(device_src, device_dst, src.states, dst.states);
+    }
+    template <typename DEVICE, typename SPEC>
+    typename DEVICE::index_t abs_diff(DEVICE& device, devices::generic::random::ArrayENGINE<SPEC>& a, devices::generic::random::ArrayENGINE<SPEC>& b){
+        using TI = typename DEVICE::index_t;
+        TI acc = 0;
+        for(TI i = 0; i < SPEC::NUM_RNGS; i++){
+            auto sa = get(a.states, 0, i);
+            auto sb = get(b.states, 0, i);
+            if(sa.state != sb.state) acc++;
+        }
+        return acc;
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/random/operations_wasm32.h

@@ -0,0 +1,57 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_UTILS_RANDOM_OPERATIONS_WASM32_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_UTILS_RANDOM_OPERATIONS_WASM32_H
+
+
+#include "../utils/generic/typing.h"
+#include "operations_generic.h"
+
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    template <typename DEV_SPEC, typename SPEC>
+    void malloc(devices::WASM32<DEV_SPEC>& device, devices::random::WASM32::ENGINE<SPEC>& rng){}
+    template <typename DEV_SPEC, typename SPEC>
+    void free(devices::WASM32<DEV_SPEC>& device, devices::random::WASM32::ENGINE<SPEC>& rng){}
+    template <typename DEV_SPEC, typename SPEC>
+    void init(devices::WASM32<DEV_SPEC>& device, devices::random::WASM32::ENGINE<SPEC>& rng, typename devices::WASM32<DEV_SPEC>::index_t seed = 1){
+        rng.state = 10000 + seed;
+    };
+    namespace random{
+        // template <typename DEV_SPEC>
+        // devices::random::WASM32::index_t default_engine(const devices::WASM32<DEV_SPEC>& dev, devices::random::WASM32::index_t seed = 1){
+        //     return default_engine(devices::random::Generic<devices::math::WASM32>{}, seed);
+        // };
+        // constexpr devices::random::WASM32::index_t next_max(const devices::random::WASM32& dev){
+        //     return devices::random::WASM32::MAX_INDEX;
+        // }
+        // template <typename TI, typename RNG>
+        // auto split(const devices::random::WASM32& dev, TI split_id, RNG& rng){
+        //     // this operation should not alter the state of rng
+        //     return split(devices::random::Generic<devices::math::WASM32>{}, split_id, rng);
+        // }
+        // template<typename RNG>
+        // void next(const devices::random::WASM32& dev, RNG& rng){
+        //     next(devices::random::Generic<devices::math::WASM32>{}, rng);
+        // }
+
+        template<typename T, typename RNG>
+        T uniform_int_distribution(const devices::random::WASM32& dev, T low, T high, RNG& rng){
+            return uniform_int_distribution(devices::random::Generic<devices::math::WASM32>{}, low, high, rng);
+        }
+        template<typename T, typename RNG>
+        T uniform_real_distribution(const devices::random::WASM32& dev, T low, T high, RNG& rng){
+            return uniform_real_distribution(devices::random::Generic<devices::math::WASM32>{}, low, high, rng);
+        }
+        namespace normal_distribution{
+            template<typename T, typename RNG>
+            T sample(const devices::random::WASM32& dev, T mean, T std, RNG& rng){
+                return sample(devices::random::Generic<devices::math::WASM32>{}, mean, std, rng);
+            }
+        }
+    }
+
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/random/persist.h

@@ -0,0 +1,77 @@
+#include "../version.h"
+#if (defined(RL_TOOLS_DISABLE_INCLUDE_GUARDS) || !defined(RL_TOOLS_RANDOM_PERSIST_H)) && (RL_TOOLS_USE_THIS_VERSION == 1)
+#pragma once
+#define RL_TOOLS_RANDOM_PERSIST_H
+#include "../devices/cpu.h"
+#include <sstream>
+#include <cstring>
+RL_TOOLS_NAMESPACE_WRAPPER_START
+namespace rl_tools{
+    namespace random_persist{
+        constexpr auto RNG_STATE_MAX_SIZE = 8192; // mt19937 state is ~5KB
+    }
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    void save(devices::CPU<DEV_SPEC>& device, devices::random::CPU::ENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        std::stringstream ss;
+        ss << rng.engine;
+        std::string state_str = ss.str();
+        utils::assert_exit(device, state_str.length() < random_persist::RNG_STATE_MAX_SIZE, "RNG state string exceeds maximum size");
+        Tensor<tensor::Specification<uint8_t, TI, tensor::Shape<TI, random_persist::RNG_STATE_MAX_SIZE>>> state_tensor;
+        malloc(device, state_tensor);
+        std::memset(data(state_tensor), 0, random_persist::RNG_STATE_MAX_SIZE);
+        std::memcpy(data(state_tensor), state_str.c_str(), state_str.length() + 1); // include null terminator
+        auto rng_group = create_group(device, group, "rng");
+        save(device, state_tensor, rng_group, "state");
+        free(device, state_tensor);
+    }
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    bool load(devices::CPU<DEV_SPEC>& device, devices::random::CPU::ENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        Tensor<tensor::Specification<uint8_t, TI, tensor::Shape<TI, random_persist::RNG_STATE_MAX_SIZE>>> state_tensor;
+        malloc(device, state_tensor);
+        auto rng_group = get_group(device, group, "rng");
+        if(!load(device, state_tensor, rng_group, "state")){
+            free(device, state_tensor);
+            return false;
+        }
+        std::string state_str(reinterpret_cast<const char*>(data(state_tensor)));
+        free(device, state_tensor);
+        std::stringstream ss(state_str);
+        ss >> rng.engine;
+        return !ss.fail();
+    }
+    // ArrayENGINE: save states as a double tensor (double has 53-bit mantissa, exactly represents all uint32 values)
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    void save(devices::CPU<DEV_SPEC>& device, devices::generic::random::ArrayENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        constexpr TI NUM_RNGS = SPEC::NUM_RNGS;
+        Tensor<tensor::Specification<double, TI, tensor::Shape<TI, NUM_RNGS>>> state_tensor;
+        malloc(device, state_tensor);
+        for(TI i = 0; i < NUM_RNGS; i++){
+            set(device, state_tensor, (double)get(rng.states, 0, i).state, i);
+        }
+        save(device, state_tensor, group, "states");
+        free(device, state_tensor);
+    }
+    template<typename DEV_SPEC, typename SPEC, typename GROUP>
+    bool load(devices::CPU<DEV_SPEC>& device, devices::generic::random::ArrayENGINE<SPEC>& rng, GROUP& group) {
+        using TI = typename devices::CPU<DEV_SPEC>::index_t;
+        constexpr TI NUM_RNGS = SPEC::NUM_RNGS;
+        Tensor<tensor::Specification<double, TI, tensor::Shape<TI, NUM_RNGS>>> state_tensor;
+        malloc(device, state_tensor);
+        if(!load(device, state_tensor, group, "states")){
+            free(device, state_tensor);
+            return false;
+        }
+        for(TI i = 0; i < NUM_RNGS; i++){
+            devices::generic::random::PortableState element;
+            element.state = static_cast<unsigned int>(get(device, state_tensor, i));
+            set(rng.states, 0, i, element);
+        }
+        free(device, state_tensor);
+        return true;
+    }
+}
+RL_TOOLS_NAMESPACE_WRAPPER_END
+#endif

hyperdrone/_vendor/rl-tools/include/rl_tools/rendering/raytracing/README.md

@@ -0,0 +1,149 @@
+# Raytracing Renderer
+
+Batch raytracing for visual RL: N cameras over one static scene plus per-camera dynamic
+overlays, rendered by one of four backends (OptiX, Vulkan, Metal, generic CPU) behind a single
+`Renderer<SPEC, BACKEND>` interface (`BACKEND` defaults to the configured backend).
+Everything is wired for a training step in which dynamics,
+rendering, and observation never touch the CPU: the host's only per-step role is issuing
+asynchronous enqueues.
+
+## Coordinate frame
+
+The renderer operates in the same FLU frame as L2F: camera principal axis = +X (forward), image
+horizontal = Y, image vertical = Z. GLB meshes (Y-up) are swizzled to FLU at load time.
+
+## Convention
+
+- **Backend selection is typed dispatch.** The renderer's second template argument is the
+  backend tag (`backends::{Generic,Optix,Metal,Vulkan}`, defaulting to `backends::Default`,
+  which the CMake backend macro resolves). Each backend header overloads the public verbs
+  directly on `Renderer<SPEC, backends::X>`, so `render(device, renderer)` resolves to the
+  backend baked into the renderer's type, and the same tag selects the backend state types.
+  The `DEVICE` argument keeps its usual RLtools meaning: it says where caller-owned tensors
+  live and (on CUDA) carries the producer stream — it does not select the render backend.
+- **State is a tensor behind an accessor.** Renderer inputs and outputs are backend-native
+  `Tensor` members exposed by accessors — `cameras()`, `cameras_open()`/`cameras_close()`
+  (motion blur), `transforms()` (overlays), `transforms_motion()` (dynamic motion blur:
+  per-sample overlay transforms, sample-major so slab `s` shares the `transforms()` layout),
+  `transforms_pair()` (dynamic motion blur producer input: shutter-open/close entries),
+  `frame_buffer()`, `depth_buffer()`, `segmentation_buffer()`, `normals_buffer()`,
+  `collision_results()`, `observation()`. Residency is a backend property: CUDA device memory
+  on OptiX, host on generic, shared/mapped on Metal/Vulkan.
+- **Data moves via typed copies and kernels.** No raw backend handles or `cudaStream_t` appear in
+  public signatures. Device producers (extraction kernels) write the input tensors in place;
+  device consumers read the output tensors in place; host readers/writers stage through
+  `copy_to_renderer`/`copy_from_renderer`.
+- **Verbs enqueue; waiting is separate.** `render`/`probe`/`update` each split into `_launch`
+  (pure enqueue) and `_sync` (true boundary: readback, benchmarks, teardown); the fused verb is
+  launch + sync. On OptiX, calling a launch verb with a CUDA device makes the backend stream
+  wait on `device.stream` via an event, so producer kernels need no user-facing stream plumbing;
+  `stream(device, renderer)` exists for power users. Write inputs only between frames — a launch
+  in flight may still be reading them.
+- **Spec-driven observation output.** With `OUTPUT_OBSERVATION`, the RGB ray gen writes float
+  pixels (frame-buffer color before 8-bit quantization) directly to `observation()` — no
+  format-conversion pass. The packed `uint32` frame buffer remains the video/golden output.
+- **Normals output.** With `OUTPUT_NORMALS`, a segmentation-style single-sample pass
+  (shutter-close camera, pixel-center ray) writes the world-frame (FLU) geometric unit normal
+  of the hit surface, oriented against the ray, as float3 per pixel to `normals_buffer()`
+  (miss = zero). Unit normals cannot be averaged, so anti-aliasing and motion-blur settings do
+  not apply, and the pass stays out of the dynamic-motion-blur accumulate/resolve machinery.
+- **Determinism is a contract.** Fixed seed ⇒ identical results, no atomics. The global
+  instance-id layout (scene instances `[0,S)`, overlay `o` slot `s` at `S + o*MAX + s`) is
+  cross-backend API surface consumed by segmentation.
+- **Dynamic motion blur** (`ENABLE_DYNAMIC_MOTION_BLUR`, requires motion blur + overlays):
+  `render_launch` internally runs `MOTION_BLUR_SAMPLES` sequential passes, rebuilding the
+  overlay acceleration structures from the per-sample `transforms_motion()` slabs between
+  passes (camera lerped at the same `(i+0.5)/N` shutter times), accumulating linear radiance
+  per pixel (each thread owns its pixel — no atomics), then restores the shutter-close overlay
+  state (segmentation and probes stay single-sample at shutter close, ids unchanged) and
+  resolves with the standard transfer curve + quantization. `set_transform_pair` expands
+  shutter-open/close entries into the samples by constant-twist screw interpolation (exact for
+  constant-velocity rigid motion below 180° per shutter — an off-origin rotation axis such as a
+  prop hub stays fixed); faster motion writes `transforms_motion()` directly. The single-pose verbs replicate across samples, so a
+  dynamic spec driven only by them renders pixel-identically to camera-only blur. All passes
+  are enqueue-only: one fenced submit on Vulkan, one command buffer on Metal, stream-ordered
+- **GPU-resident dynamic motion blur** (OptiX): a sim kernel writes the shutter pair into
+  `transforms_pair()` (entry layout `[2][num_overlays * max_instances][12]`, open then close)
+  and the camera pair in place; `expand_motion_transforms_launch` then expands the samples into
+  `transforms_motion()` and the close state into `transforms()` on the render stream
+  (`transforms_generic.h` is the single interpolant shared by the host verb and the kernel).
+  The steady-state step becomes kernel → expand → update → render with no host data path —
+  the host's per-frame role is enqueues only (kernel launches, `optixAccelBuild` enqueues, and
+  OWL's constant 48-byte launch-param upload per launch). Per overlay, use either the
+  `set_transform*` host verbs or the pair path, not both. On generic/Vulkan/Metal the same verb
+  expands on the CPU into the host-resident tensors (residency is a backend property; Vulkan's
+  and Metal's per-frame instance-descriptor composition is CPU-side by architecture). End-to-end example:
+  `src/rendering/raytracing/example/drone_device.cu`.
+
+## Lifecycle
+
+Standalone renderer (examples, tests, single scene):
+
+```cpp
+Renderer<SPEC> renderer;
+rlt::malloc(device, renderer);
+Scene scene;                       // load() asserts the scene is empty; add() composes
+rlt::load(device, scene, "scene.glb");
+rlt::init(device, renderer, scene);
+```
+
+Many renderers over (possibly repeated) scenes — the multi-scene training case:
+
+```cpp
+AssetLibrary<SPEC> library;        // one backend context, one build per unique scene
+rlt::malloc(device, library);
+for(TI s = 0; s < N; s++){
+    rlt::malloc(device, renderers[s], library);
+    TI scene_id = rlt::init(device, renderers[s], library, scene_paths[s]);  // content-hash dedup
+    // scene_id keys caller-side per-scene data; identical files share one host scene,
+    // one device build (BLAS/textures/vertex data), and return the same id
+}
+```
+
+The library owns the host scenes and device builds; renderers own only their cameras, outputs,
+ray gens, and launch params. Renderer storage, looping, and environment metadata (e.g. procthor
+indoor-position scoring) are caller-side. Ownership is symmetric: `free` every renderer, then
+`free` the library.
+
+## Steady-state step (device-resident)
+
+```cpp
+// producers on device.stream write the input tensors in place
+extract_cameras_kernel<<<..., device.stream>>>(..., rlt::data(rlt::cameras(device, renderer)));
+rlt::update_launch(device, renderer);   // overlays: fill kernel + TLAS rebuilds
+rlt::render_launch(device, renderer);   // waits device.stream internally (CUDA device arg)
+rlt::probe_launch(device, renderer);
+// consumers read rlt::data(rlt::observation(device, renderer)) etc. in place
+```
+
+## Backends
+
+| backend | device code | notes |
+|---|---|---|
+| OptiX | `backends/optix` (PTX via OWL) | production training path; shared `AssetLibrary` context |
+| Vulkan | `backends/vulkan` (GLSL → SPIR-V) | `VK_KHR_ray_query` compute; headless; runs on lavapipe for CI; genuinely-async `update` |
+| generic | `backends/generic` | freestanding CPU reference and determinism oracle |
+| Metal | `backends/metal` (MSL) | macOS; **not buildable on the Linux dev machine — changes are pattern-exact and must be validated on macOS before release** |
+
+Backend selection: `-DRL_TOOLS_RENDERING_RAYTRACING_BACKEND=AUTO|OPTIX|METAL|VULKAN|GENERIC`
+(mux in `operations_cpu_mux.h`). Code that needs a non-default backend passes an explicit
+`backends::{Generic,Optix,Metal,Vulkan}` as the renderer's second template argument and
+includes that backend's operations header directly. The cross-backend parity suite is
+`tests/src/rendering/raytracing/generic/scene.cpp`, compiled once pinned to generic and once
+against the active backend; golden image/probe comparisons live next to it.
+
+Each successful renderer allocation writes one plain-text line to stderr:
+`#rl_tools::rendering::raytracing: backend=<name>`. This makes the resolved runtime
+backend visible to both native applications and language bindings without maintaining
+announcement state; `backends::name<BACKEND>()` exposes the same lowercase name to code.
+
+Golden candidates are generated by `test_rendering_raytracing_generate_golden_generic` and
+`test_rendering_raytracing_generate_golden_<active-backend>`. They default to
+`tests/data/rendering_raytracing_golden/backend/<backend>`; pass `--output-dir` explicitly when
+promoting a selected backend's output to the canonical
+`tests/data/rendering_raytracing_golden/procthor_static_scene` directory. Generator targets are excluded from the default build and are not registered with
+CTest.
+
+Python (hypert) consumers JIT against these headers out of tree: `data()` on the accessor
+tensors yields stable device pointers suitable for dlpack/`__cuda_array_interface__` wrapping,
+and the `_launch`/`_sync` verb split maps onto phase-based scheduling.