Graphics.h

浏览该文件的文档.

#pragma once
#include <array>
#include <atomic>
#include <cstdint>
#include <glm/ext/vector_uint4_sized.hpp>
#include <glm/mat4x4.hpp>
#include <glm/vec2.hpp>
#include <glm/vec3.hpp>
#include <glm/vec4.hpp>
#include <map>
#include <memory>
#include <optional>
#include <unordered_map>
#include <vector>
#include "common/Capability.h"
#include "common/Export.h"
#include "common/GpuTimer.h"
#include "graphics/Batcher.h"
#include "graphics/ClusteredLight.h"
#include "graphics/Graphics.h"
#include "graphics/Light.h"
#include "graphics/Mesh.h"
#include "graphics/PbrSurface.h"
#include "graphics/PrimitiveTypes.h"
#include "graphics/RayTracingCaps.h"
#include "graphics/Shader.h"
#include "graphics/Shadow.h"
#include "graphics/Texture.h"
#include "graphics/vulkan/ComputePass.h"
#include "graphics/vulkan/FrameArena.h"
#include "graphics/vulkan/GpuDriven.h"
#include "vkbuilder.hpp"
#include "vkbuilder/framegraph.hpp"
 
namespace eve::graphics::vulkan {
 
class OffscreenCanvas;
 
#if defined(VKB_ENABLE_VMA)
class VmaAllocatorOwner {
public:
    VmaAllocatorOwner() = default;
    ~VmaAllocatorOwner();
    VmaAllocatorOwner(const VmaAllocatorOwner &) = delete;
    VmaAllocatorOwner &operator=(const VmaAllocatorOwner &) = delete;
 
    void create(const vkb::Instance &instance, const vkb::PhysicalDevice &physicalDevice,
                vkb::Device &device);
 
private:
    VmaAllocator allocator_ = VK_NULL_HANDLE;
};
#endif
 
struct ColorVertex {
    glm::vec2 pos;
    glm::vec4 color;
 
    static vk::VertexInputBindingDescription getBindingDescription(uint32_t binding) {
        vk::VertexInputBindingDescription b{};
        b.binding = binding;
        b.stride = sizeof(ColorVertex);
        b.inputRate = vk::VertexInputRate::eVertex;
        return b;
    }
    static std::vector<vk::VertexInputAttributeDescription> getAttributeDescription(uint32_t binding) {
        return {
            {0, binding, vk::Format::eR32G32Sfloat, offsetof(ColorVertex, pos)},
            {1, binding, vk::Format::eR32G32B32A32Sfloat, offsetof(ColorVertex, color)},
        };
    }
};
 
struct Primitive3DVertex {
    glm::vec4 clipPosition;
    glm::vec4 color;
 
    static vk::VertexInputBindingDescription getBindingDescription(uint32_t binding) {
        return {binding, sizeof(Primitive3DVertex), vk::VertexInputRate::eVertex};
    }
    static std::vector<vk::VertexInputAttributeDescription> getAttributeDescription(uint32_t binding) {
        return {{0, binding, vk::Format::eR32G32B32A32Sfloat, offsetof(Primitive3DVertex, clipPosition)},
                {1, binding, vk::Format::eR32G32B32A32Sfloat, offsetof(Primitive3DVertex, color)}};
    }
};
 
struct TexturedVertex {
    glm::vec2 pos;
    glm::vec4 color;
    glm::vec2 uv;
 
    static vk::VertexInputBindingDescription getBindingDescription(uint32_t binding) {
        vk::VertexInputBindingDescription b{};
        b.binding = binding;
        b.stride = sizeof(TexturedVertex);
        b.inputRate = vk::VertexInputRate::eVertex;
        return b;
    }
    static std::vector<vk::VertexInputAttributeDescription> getAttributeDescription(uint32_t binding) {
        return {
            {0, binding, vk::Format::eR32G32Sfloat, offsetof(TexturedVertex, pos)},
            {1, binding, vk::Format::eR32G32B32A32Sfloat, offsetof(TexturedVertex, color)},
            {2, binding, vk::Format::eR32G32Sfloat, offsetof(TexturedVertex, uv)},
        };
    }
};
 
struct UiTextureDraw {
    Texture *texture = nullptr;
    float x = 0.f;
    float y = 0.f;
    float w = 0.f;
    float h = 0.f;
    float u0 = 0.f;
    float v0 = 0.f;
    float u1 = 1.f;
    float v1 = 1.f;
    Color tint{1.f, 1.f, 1.f, 1.f};
    float clipX = 0.f;
    float clipY = 0.f;
    float clipW = 0.f;
    float clipH = 0.f;
    bool opaque = false;
};
 
struct MeshVertex {
    glm::vec3 pos;
    glm::vec3 normal;
    glm::vec2 uv;
    glm::u16vec4 joints{0};
    glm::vec4 weights{0.f};
    glm::vec4 color{1.f};
    // Optional imported tangent basis; w=0 explicitly denotes an absent stream.
    glm::vec4 tangent{0.f};
 
    static vk::VertexInputBindingDescription getBindingDescription(uint32_t binding) {
        vk::VertexInputBindingDescription b{};
        b.binding = binding;
        b.stride = sizeof(MeshVertex);
        b.inputRate = vk::VertexInputRate::eVertex;
        return b;
    }
    static std::vector<vk::VertexInputAttributeDescription> getAttributeDescription(uint32_t binding) {
        return {
            {0, binding, vk::Format::eR32G32B32Sfloat, offsetof(MeshVertex, pos)},
            {1, binding, vk::Format::eR32G32B32Sfloat, offsetof(MeshVertex, normal)},
            {2, binding, vk::Format::eR32G32Sfloat, offsetof(MeshVertex, uv)},
            {3, binding, vk::Format::eR16G16B16A16Uint, offsetof(MeshVertex, joints)},
            {4, binding, vk::Format::eR32G32B32A32Sfloat, offsetof(MeshVertex, weights)},
            {5, binding, vk::Format::eR32G32B32A32Sfloat, offsetof(MeshVertex, color)},
            {6, binding, vk::Format::eR32G32B32A32Sfloat, offsetof(MeshVertex, tangent)},
        };
    }
};
 
struct Mesh3DUBO {
    // Layout prefix matches legacy custom Mesh3D shaders (toon etc.).
    glm::mat4 mvp{1.f};
    glm::mat4 model{1.f};
    glm::vec4 lightDir{0.4f, 1.f, 0.3f, 0.f};   // xyz = primary dir; w = lightCount
    glm::vec4 lightColor{1.f, 1.f, 1.f, 0.f};    // rgb = primary color; w = envIntensity (IBL)
    glm::vec4 tint{1.f, 1.f, 1.f, 1.f};
    glm::vec4 cameraPos{0.f, 0.f, 3.f, 0.45f};    // xyz = eye; w = roughness
    glm::vec4 ambient{0.12f, 0.12f, 0.14f, 0.f}; // rgb = ambient; w = metallic
    Light3DGpu lights[Lighting3DPack::kMaxLights]{};
    // Appended: custom shaders that only read the prefix stay valid (buffer may be larger).
    glm::vec4 texBomb{4.f, 0.f, 1.f, 0.f}; // x=cellScale, y=strength (0=off), z=rotAmount
    glm::vec4 parallax{0.f, 8.f, 32.f, 0.f}; // x=scale (0=off), y=minLayers, z=maxLayers
    glm::mat4 view{1.f};                     // camera view (CSM / view-space depth)
    glm::vec4 clipInfo{0.1f, 100.f, 0.f, 0.f}; // x=near, y=far (linear depth in scene color A)
    // Dynamic cloud shadows on ground. cloud.x=strength (0=off), y=world cell size,
    // z=time, w=unused; cloudWind.xy=wind velocity (world/s), z=coverage, w=detail.
    glm::vec4 cloud{0.f, 1.5f, 0.f, 0.f};
    glm::vec4 cloudWind{4.f, 0.f, 0.55f, 0.5f};
    glm::vec4 virtualTexture{0.f}; // enabled, pageCountX, pageCountY, border/extent
    glm::vec4 virtualAtlas{0.f};   // slotsX, slotsY
    // GPU-driven only: x = bindless env cubemap slot, y = envIntensity.
    // Appended after the legacy prefix so legacy shaders are unaffected.
    glm::vec4 bindlessEnv{0.f, 0.f, 0.f, 0.f};
    glm::vec4 envProbeCenter{0.f};
    glm::vec4 envProbeExtent{0.f};
    glm::vec4 skinInfo{0.f};
    glm::vec4 reflectionProbeCenter[ReflectionProbeUpload::kMaxProbes]{};
    glm::vec4 reflectionProbeExtent[ReflectionProbeUpload::kMaxProbes]{};
    glm::vec4 diffuseProbeSh[9]{};
    glm::vec4 diffuseProbeInfo{0.f};  // x = enabled
    glm::vec4 diffuseVolumePosition[Lighting3DPack::kMaxDiffuseVolumeProbes]{};
    glm::vec4 diffuseVolumeExtent[Lighting3DPack::kMaxDiffuseVolumeProbes]{};
    glm::vec4 diffuseVolumeSh[Lighting3DPack::kMaxDiffuseVolumeProbes * 9]{};
    glm::vec4 diffuseVolumeInfo{0.f};  // x = probe count
    glm::vec4 lodFade{1.f, 0.f, 0.f, 0.f}; // coverage, complementary pattern, enabled
};
 
struct SkinPassUBO {
    glm::mat4 mvp{1.f};
    glm::mat4 model{1.f};
    glm::vec4 clip{0.f};
    glm::vec4 skinInfo{0.f};
};
static_assert(sizeof(SkinPassUBO) == 160, "SkinPassUBO must match std140 shaders");
 
struct DeferredLightingUBO {
    glm::mat4 invViewProj{1.f};
    glm::mat4 view{1.f};
    glm::vec4 lightDir{0.4f, 1.f, 0.3f, 0.f};
    glm::vec4 lightColor{1.f, 1.f, 1.f, 0.f};
    glm::vec4 cameraPos{0.f, 0.f, 3.f, 0.f};
    glm::vec4 ambient{0.12f, 0.12f, 0.14f, 0.f};
    glm::vec4 gridInfo{16.f, 9.f, 24.f, 0.f};
    glm::vec4 clipInfo{0.1f, 100.f, 1.f, 1.f};
};
static_assert(sizeof(DeferredLightingUBO) == 224, "DeferredLightingUBO must match std140 shader");
 
struct Mesh3DClusteredUBO {
    glm::mat4 mvp{1.f};
    glm::mat4 model{1.f};
    glm::mat4 view{1.f};
    glm::vec4 lightDir{0.4f, 1.f, 0.3f, 0.f};
    glm::vec4 lightColor{1.f, 1.f, 1.f, 0.f};  // rgb = primary; w = envIntensity
    glm::vec4 tint{1.f, 1.f, 1.f, 1.f};
    glm::vec4 cameraPos{0.f, 0.f, 3.f, 0.45f};
    glm::vec4 ambient{0.12f, 0.12f, 0.14f, 0.f};
    glm::vec4 gridInfo{16.f, 9.f, 24.f, 0.f};
    glm::vec4 clipInfo{0.1f, 100.f, 1.f, 1.f};
    glm::vec4 texBomb{4.f, 0.f, 1.f, 0.f}; // x=cellScale, y=strength (0=off), z=rotAmount
    glm::vec4 parallax{0.f, 8.f, 32.f, 0.f}; // x=scale (0=off), y=minLayers, z=maxLayers
    glm::vec4 virtualTexture{0.f};
    glm::vec4 virtualAtlas{0.f};
    glm::vec4 envProbeCenter{0.f};
    glm::vec4 envProbeExtent{0.f};
    glm::vec4 reflectionProbeCenter[ReflectionProbeUpload::kMaxProbes]{};
    glm::vec4 reflectionProbeExtent[ReflectionProbeUpload::kMaxProbes]{};
};
 
struct GpuTexture {
    vkb::TextureImage2D image;
    vkb::GenericImage arrayImage;
    vkb::TextureImageCube cubeImage;
    bool isCube = false;
    bool isArray = false;
    bool isVolume = false;
    bool isHDR = false;
    vk::UniqueDeviceMemory rawCubeMemory;
    vk::UniqueImage rawCubeImage;
    vk::UniqueImageView rawCubeView;
    vk::Sampler sampler;
    vkb::BoundSet descriptorSet;
    vk::ImageView viewOverride{};
    int width = 0;
    int height = 0;
    uint32_t mipLevels = 1;
    TextureSampler samplerState{};
    uint32_t bindlessIndex2D = kInvalidBindlessSlot;
    uint32_t bindlessIndexCube = kInvalidBindlessSlot;
 
