ernie-renderer 0.2.0.dev52__tar.gz → 0.2.0.dev70__tar.gz

{ernie_renderer-0.2.0.dev52 → ernie_renderer-0.2.0.dev70}/.github/workflows/ci.yml

@@ -70,7 +70,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-24.04, windows-2025, macos-15]
+        os: [ubuntu-24.04, windows-2025, macos-26]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -107,10 +107,13 @@ jobs:
             "-DCMAKE_PREFIX_PATH=$prefix"
           cmake --build build/consumer
           PATH="$prefix/bin:$PATH" ctest --test-dir build/consumer --output-on-failure
-      # The build tree without objects, for this platform's test job; tar keeps file modes.
+      # The build tree without objects, and the Slang runtime its programs load from the fetched
+      # release, for this platform's test job; tar keeps file modes.
       - name: Pack the build tree
         shell: bash
-        run: tar --exclude='*.o' --exclude='*.obj' -cf build-ci.tar build/ci
+        run: |
+          shopt -s nullglob
+          tar --exclude='*.o' --exclude='*.obj' -cf build-ci.tar build/ci .deps/slang-src/lib*/libslang*
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: build-${{ matrix.os }}
@@ -126,7 +129,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-24.04, windows-2025, macos-15]
+        os: [ubuntu-24.04, windows-2025, macos-26]
     env:
       ERNIE_TEST_REQUIRE_VULKAN: "1"
     steps:
@@ -288,7 +291,7 @@ jobs:
           - { platform: linux-x86_64, runner: ubuntu-24.04 }
           - { platform: linux-aarch64, runner: ubuntu-24.04-arm }
           - { platform: windows-amd64, runner: windows-2025 }
-          - { platform: macos-arm64, runner: macos-15 }
+          - { platform: macos-arm64, runner: macos-26 }
     env:
       CIBW_BUILD: ${{ matrix.python }}-*
     steps:
@@ -357,15 +360,20 @@ jobs:
           dnf install -y -q rpm-build
           command -v ninja >/dev/null || pipx install -q ninja
       # One build; each format installs the library where its distributions look for it, as the
-      # build image (RHEL's lib64) is not where Debian and Ubuntu look.
+      # build image (RHEL's lib64) is not where Debian and Ubuntu look. The program relinks for
+      # each, as the path to the library is in its RPATH.
       - name: Build
         run: |
           cmake --preset package
-          cmake --build --preset package --parallel 4
           cd build/package
-          cmake "-DCMAKE_INSTALL_LIBDIR=lib/$(uname -m)-linux-gnu" . && cpack -G DEB
-          cmake -DCMAKE_INSTALL_LIBDIR=lib64 . && cpack -G RPM
-          cmake -DCMAKE_INSTALL_LIBDIR=lib . && cpack -G TGZ
+          package() {
+            cmake "-DCMAKE_INSTALL_LIBDIR=$1" .
+            cmake --build . --parallel 4
+            cpack -G "$2"
+          }
+          package "lib/$(uname -m)-linux-gnu" DEB
+          package lib64 RPM
+          package lib TGZ
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: packages-linux-${{ matrix.arch }}

{ernie_renderer-0.2.0.dev52 → ernie_renderer-0.2.0.dev70}/CMakeLists.txt

@@ -15,7 +15,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev52" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev70" 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)
@@ -60,6 +60,8 @@ include(cmake/third_party/stb.cmake)
 include(cmake/third_party/tracy.cmake)
 include(cmake/third_party/vulkan_headers.cmake)
 include(cmake/third_party/volk.cmake)
+include(cmake/third_party/vma.cmake)
+include(cmake/third_party/slang.cmake)
 add_subdirectory(third_party)
 
 add_library(ernie_build_options INTERFACE)

{ernie_renderer-0.2.0.dev52 → ernie_renderer-0.2.0.dev70}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev52
+Version: 0.2.0.dev70
 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.dev70/benchmarks/CMakeLists.txt

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: BSD-3-Clause
+add_executable(ernie_benchmarks main.cpp device/rl_step.cpp scene/extents.cpp scene/storage.cpp)
+target_link_libraries(
+    ernie_benchmarks
+    PRIVATE ernie_static ernie_volk ernie_vma ernie_build_options
+)

