hyperdrone 0.1.0__py3-none-any.whl

hyperdrone/_native/render/CMakeLists.txt

@@ -0,0 +1,96 @@
+cmake_minimum_required(VERSION 3.24)
+project(hyperdrone_render LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+set(RLTOOLS_ROOT "" CACHE PATH "Path to the rl-tools source root")
+set(HYPERDRONE_VARIANT "OPTIX" CACHE STRING "Raytracing backend (OPTIX|METAL|VULKAN|GENERIC)")
+
+if(NOT RLTOOLS_ROOT)
+    message(FATAL_ERROR "RLTOOLS_ROOT must point to the rl-tools source root")
+endif()
+
+# rl_tools_full carries the backend compile definitions and dependencies (OWL/assimp/
+# nlohmann_json); targets are disabled so the dead-pinned procthor2glb subtree is never
+# configured. The backend device-program libraries are pulled in separately below.
+set(RL_TOOLS_ENABLE_TARGETS OFF CACHE BOOL "" FORCE)
+set(RL_TOOLS_ENABLE_TESTS OFF CACHE BOOL "" FORCE)
+# the ExTrack git snapshot re-runs on every build (~10s of pure overhead per Renderer
+# construction) and is useless for the JIT cache
+set(RL_TOOLS_ENABLE_GIT_DIFF OFF CACHE BOOL "" FORCE)
+set(RL_TOOLS_WARNINGS_AS_ERRORS OFF CACHE BOOL "" FORCE)
+set(RL_TOOLS_RENDERING_ENABLE_RAYTRACING ON CACHE BOOL "" FORCE)
+set(RL_TOOLS_RENDERING_RAYTRACING_BACKEND ${HYPERDRONE_VARIANT} CACHE STRING "" FORCE)
+# language enablement is directory-scoped too: the backends subtree calls embed_ptx and
+# needs CUDA enabled from here, not just inside the rl_tools subtree
+if(HYPERDRONE_VARIANT STREQUAL "OPTIX")
+    enable_language(CUDA)
+    set(CMAKE_CUDA_STANDARD 17)
+    set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+endif()
+if(HYPERDRONE_VARIANT STREQUAL "VULKAN")
+    find_package(Vulkan REQUIRED COMPONENTS glslangValidator)
+endif()
+
+# imported targets are directory-scoped; the backends subtree below needs assimp visible
+# from this scope, not just inside the rl_tools subtree
+find_package(assimp REQUIRED)
+add_subdirectory(${RLTOOLS_ROOT} rl_tools EXCLUDE_FROM_ALL)
+# the resolved-backend variable is directory-scoped inside the rl_tools subtree, so the
+# backends dispatch needs it set again here
+set(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_RESOLVED ${HYPERDRONE_VARIANT})
+add_subdirectory(${RLTOOLS_ROOT}/src/rendering/raytracing/backends rl_tools_rt_backends EXCLUDE_FROM_ALL)
+
+include(FetchContent)
+FetchContent_Declare(
+    stb
+    GIT_REPOSITORY https://github.com/nothings/stb.git
+    GIT_TAG        f1c79c02822848a9bed4315b12c8c8f3761e1296
+    EXCLUDE_FROM_ALL
+)
+FetchContent_MakeAvailable(stb)
+add_library(hyperdrone_render_stb INTERFACE)
+target_include_directories(hyperdrone_render_stb SYSTEM INTERFACE ${stb_SOURCE_DIR})
+
+find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+execute_process(
+    COMMAND ${Python_EXECUTABLE} -m nanobind --cmake_dir
+    OUTPUT_VARIABLE nanobind_DIR
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    COMMAND_ERROR_IS_FATAL ANY
+)
+find_package(nanobind CONFIG REQUIRED)
+
+nanobind_add_module(hyperdrone_render_core host.cpp scene_bindings.cpp)
+target_include_directories(hyperdrone_render_core PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../common)
+target_link_libraries(hyperdrone_render_core PRIVATE RLtools::RLtools hyperdrone_render_stb ${CMAKE_DL_LIBS})
+set_target_properties(hyperdrone_render_core PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+if(HYPERDRONE_VARIANT STREQUAL "OPTIX")
+    find_package(CUDAToolkit REQUIRED)
+    target_link_libraries(hyperdrone_render_core PRIVATE CUDA::cudart)
+endif()
+
+# per-config JIT artifacts: the output mode selects the backend device-program library
+# (0=rgb 1=rgbd 2=depth 3=segmentation 4=rgbd_segmentation)
+function(hyperdrone_component_libraries DEFINES OUT_LIBRARIES)
+    hyperdrone_jit_parse_defines("${DEFINES}" CONFIG)
+    if(NOT DEFINED CONFIG_HYPERDRONE_RENDER_OUTPUT_MODE)
+        set(CONFIG_HYPERDRONE_RENDER_OUTPUT_MODE 0)
+    endif()
+    if(CONFIG_HYPERDRONE_RENDER_OUTPUT_MODE EQUAL 0)
+        set(${OUT_LIBRARIES} rendering_raytracing_backend PARENT_SCOPE)
+    elseif(CONFIG_HYPERDRONE_RENDER_OUTPUT_MODE EQUAL 1 OR CONFIG_HYPERDRONE_RENDER_OUTPUT_MODE EQUAL 2)
+        set(${OUT_LIBRARIES} rendering_raytracing_backend_depth PARENT_SCOPE)
+    else()
+        set(${OUT_LIBRARIES} rendering_raytracing_backend_segmentation PARENT_SCOPE)
+    endif()
+endfunction()
+
+include(${CMAKE_CURRENT_SOURCE_DIR}/../cmake/hyperdrone_jit.cmake)
+hyperdrone_jit_add_configs(
+    COMPONENT render
+    SOURCES impl.cpp
+    LINK RLtools::RLtools hyperdrone_render_stb
+)

hyperdrone/_native/render/host.cpp

@@ -0,0 +1,276 @@
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/array.h>
+#include <nanobind/stl/vector.h>
+
+// type-only include: the operations headers define non-inline functions and may appear in
+// only one translation unit of this module (scene_bindings.cpp)
+#include <rl_tools/rendering/raytracing/scene.h>
+
+#include "bindings.h"
+#include "iface.h"
+#include "jit_host.h"
+
+#include <stdexcept>
+#include <string>
+
+#if defined(RL_TOOLS_RENDERING_RAYTRACING_BACKEND_OPTIX)
+#include "cuda_staging.h"
+#define HYPERDRONE_RENDER_CORE_HAS_CUDA 1
+#else
+#define HYPERDRONE_RENDER_CORE_HAS_CUDA 0
+#endif
+
+namespace nb = nanobind;
+namespace rrt = rl_tools::rendering::raytracing;
+namespace hdr = hyperdrone::render;
+
+using hyperdrone::FloatArray;
+using hyperdrone::Transform;
+using hyperdrone::Vec3;
+using hyperdrone::extract_transform;
+using hyperdrone::make_owned_array;
+
+void register_scene_bindings(nb::module_& m);
+
+struct JitRenderer {
+    hyperdrone::JitInstance<hdr::Renderer> instance;
+
+    JitRenderer(const std::string& path, const std::string& expected_config)
+        : instance(path, "hyperdrone_render", HYPERDRONE_RENDER_IFACE_VERSION, expected_config) {}
+
+    hdr::Renderer* operator->() const { return instance.instance; }
+    hdr::Renderer& renderer() const { return *instance.instance; }
+
+    size_t pixel_count() const {
+        const hdr::Config c = renderer().config();
+        return (size_t)c.num_cameras * c.height * c.width;
+    }
+    void check_image_shape(size_t ndim, const size_t* shape) const {
+        const hdr::Config c = renderer().config();
+        if(ndim != 3 || shape[0] != c.num_cameras || shape[1] != c.height || shape[2] != c.width){
+            throw std::invalid_argument("hyperdrone: output array must have shape (num_cameras, height, width)");
+        }
+    }
+    void check_cameras_dims(size_t ndim, const int64_t* dims) const {
+        const hdr::Config c = renderer().config();
+        const bool flat = ndim == 2 && dims[0] == c.num_cameras && dims[1] == 12;
+        const bool structured = ndim == 3 && dims[0] == c.num_cameras && dims[1] == 4 && dims[2] == 3;
+        if(!flat && !structured){
+            throw std::invalid_argument("hyperdrone: cameras must have shape (num_cameras, 12) or (num_cameras, 4, 3) and dtype float32");
+        }
+    }
+    void check_cameras_shape(const FloatArray& cameras) const {
+        int64_t dims[3] = {0, 0, 0};
+        for(size_t dimension = 0; dimension < cameras.ndim() && dimension < 3; dimension++){
+            dims[dimension] = (int64_t)cameras.shape(dimension);
+        }
+        check_cameras_dims(cameras.ndim(), dims);
+    }
+};
+
+NB_MODULE(hyperdrone_render_core, m){
+    m.doc() = "hyperdrone render core: scene assembly and JIT renderer loader for the RLtools raytracer";
+
+    register_scene_bindings(m);
+
+    auto jit_renderer_class = nb::class_<JitRenderer>(m, "JitRenderer");
+    jit_renderer_class
+        .def(nb::init<const std::string&, const std::string&>(), nb::arg("library_path"), nb::arg("expected_config"))
+        .def_prop_ro("backend", [](const JitRenderer& jit){ return std::string(jit->backend()); })
+        .def("init", [](JitRenderer& jit, const rrt::Scene& scene, const rrt::AssetPool* pool){
+            nb::gil_scoped_release release;
+            jit->init(&scene, pool);
+        }, nb::arg("scene"), nb::arg("asset_pool").none() = nb::none(), nb::keep_alive<1, 2>(), nb::keep_alive<1, 3>())
+        .def("update", [](JitRenderer& jit){
+            nb::gil_scoped_release release;
+            jit->update();
+        })
+        .def("synchronize", [](JitRenderer& jit){
+            nb::gil_scoped_release release;
+            jit->synchronize();
+        })
+        .def("set_cameras", [](JitRenderer& jit, FloatArray cameras){
+            jit.check_cameras_shape(cameras);
+            jit->set_cameras(cameras.data());
+        }, nb::arg("cameras"))
+        .def("set_motion_blur_cameras", [](JitRenderer& jit, FloatArray cameras_open, FloatArray cameras_close){
+            jit.check_cameras_shape(cameras_open);
+            jit.check_cameras_shape(cameras_close);
+            jit->set_motion_blur_cameras(cameras_open.data(), cameras_close.data());
+        }, nb::arg("cameras_open"), nb::arg("cameras_close"))
+        .def("generate_cameras", [](JitRenderer& jit, Vec3 center, float radius, Vec3 up, float fov){
+            jit->generate_cameras(center.data(), radius, up.data(), fov);
+        }, nb::arg("center"), nb::arg("radius"), nb::arg("up"), nb::arg("fov"))
+        .def("generate_probe_directions", [](JitRenderer& jit){ jit->generate_probe_directions(); })
+        .def("render", [](JitRenderer& jit, int target, int phase){
+            nb::gil_scoped_release release;
+            jit->render((hdr::RenderTarget)target, (hdr::RenderPhase)phase);
+        }, nb::arg("target"), nb::arg("phase"))
+        .def("read_frame_buffer", [](JitRenderer& jit, nb::ndarray<uint32_t, nb::c_contig, nb::device::cpu> out){
+            size_t shape[3] = {(size_t)out.shape(0), out.ndim() > 1 ? (size_t)out.shape(1) : 0, out.ndim() > 2 ? (size_t)out.shape(2) : 0};
+            jit.check_image_shape(out.ndim(), shape);
+            nb::gil_scoped_release release;
+            jit->read_frame_buffer(out.data());
+        }, nb::arg("out"))
+        .def("read_depth_buffer", [](JitRenderer& jit, nb::ndarray<float, nb::c_contig, nb::device::cpu> out){
+            size_t shape[3] = {(size_t)out.shape(0), out.ndim() > 1 ? (size_t)out.shape(1) : 0, out.ndim() > 2 ? (size_t)out.shape(2) : 0};
+            jit.check_image_shape(out.ndim(), shape);
+            nb::gil_scoped_release release;
+            jit->read_depth_buffer(out.data());
+        }, nb::arg("out"))
+        .def("read_segmentation_buffer", [](JitRenderer& jit, nb::ndarray<uint32_t, nb::c_contig, nb::device::cpu> out){
+            size_t shape[3] = {(size_t)out.shape(0), out.ndim() > 1 ? (size_t)out.shape(1) : 0, out.ndim() > 2 ? (size_t)out.shape(2) : 0};
+            jit.check_image_shape(out.ndim(), shape);
+            nb::gil_scoped_release release;
+            jit->read_segmentation_buffer(out.data());
+        }, nb::arg("out"))
+        .def("read_collision_results", [](JitRenderer& jit, nb::ndarray<float, nb::c_contig, nb::device::cpu> distances, nb::ndarray<int32_t, nb::c_contig, nb::device::cpu> hits){
+            const hdr::Config config = jit->config();
+            const size_t expected = (size_t)config.num_cameras * config.num_probes;
+            if(distances.size() != expected || hits.size() != expected){
+                throw std::invalid_argument("hyperdrone: collision output arrays must have num_cameras * num_probes elements");
+            }
+            nb::gil_scoped_release release;
+            jit->read_collision_results(distances.data(), hits.data());
+        }, nb::arg("distances"), nb::arg("hits"))
+        .def("framebuffer_device_ptr", [](JitRenderer& jit){ return (uintptr_t)jit->framebuffer_device_ptr(); })
+        .def("depthbuffer_device_ptr", [](JitRenderer& jit){ return (uintptr_t)jit->depthbuffer_device_ptr(); })
+        .def("frame_view", [](JitRenderer& jit, bool refresh){
+            const hdr::Config c = jit->config();
+            uint32_t* pointer;
+            {
+                nb::gil_scoped_release release;
+                pointer = jit->frame_buffer_host(refresh);
+            }
+            return nb::ndarray<nb::numpy, uint32_t>(pointer, {c.num_cameras, c.height, c.width}, nb::find(&jit));
+        }, nb::arg("refresh") = true)
+        .def("depth_view", [](JitRenderer& jit, bool refresh){
+            const hdr::Config c = jit->config();
+            float* pointer;
+            {
+                nb::gil_scoped_release release;
+                pointer = jit->depth_buffer_host(refresh);
+            }
+            return nb::ndarray<nb::numpy, float>(pointer, {c.num_cameras, c.height, c.width}, nb::find(&jit));
+        }, nb::arg("refresh") = true)
+        .def("segmentation_view", [](JitRenderer& jit, bool refresh){
+            const hdr::Config c = jit->config();
+            uint32_t* pointer;
+            {
+                nb::gil_scoped_release release;
+                pointer = jit->segmentation_buffer_host(refresh);
+            }
+            return nb::ndarray<nb::numpy, uint32_t>(pointer, {c.num_cameras, c.height, c.width}, nb::find(&jit));
+        }, nb::arg("refresh") = true)
+        .def("frame_dlpack", [](JitRenderer& jit){
+            const hdr::Config c = jit->config();
+            uint32_t* pointer = jit->frame_buffer_live();
+            return nb::ndarray<>(pointer, {c.num_cameras, c.height, c.width}, nb::find(&jit), {},
+                                 nb::dtype<uint32_t>(), jit->buffer_device_type(), 0);
+        })
+        .def("depth_dlpack", [](JitRenderer& jit){
+            const hdr::Config c = jit->config();
+            float* pointer = jit->depth_buffer_live();
+            return nb::ndarray<>(pointer, {c.num_cameras, c.height, c.width}, nb::find(&jit), {},
+                                 nb::dtype<float>(), jit->buffer_device_type(), 0);
+        })
+        .def("buffer_device_type", [](JitRenderer& jit){ return jit->buffer_device_type(); })
+        .def("save", [](JitRenderer& jit, int target, const std::string& path){
+            nb::gil_scoped_release release;
+            jit->save((hdr::SaveTarget)target, path.c_str());
+        }, nb::arg("target"), nb::arg("path"))
+        .def("scene_bounds", [](JitRenderer& jit){
+            float center[3], half_extent[3], camera_radius;
+            jit->scene_bounds(center, half_extent, camera_radius);
+            return nb::make_tuple(make_owned_array(center, {3}), make_owned_array(half_extent, {3}), camera_radius);
+        })
+        .def("can_attach", [](JitRenderer& jit, size_t camera, size_t overlay){ return jit->can_attach(camera, overlay); })
+        .def("attach", [](JitRenderer& jit, size_t camera, size_t overlay){ jit->attach(camera, overlay); })
+        .def("detach", [](JitRenderer& jit, size_t camera, size_t overlay){ jit->detach(camera, overlay); })
+        .def("can_spawn", [](JitRenderer& jit, size_t overlay, size_t asset){ return jit->can_spawn(overlay, asset); })
+        .def("spawn", [](JitRenderer& jit, size_t overlay, size_t asset, Transform transform){
+            float values[12];
+            extract_transform(transform, values);
+            hdr::OverlayPlacementData placement = jit->spawn(overlay, asset, values);
+            return nb::make_tuple(placement.first_slot, placement.num_parts, placement.first_part);
+        }, nb::arg("overlay"), nb::arg("asset"), nb::arg("transform"))
+        .def("despawn", [](JitRenderer& jit, size_t overlay, std::array<size_t, 3> placement){
+            jit->despawn(overlay, hdr::OverlayPlacementData{placement[0], placement[1], placement[2]});
+        }, nb::arg("overlay"), nb::arg("placement"))
+        .def("set_transform", [](JitRenderer& jit, size_t overlay, std::array<size_t, 3> placement, Transform transform){
+            float values[12];
+            extract_transform(transform, values);
+            jit->set_transform(overlay, hdr::OverlayPlacementData{placement[0], placement[1], placement[2]}, values);
+        }, nb::arg("overlay"), nb::arg("placement"), nb::arg("transform"))
+        .def("set_part_transform", [](JitRenderer& jit, size_t overlay, std::array<size_t, 3> placement, size_t part, Transform transform){
+            float values[12];
+            extract_transform(transform, values);
+            jit->set_part_transform(overlay, hdr::OverlayPlacementData{placement[0], placement[1], placement[2]}, part, values);
+        }, nb::arg("overlay"), nb::arg("placement"), nb::arg("part"), nb::arg("transform"))
+        .def("set_transform_pair", [](JitRenderer& jit, size_t overlay, std::array<size_t, 3> placement, Transform open, Transform close){
+            float open_values[12], close_values[12];
+            extract_transform(open, open_values);
+            extract_transform(close, close_values);
+            jit->set_transform_pair(overlay, hdr::OverlayPlacementData{placement[0], placement[1], placement[2]}, open_values, close_values);
+        }, nb::arg("overlay"), nb::arg("placement"), nb::arg("open"), nb::arg("close"))
+        .def("set_part_transform_pair", [](JitRenderer& jit, size_t overlay, std::array<size_t, 3> placement, size_t part, Transform open, Transform close){
+            float open_values[12], close_values[12];
+            extract_transform(open, open_values);
+            extract_transform(close, close_values);
+            jit->set_part_transform_pair(overlay, hdr::OverlayPlacementData{placement[0], placement[1], placement[2]}, part, open_values, close_values);
+        }, nb::arg("overlay"), nb::arg("placement"), nb::arg("part"), nb::arg("open"), nb::arg("close"))
+        .def("set_transforms_pair", [](JitRenderer& jit, nb::ndarray<const float, nb::c_contig, nb::device::cpu> pairs){
+            const hdr::Config c = jit->config();
+            const size_t expected = (size_t)2 * c.num_overlays * c.max_overlay_instances * 12;
+            if(pairs.size() != expected){
+                throw std::invalid_argument("hyperdrone: transforms_pair must hold 2 * num_overlays * max_overlay_instances * 12 floats (open then close)");
+            }
+            jit->set_transforms_pair(pairs.data());
+        }, nb::arg("pairs"))
+        .def("transforms_pair_device_ptr", [](JitRenderer& jit){
+            return (uintptr_t)jit->transforms_pair_device_ptr();
+        })
+        .def("expand_motion_transforms", [](JitRenderer& jit){
+            jit->expand_motion_transforms();
+        });
+
+#if HYPERDRONE_RENDER_CORE_HAS_CUDA
+    m.attr("HAS_CUDA") = true;
+
+    hyperdrone::register_cuda_staging(m);
+
+    jit_renderer_class
+        .def("set_cameras_device", [](JitRenderer& jit, nb::ndarray<const float, nb::c_contig, nb::device::cuda> cameras, uintptr_t stream){
+            int64_t dims[3] = {0, 0, 0};
+            for(size_t dimension = 0; dimension < cameras.ndim() && dimension < 3; dimension++){
+                dims[dimension] = (int64_t)cameras.shape(dimension);
+            }
+            jit.check_cameras_dims(cameras.ndim(), dims);
+            jit->set_cameras_device(cameras.data(), stream);
+        }, nb::arg("cameras"), nb::arg("stream") = 0)
+        // benchmark fast path: index a pre-uploaded set without any per-call DLPack traffic
+        .def("set_cameras_from_cuda_buffer", [](JitRenderer& jit, hyperdrone::CudaBuffer& buffer, size_t index, uintptr_t stream){
+            const hdr::Config c = jit->config();
+            if(buffer.slice_elements() != (size_t)c.num_cameras * 12){
+                throw std::invalid_argument("hyperdrone: CudaBuffer slices must hold num_cameras * 12 floats");
+            }
+            jit->set_cameras_device(buffer.slice_pointer(index), stream);
+        }, nb::arg("buffer"), nb::arg("index"), nb::arg("stream") = 0)
+        .def("set_motion_blur_cameras_device", [](JitRenderer& jit, nb::ndarray<const float, nb::c_contig, nb::device::cuda> cameras_open, nb::ndarray<const float, nb::c_contig, nb::device::cuda> cameras_close, uintptr_t stream){
+            int64_t dims[3] = {0, 0, 0};
+            for(size_t dimension = 0; dimension < cameras_open.ndim() && dimension < 3; dimension++){
+                dims[dimension] = (int64_t)cameras_open.shape(dimension);
+            }
+            jit.check_cameras_dims(cameras_open.ndim(), dims);
+            for(size_t dimension = 0; dimension < cameras_close.ndim() && dimension < 3; dimension++){
+                dims[dimension] = (int64_t)cameras_close.shape(dimension);
+            }
+            jit.check_cameras_dims(cameras_close.ndim(), dims);
+            jit->set_motion_blur_cameras_device(cameras_open.data(), cameras_close.data(), stream);
+        }, nb::arg("cameras_open"), nb::arg("cameras_close"), nb::arg("stream") = 0);
+#else
+    m.attr("HAS_CUDA") = false;
+#endif
+}

hyperdrone/_native/render/iface.h

@@ -0,0 +1,132 @@
+#pragma once
+#include <cstdint>
+#include <cstddef>
+
+// ABI boundary between the hyperdrone render core module and the JIT-compiled renderer
+// libraries. Both sides are compiled from the same headers with the same compiler in the
+// same build tree, so passing rl_tools scene types by pointer is safe. Everything
+// renderer-spec dependent is hidden behind the vtable; buffer exchange uses raw pointers
+// sized by config(). Bump HYPERDRONE_RENDER_IFACE_VERSION on any change to this file.
+#define HYPERDRONE_RENDER_IFACE_VERSION 3
+
+namespace rl_tools { namespace rendering { namespace raytracing {
+    struct Scene;
+    struct AssetPool;
+}}}
+
+namespace hyperdrone::render {
+    struct Config {
+        uint32_t width;
+        uint32_t height;
+        uint32_t num_cameras;
+        uint32_t num_probes;
+        int shading;                    // 0=low 1=medium 2=high 3=veryhigh
+        int output_mode;                // 0=rgb 1=rgbd 2=depth 3=segmentation 4=rgbd_segmentation
+        uint32_t motion_blur_samples;   // 1 = disabled
+        uint32_t anti_aliasing_grid;    // 1 = disabled
+        uint32_t num_overlays;
+        uint32_t max_overlay_instances;
+        uint32_t max_overlays_per_camera;
+        bool semantic_segmentation;
+        bool dynamic_motion_blur;
+    };
+
+    enum class RenderTarget : int {
+        ALL = 0,
+        RGB = 1,
+        DEPTH = 2,
+        SEGMENTATION = 3,
+        RGB_DEPTH = 4,
+        COLLISION = 5
+    };
+    enum class RenderPhase : int {
+        LAUNCH = 0,
+        SYNC = 1,
+        FULL = 2
+    };
+    enum class SaveTarget : int {
+        IMAGE = 0,
+        DEPTH_IMAGE = 1,
+        DEPTH_RAW = 2,
+        SEGMENTATION_IMAGE = 3,
+        PROBES = 4
+    };
+
+    struct OverlayPlacementData {
+        size_t first_slot;
+        size_t num_parts;
+        size_t first_part;
+    };
+
+    class Renderer {
+    public:
+        virtual ~Renderer() = default;
+        virtual Config config() const = 0;
+        virtual const char* backend() const = 0;
+
+        virtual void init(const rl_tools::rendering::raytracing::Scene* scene, const rl_tools::rendering::raytracing::AssetPool* pool) = 0;
+        virtual void update() = 0;
+        virtual void synchronize() = 0;
+
+        virtual void set_cameras(const float* cameras) = 0; // num_cameras * 12 floats (pos, dir_00, dir_du, dir_dv)
+        // cameras in CUDA device memory, same packed layout; producer_stream (a
+        // cudaStream_t handle, 0 = none) is awaited via an event on the render stream —
+        // no host synchronization. OptiX backend only.
+        virtual void set_cameras_device(const float* cameras, unsigned long long producer_stream) = 0;
+        virtual void set_motion_blur_cameras(const float* cameras_open, const float* cameras_close) = 0;
+        virtual void generate_cameras(const float center[3], float radius, const float up[3], float fov) = 0;
+        virtual void generate_probe_directions() = 0;
+
+        virtual void render(RenderTarget target, RenderPhase phase) = 0;
+
+        virtual void read_frame_buffer(uint32_t* dst) = 0;        // num_cameras * height * width
+        virtual void read_depth_buffer(float* dst) = 0;           // num_cameras * height * width
+        virtual void read_segmentation_buffer(uint32_t* dst) = 0; // num_cameras * height * width
+        virtual void read_collision_results(float* distances, int32_t* hits) = 0; // num_cameras * num_probes each
+        virtual uint32_t* framebuffer_device_ptr() = 0;
+        virtual float* depthbuffer_device_ptr() = 0;
+
+        // zero-copy access. The live buffers are where rendering writes (CUDA device memory
+        // on OptiX, CPU-visible memory elsewhere) and are valid after the corresponding
+        // sync; the host buffers are the renderer-owned staging tensors, optionally
+        // refreshed from the backend first.
+        virtual int buffer_device_type() const = 0; // DLPack device type: 1 = kDLCPU, 2 = kDLCUDA
+        virtual uint32_t* frame_buffer_live() = 0;
+        virtual float* depth_buffer_live() = 0;
+        virtual uint32_t* frame_buffer_host(bool refresh) = 0;
+        virtual float* depth_buffer_host(bool refresh) = 0;
+        virtual uint32_t* segmentation_buffer_host(bool refresh) = 0;
+
+        virtual void save(SaveTarget target, const char* path) = 0;
+
+        virtual void scene_bounds(float center[3], float half_extent[3], float& camera_radius) const = 0;
+
+        virtual bool can_attach(size_t camera, size_t overlay) = 0;
+        virtual void attach(size_t camera, size_t overlay) = 0;
+        virtual void detach(size_t camera, size_t overlay) = 0;
+        virtual bool can_spawn(size_t overlay, size_t asset) = 0;
+        virtual OverlayPlacementData spawn(size_t overlay, size_t asset, const float transform[12]) = 0;
+        virtual void despawn(size_t overlay, const OverlayPlacementData& placement) = 0;
+        virtual void set_transform(size_t overlay, const OverlayPlacementData& placement, const float transform[12]) = 0;
+        virtual void set_part_transform(size_t overlay, const OverlayPlacementData& placement, size_t part, const float transform[12]) = 0;
+        // dynamic motion blur: shutter-open/close transforms, slerped across the motion samples
+        virtual void set_transform_pair(size_t overlay, const OverlayPlacementData& placement, const float open[12], const float close[12]) = 0;
+        virtual void set_part_transform_pair(size_t overlay, const OverlayPlacementData& placement, size_t part, const float open[12], const float close[12]) = 0;
+        // GPU-resident producer path: cameras_open/cameras_close in CUDA device memory (OptiX
+        // only), the whole transforms_pair tensor ([2][num_overlays*max_instances][12] entries,
+        // open then close), and the on-device expansion into the per-sample slabs
+        virtual void set_motion_blur_cameras_device(const float* cameras_open, const float* cameras_close, unsigned long long producer_stream) = 0;
+        virtual void set_transforms_pair(const float* pairs) = 0;
+        virtual float* transforms_pair_device_ptr() = 0;
+        virtual void expand_motion_transforms() = 0;
+    };
+}
+
+extern "C" {
+    hyperdrone::render::Renderer* hyperdrone_render_create();
+    void hyperdrone_render_destroy(hyperdrone::render::Renderer* renderer);
+    // canonical config string baked at compile time; the loader compares it against the
+    // requested configuration to catch stale or mislabeled cache entries
+    const char* hyperdrone_render_config_string();
+    int hyperdrone_render_iface_version();
+}