    vk::ImageView imageView() const {
        if (viewOverride) return viewOverride;
        if (rawCubeView) return *rawCubeView;
        if (isArray || isVolume) return arrayImage.imageView();
        return isCube ? cubeImage.imageView() : image.imageView();
    }
};
 
struct GpuMesh {
    static constexpr size_t                                 kDynamicVertexCopies = 3;
    vkb::HostVertexBuffer                                   vertices;
    vkb::GenericBuffer                                      indices;
    std::array<vkb::HostVertexBuffer, kDynamicVertexCopies> dynVertices;
    std::array<vkb::GenericBuffer, kDynamicVertexCopies>    dynIndices;
    std::vector<uint32_t> cpuIndices;
    uint64_t      dynamicWriteCount = 0;
    bool          dynamic           = false;
    uint32_t      vertexCount       = 0;
    uint32_t      indexCount        = 0;
    vk::IndexType indexType         = vk::IndexType::eUint32;
    uint32_t gpuRecordIndex = kInvalidBindlessSlot;
    GpuMeshRecord record;
};
 
struct MeshShaderResources;
struct MeshShaderResourcesDeleter {
    void operator()(MeshShaderResources *resources) const noexcept;
};
 
struct GpuShader {
    vk::Pipeline       swapchainPipeline;
    vk::Pipeline       offscreenPipeline;
    vk::Pipeline       swapchainOpaquePipeline;
    vk::Pipeline       offscreenOpaquePipeline;
    vk::Pipeline       hdrOffscreenPipeline;
    vk::Pipeline       hdrOffscreenOpaquePipeline;
    vk::Pipeline       mesh3dPipeline;
    vk::Pipeline       mesh3dXrayPipeline;
    vk::Pipeline       mesh3dOffscreenPipeline;
    vk::Pipeline       mesh3dHdrOffscreenPipeline;
    vk::PipelineLayout pipelineLayout;
    vk::DescriptorSet                                                resourceSet;
    std::unique_ptr<MeshShaderResources, MeshShaderResourcesDeleter> resources;
    bool isMesh3D = false;
    bool isHair3D = false;
    Shader *owner = nullptr;
};
 
class EVENGINE_API_BACKENDS Graphics final : public eve::graphics::Graphics, public eve::service::IGpuTimer {
public:
    // Keep the base draw(Drawable*, mat4) overload visible alongside the
    // canvas composite overloads below.
    using eve::graphics::Graphics::draw;
 
    Graphics();
    ~Graphics() override;
 
    // ---- GPU frame timing (eve::service::IGpuTimer) ----------------------
    void initGpuTiming();
    void writeGpuTimestampBegin();
    void writeGpuTimestampEnd();
    void readGpuFrameTiming();
 
    bool gpuTimingAvailable() const override;
    float gpuFrameMs() const override;
 
    std::string getBackendName() const override;
    bool        supportsRuntimeGlslCompilation() const override;
 
    void initWithWindow(void *nativeWindow) override;
    void initHeadless(int width, int height) override;
    bool isHeadless() const override { return headless_; }
    void present() override;
    void requestSurfaceRecreate() override { surfaceNeedsRecreate = true; }
    void onNativeWindowDestroyed() override;
    void setScreenReadbackEnabled(bool enabled) override {
        eve::graphics::Graphics::setScreenReadbackEnabled(enabled);
        ensurePresentCaptureHook();
    }
    void setVSync(bool enabled) override {
        if (vsyncEnabled == enabled) return;
        eve::graphics::Graphics::setVSync(enabled);
        markSwapchainDirty();
    }
    void setMsaaSamples(int samples) override {
        const int raw = samples > 1 ? samples : 0;
        if (raw == msaaSamples) return;
        eve::graphics::Graphics::setMsaaSamples(raw);
    }
    int getMsaaSamples() const override { return msaaSamples; }
    void setViewportSize(int width, int height, int pixelwidth, int pixelheight) override;
 
    // ---- GPU-driven rendering (stage 0: bindless + resource tables) ----
 
    const GpuDrivenCaps &gpuDrivenCaps() const { return gpuDrivenCaps_; }
 
    const RayTracingCaps& rayTracingCapsRef() const { return rayTracingCaps_; }
    RayTracingCaps        rayTracingCaps() const override { return rayTracingCaps_; }
    bool                  supportsRayTracing() const override { return rayTracingCaps_.rayTracingAvailable(); }
 
    FrameArena &currentFrameArena();
 
    uint32_t materialTableGetOrCreate(eve::graphics::Material *material);
 
    void syncMaterialTable();
 
    uint32_t bindlessSlot2D(const GpuTexture *tex) const {
        return tex ? tex->bindlessIndex2D : kInvalidBindlessSlot;
    }
    uint32_t bindlessSlotCube(const GpuTexture *tex) const {
        return tex ? tex->bindlessIndexCube : kInvalidBindlessSlot;
    }
    bool supportsGpuDriven3D() const override {
        return gpuDrivenCaps_.gpuDrivenAvailable();
    }
    bool supportsDeferredLighting() const override { return true; }
    void drawDeferredLighting() override;
    bool gpuDrivenEnabled() const override {
        return gpuDrivenEnabled_ && gpuDrivenCaps_.gpuDrivenAvailable();
    }
    void gpuDrivenSetEnabled(bool enabled) override { gpuDrivenEnabled_ = enabled; }
    uint32_t gpuDrivenMeshRecord(Mesh *mesh) override;
    uint32_t gpuDrivenMaterialRecord(Material *material) override {
        return materialTableGetOrCreate(material);
    }
    bool gpuDrivenMaterialUsable(Material *material) override;
    [[nodiscard]] Result<void> gpuDrivenReleaseMaterialRecord(Material *material) override;
    uint32_t gpuDrivenReflectionProbeSlot(Texture *cubemap) override;
    bool gpuDrivenSubmitOpaque(const GpuInstance *instances, uint32_t instanceCount) override;
    GpuResidentSubmitStatus gpuDrivenSubmitResident(const GpuResidentInstanceBatch &batch) override;
    Texture *getSceneLinearDepthTexture() override;
 
    bool supportsGpuParticles() const override { return initialized && !headless_; }
    bool canSubmitGpuParticles() const override;
    GpuParticleHandle createGpuParticleEmitter(std::uint32_t capacity) override;
    void releaseGpuParticleEmitter(GpuParticleHandle handle) override;
    void resetGpuParticleEmitter(GpuParticleHandle handle) override;
    bool updateGpuParticleEmitter(GpuParticleHandle handle, const GpuParticleUpdate &update,
                                  const GpuParticleSpawn *spawns,
                                  std::uint32_t spawnCount) override;
    bool drawGpuParticleEmitter(GpuParticleHandle handle,
                                const GpuParticleDraw &draw) override;
    GpuParticleStats getGpuParticleStats(GpuParticleHandle handle) const override;
    uint32_t debugBindlessIndex(Texture *tex) const;
    uint32_t debugMeshRecordIndex(Mesh *mesh) const;
    uint32_t debugLastGpuDrivenDrawCount() const { return lastGpuDrivenDrawCount_; }
    void waitForSharedGpuResources();
    bool gpuDrivenCullEnabled() const {
        return gpuDrivenEnabled_ && gpuDrivenCaps_.gpuDrivenCullAvailable();
    }
    bool gpuDrivenScenePassPending() const { return gpuDrivenScenePassPending_; }
    bool gpuDrivenCullBegin(const GpuInstance *instances, uint32_t instanceCount);
    void gpuDrivenCullEmit(const glm::mat4 &viewProj, const glm::vec3 &eye, float fovYDeg,
                           float nearZ, float farZ);
    void gpuDrivenOpenScenePass();
    void gpuDrivenDrawOpaque();
    bool gpuDrivenResolveWanted() const override;
    void gpuDrivenRecordVisPass() override;
    void gpuDrivenResolve() override;
    uint32_t gpuDrivenVgUpload(const GpuVgAssetUpload &asset) override;
    uint32_t gpuDrivenVgAssetId(Mesh *mesh) const override;
    bool gpuDrivenVgAttachToMesh(Mesh *mesh, uint32_t vgAssetId) override;
    bool gpuDrivenVgSetInstance(uint32_t vgAssetId, const glm::mat4 &model,
                                uint32_t materialId) override;
    void gpuDrivenVgComputeSection(const glm::mat4 &viewProj, const glm::vec3 &eye,
                                   float fovYDeg, float nearZ, float farZ) override;
    uint32_t debugGpuDrivenVgVisibleCount() const;
    uint32_t debugGpuDrivenVisibleCount() const;
    uint32_t debugGpuDrivenCulledDrawCount() const;
 