ernie_renderer-0.2.0.dev70/benchmarks/device/rl_step.cpp

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file rl_step.cpp
+/// @brief A steady-state RL step of 16,384 worlds on device columns: poses written in place, then
+/// turned into instance transforms, with no bulk bytes through the host.
+#include "tests/device/rl_step.h"
+#include "benchmarks/bench.h"
+
+#include <cstdio>
+#include <memory>
+
+namespace ernie::bench {
+namespace {
+
+const bool kRlStep = Register("device.rl_step.poses_16k", [] {
+    std::unique_ptr<DeviceContext> context;
+    try {
+        context = std::make_unique<DeviceContext>();
+    } catch (const DeviceError& error) {
+        std::printf("skipped: %s\n", error.what());
+        return Timing{0.0, 1.0};
+    }
+    const ShaderCompiler compiler;
+    test::RlStep rl(*context, compiler, 16'384);
+    std::uint32_t step = 0;
+    const auto run = [&] {
+        const Ticket ticket = rl.Step(++step);
+        ticket.Wait();
+    };
+    run();
+    const Transfers before = context->Transfers();
+    const double ms = Fastest([] {}, run, 20);
+    if (context->Transfers() != before) {
+        std::printf("device.rl_step.poses_16k moved bytes through the host\n");
+    }
+    return Timing{ms, 1.0};
+});
+
+}  // namespace
+}  // namespace ernie::bench

{ernie_renderer-0.2.0.dev52 → ernie_renderer-0.2.0.dev70}/cmake/ErnieFetch.cmake

@@ -14,7 +14,7 @@ function(ernie_fetch name)
     cmake_parse_arguments(
         ARG
         ""
-        "URL;GIT_REPOSITORY;GIT_TAG;GIT_SHALLOW;SOURCE_SUBDIR"
+        "URL;URL_HASH;GIT_REPOSITORY;GIT_TAG;GIT_SHALLOW;SOURCE_SUBDIR"
         "GIT_SUBMODULES"
         ${ARGN}
     )

{ernie_renderer-0.2.0.dev52 → ernie_renderer-0.2.0.dev70}/cmake/ErnieInstall.cmake

@@ -13,6 +13,34 @@ install(
     ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}" COMPONENT dev
 )
 
