ernie-renderer 0.2.0.dev117__tar.gz → 0.2.0.dev119__tar.gz

{ernie_renderer-0.2.0.dev117 → ernie_renderer-0.2.0.dev119}/CMakeLists.txt

@@ -15,7 +15,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev117" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev119" 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)
@@ -54,6 +54,7 @@ include(cmake/ErnieFetch.cmake)
 include(cmake/third_party/openexr.cmake)
 include(cmake/third_party/tracy.cmake)
 include(cmake/third_party/slang.cmake)
+include(cmake/ErnieShaders.cmake)
 add_subdirectory(third_party)
 
 add_library(ernie_build_options INTERFACE)

{ernie_renderer-0.2.0.dev117 → ernie_renderer-0.2.0.dev119}/Dockerfile

@@ -17,6 +17,8 @@ RUN apt-get update \
     && apt-get install -y --no-install-recommends libvulkan1 mesa-vulkan-drivers \
     && rm -rf /var/lib/apt/lists/*
 COPY --from=build /opt/ernie/bin/ernie /usr/local/bin/ernie
+# Its private libraries, as Slang's compiler, where its rpath ($ORIGIN/../lib/ernie) looks.
+COPY --from=build /opt/ernie/lib/ernie /usr/local/lib/ernie
 # Data and the licences of everything the program carries.
 COPY --from=build /opt/ernie/share /usr/local/share
 ENV NVIDIA_DRIVER_CAPABILITIES=graphics,compute,utility

{ernie_renderer-0.2.0.dev117 → ernie_renderer-0.2.0.dev119}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev117
+Version: 0.2.0.dev119
 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.dev119/cmake/EmbedShader.cmake

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Embeds one Slang file in a header as an ernie::ShaderModule
+file(READ "${INPUT}" source)
+string(FIND "${source}" ")slang\"" delimiter)
+if(NOT delimiter EQUAL -1)
+    message(FATAL_ERROR "${INPUT} holds )slang\", which ends the raw string it is embedded in")
+endif()
+
+string(REPLACE "_" ";" words "${NAME}")
+set(identifier "k")
+foreach(word IN LISTS words)
+    string(SUBSTRING "${word}" 0 1 first)
+    string(SUBSTRING "${word}" 1 -1 rest)
+    string(TOUPPER "${first}" first)
+    string(APPEND identifier "${first}${rest}")
+endforeach()
+
+set(chunks "")
+string(LENGTH "${source}" length)
+set(chunk 8192)
+set(at 0)
+while(at LESS length)
+    string(SUBSTRING "${source}" ${at} ${chunk} piece)
+    string(APPEND chunks "    R\"slang(${piece})slang\"\n")
+    math(EXPR at "${at} + ${chunk}")
+endwhile()
+if(chunks STREQUAL "")
+    set(chunks "    \"\"\n")
+endif()
+
+file(RELATIVE_PATH from "${ROOT}" "${INPUT}")
+set(header
+    "// Generated from ${from} by cmake/EmbedShader.cmake: edit that file.\n#pragma once\n\n#include \"ernie/device/shader_compiler.h\"\n\nnamespace ernie::shaders {\n\ninline const ShaderModule ${identifier}{\n    \"${NAME}\",\n${chunks}};\n\n}  // namespace ernie::shaders\n"
+)
+# Unchanged headers keep their times, so nothing that includes them rebuilds.
+if(EXISTS "${OUTPUT}")
+    file(READ "${OUTPUT}" previous)
+    if(previous STREQUAL header)
+        return()
+    endif()
+endif()
+file(WRITE "${OUTPUT}" "${header}")

ernie_renderer-0.2.0.dev119/cmake/ErnieShaders.cmake

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Slang shaders kept in .slang files and embedded in the library, so editors highlight and
+# resolve them and the program needs no files beside it.
+#
+#     ernie_add_shaders(ernie_render shaders/affine.slang shaders/world.slang)
+#     // In C++: #include "ernie/render/shaders/affine.h" for ernie::shaders::kAffine.
+
+# Builds each file's header beside its path under the build's include directory, before the
+# target compiles.
+function(ernie_add_shaders target)
+    set(headers "")
+    foreach(file IN LISTS ARGN)
+        get_filename_component(source "${file}" ABSOLUTE)
+        get_filename_component(name "${file}" NAME_WE)
+        file(RELATIVE_PATH relative "${PROJECT_SOURCE_DIR}" "${source}")
+        string(REGEX REPLACE "\\.slang$" ".h" relative "${relative}")
+        set(header "${PROJECT_BINARY_DIR}/include/${relative}")
+        add_custom_command(
+            OUTPUT "${header}"
+            COMMAND
+                "${CMAKE_COMMAND}" "-DINPUT=${source}" "-DOUTPUT=${header}" "-DNAME=${name}"
+                "-DROOT=${PROJECT_SOURCE_DIR}" -P "${PROJECT_SOURCE_DIR}/cmake/EmbedShader.cmake"
+            DEPENDS "${source}" "${PROJECT_SOURCE_DIR}/cmake/EmbedShader.cmake"
+            COMMENT "Embedding ${relative}"
+            VERBATIM
+        )
+        list(APPEND headers "${header}")
+    endforeach()
+    target_sources(${target} PRIVATE ${headers})
+endfunction()

{ernie_renderer-0.2.0.dev117 → ernie_renderer-0.2.0.dev119}/ernie/render/CMakeLists.txt

@@ -7,10 +7,22 @@ add_library(
     geometry.cpp
     instances.cpp
     prim_rows.cpp
+    ray_tracer.cpp
     scene_columns.cpp
     top_levels.cpp
     transform_graph.cpp
 )
+ernie_add_shaders(
+    ernie_render
+    shaders/affine.slang
+    shaders/compose.slang
+    shaders/double_float.slang
+    shaders/local.slang
+    shaders/ray_tracer.slang
+    shaders/shapes.slang
+    shaders/world.slang
+    shaders/write_instances.slang
+)
 target_link_libraries(
     ernie_render
     PUBLIC ernie_geometry ernie_scene ernie_graph

ernie_renderer-0.2.0.dev119/ernie/render/ray_tracer.cpp

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file ray_tracer.cpp
+/// @brief The tracing modules: the geometry kinds generated from `GeometryKind`, then the shapes
+/// and ray tracer embedded from their .slang files.
+#include "ernie/render/ray_tracer.h"
+
+#include "ernie/render/geometry.h"
+#include "ernie/render/shaders/ray_tracer.h"
+#include "ernie/render/shaders/shapes.h"
+
+#include <array>
+#include <string>
+
+namespace ernie {
+namespace {
+
+/// The geometry kinds as the shaders name them, from `GeometryKind`.
+ShaderModule KindsModule() {
+    std::string source;
+    const auto kind = [&](const char* name, GeometryKind value) {
+        source += std::string("public static const uint ") + name + " = " +
+                  std::to_string(static_cast<std::uint32_t>(value)) + ";\n";
+    };
+    kind("kTriangles", GeometryKind::Triangles);
+    kind("kSphere", GeometryKind::Sphere);
+    kind("kCube", GeometryKind::Cube);
+    kind("kCylinder", GeometryKind::Cylinder);
+    kind("kCone", GeometryKind::Cone);
+    kind("kCapsule", GeometryKind::Capsule);
+    kind("kPlane", GeometryKind::Plane);
+    return {"geometry_kinds", std::move(source)};
+}
+
+}  // namespace
+
+std::span<const ShaderModule> RayTracerModules() {
+    static const std::array modules{KindsModule(), shaders::kShapes, shaders::kRayTracer};
+    return modules;
+}
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev119/ernie/render/ray_tracer.h

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file ray_tracer.h
+/// @brief The Slang modules every tracing kernel imports: `IRayTracer`, the one interface passes
+/// trace through whatever backend answers it, its hardware ray-query backend, and the exact
+/// intersections of the implicit shapes.
+///
+///     import ray_tracer;
+///     HardwareRayQuery tracer = { parameters.scene, parameters.records };
+///     Hit hit = tracer.TraceClosest(ray, 0xff);
+///     if (hit.found) { float3 n = WorldNormal(hit, parameters.records); }
+#pragma once
+
+#include "ernie/device/shader_compiler.h"
+
+#include <span>
+
+namespace ernie {
+
+/// @return The modules, in import order, a tracing kernel compiles with: the geometry kinds,
+/// `shapes` (unit shapes intersected in their own frame) and `ray_tracer`.
+std::span<const ShaderModule> RayTracerModules();
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev119/ernie/render/shaders/affine.slang

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file affine.slang
+/// @brief 3x4 affine transforms as float rows: identity, loads, stores and products.
+
+/// A 3x4 affine transform's rows; its fourth row is (0, 0, 0, 1).
+public struct Affine {
+    public float4 rows[3];
+};
+
+public Affine Identity() {
+    Affine m;
+    m.rows[0] = float4(1, 0, 0, 0);
+    m.rows[1] = float4(0, 1, 0, 0);
+    m.rows[2] = float4(0, 0, 1, 0);
+    return m;
+}
+
+public Affine Load(float4* matrices, uint index) {
+    Affine m;
+    for (uint r = 0; r < 3; ++r) {
+        m.rows[r] = matrices[3 * index + r];
+    }
+    return m;
+}
+
+public void Store(float4* matrices, uint index, Affine m) {
+    for (uint r = 0; r < 3; ++r) {
+        matrices[3 * index + r] = m.rows[r];
+    }
+}
+
+public Affine Mul(Affine a, Affine b) {
+    Affine c;
+    for (uint r = 0; r < 3; ++r) {
+        float4 row = a.rows[r];
+        c.rows[r] = row.x * b.rows[0] + row.y * b.rows[1] + row.z * b.rows[2] +
+                    float4(0, 0, 0, row.w);
+    }
+    return c;
+}

ernie_renderer-0.2.0.dev119/ernie/render/shaders/compose.slang

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file compose.slang
+/// @brief One level of the transform graph: each node's world from its parent's and its local, in
+/// double-float.
+import affine;
+import double_float;
+// The op kinds and program layout, generated from transform_graph.cpp's constants.
+import ops;
+
+struct Parameters { uint* slots; uint* parents; float4* locals; float4* worlds; uint count; };
+[[vk::push_constant]] ConstantBuffer<Parameters> parameters;
+
+[shader("compute")]
+[numthreads(64, 1, 1)]
+void main(uint3 id : SV_DispatchThreadID) {
+    if (id.x >= parameters.count) {
+        return;
+    }
+    uint slot = parameters.slots[id.x];
+    uint parent = parameters.parents[slot];
+    DoubleAffine local = LoadDouble(parameters.locals, slot);
+    StoreDouble(parameters.worlds, slot,
+                parent == kNone ? local : Mul(LoadDouble(parameters.worlds, parent), local));
+}

ernie_renderer-0.2.0.dev119/ernie/render/shaders/double_float.slang

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file double_float.slang
+/// @brief Double-float arithmetic after Dekker (1971) and Hida, Li and Bailey's QD library (2001):
+/// error-free sums and Veltkamp-split products, about 48 bits of mantissa from pairs of floats.
+/// `precise` keeps every step as written (SPIR-V NoContraction).
+import affine;
+
+/// Four values, each the unevaluated sum of a high float and a low one.
+public struct Double4 {
+    public float4 hi;
+    public float4 lo;
+};
+
+Double4 Pair(float4 hi, float4 lo) {
+    Double4 d;
+    d.hi = hi;
+    d.lo = lo;
+    return d;
+}
+
+/// The sum and its rounding error, for any a and b.
+Double4 TwoSum(float4 a, float4 b) {
+    precise float4 s = a + b;
+    precise float4 v = s - a;
+    precise float4 e = (a - (s - v)) + (b - v);
+    return Pair(s, e);
+}
+
+/// The sum renormalised, for |a| >= |b|.
+Double4 QuickTwoSum(float4 a, float4 b) {
+    precise float4 s = a + b;
+    precise float4 e = b - (s - a);
+    return Pair(s, e);
+}
+
+public Double4 Add(Double4 a, Double4 b) {
+    Double4 s = TwoSum(a.hi, b.hi);
+    precise float4 e = s.lo + (a.lo + b.lo);
+    return QuickTwoSum(s.hi, e);
+}
+
+/// Veltkamp's split of each float into two 12-bit halves, whose products are exact.
+void Halves(float4 a, out float4 high, out float4 low) {
+    precise float4 c = 4097.0 * a;
+    precise float4 big = c - a;
+    precise float4 h = c - big;
+    precise float4 l = a - h;
+    high = h;
+    low = l;
+}
+
+/// The product and its rounding error, without fused multiply-adds: Vulkan and WebGPU do not
+/// promise `fma` rounds once.
+Double4 TwoProduct(float4 a, float4 b) {
+    float4 ah, al, bh, bl;
+    Halves(a, ah, al);
+    Halves(b, bh, bl);
+    precise float4 p = a * b;
+    precise float4 e = ((ah * bh - p) + ah * bl + al * bh) + al * bl;
+    return Pair(p, e);
+}
+
+/// `a` times the double-float scalar `hi + lo`.
+public Double4 Scale(Double4 a, float hi, float lo) {
+    Double4 p = TwoProduct(a.hi, float4(hi));
+    precise float4 e = p.lo + (a.hi * lo + a.lo * hi);
+    return QuickTwoSum(p.hi, e);
+}
+
+/// A 3x4 affine transform's rows in double-float.
+public struct DoubleAffine {
+    public Double4 rows[3];
+};
+
+public DoubleAffine Promote(Affine m) {
+    DoubleAffine d;
+    for (uint r = 0; r < 3; ++r) {
+        d.rows[r] = Pair(m.rows[r], float4(0));
+    }
+    return d;
+}
+
+public DoubleAffine Mul(DoubleAffine a, DoubleAffine b) {
+    DoubleAffine c;
+    for (uint r = 0; r < 3; ++r) {
+        Double4 row = a.rows[r];
+        Double4 sum = Pair(float4(0, 0, 0, row.hi.w), float4(0, 0, 0, row.lo.w));
+        sum = Add(sum, Scale(b.rows[0], row.hi.x, row.lo.x));
+        sum = Add(sum, Scale(b.rows[1], row.hi.y, row.lo.y));
+        c.rows[r] = Add(sum, Scale(b.rows[2], row.hi.z, row.lo.z));
+    }
+    return c;
+}
+
+/// Six float4 a transform: its high rows, then its low rows.
+public DoubleAffine LoadDouble(float4* matrices, uint index) {
+    DoubleAffine m;
+    for (uint r = 0; r < 3; ++r) {
+        m.rows[r] = Pair(matrices[6 * index + r], matrices[6 * index + 3 + r]);
+    }
+    return m;
+}
+
+public void StoreDouble(float4* matrices, uint index, DoubleAffine m) {
+    for (uint r = 0; r < 3; ++r) {
+        matrices[6 * index + r] = m.rows[r].hi;
+        matrices[6 * index + 3 + r] = m.rows[r].lo;
+    }
+}
+
+public Affine Round(DoubleAffine m) {
+    Affine f;
+    for (uint r = 0; r < 3; ++r) {
+        f.rows[r] = m.rows[r].hi + m.rows[r].lo;
+    }
+    return f;
+}

ernie_renderer-0.2.0.dev119/ernie/render/shaders/local.slang

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file local.slang
+/// @brief The transform graph's local transforms: each programmed node's ops evaluated in
+/// double-float, bound ops read in place from the columns CUDA, Warp or kernels write.
+import affine;
+import double_float;
+// The op kinds and program layout, generated from transform_graph.cpp's constants.
+import ops;
+
+struct Op { uint kind; uint flags; float* source; float4 hi[3]; float4 lo[3]; };
+struct Parameters { uint* slots; Op* programs; uint* lengths; float4* locals; uint count; };
+[[vk::push_constant]] ConstantBuffer<Parameters> parameters;
+
+static const uint3 kAxes[6] = { uint3(0, 1, 2), uint3(0, 2, 1), uint3(1, 0, 2),
+                                uint3(1, 2, 0), uint3(2, 0, 1), uint3(2, 1, 0) };
+
+/// A right-handed turn about one axis, as the host's AxisRotation builds it.
+Affine Turn(uint axis, float degrees) {
+    float c = cos(radians(degrees));
+    float s = sin(radians(degrees));
+    uint a = (axis + 1) % 3;
+    uint b = (axis + 2) % 3;
+    Affine m = Identity();
+    m.rows[a][a] = c;
+    m.rows[a][b] = -s;
+    m.rows[b][a] = s;
+    m.rows[b][b] = c;
+    return m;
+}
+
+Affine Inverse(Affine m) {
+    float3 a = m.rows[0].xyz;
+    float3 b = m.rows[1].xyz;
+    float3 c = m.rows[2].xyz;
+    float3 r0 = cross(b, c);
+    float3 r1 = cross(c, a);
+    float3 r2 = cross(a, b);
+    float invDet = 1 / dot(a, r0);
+    // The inverse's columns are the cofactor rows over the determinant.
+    float3x3 inv = transpose(float3x3(r0, r1, r2)) * invDet;
+    float3 t = float3(m.rows[0].w, m.rows[1].w, m.rows[2].w);
+    float3 back = -mul(inv, t);
+    Affine result;
+    for (uint r = 0; r < 3; ++r) {
+        result.rows[r] = float4(inv[r], back[r]);
+    }
+    return result;
+}
+
+/// A bound op's matrix from the floats it reads.
+Affine OpMatrix(Op op) {
+    Affine m = Identity();
+    float* v = op.source;
+    uint floats = (op.flags >> kFloatsShift) & 0xff;
+    if (op.kind == kTranslate) {
+        m.rows[0].w = v[0];
+        m.rows[1].w = v[1];
+        m.rows[2].w = v[2];
+    } else if (op.kind == kScale) {
+        float3 s = floats == 1 ? float3(v[0]) : float3(v[0], v[1], v[2]);
+        m.rows[0].x = s.x;
+        m.rows[1].y = s.y;
+        m.rows[2].z = s.z;
+    } else if (op.kind < kRotateXYZ) {
+        m = Turn(op.kind - kRotateX, v[0]);
+    } else if (op.kind < kOrient) {
+        // The order's first axis turns first: R = Rk * Rj * Ri, each by its own axis' angle.
+        uint3 axes = kAxes[op.kind - kRotateXYZ];
+        m = Mul(Mul(Turn(axes.z, v[axes.z]), Turn(axes.y, v[axes.y])),
+                Turn(axes.x, v[axes.x]));
+    } else if (op.kind == kOrient) {
+        float4 q = normalize(float4(v[0], v[1], v[2], v[3]));
+        m.rows[0] = float4(1 - 2 * (q.y * q.y + q.z * q.z), 2 * (q.x * q.y - q.z * q.w),
+                           2 * (q.x * q.z + q.y * q.w), 0);
+        m.rows[1] = float4(2 * (q.x * q.y + q.z * q.w), 1 - 2 * (q.x * q.x + q.z * q.z),
+                           2 * (q.y * q.z - q.x * q.w), 0);
+        m.rows[2] = float4(2 * (q.x * q.z - q.y * q.w), 2 * (q.y * q.z + q.x * q.w),
+                           1 - 2 * (q.x * q.x + q.y * q.y), 0);
+    } else {
+        // Column-major, as the scene's matrices are.
+        for (uint r = 0; r < 3; ++r) {
+            m.rows[r] = float4(v[r], v[4 + r], v[8 + r], v[12 + r]);
+        }
+    }
+    return (op.flags & kInvert) != 0 ? Inverse(m) : m;
+}
+
+/// An op's matrix: a folded constant exactly as the host split it, a bound op from its floats.
+DoubleAffine OpDoubleMatrix(Op op) {
+    if (op.kind != kConstant) {
+        return Promote(OpMatrix(op));
+    }
+    DoubleAffine m;
+    for (uint r = 0; r < 3; ++r) {
+        m.rows[r].hi = op.hi[r];
+        m.rows[r].lo = op.lo[r];
+    }
+    return m;
+}
+
+/// One thread a programmed node, its program at its place in the list.
+[shader("compute")]
+[numthreads(64, 1, 1)]
+void main(uint3 id : SV_DispatchThreadID) {
+    uint at = id.x;
+    if (at >= parameters.count) {
+        return;
+    }
+    DoubleAffine local = Promote(Identity());
+    for (uint k = 0; k < parameters.lengths[at]; ++k) {
+        local = Mul(local, OpDoubleMatrix(parameters.programs[at * kMaxOps + k]));
+    }
+    StoreDouble(parameters.locals, parameters.slots[at], local);
+}

ernie_renderer-0.2.0.dev119/ernie/render/shaders/ray_tracer.slang

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file ray_tracer.slang
+/// @brief `IRayTracer`, the one interface passes trace through whatever backend answers it, and
+/// its hardware ray-query backend.
+// The geometry kinds, generated from GeometryKind in ray_tracer.cpp.
+import geometry_kinds;
+import shapes;
+
+/// A geometry's record, as the C++ `GeometryRecord`: an instance's custom index finds it.
+public struct GeometryRecord {
+    public uint kind;
+    public float halfLength;
+    public uint vertexCount;
+    public uint triangleCount;
+    public float* vertices;
+    public uint* indices;
+};
+
+/// What a ray hit: where along it, which instance, primitive and geometry, and the transforms
+/// between the instance's frame and the scene's. Surfaces are reconstructed from it.
+public struct Hit {
+    public bool found;
+    public float t;
+    /// The instance's row: `InstanceIndex()`.
+    public uint instance;
+    public uint primitive;
+    public uint geometry;
+    public float2 barycentrics;
+    /// An implicit shape's outward normal, in its own frame.
+    public float3 objectNormal;
+    public float3x4 objectToWorld;
+    public float3x4 worldToObject;
+};
+
+/// The one interface every pass traces through, whichever backend answers it.
+public interface IRayTracer {
+    /// @return The nearest hit along the ray among instances in `mask`.
+    Hit TraceClosest(RayDesc ray, uint mask);
+    /// @return Whether anything in `mask` blocks the ray, for visibility.
+    bool TraceAny(RayDesc ray, uint mask);
+}
+
+/// Ray queries against a hardware top level, by its device address.
+public struct HardwareRayQuery : IRayTracer {
+    public uint64_t scene;
+    public GeometryRecord* records;
+
+    /// Runs the query, solving each procedural candidate exactly; `Flags` may end it at the first
+    /// hit. NVIDIA's compiler fails on `CandidateObjectRay*`: the object ray comes from the
+    /// candidate's matrix instead.
+    void Run<let Flags : int>(inout RayQuery<Flags> query, RayDesc ray, uint mask,
+                              out ShapeHit nearest) {
+        query.TraceRayInline(RaytracingAccelerationStructure(scene), RAY_FLAG_NONE, mask, ray);
+        nearest.t = ray.TMax;
+        nearest.normal = float3(0, 0, 1);
+        while (query.Proceed()) {
+            if (query.CandidateType() != CANDIDATE_PROCEDURAL_PRIMITIVE) {
+                continue;
+            }
+            GeometryRecord record = records[query.CandidateInstanceID()];
+            float3x4 toObject = query.CandidateWorldToObject3x4();
+            float3 o = mul(toObject, float4(query.WorldRayOrigin(), 1));
+            float3 d = mul(toObject, float4(query.WorldRayDirection(), 0));
+            // Object-space distances along the transformed direction are the ray's own.
+            ShapeHit hit = nearest;
+            hit.t = query.CommittedRayT();
+            if (IntersectShape(record.kind, record.halfLength, o, d, ray.TMin, hit)) {
+                query.CommitProceduralPrimitiveHit(hit.t);
+                nearest = hit;
+            }
+        }
+    }
+
+    public Hit TraceClosest(RayDesc ray, uint mask) {
+        RayQuery<RAY_FLAG_NONE> query;
+        ShapeHit nearest;
+        Run(query, ray, mask, nearest);
+        Hit hit;
+        uint status = query.CommittedStatus();
+        hit.found = status != COMMITTED_NOTHING;
+        hit.t = query.CommittedRayT();
+        hit.instance = hit.found ? query.CommittedInstanceIndex() : 0;
+        hit.primitive = hit.found ? query.CommittedPrimitiveIndex() : 0;
+        hit.geometry = hit.found ? query.CommittedInstanceID() : 0;
+        hit.barycentrics = status == COMMITTED_TRIANGLE_HIT ? query.CommittedTriangleBarycentrics()
+                                                            : float2(0);
+        hit.objectNormal = nearest.normal;
+        hit.objectToWorld = query.CommittedObjectToWorld3x4();
+        hit.worldToObject = query.CommittedWorldToObject3x4();
+        return hit;
+    }
+
+    public bool TraceAny(RayDesc ray, uint mask) {
+        RayQuery<RAY_FLAG_ACCEPT_FIRST_HIT_AND_END_SEARCH> query;
+        ShapeHit nearest;
+        Run(query, ray, mask, nearest);
+        return query.CommittedStatus() != COMMITTED_NOTHING;
+    }
+}
+
+/// @return The surface's geometric normal at a hit, in the scene's frame, facing out of an
+/// implicit shape or by a triangle's winding.
+public float3 WorldNormal(Hit hit, GeometryRecord* records) {
+    float3 normal = hit.objectNormal;
+    GeometryRecord record = records[hit.geometry];
+    if (record.kind == kTriangles) {
+        uint* corners = record.indices + 3 * hit.primitive;
+        float3 p[3];
+        for (uint i = 0; i < 3; ++i) {
+            float* v = record.vertices + 3 * corners[i];
+            p[i] = float3(v[0], v[1], v[2]);
+        }
+        normal = cross(p[1] - p[0], p[2] - p[0]);
+    }
+    // Normals take the inverse transpose: a row vector times the world-to-object matrix.
+    return normalize(mul(normal, (float3x3)hit.worldToObject));
+}