    void drawSolidRect(float x, float y, float w, float h, const Color &color,
                       BlendMode blend = BlendMode::Alpha) override;
    void     drawPrimitiveCanvas(const PrimitiveCanvas2D &canvas) override;
    void drawSolidRectRotated(float cx, float cy, float w, float h, float degrees,
                              const Color &color,
                              BlendMode blend = BlendMode::Alpha) override;
    void pushValidationScope() override {}
    void popValidationScope() override {}
    Texture *newTexture(int width, int height, const uint8_t *rgba, bool repeatU = false,
                        bool repeatV = false) override;
    Texture *newTexture(int width, int height, const uint8_t *rgba,
                        const TextureCreateInfo &info) override;
    [[nodiscard]] Result<Texture *> newTextureMipChain(uint32_t width, uint32_t height, uint32_t levels,
                                                        std::span<const uint8_t> rgba) override;
    [[nodiscard]] Result<Texture *> newTextureArrayRgba16f(uint32_t width, uint32_t height, uint32_t layers,
                                                            std::span<const uint16_t> rgbaHalf) override;
    [[nodiscard]] Result<Texture *> newTexture3DRgba8(uint32_t width, uint32_t height, uint32_t depth,
                                                       std::span<const uint8_t> rgba) override;
    Texture *newCubemap(int faceSize, const uint8_t *rgbaFaces) override;
    Texture *newCubemap(int faceSize, const uint8_t *rgbaFaces,
                        const TextureCreateInfo &info) override;
    Texture *newHDRCubemap(int faceSize) override;
    bool copyHDRCanvasToCubemapFace(Canvas *source, Texture *cubemap, int face) override;
    bool copyHDRCanvasesToCubemap(Canvas *const *sources, int faceCount,
                                  Texture *cubemap) override;
    bool filterHDRReflectionCubemap(Texture *cubemap, int sampleCount = 64) override;
    Texture *newTexture(image::ImageData *data) override;
    Texture *newTexture(image::ImageData *data, const TextureCreateInfo &info) override;
    [[nodiscard]] ResultRef<Texture> newSharedTexture(image::ImageData *data, const std::string &contentKey) override;
    void setTextureSampler(Texture *texture, const TextureSampler &sampler) override;
    float getMaxAnisotropy() const override;
    Texture *newTextureFromFile(const std::string &filename) override;
    bool reloadTextureFromFile(const std::string &filename) override;
    bool uploadDeferredFileTexture(Texture *texture, image::ImageData *data) override;
    bool releaseTexture(Texture *texture) override;
    bool updateTexture(Texture *texture, int width, int height,
                       const uint8_t *rgba) override;
    eve::Result<void> updateTextureFromResidentRgba8(Texture* texture, const GpuResidentBufferView& source, int width,
                                                     int height) override;
    eve::Result<void> updateTextureRegion(Texture *texture, int x, int y, int width,
                                          int height, std::span<const std::uint8_t> rgba,
                                          std::size_t bytesPerRow = 0) override;
    eve::Result<void> updateTextureRegions(
        Texture *texture, std::span<const TextureRegionUpload> regions) override;
    bool replaceTexturePixels(Texture *tex, image::ImageData *data);
    bool replaceTexturePixelsRGBA(Texture *tex, int w, int h, const uint8_t *rgba);
    void drawTexturedRect(Texture *texture, float x, float y, float w, float h, const Color &color) override;
    void drawTexturedRectShader(Texture *texture, Shader *shader, float x, float y, float w, float h,
                                const Color &color) override;
    void drawTexturedRectUV(Texture *texture, float x, float y, float w, float h, float u0, float v0,
                            float u1, float v1, const Color &color) override;
    void drawTexturedRectShaderUV(Texture *texture, Shader *shader, float x, float y, float w,
                                  float h, float u0, float v0, float u1, float v1,
                                  const Color &color, bool rotatedUV = false,
                                  BlendMode blend = BlendMode::Alpha) override;
    void drawTexturedRectShaderUVRotated(Texture *texture, Shader *shader, float cx, float cy,
                                         float w, float h, float degrees, float u0, float v0,
                                         float u1, float v1, const Color &color,
                                         bool rotatedUV = false,
                                         BlendMode blend = BlendMode::Alpha) override;
    void drawTexturedRectShaderDepth(Texture *color, Texture *depth, Shader *shader, float x, float y,
                                     float w, float h, const Color &tint) override;
    void drawTexturedRectShaderDepthMotion(Texture *color, Texture *depth, Texture *motion,
                                           Shader *shader, float x, float y, float w, float h,
                                           const Color &tint) override;
    void drawTexturedRectShader4(Texture *color, Texture *depth, Texture *motion, Texture *extra,
                                 Shader *shader, float x, float y, float w, float h,
                                 const Color &tint) override;
    void drawTexturedRectShader5(Texture *color, Texture *depth, Texture *motion, Texture *extra,
                                 Texture *specular, Shader *shader, float x, float y, float w,
                                 float h, const Color &tint) override;
    SceneColorDistortionStatus drawSceneColorDistortionUVRotated(
        Texture *displacement, float cx, float cy, float w, float h, float degrees, float u0,
        float v0, float u1, float v1, float strengthPixels, float opacity,
        bool rotatedUV = false) override;
    void drawTexturedRectLitUV(Texture *albedo, Texture *normal, float x, float y, float w, float h, float u0, float v0,
                               float u1, float v1, const Color &color, BlendMode blend = BlendMode::Alpha) override;
    void drawTexturedRectLitUVRotated(Texture *albedo, Texture *normal, float cx, float cy, float w, float h,
                                      float degrees, float u0, float v0, float u1, float v1, const Color &color,
                                      BlendMode blend = BlendMode::Alpha) override;
    void setLighting2D(const Lighting2DUBO &ubo) override;
    Shader *newShaderFromSpv(const std::vector<uint32_t> &vertSpv,
                             const std::vector<uint32_t> &fragSpv) override;
    Shader *newShaderFromSpvFile(const std::string &vertPath, const std::string &fragPath) override;
    Shader *newShader(const std::string &vertGlsl, const std::string &fragGlsl) override;
    Shader *newMeshShaderFromSpv(const std::vector<uint32_t> &vertSpv,
                                 const std::vector<uint32_t> &fragSpv) override;
    Shader *newMeshShaderFromWgsl(const std::string &vertWgsl,
                                  const std::string &fragWgsl) override;
    Shader *newShaderFromWgsl(const std::string &vertWgsl,
                              const std::string &fragWgsl) override;
    [[nodiscard]] Result<void> replaceShaderFromSpv(
        Shader &shader, const std::vector<uint32_t> &vertSpv,
        const std::vector<uint32_t> &fragSpv) override;
    [[nodiscard]] Result<void> replaceMeshShaderResources(Shader &shader, const std::vector<uint32_t> &vertSpv,
                                                          const std::vector<uint32_t> &fragSpv,
                                                          const ShaderResourceInputs  &resources) override;
    [[nodiscard]] Result<void> replaceShaderFromWgsl(
        Shader &shader, const std::string &vertWgsl,
        const std::string &fragWgsl) override;
    [[nodiscard]] Result<void> replaceShaderFromGlsl(
        Shader &shader, const std::string &vertGlsl,
        const std::string &fragGlsl) override;
    Shader *newMeshShader(const std::string &vertGlsl, const std::string &fragGlsl) override;
    Shader *newHairShaderFromSpv(const std::vector<uint32_t> &vertSpv,
                                 const std::vector<uint32_t> &fragSpv) override;
    Shader *newHairShaderFromWgsl(const std::string &vertWgsl,
                                  const std::string &fragWgsl) override;
    bool releaseShader(Shader *shader) override;
    eve::Result<void> configureMeshShaderSurface(Shader &shader, BlendMode blend, bool depthWrite,
                                                 bool doubleSided) override;
    eve::Result<void> configureMeshShaderRaster(Shader &shader, const MeshShaderRasterState &state) override;
    Mesh *newMeshFromAssimp(const ::aiMesh &mesh) override;
    Mesh *newMeshFromAssimp(const ::aiMesh &mesh, const aiMatrix4x4 &worldTransform) override;
    Mesh *newMeshFromArrays(const float *posXYZ, const float *nrmXYZ, const float *uvST,
                            int vertexCount, const uint32_t *indices, int indexCount) override;
    Mesh *newMeshFromArraysColored(const float *posXYZ, const float *nrmXYZ, const float *uvST,
                                   const float *colorRGBA, int vertexCount,
                                   const uint32_t *indices, int indexCount) override;
    [[nodiscard]] std::optional<eve::graphics::MeshBackendDescriptor> describeMesh(Mesh *mesh) const override;
    bool bakeMeshMorph(Mesh *mesh) override;
    bool updateMeshVertices(Mesh *mesh, const float *posXYZ, const float *nrmXYZ, const float *uvST,
                            int vertexCount, const uint32_t *indices, int indexCount) override;
    bool setMeshSkinningData(Mesh *mesh, const uint16_t *joints4, const float *weights4,
                             int vertexCount) override;
    Mesh *newMeshSphere(int slices = 32, int stacks = 16) override;
    Mesh *newMeshCylinder(int slices = 32, int stacks = 1, bool caps = true) override;
    bool releaseMesh(Mesh *mesh) override;
    void begin3DFrame() override;
    void begin3DFrameToCanvas(Canvas *canvas) override;
    void end3DFrameToCanvas() override;
    void  drawPrimitiveScene(const PrimitiveSceneCanvas3D &canvas) override;
    float getLastOffscreen3DGpuDurationMs() const override {
        return lastOffscreen3DGpuDurationMs;
    }
    void setMesh3DViewProj(const glm::mat4 &viewProj) override;
    void setMesh3DView(const glm::mat4 &view) override;
    void setMesh3DClip(float nearZ, float farZ) override;
    Texture *getSceneColorTexture() override;
    image::ImageData *renderEntityIdMask(
        const std::vector<eve::graphics::Graphics::EntityIdDraw> &draws, const glm::mat4 &viewProj,
        int width, int height) override;
    image::ImageData *readGBufferToImageData(const std::string &name) override;
    image::ImageData *readDecalLayerToImageData(const std::string &attachment) override;
    void drawMesh(Mesh *mesh, const glm::mat4 &model, Texture *texture, const Color &tint) override;
    void drawMeshShader(Mesh *mesh, const glm::mat4 &model, Texture *texture, const Color &tint,
                        Shader *shader) override;
    [[nodiscard]] Result<void> drawMeshShaderInstances(Mesh &mesh, Shader &shader, const glm::mat4 &model,
                                                       const Color &tint, std::uint32_t first,
                                                       std::uint32_t count) override;
    void drawVoxelFaceInstances(const uint32_t *packed, int count, float originX, float originY, float originZ,
                                const std::string &faceDir, Texture *atlas, int tilesPerRow = 16,
                                const uint32_t *ao = nullptr) override;
    void setMesh3DNormalTexture(Texture *normal) override;
    void setMesh3DPackedNormalMask(bool enabled) override;
    void setMesh3DHeightTexture(Texture *height) override;
    void setMesh3DVirtualTexture(bool enabled, int pageCountX, int pageCountY,
                                 int atlasSlotsX, int atlasSlotsY,
                                 float borderFraction) override;
    void              setMesh3DSceneDepth(Texture *depth) override;
    void              setMesh3DSceneColor(Texture *color) override;
    [[nodiscard]] Mesh3DSceneColorCaptureStatus captureMesh3DSceneColor() override;
    void              setMesh3DMaterial(float metallic, float roughness) override;
    [[nodiscard]] Result<void>                  setMesh3DPbrSurface(const PbrSurface* surface) override;
    void              setMesh3DSurface(SurfaceMode mode, BlendMode blend, bool depthWrite,
                                       bool doubleSided, float alphaCutoff,
                                       const std::string &alphaTechnique = "cutoff") override;
    void              setMesh3DTexCellBomb(float cellScale, float strength, float rotAmount = 1.f) override;
    void              setMesh3DParallax(float scale, float minLayers = 8.f, float maxLayers = 32.f) override;
    void              setMesh3DLodDither(float weight, bool reverse, bool enabled) override;
    void              setMesh3DLighting(const Lighting3DPack &pack) override;
    void setCloudShadows(float strength, float worldCell, float time, float windSpeed, float windAngle, float coverage,
                         float detail) override;
    void setMesh3DClusteredLighting(const ClusteredLightingUpload &upload) override;
    void setMesh3DClusteredActive(bool active) override;
    void setMesh3DSSAO(float intensity) override { (void)intensity; }
    void setMesh3DLight(const glm::vec3 &dir, const glm::vec3 &color) override;
    void setMesh3DCameraPos(const glm::vec3 &eye) override;
    void setMesh3DEnv(Texture *cube, float intensity) override;
    void setMesh3DEnvProbe(const glm::vec3 &center, const glm::vec3 &extent) override;
    void setMesh3DReflectionProbes(const ReflectionProbeUpload &upload) override;
    [[nodiscard]] Result<void> setSceneToneMapping(SceneToneMapping mode) override;
    SceneToneMapping           getSceneToneMapping() const override { return sceneToneMapping_; }
    [[nodiscard]] Result<void> setDisplayOutputMode(DisplayOutputMode mode) override;
    [[nodiscard]] Result<void> setDisplayHdrCalibration(float paperWhiteNits, float peakNits) override;
    [[nodiscard]] Result<DisplayOutputSupport> queryDisplayOutputSupport() const override;
    [[nodiscard]] Result<void> setScenePhotographicVignette(float intensity) override;
    float getScenePhotographicVignette() const override { return scenePhotographicVignette_; }
    void setSceneExposure(float exposure) override { sceneExposure = std::max(exposure, 0.f); }
    float getSceneExposure() const override { return sceneExposure; }
    void setSceneColorFilter(const glm::vec3& color) override {
        sceneColorFilter = glm::max(color, glm::vec3(0.f));
    }
    glm::vec3 getSceneColorFilter() const override { return sceneColorFilter; }
    void setSceneLiftGammaGain(const glm::vec3& lift, const glm::vec3& inverseGamma,
                               const glm::vec3& gain) override {
        sceneLift = lift;
        sceneInverseGamma = glm::max(inverseGamma, glm::vec3(0.001F));
        sceneGain = gain;
    }
    glm::vec3 getSceneLift() const override { return sceneLift; }
    glm::vec3 getSceneInverseGamma() const override { return sceneInverseGamma; }
    glm::vec3 getSceneGain() const override { return sceneGain; }
    void setSceneTransitionFx(float vignette, float vignetteSmoothness,
                              float lensDistortion, float lensScale) override {
        sceneTransitionVignette = std::clamp(vignette, 0.0F, 1.0F);
        sceneTransitionVignetteSmoothness = std::clamp(vignetteSmoothness, 0.01F, 1.0F);
        sceneTransitionLensDistortion = std::clamp(lensDistortion, 0.0F, 1.0F);
        sceneTransitionLensScale = std::clamp(lensScale, 0.01F, 5.0F);
    }
    float getSceneTransitionVignette() const override { return sceneTransitionVignette; }
    float getSceneTransitionVignetteSmoothness() const override { return sceneTransitionVignetteSmoothness; }
    float getSceneTransitionLensDistortion() const override { return sceneTransitionLensDistortion; }
    float getSceneTransitionLensScale() const override { return sceneTransitionLensScale; }
    void setSceneAutoExposure(bool enabled, float minEV, float maxEV) override {
        sceneAutoExposure = enabled;
        sceneAutoExposureMinEV = minEV;
        sceneAutoExposureMaxEV = maxEV;
    }
    bool getSceneAutoExposure() const override { return sceneAutoExposure; }
    float getSceneAutoExposureMinEV() const override { return sceneAutoExposureMinEV; }
    float getSceneAutoExposureMaxEV() const override { return sceneAutoExposureMaxEV; }
    void setSceneBloom(float intensity, float threshold) override {
        sceneBloomIntensity = intensity;
        sceneBloomThreshold = threshold;
    }
    float getSceneBloomIntensity() const override { return sceneBloomIntensity; }
    float getSceneBloomThreshold() const override { return sceneBloomThreshold; }
    void setSceneDepthOfField(float focusDistance, float maxBlurPx, float focusRange, float nearZ,
                              float farZ) override {
        sceneDofFocusDistance = focusDistance;
        sceneDofMaxBlurPx = maxBlurPx;
        sceneDofFocusRange = focusRange;
        sceneDofNearZ = nearZ;
        sceneDofFarZ = farZ;
    }
    float getSceneDofFocusDistance() const override { return sceneDofFocusDistance; }
    float getSceneDofMaxBlur() const override { return sceneDofMaxBlurPx; }
    float getSceneDofFocusRange() const override { return sceneDofFocusRange; }
    float getSceneDofNearZ() const override { return sceneDofNearZ; }
    float getSceneDofFarZ() const override { return sceneDofFarZ; }
    void setMesh3DShadows(const ShadowUpload &upload) override;
    void setMesh3DShadowReceive(bool receive) override;
    void setMesh3DSkinInfluenceLimit(SkinInfluenceLimit count) override;
    void beginShadowPass(int cascadeIndex) override;
    void drawMeshShadow(Mesh *mesh, const glm::mat4 &lightMVP, bool doubleSided = true) override;
    void drawMeshShadowAlpha(Mesh *mesh, const glm::mat4 &lightMVP, Texture *albedo = nullptr,
                             bool doubleSided = true, float lodWeight = 1.f,
                             bool lodFadeReverse = false, bool lodDither = false) override;
    void endShadowPass() override;
 