+# Slang's runtime, private to Ernie in lib/ernie and found through RPATHs, so it never clashes with
+# another Slang on the system; on Windows beside the DLLs, where programs look. Installed as
+# programs, as shared libraries are: RPM lists only what an executable library provides.
+if(APPLE)
+    set(ernie_origin "@loader_path")
+else()
+    set(ernie_origin "$ORIGIN")
+endif()
+set(ernie_private_libdir "${CMAKE_INSTALL_LIBDIR}/ernie")
+set_target_properties(ernie PROPERTIES INSTALL_RPATH "${ernie_origin}/ernie")
+if(TARGET ernie_app)
+    file(
+        RELATIVE_PATH
+        ernie_bin_to_private
+        "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_BINDIR}"
+        "${CMAKE_INSTALL_PREFIX}/${ernie_private_libdir}"
+    )
+    set_target_properties(
+        ernie_app
+        PROPERTIES INSTALL_RPATH "${ernie_origin}/${ernie_bin_to_private}"
+    )
+endif()
+if(WIN32)
+    install(FILES ${ERNIE_SLANG_RUNTIME} DESTINATION "${CMAKE_INSTALL_BINDIR}" COMPONENT runtime)
+else()
+    install(PROGRAMS ${ERNIE_SLANG_RUNTIME} DESTINATION "${ernie_private_libdir}" COMPONENT runtime)
+endif()
+
 set(ernie_public_headers
     util/glm.h
     util/log.h
@@ -93,7 +121,9 @@ set(ernie_notices
     "nlohmann_json|${nlohmann_json_SOURCE_DIR}/LICENSE.MIT"
     "openexr|${openexr_SOURCE_DIR}/LICENSE.md"
     "openjph|${openexr_SOURCE_DIR}/external/OpenJPH/LICENSE"
+    "slang|${slang_SOURCE_DIR}/LICENSE"
     "stb|${stb_SOURCE_DIR}/LICENSE"
+    "vma|${vma_SOURCE_DIR}/LICENSE.txt"
     "volk|${volk_SOURCE_DIR}/LICENSE.md"
     "vulkan_headers|${vulkan_headers_SOURCE_DIR}/LICENSE.md"
     "zstd|${openexr_SOURCE_DIR}/external/zstd/LICENSE"

ernie_renderer-0.2.0.dev70/cmake/third_party/slang.cmake

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_slang
+    2026.19
+    CACHE STRING
+    "Release of Slang to fetch. Changing it requires updating the hashes below."
+)
+mark_as_advanced(ERNIE_DEP_VERSION_slang)
+
+# Prebuilt Slang: the compiler Ernie links to turn Slang modules into SPIR-V (and WGSL) at run
+# time, so user models compile into Ernie's kernels. The Linux builds target old glibc versions,
+# so they run wherever manylinux_2_34 wheels do.
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64")
+    set(slang_platform linux-x86_64-glibc-2.27)
+    set(slang_sha256 ae348a33d906ed29d14c2294f2260746cb2c3eb4aa2c7fc4bfd887a3a298737d)
+elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
+    set(slang_platform linux-aarch64-glibc-2.28)
+    set(slang_sha256 52b1e6b2aad2d9a119308fe8f99d1699d1854e4ac2d7b579cf0f8f25349bcd17)
+elseif(APPLE AND CMAKE_SYSTEM_PROCESSOR MATCHES "arm64|aarch64")
+    set(slang_platform macos-aarch64)
+    set(slang_sha256 f77d89b91ec63698a7a8e5aa4316ce08b70d3211a236640ee4551f55be85d9ed)
+elseif(APPLE)
+    set(slang_platform macos-x86_64)
+    set(slang_sha256 c5e18233c0b90cc651c792ec4c4e4a467a9a101ffb6301643aab89c016b48e42)
+elseif(WIN32 AND CMAKE_SYSTEM_PROCESSOR MATCHES "AMD64|x86_64")
+    set(slang_platform windows-x86_64)
+    set(slang_sha256 fc922f214b5d115f663932e59e80e0f6b6cc6fae140979cf307da6459b6f8f33)
+else()
+    message(FATAL_ERROR "No prebuilt Slang for ${CMAKE_SYSTEM_NAME} ${CMAKE_SYSTEM_PROCESSOR}")
+endif()
+
+ernie_fetch(
+    slang
+    URL
+        https://github.com/shader-slang/slang/releases/download/v${ERNIE_DEP_VERSION_slang}/slang-${ERNIE_DEP_VERSION_slang}-${slang_platform}.zip
+    URL_HASH SHA256=${slang_sha256}
+    SOURCE_SUBDIR no-build
+)
+
+# Each release keeps its CMake package in lib/ (Linux x86_64, macOS), lib64/ (Linux aarch64) or
+# the top (Windows).
+find_package(
+    slang
+    CONFIG
+    REQUIRED
+    PATHS "${slang_SOURCE_DIR}"
+    PATH_SUFFIXES lib/cmake/slang lib64/cmake/slang cmake
+    NO_DEFAULT_PATH
+)
+set_target_properties(slang::slang PROPERTIES IMPORTED_GLOBAL TRUE)
+
+# The runtime files Ernie's binaries need beside them: the compiler library, and the glslang
+# library it loads at run time.
+get_target_property(slang_library slang::slang IMPORTED_LOCATION_RELEASE)
+if(NOT slang_library)
+    get_target_property(slang_library slang::slang IMPORTED_LOCATION)
+endif()
+get_filename_component(ERNIE_SLANG_RUNTIME_DIR "${slang_library}" DIRECTORY)
+file(
+    GLOB ERNIE_SLANG_RUNTIME
+    "${ERNIE_SLANG_RUNTIME_DIR}/libslang-compiler.so.*"
+    "${ERNIE_SLANG_RUNTIME_DIR}/libslang-glslang-*.so"
+    "${ERNIE_SLANG_RUNTIME_DIR}/libslang-compiler*.dylib"
+    "${ERNIE_SLANG_RUNTIME_DIR}/libslang-glslang-*.dylib"
+    "${ERNIE_SLANG_RUNTIME_DIR}/slang-compiler.dll"
+    "${ERNIE_SLANG_RUNTIME_DIR}/slang-glslang.dll"
+)
+# Windows has no rpath: a program finds its DLLs beside it, so the build's programs get Slang's.
+if(WIN32 AND CMAKE_RUNTIME_OUTPUT_DIRECTORY)
+    file(COPY ${ERNIE_SLANG_RUNTIME} DESTINATION "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}")
+endif()

ernie_renderer-0.2.0.dev70/cmake/third_party/vma/vma.cpp

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// Vulkan Memory Allocator's implementation, compiled once, its Vulkan functions from volk.
+#include <volk.h>
+
+#define VMA_IMPLEMENTATION
+#include <vk_mem_alloc.h>

ernie_renderer-0.2.0.dev70/cmake/third_party/vma.cmake

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: BSD-3-Clause
+set(ERNIE_DEP_VERSION_vma v3.4.0 CACHE STRING "Tag of Vulkan Memory Allocator to fetch")
+mark_as_advanced(ERNIE_DEP_VERSION_vma)
+
+ernie_fetch(
+    vma
+    URL
+        https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/archive/refs/tags/${ERNIE_DEP_VERSION_vma}.tar.gz
+    SOURCE_SUBDIR no-build
+)
+
+# The allocator is header-only; vma/vma.cpp compiles its implementation once, fetching Vulkan
+# functions through volk.
+add_library(ernie_vma STATIC "${CMAKE_CURRENT_LIST_DIR}/vma/vma.cpp")
+target_include_directories(ernie_vma SYSTEM PUBLIC "${vma_SOURCE_DIR}/include")
+target_compile_definitions(
+    ernie_vma
+    PUBLIC VMA_STATIC_VULKAN_FUNCTIONS=0 VMA_DYNAMIC_VULKAN_FUNCTIONS=1
+)
+target_link_libraries(ernie_vma PUBLIC ernie_volk)
+set_target_properties(ernie_vma PROPERTIES POSITION_INDEPENDENT_CODE ON)
+ernie_quiet_third_party(ernie_vma)

{ernie_renderer-0.2.0.dev52 → ernie_renderer-0.2.0.dev70}/cmake/third_party/volk.cmake

@@ -14,3 +14,7 @@ target_include_directories(ernie_volk SYSTEM PUBLIC "${volk_SOURCE_DIR}")
 target_compile_definitions(ernie_volk PUBLIC VK_NO_PROTOTYPES)
 target_link_libraries(ernie_volk PUBLIC ernie_vulkan_headers ${CMAKE_DL_LIBS})
 set_target_properties(ernie_volk PROPERTIES POSITION_INDEPENDENT_CODE ON)
+# Loads the Win32 sharing functions, which only external.cpp declares.
+if(WIN32)
+    target_compile_definitions(ernie_volk PRIVATE VK_USE_PLATFORM_WIN32_KHR)
+endif()

{ernie_renderer-0.2.0.dev52 → ernie_renderer-0.2.0.dev70}/ernie/app/main.cpp

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: BSD-3-Clause
 /// @file main.cpp
 /// @brief The ernie program.
-#include "ernie/device/vulkan_devices.h"
+#include "ernie/device/device.h"
 #include "ernie/scene/reference.h"
 #include "ernie/util/file.h"
 #include "ernie/util/version.h"
@@ -25,7 +25,8 @@ void PrintUsage() {
 int PrintDevices() {
     for (const ernie::VulkanDeviceInfo& device : ernie::ListVulkanDevices()) {
         std::printf("%s (%s, Vulkan %u.%u%s)\n", device.name.c_str(), ernie::ToString(device.type),
-                    device.apiMajor, device.apiMinor, device.rayQuery ? ", ray queries" : "");
+                    device.apiMajor, device.apiMinor,
+                    device.capabilities.rayQuery ? ", ray queries" : "");
     }
     return 0;
 }

ernie_renderer-0.2.0.dev70/ernie/device/CMakeLists.txt

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: BSD-3-Clause
+add_library(
+    ernie_device
+    OBJECT
+    arena.cpp
+    bindless.cpp
+    buffer.cpp
+    column.cpp
+    context.cpp
+    cuda.cpp
+    external.cpp
+    image.cpp
+    instance.cpp
+    kernel.cpp
+    queue.cpp
+    shader_compiler.cpp
+    staging.cpp
+    vulkan.cpp
+)
+target_link_libraries(
+    ernie_device
+    PUBLIC ernie_util
+    PRIVATE ernie_volk ernie_vma ernie_glm slang::slang ernie_build_options
+)

ernie_renderer-0.2.0.dev70/ernie/device/arena.cpp

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file arena.cpp
+/// @brief Sub-allocating arenas with VMA's virtual blocks.
+#include "ernie/device/arena.h"
+
+#include <algorithm>
+#include <optional>
+
+namespace ernie {
+
+Arenas::Arena::~Arena() {
+    if (block != VK_NULL_HANDLE) {
+        vmaClearVirtualBlock(block);
+        vmaDestroyVirtualBlock(block);
+    }
+}
+
+Arenas::Arenas(DeviceContext& context, MemoryUse use, std::string_view name,
+               std::uint64_t arenaSize)
+    : context_(context), use_(use), name_(name),
+      arenaSize_(std::min(arenaSize, context.MaxBufferSize())) {}
+
+Arenas::~Arenas() {
+    Quietly([this] { context_.WaitIdle(); });
+}
+
+BufferRange Arenas::Allocate(std::uint64_t size, std::uint64_t alignment) {
+    if (size > context_.MaxBufferSize()) {
+        throw DeviceError(DeviceErrorKind::Unsupported,
+                          std::to_string(size) + " bytes of " + name_ +
+                              " exceed the largest buffer the device can address");
+    }
+    size = std::max<std::uint64_t>(size, 1);
+    const VmaVirtualAllocationCreateInfo info{.size = size, .alignment = alignment};
+    const auto take = [&](std::uint32_t index) -> std::optional<BufferRange> {
+        Arena& arena = *arenas_[index];
+        VmaVirtualAllocation allocation = VK_NULL_HANDLE;
+        VkDeviceSize offset = 0;
+        if (vmaVirtualAllocate(arena.block, &info, &allocation, &offset) != VK_SUCCESS) {
+            return std::nullopt;
+        }
+        arena.allocations.emplace(offset, allocation);
+        arena.used += size;
+        return BufferRange{index, offset, size};
+    };
+    const auto takeAny = [&]() -> std::optional<BufferRange> {
+        for (std::uint32_t index = 0; index < arenas_.size(); ++index) {
+            if (const std::optional<BufferRange> range = take(index)) {
+                return range;
+            }
+        }
+        return std::nullopt;
+    };
+    {
+        const std::lock_guard lock(mutex_);
+        if (const std::optional<BufferRange> range = takeAny()) {
+            return *range;
+        }
+    }
+    // Ranges freed earlier come back once their work is done; collected without the lock, as
+    // giving them back takes it.
+    context_.Collect();
+    const std::lock_guard lock(mutex_);
+    if (const std::optional<BufferRange> range = takeAny()) {
+        return *range;
+    }
+    // A range larger than the arena size gets an arena of its own.
+    const std::uint64_t own = std::max(size, arenaSize_);
+    if (const std::optional<BufferRange> range = take(AddArena(own))) {
+        return *range;
+    }
+    throw DeviceError(DeviceErrorKind::Failed, "Allocating " + std::to_string(size) + " bytes of " +
+                                                   name_ + " at alignment " +
+                                                   std::to_string(alignment));
+}
+
+const Buffer& Arenas::Storage(const BufferRange& range) const {
+    const std::lock_guard lock(mutex_);
+    return arenas_[range.arena]->buffer;
+}
+
+void Arenas::Free(const BufferRange& range) {
+    context_.Retire([this, range] { Release(range); });
+}
+
+std::uint64_t Arenas::Used() const {
+    const std::lock_guard lock(mutex_);
+    std::uint64_t used = 0;
+    for (const auto& arena : arenas_) {
+        used += arena->used;
+    }
+    return used;
+}
+
+std::uint32_t Arenas::AddArena(std::uint64_t size) {
+    auto arena = std::make_unique<Arena>();
+    arena->buffer =
+        Buffer(context_, size, use_, name_ + " arena " + std::to_string(arenas_.size()));
+    const VmaVirtualBlockCreateInfo block{.size = size};
+    CheckVk(vmaCreateVirtualBlock(&block, &arena->block), "Creating " + name_ + "'s arena");
+    arenas_.push_back(std::move(arena));
+    return static_cast<std::uint32_t>(arenas_.size() - 1);
+}
+
+void Arenas::Release(const BufferRange& range) {
+    const std::lock_guard lock(mutex_);
+    Arena& arena = *arenas_[range.arena];
+    const auto found = arena.allocations.find(range.offset);
+    if (found != arena.allocations.end()) {
+        vmaVirtualFree(arena.block, found->second);
+        arena.allocations.erase(found);
+        arena.used -= range.size;
+    }
+}
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev70/ernie/device/arena.h

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file arena.h
+/// @brief Device memory as a few large buffers sub-allocated by offset. Shaders reach data as
+/// (arena, offset): a buffer device address on Vulkan, a bound storage buffer and offset on
+/// WebGPU, which has no pointers.
+#pragma once
+
+#include "ernie/device/buffer.h"
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+#include <vector>
+
+namespace ernie {
+
+/// @brief Where data lives on the device: a range of one arena.
+struct BufferRange {
+    std::uint32_t arena = 0;
+    std::uint64_t offset = 0;
+    std::uint64_t size = 0;
+    bool operator==(const BufferRange&) const = default;
+};
+
+/// @brief The arenas of one memory use. Ranges are handed out by offset; a full arena is joined
+/// by another, and a range larger than the arena size gets an arena of its own. No arena is
+/// larger than the device's largest addressable buffer.
+class Arenas {
+  public:
+    /// @param arenaSize Bytes per arena, capped at `DeviceContext::MaxBufferSize`.
+    Arenas(DeviceContext& context, MemoryUse use, std::string_view name,
+           std::uint64_t arenaSize = std::uint64_t{256} << 20);
+    /// Waits for the device, so ranges freed late are back before the arenas go.
+    ~Arenas();
+    Arenas(const Arenas&) = delete;
+    Arenas& operator=(const Arenas&) = delete;
+
+    /// @brief Takes a range of `size` bytes at a multiple of `alignment`.
+    /// @throws DeviceError when `size` exceeds the largest buffer the device can address, or the
+    /// memory runs out.
+    BufferRange Allocate(std::uint64_t size, std::uint64_t alignment = 16);
+    /// @brief Gives a range back once every queue's work submitted so far is done.
+    void Free(const BufferRange& range);
+
+    /// @return The buffer of a range's arena: its handle, and its mapping for host-visible uses.
+    const Buffer& Storage(const BufferRange& range) const;
+    /// @return The range's device address, as shaders read it on Vulkan.
+    VkDeviceAddress Address(const BufferRange& range) const {
+        return Storage(range).Address() + range.offset;
+    }
+    std::size_t Count() const {
+        return arenas_.size();
+    }
+    /// @return The bytes handed out and not yet given back.
+    std::uint64_t Used() const;
+
+  private:
+    struct Arena {
+        Buffer buffer;
+        VmaVirtualBlock block = VK_NULL_HANDLE;
+        /// Each range's allocation in `block`, by offset.
+        std::unordered_map<std::uint64_t, VmaVirtualAllocation> allocations;
+        std::uint64_t used = 0;
+        ~Arena();
+    };
+
+    std::uint32_t AddArena(std::uint64_t size);
+    void Release(const BufferRange& range);
+
+    DeviceContext& context_;
+    MemoryUse use_;
+    std::string name_;
+    std::uint64_t arenaSize_;
+    mutable std::mutex mutex_;
+    std::vector<std::unique_ptr<Arena>> arenas_;
+};
+
+}  // namespace ernie