    void beginGBufferPass(int width, int height) override;
    void drawMeshGBuffer(Mesh *mesh, const glm::mat4 &mvp, const glm::mat4 &model, float nearZ,
                         float farZ, Texture *albedo = nullptr, float tintR = 1.f, float tintG = 1.f,
                         float tintB = 1.f, float motionX = 0.f, float motionY = 0.f,
                         float roughness = 0.45f, float metallic = 0.f) override;
    void drawMeshGBufferAlpha(Mesh *mesh, const glm::mat4 &mvp, const glm::mat4 &model, float nearZ,
                              float farZ, Texture *albedo = nullptr, float tintR = 1.f,
                              float tintG = 1.f, float tintB = 1.f, float motionX = 0.f,
                              float motionY = 0.f, float roughness = 0.45f,
                              float metallic = 0.f) override;
    void endGBufferPass() override;
 
    bool supportsDecal() const override { return true; }
    void beginDecalPass(int width, int height) override;
    void setDecalCamera(const glm::mat4 &viewProj, float nearZ, float farZ) override;
    void drawDecal(const glm::mat4 &model, Texture *albedo, Texture *normal, Texture *params,
                   const float uvRect[4], float fade, float normalStrength, float roughnessStrength,
                   float metalStrength, float emissiveStrength, int blendMode = 0,
                   int projectionMode = 0, float blendSharpness = 4.f,
                   float parallaxScale = 0.f, float parallaxMinLayers = 8.f,
                   float parallaxMaxLayers = 24.f, float edgeFadeWidth = 0.06f) override;
    void endDecalPass() override;
 
    Canvas *newCanvas(int width, int height) override;
    Canvas *newHDRCanvas(int width, int height) override;
    void setCanvas(Canvas *canvas) override;
    bool isCanvasActive() const override;
    Canvas *getCanvas() const override;
 
    Texture *getTexture() override;
    image::ImageData *newImageData() override;
 
    void draw(eve::graphics::Graphics *gfx, const glm::mat4 &matrix) const override;
    void draw(Canvas *C, const glm::mat4 &matrix) const override;
    void clear(std::optional<Color> color, std::optional<int> stencil, std::optional<double> depth) override;
    Color getPixel(int x, int y) override;
 
    vkb::Device &getDevice() { return device; }
    vk::CommandPool getUploadPool() const { return uploadPool; }
    bool canRecordPostSceneGpuWork() const { return bool(presentRecording) && !sceneColorPassOpen; }
    vk::CommandBuffer&          postSceneCommandBuffer() { return currentPresentCb(); }
    vk::DescriptorSetLayout getTexSetLayout() const { return texSetLayout; }
    vk::DescriptorPool getDescriptorPool() const { return descriptorPool; }
    const vkb::BuiltRenderPass &getOffscreenRenderPass(bool hdr = false) const {
        return hdr ? hdrOffscreenRenderPass : offscreenRenderPass;
    }
    const vkb::BuiltRenderPass &getOffscreen3DRenderPass(bool hdr = false) {
        return hdr ? hdrOffscreen3DRenderPass : offscreen3DRenderPass;
    }
    vk::Format getDepthFormat() const { return depthFormat; }
    vk::RenderPass getSwapchainRenderPass() const { return renderpass; }
    vk::RenderPass getUiMsaaRenderPass() const { return uiRenderPass; }
    vk::SampleCountFlagBits getUiMsaaSamples() const { return uiColorSamples; }
    void ensureUiColorResources() {
        createUiColorResources(int(swapchain.extent.width), int(swapchain.extent.height));
    }
    void drawUiTextureRects(void* commandBuffer, const std::vector<UiTextureDraw>& draws, std::size_t bufferOffset = 0);
    vkb::Instance &getInstance() { return inst; }
    vkb::Swapchain &getSwapchain() { return swapchain; }
    void *getSdlWindow() const { return sdlWindow; }
    uint32_t getSwapchainImageCount() const { return swapchain.image_count; }
 
    friend class OffscreenCanvas;
 
    struct LitBatch {
        Texture *albedo = nullptr;
        Texture *normal = nullptr;
        BlendMode blend  = BlendMode::Alpha;
        Batcher batch;
    };
 
private:
    void drawMeshShaderRange(Mesh *mesh, const glm::mat4 &model, Texture *texture, const Color &tint, Shader *shader,
                             std::uint32_t first, std::uint32_t count);
    struct GpuParticleDrawRequest;
    struct GpuParticleResource;
 
    struct Mesh3dFrameSlots;
    struct Mesh3dClusteredFrameSlots;
    struct DecalSlot;
    struct DecalSetKey;
    struct DecalSetKeyHash;
    struct GBufferSlot;
    void createSwapchainAndPipeline();
    void applyPreferredSwapchainFormats(vkb::SwapchainBuilder &builder);
    void createTexturedPipeline();
    void createLit2DPipeline();
    void          createGpuParticlePipelines();
    void          destroyGpuParticleResources();
    void          recordGpuParticleCompute(vk::CommandBuffer cb);
    void          drawGpuParticleRequest(vk::CommandBuffer cb, const GpuParticleDrawRequest& request);
    struct PbrResources;
    static void                                            deletePbrResources(PbrResources* resources);
    std::unique_ptr<PbrResources, void (*)(PbrResources*)> pbrResources_{nullptr, &deletePbrResources};
    std::optional<PbrSurface>                              pbrSurface_;
    void                                                   destroyPbrResources();
    void          drawPbrMesh(Mesh* mesh, const glm::mat4& model, const Color& tint);
    void createMesh3DPipeline();
    void createMesh3DClusteredPipeline();
    void                                                   createDeferredLightingPipeline();
    void                                                   destroyDeferredLightingResources();
    void createVoxelRectPipeline();
    vk::Pipeline buildVoxelRectPipeline(const vkb::BuiltRenderPass &rp,
                                        vk::SampleCountFlagBits samples);
    void destroyVoxelRectResources();
    void ensureVoxelUnitQuad();
    vkb::BoundSet voxelRectSetFor(GpuTexture *gpuTex);
    void createShadowResources();
    void destroyShadowResources();
    void createGBufferResources(int width, int height);
    void destroyGBufferResources();
    void createDecalResources(int width, int height);
    void destroyDecalResources();
    void recordDecalPass();
    void recordDecalPassInto(vk::CommandBuffer cb, DecalSlot &slot, GBufferSlot &gslot);
    void ensureDecalUnitBox();
    void ensureDecalPlaceholders();
    vkb::BoundSet decalSetFor(DecalSlot &slot, GpuTexture *albedo, GpuTexture *normal,
                              GpuTexture *params, GpuTexture *depth, GpuTexture *gbNormal);
    DecalSlot *currentDecalSlot();
    void createSceneColorResources(int width, int height);
    void destroySceneColorResources();
    void createUiColorResources(int width, int height);
    void destroyUiColorTargets();
    void destroyUiColorResources();
    void queueUiResolve();
    bool renderUiOverlayPass();
    void recordDeferredFrameGraph();
    void dropPendingOffscreenPasses();
    bool beginSwapchainRenderPass();
    void          beginSwapchainColorPass();
    bool          beginSceneColorRenderPass();
    void          endSceneColorRenderPass();
    void          ensureOffscreen3DResources();
    void          destroyOffscreen3DResources();
    void          queueSceneColorResolve();
    void          materializeSceneColorResolve();
    void          ensureClusteredBuffers(size_t lightsBytes, size_t tableBytes, size_t indicesBytes);
    void          uploadClusteredLighting(const ClusteredLightingUpload &upload);
    void          ensureMesh3dStrides();
    void          ensureMesh3dRing(Mesh3dFrameSlots &fslots);
    size_t                  uploadSkinPalette(Mesh* mesh, Mesh3dFrameSlots& fslots);
    vk::DescriptorSet skinPassSetFor(GpuTexture *albedo, Mesh3dFrameSlots &fslots);
    bool prepareSkinPass(Mesh *mesh, Texture *albedo, const glm::mat4 &mvp,
                         const glm::mat4 &model, const glm::vec4 &clip,
                         vk::DescriptorSet &set, uint32_t &uboOffset);
    void          ensureMesh3dClusteredRing(Mesh3dClusteredFrameSlots &fslots);
    vkb::BoundSet mesh3dClusteredSetFor(GpuTexture *gpuTex, GpuTexture *normalTex,
                                        GpuTexture *envTex, GpuTexture *heightTex,
                                        GpuTexture *decalAlbedo, GpuTexture *decalNormal,
                                        GpuTexture *decalParams,
                                        Mesh3dClusteredFrameSlots &fslots);
    void          ensureOffscreenPipelines();
    void          ensureHdrOffscreenPipelines();
    void          ensureShaderOffscreenPipeline(Shader *shader);
    void          ensureShaderHdrOffscreenPipeline(Shader *shader);
    void          destroyPresentGraphicsPipelines();
    void          rebuildGpuParticleDrawPipelines(const vkb::BuiltRenderPass &target);
    void          ensureHdrGpuParticleDrawPipelines();
    void          ensurePresentComposeResources(int width, int height);
    void          destroyPresentComposeResources();
    struct PresentComposeSlot;
    PresentComposeSlot *currentPresentComposeSlot();
    bool          beginPresentComposePass();
    void          endPresentComposePass();
    void          encodePresentComposeToSwapchain(vk::CommandBuffer cb);
    vk::Pipeline  createTexturedStylePipeline(const std::vector<uint32_t> &vert, const std::vector<uint32_t> &frag,
                                              const vkb::BuiltRenderPass &rp, vk::PipelineLayout layout,
                                              BlendMode mode = BlendMode::Alpha,
                                              vk::SampleCountFlagBits samples = vk::SampleCountFlagBits::e1);
    vk::Pipeline      createMesh3DStylePipeline(const std::vector<uint32_t> &vert, const std::vector<uint32_t> &frag,
                                                vk::PipelineLayout layout, const vkb::BuiltRenderPass &rp,
                                                vk::SampleCountFlagBits samples, BlendMode blend = BlendMode::Opaque,
                                                bool depthWrite = true, bool doubleSided = true,
                                                const MeshShaderRasterState &raster = {});
    eve::Result<void> rebuildMeshShaderSurface(Shader &shader, BlendMode blend, bool depthWrite, bool doubleSided,
                                               const MeshShaderRasterState &raster);
    static constexpr size_t kMesh3DPipelineVariants = 20;
    static size_t mesh3dPipelineIndex(BlendMode blend, bool depthWrite, bool doubleSided);
    static constexpr size_t kPrimitive3DPipelineVariants = 45;
    static size_t           primitive3DPipelineIndex(PrimitiveDepthMode depth, BlendMode blend, PrimitiveCullMode cull);
    vk::Pipeline createMesh3DXrayPipeline(const std::vector<uint32_t> &vert,
                                          const std::vector<uint32_t> &frag,
                                          vk::PipelineLayout layout,
                                          const vkb::BuiltRenderPass &rp,
                                          vk::SampleCountFlagBits samples);
    vk::Pipeline createMesh3DHairPipeline(const std::vector<uint32_t> &vert,
                                          const std::vector<uint32_t> &frag,
                                          vk::PipelineLayout layout,
                                          const vkb::BuiltRenderPass &rp,
                                          vk::SampleCountFlagBits samples);
    void ensureScenePassPipelines(const vkb::BuiltRenderPass &target,
                                  vk::SampleCountFlagBits samples);
    void rebuildPrimitive3DPipelines(const vkb::BuiltRenderPass &target, vk::SampleCountFlagBits samples);
    void buildPrimitive3DPipelines(const vkb::BuiltRenderPass &target, vk::SampleCountFlagBits samples,
                                   std::array<vk::Pipeline, kPrimitive3DPipelineVariants> &pipelines);
    int clampMsaaSamples(int requested) const;
    const vkb::BuiltRenderPass &activeScenePass() const {
        return sceneColorRenderPass ? sceneColorRenderPass : renderpass;
    }
    vk::SampleCountFlagBits activeSceneSamples() const {
        return sceneColorRenderPass ? sceneColorSamples : vk::SampleCountFlagBits::e1;
    }
    void destroySwapchainResources();
    void flushBatch();
    void flushToSwapchain();
    void flushToOffscreen(OffscreenCanvas *canvas);
    void abortOpen3DFrame();
    void noteSolidOverlay(uint32_t batchIndex);
    void noteTexturedOverlay(Texture *tex, uint32_t batchIndex);
    void noteLitOverlay(uint32_t batchIndex);
    void clear2DBatches();
    void          drawLitBatches(vk::CommandBuffer cb, int viewW, int viewH, std::vector<LitBatch> &batches,
                                 std::vector<vkb::HostVertexBuffer> &texBufs, size_t &texBufIndex, bool offscreen,
                                 bool hdr = false);
    vkb::BoundSet lit2dSetFor(GpuTexture *albedo, GpuTexture *normal, bool offscreen);
    vkb::BoundSet post2SetFor(GpuTexture *color, GpuTexture *depth,
                              GpuTexture *motion = nullptr, GpuTexture *extra = nullptr,
                              GpuTexture *specular = nullptr);
    void          ensureFlatNormalTexture();
    void          ensureReadbackSlots();
    bool          recordSwapchainReadback(vk::CommandBuffer cb);
    void          syncReadbackCpu();
    void          destroyReadbackResources();
    void          ensurePresentCaptureHook();
    vkb::BoundSet mesh3dSetFor(GpuTexture *gpuTex, GpuTexture *normalTex, GpuTexture *envTex,
                               GpuTexture *heightTex, GpuTexture *depthTex, GpuTexture *sceneColorTex,
                               GpuTexture *decalAlbedo, GpuTexture *decalNormal,
                               GpuTexture *decalParams, Mesh3dFrameSlots &fslots);
    void          ensureDefaultEnvCubemap();
    void          ensureFlatNormalTexture3D();
    void          ensureFlatHeightTexture3D();
    vk::Sampler   createVkSampler(const TextureSampler &sampler, uint32_t mipLevels) const;
    void          writeCombinedImageDescriptor(GpuTexture *gpu);
    void createInstanceAndDevice(const std::vector<const char *> &instanceExtensions,
                                 void *nativeWindow, vk::SurfaceKHR *surfaceOut);
    bool rebuildSwapchainIfNeeded();
    bool beginPresentCommandBuffer();
 
    bool initialized = false;
    bool headless_ = false;
    bool hasPresentedFrame = false;
    float maxSamplerAnisotropy = 1.f;
    std::vector<uint8_t> lastFrameRgba;
    // Persistent host-visible staging buffers for swapchain readback. The copy
    // is recorded into the present command buffer (no extra submit / no
    // per-frame GPU wait), and each present frame slot owns one slot so a
    // staging buffer is only reused after that slot's fence has signaled.
    struct ScreenReadbackSlot {
        vkb::GenericBuffer staging;
        void *mapped = nullptr;
    };
    std::vector<ScreenReadbackSlot> screenReadbackSlots;
    size_t screenReadbackBytes = 0;
    size_t readbackWriteSlot = 0;
    bool readbackReady = false;     // at least one copy submitted
    bool readbackCpuSynced = false; // newest copy already converted to lastFrameRgba
    bool readbackBgra = false;      // swapchain format of the newest captured frame
    Canvas *activeCanvas = nullptr;
    bool swapchainDirty = false;
    void markSwapchainDirty() override { swapchainDirty = true; }
    // Set from the SDL event-watch thread on Android foreground; consumed on
    // the render thread inside flushToSwapchain().
    std::atomic<bool> surfaceNeedsRecreate{false};
    void recreateSurfaceForResume();
    // False while the native window is mid-(re)creation / rotation (Android),
    // when touching the swapchain or presenting would crash the GPU driver.
    bool isRenderSurfaceReady() const;
    // Returns true only once the drawable size has been non-zero and identical
    // across consecutive frames, i.e. the surface has settled after a
    // rotation/resume and is safe to (re)build a swapchain against.
    bool isRenderSurfaceStable();
    int pendingSurfaceW = 0;
    int pendingSurfaceH = 0;
    int surfaceStableFrames = 0;
    void *sdlWindow = nullptr;
    vk::SurfaceKHR surface;
 
    vkb::Instance inst;
#if defined(VKB_ENABLE_VMA)
    // Declared before Device and all GPU resources so reverse member
    // destruction keeps the allocator alive until every buffer is gone.
    VmaAllocatorOwner vmaAllocatorOwner_;
#endif
    vkb::Device device;
    vkb::Swapchain swapchain;
    vkb::BuiltRenderPass renderpass;
 
    vk::Pipeline pipeline;
    vk::PipelineLayout pipelineLayout;
    vk::Pipeline solidAlphaPipeline;       // alpha-blended solid (BlendMode::Alpha)
    vk::Pipeline additiveSolidPipeline;    // additive solid (BlendMode::Additive)
    vk::Pipeline premultipliedSolidPipeline;
    vk::Pipeline multiplySolidPipeline;
 
    vk::DescriptorSetLayout texSetLayout;
    vk::UniqueDescriptorSetLayout texSetLayoutUnique;
    vk::DescriptorPool descriptorPool;
    vk::Pipeline texPipeline;
    vk::Pipeline additiveTexPipeline;
    vk::Pipeline premultipliedTexPipeline;
    vk::Pipeline multiplyTexPipeline;
    vk::Pipeline opaqueTexPipeline;
    vk::Pipeline particleDistortionPipeline;
    vk::Pipeline sceneTonemapPipeline;
    vk::Format presentAttachmentFormat_ = vk::Format::eUndefined;
    SceneToneMapping              sceneToneMapping_      = SceneToneMapping::Aces;
    vk::SurfaceFormatKHR          selectedSurfaceFormat_{vk::Format::eB8G8R8A8Unorm,
                                                vk::ColorSpaceKHR::eSrgbNonlinear};
    float sceneExposure = 1.f;
    glm::vec3 sceneColorFilter{1.f};
    glm::vec3 sceneLift{0.f};
    glm::vec3 sceneInverseGamma{1.f};
    glm::vec3 sceneGain{1.f};
    float                         scenePhotographicVignette_        = 0.0F;
    float sceneTransitionVignette = 0.0F;
    float sceneTransitionVignetteSmoothness = 0.2F;
    float sceneTransitionLensDistortion = 0.0F;
    float sceneTransitionLensScale = 1.0F;
    bool sceneAutoExposure = false;
    float sceneAutoExposureMinEV = -8.f;
    float sceneAutoExposureMaxEV = 8.f;
    float sceneBloomIntensity = 0.f;
    float sceneBloomThreshold = 1.f;
    float sceneDofFocusDistance = 0.f;
    float sceneDofMaxBlurPx = 0.f;
    float sceneDofFocusRange = 8.f;
    float sceneDofNearZ = 0.1f;
    float sceneDofFarZ = 100.f;
    vk::PipelineLayout texPipelineLayout;
    vk::PipelineLayout shaderPipelineLayout;  // tex set + push constants
    vk::CommandPool uploadPool;
 
    vkb::BuiltRenderPass offscreenRenderPass;
    vkb::BuiltRenderPass hdrOffscreenRenderPass;
    vk::Pipeline offscreenSolidPipeline;
    vk::Pipeline offscreenSolidAlphaPipeline;
    vk::Pipeline offscreenAdditiveSolidPipeline;
    vk::Pipeline offscreenPremultipliedSolidPipeline;
    vk::Pipeline offscreenMultiplySolidPipeline;
    vk::Pipeline offscreenTexPipeline;
    vk::Pipeline offscreenAdditiveTexPipeline;
    vk::Pipeline offscreenPremultipliedTexPipeline;
    vk::Pipeline offscreenMultiplyTexPipeline;
    vk::Pipeline offscreenOpaqueTexPipeline;
    vk::Pipeline hdrOffscreenTexPipeline;
    vk::Pipeline hdrOffscreenOpaqueTexPipeline;
    vk::Pipeline hdrOffscreenAdditiveTexPipeline;
    vk::Pipeline hdrOffscreenPremultipliedTexPipeline;
    vk::Pipeline hdrOffscreenMultiplyTexPipeline;
    vk::Pipeline hdrOffscreenSolidPipeline;
    vk::Pipeline hdrOffscreenSolidAlphaPipeline;
    vk::Pipeline hdrOffscreenAdditiveSolidPipeline;
    vk::Pipeline hdrOffscreenPremultipliedSolidPipeline;
    vk::Pipeline hdrOffscreenMultiplySolidPipeline;
    vk::Pipeline hdrOffscreenLitPipeline;
    vk::Pipeline         hdrOffscreenLitAdditivePipeline;
    vk::Pipeline         hdrOffscreenLitPremultipliedPipeline;
    vk::Pipeline         hdrOffscreenLitMultiplyPipeline;
    vk::Pipeline         hdrOffscreenLitOpaquePipeline;
    vk::Pipeline hdrOffscreenTonemapPipeline;
    vk::Pipeline hdrOffscreenParticleDistortionPipeline;
    vk::Pipeline hdrGpuParticleAlphaPipeline_{};
    vk::Pipeline hdrGpuParticleAdditivePipeline_{};
    vk::Pipeline hdrGpuParticlePremultipliedPipeline_{};
    vk::Pipeline hdrGpuParticleMultiplyPipeline_{};
    vk::Pipeline hdrGpuParticleOpaquePipeline_{};
    bool presentComposeActive_ = false;
 
    vk::DescriptorSetLayout mesh3dSetLayout;
    vk::UniqueDescriptorSetLayout mesh3dSetLayoutUnique;
    vk::PipelineLayout mesh3dPipelineLayout;
    vk::PipelineLayout mesh3dShaderPipelineLayout;  // + push constants for custom mesh shaders
    vk::Pipeline mesh3dPipeline;
    vk::Pipeline mesh3dTransparentPipeline;
    std::array<vk::Pipeline, kMesh3DPipelineVariants> mesh3dSurfacePipelines{};
    std::array<vk::Pipeline, kPrimitive3DPipelineVariants> primitive3DPipelines{};
    std::array<vk::Pipeline, kPrimitive3DPipelineVariants> offscreenPrimitive3DPipelines{};
    std::array<vk::Pipeline, kPrimitive3DPipelineVariants> hdrOffscreenPrimitive3DPipelines{};
    std::vector<vkb::HostVertexBuffer>                     offscreenPrimitive3DBufs;
    std::size_t                                            offscreenPrimitive3DDrawIndex = 0;
    // One UBO (+ per-texture descriptor sets) per draw in the current 3D frame.
    // Avoids vkUpdateDescriptorSets on a set already bound in a recording /
    // executable command buffer (which invalidates the CB).
    struct Mesh3dSetKey {
        GpuTexture *albedo = nullptr;
        GpuTexture *normal = nullptr;
        GpuTexture *env = nullptr;
        GpuTexture *reflectionProbe0 = nullptr;
        GpuTexture *reflectionProbe1 = nullptr;
        GpuTexture *height = nullptr;
        GpuTexture *depth = nullptr;
        GpuTexture *sceneColor = nullptr;
        GpuTexture *decalAlbedo = nullptr;
        GpuTexture *decalNormal = nullptr;
        GpuTexture *decalParams = nullptr;
        size_t      paletteSlot      = 0;
        bool operator==(const Mesh3dSetKey &o) const {
            return albedo == o.albedo && normal == o.normal && env == o.env && reflectionProbe0 == o.reflectionProbe0 &&
                   reflectionProbe1 == o.reflectionProbe1 && height == o.height && depth == o.depth &&
                   sceneColor == o.sceneColor && decalAlbedo == o.decalAlbedo && decalNormal == o.decalNormal &&
                   decalParams == o.decalParams && paletteSlot == o.paletteSlot;
        }
    };
    struct Mesh3dSetKeyHash {
        size_t operator()(const Mesh3dSetKey &k) const {
            return std::hash<GpuTexture*>()(k.albedo) ^ (std::hash<GpuTexture*>()(k.normal) << 1) ^
                   (std::hash<GpuTexture*>()(k.env) << 2) ^ (std::hash<GpuTexture*>()(k.height) << 3) ^
                   (std::hash<GpuTexture*>()(k.reflectionProbe0) << 8) ^
                   (std::hash<GpuTexture*>()(k.reflectionProbe1) << 9) ^ (std::hash<GpuTexture*>()(k.depth) << 4) ^
                   (std::hash<GpuTexture*>()(k.sceneColor) << 10) ^ (std::hash<GpuTexture*>()(k.decalAlbedo) << 5) ^
                   (std::hash<GpuTexture*>()(k.decalNormal) << 6) ^ (std::hash<GpuTexture*>()(k.decalParams) << 7) ^
                   k.paletteSlot;
        }
    };
    // Per-frame-slot UBO rings, keyed by Present::frames_in_flight so a frame
    // never overwrites a UBO that an in-flight frame is still reading.
    // Per-draw data is written at dynamic offsets into the ring and the same
    // descriptor set (cached per texture combination) is re-bound with a new
    // offset, so descriptor-pool usage is bounded by texture count instead of
    // growing with draw count.
    struct Mesh3dFrameSlots {
        vkb::GenericBuffer uboRing;            // capacity * mesh3dUboStride bytes
        vkb::GenericBuffer shadowRing;         // capacity * shadowUboStride bytes
        size_t             capacity      = 0;  // per-draw slot count the rings hold
        size_t             drawIndex     = 0;
        size_t             lastDrawCount = 0;
        std::unordered_map<Mesh3dSetKey, vkb::BoundSet, Mesh3dSetKeyHash> sets;
        std::map<std::pair<size_t, GpuTexture*>, vkb::BoundSet>           skinSets;
        std::vector<vkb::GenericBuffer>                                   palettes;
        size_t                                                            activePalette = 0;
    };
    std::vector<Mesh3dFrameSlots> mesh3dFrameSlots;
    Texture                      *whiteTexture            = nullptr;
    Texture                      *defaultExtrasArray = nullptr;
    Texture                      *defaultColorsArray = nullptr;
    Texture                      *defaultVertexArray = nullptr;
    Texture                      *defaultMotionArray = nullptr;
    Texture                      *defaultVegetationFadeNoise = nullptr;
    Texture                      *defaultBindlessCube     = nullptr;
    Texture                      *flatNormalTexture3D     = nullptr;
    Texture                      *flatHeightTexture3D     = nullptr;
    Texture                      *defaultEnvCubemap       = nullptr;
    Texture                      *mesh3dNormalTexture     = nullptr;
    Texture                      *mesh3dHeightTexture     = nullptr;
    Texture *mesh3dEnvTexture = nullptr;
    Texture *mesh3dSceneDepthTexture = nullptr;
    Texture *mesh3dSceneColorTexture = nullptr;
    float mesh3dEnvIntensity = 0.f;
    glm::vec3 mesh3dEnvProbeCenter{0.f};
    glm::vec3 mesh3dEnvProbeExtent{0.f};
    ReflectionProbeUpload mesh3dReflectionProbes{};
    float mesh3dMetallic = 0.f;
    float mesh3dRoughness = 0.45f;
    SurfaceMode mesh3dSurfaceMode = SurfaceMode::Opaque;
    BlendMode mesh3dSurfaceBlend = BlendMode::Alpha;
    bool mesh3dSurfaceDepthWrite = false;
    bool mesh3dSurfaceDoubleSided = false;
    float mesh3dAlphaCutoff = 0.5f;
    std::string mesh3dAlphaTechnique = "cutoff";
    glm::vec4 mesh3dLodFade{1.f, 0.f, 0.f, 0.f};
    float mesh3dTexBombScale = 4.f;
    float mesh3dTexBombStrength = 0.f;
    float mesh3dTexBombRot = 1.f;
    float mesh3dParallaxScale = 0.f;
    float mesh3dParallaxMinLayers = 8.f;
    float mesh3dParallaxMaxLayers = 32.f;
    glm::vec4 mesh3dVirtualTexture{0.f};
    glm::vec4 mesh3dVirtualAtlas{0.f};
    Lighting3DPack mesh3dLighting{};
    ShadowUpload mesh3dShadows{};
    bool mesh3dShadowReceive = true;
    int mesh3dSkinInfluenceLimit = 4;
 
    // Clustered forward (separate set layout / pipeline; default PBR only).
    bool mesh3dClusteredActive = false;
    ClusteredLightingUpload mesh3dClustered{};
    vk::DescriptorSetLayout mesh3dClusteredSetLayout;
    vk::UniqueDescriptorSetLayout mesh3dClusteredSetLayoutUnique;
    vk::PipelineLayout mesh3dClusteredPipelineLayout;
    vk::Pipeline mesh3dClusteredPipeline;
    // Per-frame clustered storage (lights / cluster table / light indices),
    // multi-buffered so an in-flight frame's forward pass never reads storage
    // that the next frame is overwriting.
    struct ClusteredStorage {
        vkb::GenericBuffer lightsBuf;
        vkb::GenericBuffer tableBuf;
        vkb::GenericBuffer indicesBuf;
        size_t             lightsCap  = 0;
        size_t             tableCap   = 0;
        size_t             indicesCap = 0;
    };
    std::vector<ClusteredStorage> clusteredStorages;  // per swapchain frame slot
    struct Mesh3dClusteredFrameSlots {
        vkb::GenericBuffer uboRing;     // capacity * mesh3dClusteredUboStride bytes
        vkb::GenericBuffer shadowRing;  // capacity * shadowUboStride bytes
        size_t             capacity      = 0;
        size_t             drawIndex     = 0;
        size_t             lastDrawCount = 0;
        std::unordered_map<Mesh3dSetKey, vkb::BoundSet, Mesh3dSetKeyHash> sets;
    };
    std::vector<Mesh3dClusteredFrameSlots> mesh3dClusteredFrameSlots;
 
    uint32_t mesh3dUboStride          = 0;
    uint32_t shadowUboStride          = 0;
    uint32_t mesh3dClusteredUboStride = 0;
    vk::Pipeline lastMesh3dPipeline          = nullptr;
    vk::Pipeline lastMesh3dClusteredPipeline = nullptr;
 
    // Ping-pong copies so frame N+1 can write while frame N still samples.
    static constexpr uint32_t kAsyncResourceCopies = 2;
 
    // ---- GPU-driven (stage 0): bindless set + per-frame arena + tables ----
    GpuDrivenCaps gpuDrivenCaps_{};
    RayTracingCaps          rayTracingCaps_{};
    std::vector<FrameArena> frameArenas_;
 
    vk::UniqueDescriptorSetLayout bindlessSetLayoutUnique_{};
    vk::DescriptorSetLayout bindlessSetLayout_ = nullptr;
    vk::DescriptorPool bindlessPool_ = nullptr;
    // One bindless set per frame-in-flight slot. A frame rewrites only the set
    // belonging to its own slot, and only AFTER acquireForFrame() has waited
    // that slot's fence; pending command buffers therefore never observe a
    // descriptor set being rewritten (VUID-vkUpdateDescriptorSets-None-03047).
    // The texture arrays (bindings 0/1) are mirrored into every set at
    // registration time so any slot can sample any registered texture.
    std::vector<vk::DescriptorSet> bindlessSets_;
    std::vector<GpuTexture *> bindlessTextures2D_;
    std::vector<uint32_t> bindlessFree2D_;
    std::vector<GpuTexture *> bindlessCubemaps_;
    std::vector<uint32_t> bindlessFreeCube_;
 
    vkb::GenericBuffer meshTableBuffer_;
    std::vector<GpuMeshRecord> meshTableRecords_;
    std::vector<GpuMesh *> meshRecordOwners_;
    uint32_t meshTableCapacity_ = 0;
 
    vkb::GenericBuffer materialTableBuffer_;
    std::vector<GpuMaterialRecord> materialTableRecords_;
    std::vector<uint32_t> materialTableFree_;
    std::unordered_map<const Material *, uint32_t> materialTableIndex_;
    uint32_t materialTableCapacity_ = 0;
 
    uint32_t registerBindlessTexture2D(GpuTexture *tex);
    uint32_t registerBindlessTextureCube(GpuTexture *tex);
    void unregisterBindlessTexture(GpuTexture *tex);
    uint32_t          registerMeshRecord(GpuMesh *gpu, const std::vector<MeshVertex> *vertices = nullptr,
                                         const std::vector<uint32_t> *indices = nullptr);
    void syncMeshTable();
    GpuMaterialRecord buildMaterialRecord(Material *material);
    void createBindlessSet();
    vk::DescriptorSet bindlessSetForFrame() const;
 
    // ---- GPU-driven (stage 3): pooled vertices + visibility buffer ----
    struct GpuVertexPool {
        vkb::GenericBuffer positions;  // vec4 per vertex (16B; w unused)
        vkb::GenericBuffer normals;    // vec4 per vertex
        vkb::GenericBuffer uvs;        // vec2 per vertex (8B)
        vkb::GenericBuffer indices;    // uint32 (u16 meshes converted)
        uint32_t vertexCount = 0;
        uint32_t indexCount = 0;
    };
    GpuVertexPool gpuVertexPool_;
    void ensureGpuVertexPool();
    void growGpuVertexPool(uint32_t needVertices, uint32_t needIndices);
    void bindGpuVertexPoolBindless();
    void appendGpuMeshToPool(GpuMesh &gpu, const std::vector<MeshVertex> *vertices = nullptr,
                             const std::vector<uint32_t> *indices = nullptr);
 
    // ---- GPU-driven (stage 3): virtual geometry ----
    static constexpr uint32_t kMaxVgAssets = 64;
    static constexpr uint32_t kMaxVgClusters = 65536;
    struct VgGpuBuffers {
        vkb::GenericBuffer positions;      // float xyz stream (growable)
        vkb::GenericBuffer triangles;      // u32 global triangle stream
        vkb::GenericBuffer clusters;       // GpuVgCluster (4 x uvec4)
        vkb::GenericBuffer clusterAssets;  // u32 per cluster -> asset id
        vkb::GenericBuffer visible;        // kAsyncResourceCopies x (counter + ids)
        vkb::GenericBuffer indirect;       // kAsyncResourceCopies x VkDrawIndirectCommand
        vkb::GenericBuffer assetMaterials; // kAsyncResourceCopies x u32 per asset
        vkb::GenericBuffer assetModels;    // kAsyncResourceCopies x mat4 per asset
    };
    VgGpuBuffers vgGpu_;
    uint32_t vgClusterCount_ = 0;   // total clusters across uploaded assets
    uint32_t vgAssetCount_ = 0;
    uint32_t vgVertexCount_ = 0;    // global position-stream vertices
    uint32_t vgTriangleCount_ = 0;  // global triangle-stream indices
    uint32_t vgLastVisible_ = 0;
    bool vgAnyThisFrame_ = false;
    ComputePass vgCullPass_;
    vk::Pipeline gbufferVgVisPipeline = nullptr;
    void ensureVgBuffers();
    void growVgBuffers(uint32_t needClusters, uint32_t needVertices, uint32_t needTriangles);
    void bindVgPoolBindless();
    void bindVgFrameBindless(vk::DescriptorSet bindless, size_t slot);
    void recordVgCull();
    void drawVgClusters(vk::CommandBuffer cb);
 
    // ---- GPU-driven (stage 1): opaque forward path ----
    bool gpuDrivenEnabled_ = false;
    uint32_t lastGpuDrivenDrawCount_ = 0;
    vk::PipelineLayout mesh3dGpuDrivenPipelineLayout = nullptr;
    vk::Pipeline mesh3dGpuDrivenPipeline = nullptr;
    vk::Pipeline resolveVisPipeline = nullptr;
    // Phase C: Hybrid clustered deferred lighting (fullscreen into scene color).
    vk::DescriptorSetLayout       deferredLightingSetLayout{};
    vk::UniqueDescriptorSetLayout deferredLightingSetLayoutUnique;
    vk::PipelineLayout            deferredLightingPipelineLayout{};
    vk::Pipeline                  deferredLightingPipeline{};
    vkb::GenericBuffer            deferredLightingUbo{};
    vk::DescriptorSet             deferredLightingSet{};
    vk::Sampler                   deferredLightingSampler{};
    void createMesh3DGpuDrivenPipeline();
    struct GpuDrivenFrameSet0 {
        vk::DescriptorSet set;
        uint32_t uboOffset = 0;
        uint32_t shadowOffset = 0;
    };
    GpuDrivenFrameSet0 gpuDrivenFrameSet0();
    void createResolveVisPipeline(const vkb::BuiltRenderPass &rp,
                                  vk::SampleCountFlagBits samples);
    void initGpuDrivenResources();
    void createGpuDrivenVisResources(int width, int height);
 
    // ---- GPU-driven (stage 2): HZB + GPU cull ----
    struct GpuDrivenCullSlot {
        vkb::GenericBuffer visibleFlags;    // uint32 per instance (GPU-written)
        vkb::GenericBuffer compacted;       // GpuInstance per instance (GPU-written)
        vkb::GenericBuffer indirect;        // GpuIndirectCommand per bucket (GPU-written)
        vkb::GenericBuffer indirectNI;      // VkDrawIndirectCommand per bucket (non-indexed)
        vkb::GenericBuffer bucketCounters;  // uint32 per bucket (GPU atomic, CPU-reset)
        vkb::GenericBuffer hzb;             // header + R32F mip chain (GPU-written)
        vkb::GenericBuffer cullParams;      // GpuCullParams UBO (CPU-written)
    };
    std::vector<GpuDrivenCullSlot> gpuDrivenCullSlots_;
    vkb::GenericBuffer gpuDrivenCullParamsPlaceholder_;  // valid UBO target at set creation
    int gpuDrivenCullWidth = 0;
    int gpuDrivenCullHeight = 0;
    uint32_t gpuDrivenCullMaxMip = 0;
    vk::PipelineLayout gpuDrivenComputeLayout = nullptr;
    vk::DescriptorSetLayout gpuDrivenComputeEmptyLayout_ = nullptr;
    ComputePass hzbBuildPass_;
    ComputePass cullPass_;
    ComputePass emitPass_;
    bool gpuDrivenCullReady_ = false;
    bool gpuDrivenScenePassPending_ = false;
    // Per-frame CPU metadata for the cull chain (uploaded to the frame arena).
    std::vector<uint32_t> gpuDrivenBucketIds_;
    std::vector<uint32_t> gpuDrivenBucketOffsets_;
    std::vector<uint32_t> gpuDrivenBucketMeshIds_;
    uint32_t gpuDrivenBucketCount_ = 0;
    uint32_t gpuDrivenCullInstanceCount_ = 0;
    uint32_t gpuDrivenLastCullSlot_ = 0;
    FrameArena::Alloc gpuDrivenInstAlloc_{};
    FrameArena::Alloc gpuDrivenBucketIdAlloc_{};
    FrameArena::Alloc gpuDrivenBucketOffAlloc_{};
    void ensureGpuDrivenCullResources(int width, int height);
    void recordGpuDrivenHzbBuild();
    void gpuDrivenRecordComputeSection(const glm::mat4 &viewProj, const glm::vec3 &eye,
                                       float fovYDeg, float nearZ, float farZ);
    void destroyGpuDrivenCullResources();
    GpuDrivenCullSlot &currentGpuDrivenCullSlot();
    GpuDrivenCullSlot &gpuDrivenCullSlot(uint32_t frameSlot);
 
    // CSM shadow map (3 cascade layers), one array per in-flight slot.
    struct ShadowMapSlot {
        vkb::DepthArrayImage image;
        vk::Framebuffer      framebuffers[ShadowConfig::kTotalLayers]{};
    };
    std::vector<ShadowMapSlot> shadowMaps;
    vkb::DepthSampler shadowSampler{};
    vk::Sampler shadowRawSampler{};
    vkb::BuiltRenderPass shadowRenderPass{};
    vk::PipelineLayout shadowPipelineLayout{};
    vk::Pipeline shadowPipeline{};
    vk::Pipeline shadowSingleSidedPipeline{};
    vk::PipelineLayout shadowAlphaPipelineLayout{};
    vk::Pipeline shadowAlphaPipeline{};
    vk::Pipeline shadowAlphaSingleSidedPipeline{};
    vk::PipelineLayout skinPassPipelineLayout{};
    vk::DescriptorSetLayout skinPassSetLayout{};
    vk::UniqueDescriptorSetLayout skinPassSetLayoutUnique;
    vk::Pipeline shadowSkinPipeline{};
    vk::Pipeline shadowSkinSingleSidedPipeline{};
    vk::Pipeline shadowSkinAlphaPipeline{};
    vk::Pipeline shadowSkinAlphaSingleSidedPipeline{};
    int shadowPassCascade = -1;
    struct ShadowDraw {
        Mesh *mesh = nullptr;
        glm::mat4 mvp{1.f};
        Texture *albedo = nullptr;
        bool alphaTest = false;  // use the alpha-cutout shadow pipeline
        bool doubleSided = true;
        glm::vec4 lodFade{1.f, 0.f, 0.f, 0.f};
        vk::DescriptorSet skinSet{};
        uint32_t skinUboOffset = 0;
    };
    struct ShadowAlphaPush {
        glm::mat4 mvp{1.f};
        glm::vec4 lodFade{1.f, 0.f, 0.f, 0.f};
    };
    std::vector<ShadowDraw> shadowPassDraws;
    std::vector<ShadowDraw> shadowCascadeDraws[ShadowConfig::kTotalLayers];
    uint32_t shadowPendingMask = 0;
    ShadowMapSlot &currentShadowMap();
    vk::ImageView currentShadowArrayView();
 
    // Screen-space G-buffer (normal / linear-depth / albedo + HW depth).
    struct GBufferPush {
        glm::mat4 mvp{1.f};
        glm::vec4 modelR0{1.f, 0.f, 0.f, 0.f};
        glm::vec4 modelR1{0.f, 1.f, 0.f, 0.f};
        glm::vec4 modelR2{0.f, 0.f, 1.f, 0.f};
        glm::vec4 clip{0.1f, 100.f, 0.f, 0.f};
    };
    static_assert(sizeof(GBufferPush) == 128, "GBuffer push constants must be 128 bytes");
    struct GBufferDraw {
        Mesh *mesh = nullptr;
        Texture *albedo = nullptr;
        GBufferPush push{};
        bool alphaTest = false;  // use the alpha-cutout gbuffer pipeline
        vk::DescriptorSet skinSet{};
        uint32_t skinUboOffset = 0;
    };
    struct GBufferSlot {
        vkb::ColorTarget normal;
        vkb::ColorTarget depthColor;
        vkb::ColorTarget albedo;
        vkb::ColorTarget pbrParams;  // RGBA8: metallic, roughness, occlusion, specularFactor
        vkb::ColorTarget emissive;   // RGB emissive (A unused)
        vkb::ColorTarget visID;    // R32G32UI: x = instance, y = pooled index offset
        vkb::ColorTarget visBary;  // R16G16F: barycentric (u, v)
        vkb::DepthTarget depth;
        vk::Framebuffer framebuffer{};
        vk::Framebuffer visFramebuffer{};
        GpuTexture normalGpu{};
        GpuTexture depthColorGpu{};
        GpuTexture albedoGpu{};
        GpuTexture       pbrParamsGpu{};
        GpuTexture       emissiveGpu{};
        GpuTexture visIDGpu{};
        GpuTexture visBaryGpu{};
        GpuTexture depthGpu{};
        Texture normalTex{};
        Texture depthColorTex{};
        Texture albedoTex{};
        Texture          pbrParamsTex{};
        Texture          emissiveTex{};
        Texture visIDTex{};
        Texture visBaryTex{};
        Texture depthTex{};
    };
    int gbufferWidth = 0;
    int gbufferHeight = 0;
    std::vector<GBufferSlot> gbufferSlots;
    vkb::BuiltRenderPass gbufferRenderPass{};
    vkb::BuiltRenderPass gbufferVisRenderPass{};
    vk::PipelineLayout gbufferPipelineLayout{};
    vk::Pipeline gbufferPipeline{};
    vk::Pipeline gbufferAlphaPipeline{};
    vk::Pipeline gbufferSkinPipeline{};
    vk::Pipeline gbufferSkinAlphaPipeline{};
    vk::Pipeline gbufferVisPipeline = nullptr;
    bool gbufferPassActive = false;
    bool gbufferPending = false;
    std::vector<GBufferDraw> gbufferPassDraws;
    GBufferSlot *currentGBufferSlot();
 
    // Screen-space decal layer: box-projected decals write albedo/normal/params
    // targets after the G-buffer; mesh3d.frag samples them before lighting.
    struct DecalInstanceData {
        glm::mat4 model{1.f};
        glm::vec4 uvRect{0.f, 0.f, 1.f, 1.f};
        glm::vec4 fadeParams{1.f, 0.f, 0.f, 0.f};   // fade, normalStrength, roughStrength, metalStrength
        glm::vec4 extraParams{0.f, 0.f, 0.f, 0.f};  // emissive, blendMode, projectionMode, sharpness
        glm::vec4 surfaceParams{0.f, 8.f, 24.f, 0.06f};  // POM scale/min/max, edge fade width
    };
    static_assert(sizeof(DecalInstanceData) == 128, "DecalInstanceData must be 128 bytes");
    struct DecalCameraUBO {
        glm::mat4 viewProj{1.f};
        glm::mat4 invViewProj{1.f};
        glm::vec4 nearFarTexel{0.1f, 100.f, 0.f, 0.f};  // x=near, y=far, z=1/w, w=1/h
    };
    static constexpr size_t kMaxDecalInstances = 512;
    struct DecalDraw {
        glm::mat4 model{1.f};
        Texture *albedo = nullptr;
        Texture *normal = nullptr;
        Texture *params = nullptr;
        float uvRect[4] = {0.f, 0.f, 1.f, 1.f};
        float fade = 1.f;
        float normalStrength = 0.f;
        float roughnessStrength = 0.f;
        float metalStrength = 0.f;
        float emissiveStrength = 0.f;
        int blendMode = 0;       // 0 = premultiplied over, 1 = additive (emissive)
        int projectionMode = 0;  // 0 = planar, 1 = local triplanar, 2 = spherical, 3 = world-aligned
        float blendSharpness = 4.f;
        float parallaxScale = 0.f;
        float parallaxMinLayers = 8.f;
        float parallaxMaxLayers = 24.f;
        float edgeFadeWidth = 0.06f;
    };
    struct DecalSetKey {
        GpuTexture *albedo = nullptr;
        GpuTexture *normal = nullptr;
        GpuTexture *params = nullptr;
        GpuTexture *depth = nullptr;
        GpuTexture *gbNormal = nullptr;
        bool operator==(const DecalSetKey &o) const {
            return albedo == o.albedo && normal == o.normal && params == o.params &&
                   depth == o.depth && gbNormal == o.gbNormal;
        }
    };
    struct DecalSetKeyHash {
        size_t operator()(const DecalSetKey &k) const {
            return std::hash<GpuTexture *>()(k.albedo) ^
                   (std::hash<GpuTexture *>()(k.normal) << 1) ^
                   (std::hash<GpuTexture *>()(k.params) << 2) ^
                   (std::hash<GpuTexture *>()(k.depth) << 3) ^
                   (std::hash<GpuTexture *>()(k.gbNormal) << 4);
        }
    };
    struct DecalSlot {
        vkb::ColorTarget albedo;
        vkb::ColorTarget normal;
        vkb::ColorTarget params;
        vk::Framebuffer framebuffer{};
        GpuTexture albedoGpu{};
        GpuTexture normalGpu{};
        GpuTexture paramsGpu{};
        Texture albedoTex{};
        Texture normalTex{};
        Texture paramsTex{};
        vkb::GenericBuffer cameraUbo;  // capacity 1 per frame slot
        std::unordered_map<DecalSetKey, vkb::BoundSet, DecalSetKeyHash> sets;
    };
    int decalWidth = 0;
    int decalHeight = 0;
    std::vector<DecalSlot> decalSlots;
    vkb::BuiltRenderPass decalRenderPass{};
    vk::DescriptorSetLayout decalSetLayout;
    vk::UniqueDescriptorSetLayout decalSetLayoutUnique;
    vk::PipelineLayout decalPipelineLayout{};
    vk::Pipeline decalPipeline{};
    bool decalPassActive = false;
    bool decalPending = false;
    bool decalLayerFresh = false;
    std::vector<DecalDraw> decalPassDraws;
    vk::Pipeline lastDecalPipeline = nullptr;
    Mesh *decalUnitBox = nullptr;
    Texture *decalFlatAlbedo = nullptr;
    Texture *decalFlatNormal = nullptr;
    Texture *decalFlatParams = nullptr;
    glm::mat4 decalViewProj{1.f};
    float decalNear = 0.1f;
    float decalFar = 100.f;
    // One FrameGraph per in-flight slot for the deferred passes: the 3 CSM
    // shadow cascades + the G-buffer fill are declarative passes in one layer,
    // recorded concurrently on JobSystem workers. Each graph's command buffer
    // is only reused two frames later — by then the present slot fence (waited
    // in Present::begin) guarantees the previous graph submit has completed
    // (same queue, submitted before the present command buffer). The graphs
    // import the engine-owned shadow array + ColorTarget images; the engine
    // keeps ownership so readback / entity-ID rendering / postFX wrappers keep
    // working unchanged.
    std::array<std::unique_ptr<vkb::FrameGraph>, kAsyncResourceCopies> deferredFrameGraphs_;
    vkb::FrameGraph *currentDeferredFrameGraph();
    bool deferredGraphRecorded_ = false;
    size_t deferredGraphRecordedSlot_ = 0;
    void buildDeferredFrameGraphs();
    void resetDeferredFrameGraphs();
    void recordShadowCascadePass(vkb::FrameGraphPassContext &ctx, int cascade);
    void recordGBufferPassDraws(vkb::FrameGraphPassContext &ctx);
 
    struct SceneColorSlot {
        vkb::ColorTarget msaaColor;
        vkb::ColorTarget color;
        vkb::DepthTarget depth;
        vk::Framebuffer framebuffer{};
        GpuTexture colorGpu{};
        Texture colorTex{};
    };
    int sceneColorWidth = 0;
    int sceneColorHeight = 0;
    vk::Format sceneColorFormat = vk::Format::eUndefined;
    vk::SampleCountFlagBits sceneColorSamples = vk::SampleCountFlagBits::e1;
    std::vector<SceneColorSlot> sceneColorSlots;
    size_t completedSceneColorSlot = 0;
    bool sceneColorHistoryValid = false;
    vkb::BuiltRenderPass sceneColorRenderPass{};
    vk::RenderPass sceneColorResumeRenderPass{};
    bool sceneColorPassOpen = false;
    vk::RenderPass scenePassPipelineTarget = vk::RenderPass{};
    vk::SampleCountFlagBits scenePassPipelineSamples = vk::SampleCountFlagBits::e1;
    int appliedMsaa = -1;
    SceneColorSlot *currentSceneColorSlot();
 
    // Offscreen 3D render-to-canvas (color + D32 depth) used for planar
    // reflection / render targets. Rendered on a dedicated command buffer and
    // submitted directly to the graphics queue (no swapchain / present).
    vkb::BuiltRenderPass offscreen3DRenderPass{};
    vkb::BuiltRenderPass hdrOffscreen3DRenderPass{};
    vk::Pipeline offscreen3DMeshPipeline = nullptr;
    vk::Pipeline hdrOffscreen3DMeshPipeline = nullptr;
    std::array<vk::Pipeline, kMesh3DPipelineVariants> offscreen3DSurfacePipelines{};
    std::array<vk::Pipeline, kMesh3DPipelineVariants> hdrOffscreen3DSurfacePipelines{};
    vk::UniqueDescriptorSetLayout reflectionProbeFilterSetLayout;
    vk::UniquePipelineLayout reflectionProbeFilterPipelineLayout;
    ComputePass reflectionProbeFilterPass;
    vk::CommandPool offscreen3DPool = nullptr;
    vk::CommandBuffer offscreen3DCB = nullptr;
    vk::Fence offscreen3DFence = nullptr;
    vk::QueryPool offscreen3DTimestampQueryPool = nullptr;
    float offscreen3DTimestampPeriodNs = 0.f;
    float lastOffscreen3DGpuDurationMs = 0.f;
    bool offscreen3DPassOpen = false;
    bool offscreen3DHDRActive = false;
    OffscreenCanvas *offscreen3DCanvas = nullptr;
 
    // Dedicated 4x-MSAA color target for the UI overlay (ImGui), resolved to a
    // single-sample texture that is composited as the top-most fullscreen quad.
    struct UiColorSlot {
        vkb::ColorTarget msaaColor;
        vkb::ColorTarget color;
        vk::Framebuffer framebuffer{};
        GpuTexture colorGpu{};
        Texture colorTex{};
    };
    int uiColorWidth = 0;
    int uiColorHeight = 0;
    vk::Format uiColorFormat = vk::Format::eUndefined;
    vk::SampleCountFlagBits uiColorSamples = vk::SampleCountFlagBits::e1;
    std::vector<UiColorSlot> uiColorSlots;
    vkb::BuiltRenderPass uiRenderPass{};
    vk::Pipeline uiTexturePipeline{};
    vk::Pipeline uiTextureOpaquePipeline{};
    UiColorSlot *currentUiColorSlot();
 
    // Linear HDR compose target: scene + overlays blend in paper-white-relative
    // display-linear space, then a single fullscreen tonemap encodes to the
    // HDR10/scRGB swapchain.
    struct PresentComposeSlot {
        vkb::ColorTarget color;
        vk::Framebuffer framebuffer{};
        GpuTexture colorGpu{};
        Texture colorTex{};
    };
    int presentComposeWidth = 0;
    int presentComposeHeight = 0;
    std::vector<PresentComposeSlot> presentComposeSlots;
 
    vkb::Present presentModel;
    vkb::RecordingCmd presentRecording;
    vkb::InRenderPass swapchainPass;
    vkb::DepthStencilImage depthImage;
    vk::Format depthFormat = vk::Format::eD32Sfloat;
 
    // GPU timestamp queries (one pool of 2: [0]=frame begin, [1]=frame end).
    vk::QueryPool gpuQueryPool_{};
    float         timestampPeriod_ = 1.f;
    bool          gpuTimingReady_  = false;
    float         gpuFrameMs_      = 0.f;
 
    struct SolidBatch {
        BlendMode blend = BlendMode::Alpha;
        Batcher batch;
    };
    std::vector<SolidBatch> solidBatches;
    struct TexturedBatch {
        enum class Effect { Default, SceneColorDistortion, DisplayEncode };
        Texture *texture = nullptr;
        Texture *depth = nullptr;
        Shader *shader = nullptr;
        BlendMode blend = BlendMode::Alpha;
        Batcher batch;
        Effect effect = Effect::Default;
        Texture *motion = nullptr;
        Texture *extra = nullptr;
        Texture *specular = nullptr;
    };
    std::vector<TexturedBatch> texturedBatches;
 
    std::vector<LitBatch> litBatches;
 
    enum class OverlayKind : uint8_t { Solid, Textured, Lit, GpuParticles };
    struct OverlaySpan {
        OverlayKind kind = OverlayKind::Solid;
        uint32_t index = 0;
        uint32_t vertBegin = 0;
        uint32_t vertCount = 0;
    };
    std::vector<OverlaySpan> overlaySpans;
    std::vector<OverlaySpan> engine3DSpans;
    std::optional<TexturedBatch> pendingSceneResolve;
    Texture *pendingSceneResolveSource = nullptr;
    std::optional<TexturedBatch> pendingUiResolve;
    bool sceneColorComposited = false;
 
    struct GpuParticleDrawRequest {
        GpuParticleHandle handle = kInvalidGpuParticleHandle;
        GpuParticleDraw   draw;
    };
    std::unordered_map<GpuParticleHandle, GpuParticleResource*> gpuParticles_;
    std::vector<GpuParticleDrawRequest>                         gpuParticleDraws_;
    GpuParticleHandle                                           nextGpuParticleHandle_ = 1;
    vk::DescriptorSetLayout                                     gpuParticleComputeSetLayout_{};
    vk::DescriptorSetLayout                                     gpuParticleDrawSetLayout_{};
    vk::DescriptorSetLayout                                     gpuParticleSortSetLayout_{};
    vk::PipelineLayout                                          gpuParticleComputeLayout_{};
    vk::PipelineLayout                                          gpuParticleDrawLayout_{};
    vk::PipelineLayout                                          gpuParticleSortLayout_{};
    vk::Pipeline                                                gpuParticleComputePipeline_{};
    vk::Pipeline                                                gpuParticleSortPipeline_{};
    vk::Pipeline                                                gpuParticleAlphaPipeline_{};
    vk::Pipeline                                                gpuParticleAdditivePipeline_{};
    vk::Pipeline                                                gpuParticlePremultipliedPipeline_{};
    vk::Pipeline                                                gpuParticleMultiplyPipeline_{};
    vk::Pipeline                                                gpuParticleOpaquePipeline_{};
 
    // Persistent host-visible vertex buffers for 2D batching, reused across
    // frames. GenericBuffer now owns the Vulkan handles.
    struct Frame2DBuffers {
        std::vector<vkb::HostVertexBuffer> solidBufs;
        std::vector<vkb::HostVertexBuffer> texBufs;
        std::vector<vkb::HostVertexBuffer> uiTexBufs;
        std::vector<vkb::HostVertexBuffer> primitive3DBufs;
        std::size_t                        primitive3DDrawIndex = 0;
    };
    std::vector<Frame2DBuffers> frame2dBuffers;  // per swapchain frame slot
    Frame2DBuffers offscreenBuffers;             // synchronous offscreen path
 
    vk::DescriptorSetLayout lit2dSetLayout;
    vk::UniqueDescriptorSetLayout lit2dSetLayoutUnique;
    vk::PipelineLayout lit2dPipelineLayout;
    vk::Pipeline lit2dPipeline;
    vk::Pipeline                  lit2dAdditivePipeline;
    vk::Pipeline                  lit2dPremultipliedPipeline;
    vk::Pipeline                  lit2dMultiplyPipeline;
    vk::Pipeline                  lit2dOpaquePipeline;
    vk::Pipeline offscreenLitPipeline;
    vk::Pipeline                  offscreenLitAdditivePipeline;
    vk::Pipeline                  offscreenLitPremultipliedPipeline;
    vk::Pipeline                  offscreenLitMultiplyPipeline;
    vk::Pipeline                  offscreenLitOpaquePipeline;
    vk::Pipeline                    selectLit2DPipeline(BlendMode blend, bool offscreen, bool hdr = false) const;
    std::vector<vkb::GenericBuffer> lighting2dUboSlots;  // per swapchain frame slot
    vkb::GenericBuffer offscreenLighting2dUbo;           // synchronous offscreen path
    Lighting2DUBO lighting2dFrame{};
    struct LitSetKey {
        GpuTexture *albedo = nullptr;
        GpuTexture *normal = nullptr;
        bool operator==(const LitSetKey &o) const {
            return albedo == o.albedo && normal == o.normal;
        }
    };
    struct LitSetKeyHash {
        size_t operator()(const LitSetKey &k) const {
            return std::hash<void *>()(k.albedo) ^ (std::hash<void *>()(k.normal) << 1);
        }
    };
    struct PostSetKey {
        GpuTexture *color = nullptr;
        GpuTexture *depth = nullptr;
        GpuTexture *motion = nullptr;
        GpuTexture *extra = nullptr;
        GpuTexture *specular = nullptr;
        bool operator==(const PostSetKey &o) const {
            return color == o.color && depth == o.depth && motion == o.motion && extra == o.extra &&
                   specular == o.specular;
        }
    };
    struct PostSetKeyHash {
        size_t operator()(const PostSetKey &k) const {
            return std::hash<void *>()(k.color) ^ (std::hash<void *>()(k.depth) << 1) ^
                   (std::hash<void *>()(k.motion) << 2) ^
                   (std::hash<void *>()(k.extra) << 3) ^
                   (std::hash<void *>()(k.specular) << 4);
        }
    };
    std::vector<std::unordered_map<LitSetKey, vkb::BoundSet, LitSetKeyHash>> lit2dSets;
    std::unordered_map<LitSetKey, vkb::BoundSet, LitSetKeyHash> offscreenLit2dSets;
    std::unordered_map<PostSetKey, vkb::BoundSet, PostSetKeyHash> post2Sets;
    Texture *flatNormalTexture = nullptr;
 
    Color clearColor{0.1f, 0.1f, 0.12f, 1.0f};
    bool hasPendingClear = true;
 
    std::vector<std::unique_ptr<Texture>> ownedTextures;
    std::vector<std::unique_ptr<GpuTexture>> ownedGpuTextures;
    std::unordered_map<std::string, Texture *> texturesByPath;
    std::unordered_map<std::string, Texture *>          sharedTexturesByContent;
    std::vector<std::unique_ptr<Mesh>> ownedMeshes;
    std::vector<std::unique_ptr<GpuMesh>> ownedGpuMeshes;
    std::vector<std::unique_ptr<Shader>> ownedShaders;
    std::vector<std::unique_ptr<GpuShader>> ownedGpuShaders;
    std::vector<std::unique_ptr<eve::graphics::Canvas>> ownedCanvases;
 
    bool swapchainPassOpen = false;
    bool flushingSwapchain_ = false;
    Mesh3DUBO mesh3dFrameUbo{};
 
    // Instanced voxel face rectangles (packed uint32 instances).
    struct VoxelRectPC {
        glm::mat4 viewProj{1.f};
        glm::vec4 chunkOrigin{0.f};  // xyz = origin, w = faceDir
        glm::vec4 atlasInfo{16.f, 0.f, 0.f, 0.f};
        glm::vec4 tint{1.f};
    };
    vk::DescriptorSetLayout voxelRectSetLayout{};
    vk::UniqueDescriptorSetLayout voxelRectSetLayoutUnique;
    vk::PipelineLayout voxelRectPipelineLayout{};
    vk::Pipeline voxelRectPipeline{};
    vkb::GenericBuffer voxelUnitQuadVerts;
    vkb::GenericBuffer voxelUnitQuadIndices;
    bool voxelUnitQuadReady = false;
    std::unordered_map<GpuTexture *, vkb::BoundSet> voxelRectSets;
    // Grow-only instance buffer pool (reset index each begin3DFrame), per
    // swapchain frame slot for async safety.
    struct VoxelInstanceSlot {
        vkb::GenericBuffer buffer;
        size_t capacityBytes = 0;
        vkb::GenericBuffer aoBuffer;
        size_t aoCapacityBytes = 0;
    };
    struct VoxelInstanceFrame {
        std::vector<VoxelInstanceSlot> slots;
        size_t drawIndex = 0;
    };
    std::vector<VoxelInstanceFrame> voxelInstanceFrames;  // per swapchain frame slot
 
    Frame2DBuffers &currentFrame2DBuffers();
    Mesh3dFrameSlots &currentMesh3dFrameSlots();
    Mesh3dClusteredFrameSlots &currentMesh3dClusteredFrameSlots();
    vkb::GenericBuffer &currentLighting2dUbo();
    std::unordered_map<LitSetKey, vkb::BoundSet, LitSetKeyHash> &currentLit2dSets();
    ClusteredStorage &currentClusteredStorage();
    VoxelInstanceFrame &currentVoxelInstanceFrame();
    uint32_t frameSlotCount() const;
    size_t currentFrameSlot() const;
    vk::CommandBuffer &currentPresentCb();
    vkb::FrameSlot frameToken() const;
    void invalidateTextureBindings();
};
 
}  // namespace eve::graphics::vulkan