GPUScene.hpp

Go to the documentation of this file.

#pragma once
#include <cstddef>
#include <Core/Allocator.hpp>
#include <Core/AllocatorStack.hpp>
#include <Core/Logging.hpp>
#include <RenderCore/Bindless.hpp>
#include <RenderCore/ImmediateContext.hpp>
#include "Curve.hpp"
#include "Mesh.hpp"
#include "Texture.hpp"
#include "Precompute.hpp"
 
using namespace Math;
using namespace RenderCore;
struct UBO;
struct GPUSceneImpl;
 
// Must match the procedural hit-group bindings in Render/Pathtracer.cpp.
inline constexpr uint32_t kRectLightSBTOffset = 3u;
inline constexpr uint32_t kDiskLightSBTOffset = 4u;
inline constexpr uint32_t kCurveSBTOffset = 5u;
inline constexpr uint32_t kGSInstanceTypeMesh = 0u;
inline constexpr uint32_t kGSInstanceTypeCurve = 1u;
// GSInstance::type low byte is the geometry kind; bit 8 flags CPU-updateable dynamic geometry
// so shaders read its primitive data from the dynamic ring instead of the immutable buffer.
inline constexpr uint32_t kGSInstanceTypeMask = 0xFFu;
inline constexpr uint32_t kGSInstanceFlagDynamic = 0x100u;
 
struct GeometryHandle
{
    uint32_t index{~0u};
    uint32_t generation{0};
    [[nodiscard]] bool IsValid() const { return index != ~0u; }
};
struct TextureHandle
{
    uint32_t index{~0u};
    uint32_t generation{0};
    bool is3D{false};
    [[nodiscard]] bool IsValid() const { return index != ~0u; }
};
 
struct InstanceDesc
{
    GeometryHandle geometry{};
    float3 transform{0, 0, 0};
    quat rotation{0, 0, 0, 1};
    float3 scale{1, 1, 1};
    uint32_t materialIndex{0};
};
 
#pragma pack(push, 1)
struct GSMesh
{
    // Offsets are absolute, and are in Primitive buffer (bytes).
    // @ref FVertex
    uint32_t vtxOffset;
    uint32_t vtxCount;
    // LOD0 UINT32 indices
    uint32_t idxOffset;
    uint32_t idxCount;
    // -- DAG LOD Group @ref FLODGroup
    uint32_t groupOffset;
    uint32_t groupCount;
    // -- DAG Meshlets @ref FMeshlet
    uint32_t meshletOffset;
    uint32_t meshletCount;
    uint32_t meshletVtxOffset;
    uint32_t meshletTriOffset;
    // -- Global index (amongst all loaded meshes)
    uint32_t meshletGlobalIndex;
};
struct GSInstance
{
    // TRS
    float3 transform{0, 0, 0};
    quat rotation{0, 0, 0, 1};
    float3 scale{1, 1, 1};
    uint32_t resourceOffset; // Mesh or curve set offset in Primitive buffer (bytes)
    uint32_t materialIndex; // In Material buffer (offset)
    uint32_t resourceIndex; // Debug use
    uint32_t type{kGSInstanceTypeMesh};
};
// XXX: Uber. Super, even. Surely this works for all our needs...
struct GSMaterial
{
    uint32_t baseColorTexture = UINT32_MAX;
    uint32_t emissiveTexture = UINT32_MAX;
    uint32_t metallicRoughnessTexture = UINT32_MAX;
    uint32_t normalTexture = UINT32_MAX;
    uint32_t transmissionTexture = UINT32_MAX;
    uint32_t specularTexture = UINT32_MAX;
    uint32_t specularColorTexture = UINT32_MAX;
    uint32_t anisotropyTexture = UINT32_MAX;
    uint32_t sheenColorTexture = UINT32_MAX;
    uint32_t sheenRoughnessTexture = UINT32_MAX;
    uint32_t clearcoatTexture = UINT32_MAX;
    uint32_t clearcoatRoughnessTexture = UINT32_MAX;
    float4 baseColorFactor;
    float3 emissiveFactor;
    float metallicFactor;
    float roughnessFactor;
    float transmissionFactor;
    float ior;
    float specularFactor;
    float3 specularColorFactor;
    float anisotropyStrength;
    float anisotropyRotation;
    float3 sheenColorFactor;
    float sheenRoughnessFactor;
    float clearcoatFactor;
    float clearcoatRoughnessFactor;
    float subsurfaceFactor;
    float subsurfaceScale;
    float3 subsurfaceColor;
    float3 subsurfaceRadius;
    uint32_t shaderBlockID;
    float hairBetaM;
    float hairBetaN;
    float hairAlpha;
};
struct GSLight
{
    uint32_t type{0u};       // 0=Directional, 1=Point, 2=Spot, 3=Disk, 4=Rect
    float3 color{1,1,1};    // Normalized RGB color
    float power{1.0f};      // Radiant power (type-dependent unit)
    float3 position{0,0,0};
    float3 direction{0,0,-1};
    float range{0.0f};
    float spotInnerCosAngle{1.0f};
    float spotOuterCosAngle{0.7071f};
    // Area lights (Disk / Rect)
    float3 dpdu{1,0,0};     // tangent u-axis (Rect: half-extent u)
    float3 dpdv{0,1,0};     // tangent v-axis (Rect: half-extent v)
    float2 radius{0.5f, 0.5f}; // Disk radius (x, y for ellipse)
    uint32_t twoSided{0u};
    float selectionWeight{0.0f};
};
#pragma pack(pop)
static_assert(sizeof(GSMesh) == 44);
static_assert(sizeof(GSInstance) == 56);
static_assert(sizeof(GSMaterial) == 188);
static_assert(sizeof(GSLight) == 96);
 
struct GPUSceneDesc
{
    uint32_t primitiveBudget = 16 * (1u << 20); // 16MB
    uint32_t curveAABBBudget = 16 * (1u << 20); // 16MB
    uint32_t instanceBudget = static_cast<uint32_t>(1e4); // # of GSInstance elements (ring)
    uint32_t materialBudget = static_cast<uint32_t>(1e3); // # of materials (ring)
    uint32_t lightBudget = static_cast<uint32_t>(1e4); // # of lights (ring)
    uint32_t texturesBudget = static_cast<uint32_t>(1e3); // # of textures
    // Max distinct geometries (meshes + curves). The residency/BLAS vectors the renderer
    // reads are reserved to this so background uploads never reallocate them; uploads beyond
    // it are rejected rather than risking a concurrent reallocation.
    uint32_t geometryBudget = static_cast<uint32_t>(1e4);
    uint32_t tlasInstanceBudget = static_cast<uint32_t>(1e4); // # of TLAS instances (ring)
    uint32_t tlasBudget = 16 * (1u << 20); // 16MB
    uint32_t tlasScratchBudget = 32 * (1u << 20); // 32MB (ring)
    // CPU-updateable dynamic geometry (deformation: skinning / sims / morphs). Quantized
    // primitive bytes (header + verts + indices, no DAG/meshlets) live in a host-coherent ring
    // sized `dynamicGeometryBudget` per frame slot, replicated across `framesInFlight + 1` slots.
    // The BLAS is a single AllowUpdate AS refit in place each frame. Default 0 = feature off (no
    // buffer allocated); examples / the editor opt in by sizing these explicitly.
    uint32_t dynamicGeometryBudget = 0; // bytes per frame slot (0 = dynamic geometry disabled)
    // The renderer's max frames in flight (its swapchain image count, @ref Renderer::GetFrameSwaps()).
    // The dynamic ring is sized to framesInFlight + 1 slots and advanced once per frame: the CPU
    // writes the next frame's slot before that frame's GPU fence, so one slot beyond the in-flight
    // count keeps the write target clear of every slot the in-flight GPU frames are still reading
    // (N+1 buffering for a non-blocking producer, mirroring the renderer's per-frame resources).
    uint32_t framesInFlight = 2;
};
 
class GPUScene
{
public:
    enum class Result
    {
        Ready,
        InProgress,
        InvalidInput,
        InvalidHandle,
        OutOfMemory,
        DecodeFailed,
        SubmitFailed,
        Cancelled,
    };
 
    enum class LightSamplerType
    {
        Uniform,
        Power
    };
    LightSamplerType mLightSamplerType = LightSamplerType::Power;
 
    [[nodiscard]] static size_t CalculateMeshPrimitiveSize(FSerializedMesh const& src);
    [[nodiscard]] static size_t CalculateCurvePrimitiveSize(FSerializedCurve const& src);
    [[nodiscard]] static size_t CalculateCurveAABBSize(FSerializedCurve const& src);
 
    GPUScene(RHIDevice* device, Allocator* allocator, GPUSceneDesc const& desc,
             AllocatorStack* frameScratch = nullptr);
    ~GPUScene();
 
 
    Result Upload(FBlobDeserializer* blobs, FSerializedMesh const& source, GeometryHandle& outHandle);
    Result Upload(FBlobDeserializer* blobs, FSerializedCurve const& source, GeometryHandle& outHandle);
    Result UploadDynamic(FBlobDeserializer* blobs, FSerializedMesh const& source, GeometryHandle& outHandle);
    Result Upload(FBlobDeserializer* blobs, FSerializedTexture const& source, TextureHandle& outTexture,
                  const char* debugName = nullptr, bool pinned = false);
    Result Upload(FTexture const& source, TextureHandle& outTexture, const char* debugName = nullptr,
                  bool pinned = false);
    Result Upload(RHIBuffer* dst, Span<const unsigned char> data, uint32_t dstOffset = 0);
    [[nodiscard]] Result Query(GeometryHandle handle) const;
    [[nodiscard]] Result Query(TextureHandle texture) const;
    void Join();
    [[nodiscard]] Result Poll();
 
    Result UploadViewLUTs(FTexture const& sdr, FTexture const& hdr);
    Result UploadEnvMap(FTexture const& source);
 
    void BuildUBO(UBO& globals, bool hdr) const;
 
    struct UpdateResult
    {
        uint32_t firstInstance;
        uint32_t numInstances;
        uint32_t firstMaterial;
        uint32_t numMaterials;
        uint32_t firstLight;
        uint32_t firstLightAliasTable;
        uint32_t numLights;
        float sceneLightWeightSum;
    };
 
    struct GPUSceneTables
    {
        Span<InstanceDesc> instances;
        Span<GSMaterial> materials;
        Span<GSLight> lights;
        uint32_t firstInstance{0};
        uint32_t firstMaterial{0};
        uint32_t firstLight{0};
        uint32_t firstLightAliasTable{0};
    };
    GPUSceneTables BeginScene(uint32_t instanceCount, uint32_t materialCount, uint32_t lightCount);
    UpdateResult EndScene(GPUSceneTables& tables);
 
    struct MemoryStat
    {
        String name;
        size_t bytes;
    };
    void DbgGetMemoryStatistics(Vector<MemoryStat>& outStats) const;
    [[nodiscard]] String DbgGetBufferStatistics() const;
    [[nodiscard]] uint32_t GetLightCapacity() const;
 
    enum class TLASBuildResult
    {
        Built,
        Empty
    };
    [[nodiscard]] TLASBuildResult BuildTLAS(RHICommandList* cmd, bool update = false);
 
    /* --- Dynamic (CPU-updateable) geometry: per-frame deformation ---
     * Per-frame contract (mirrors a renderer Begin/End frame bracket):
     *     BeginDynamicGeometryUpdate();              // once per frame, advances the ring slot
     *     for each deforming geo: fill UpdateDynamicGeometry(handle);
     *     EndDynamicGeometryUpdate();                // closes the window
     *     ... BeginScene/EndScene, then the graph's "Dynamic BLAS Refit" pass ...
     * @ref UpdateDynamicGeometry may only be called inside the open window; the window state also
     * guards the per-frame getters. */
    [[nodiscard]] bool HasDynamicGeometry() const;
    void BeginDynamicGeometryUpdate();
    [[nodiscard]] Span<std::byte> UpdateDynamicGeometry(GeometryHandle handle);
    void EndDynamicGeometryUpdate();
    void BuildBLAS(RHICommandList* cmd);
    void SetDynamicGeometryRebuildRate(uint32_t framesOrZero);
    [[nodiscard]] uint32_t GetDynamicRefitCount() const;
    [[nodiscard]] uint32_t GetDynamicRebuildCount() const;
 
    void Collect();
 
    /* --- Committed scene reads (snapshots; index == TLAS instanceID for instances) --- */
    [[nodiscard]] GSInstance GetInstance(uint32_t index) const
    {
        CHECK_MSG(index < mCommittedInstances.size(), "GetInstance index {} out of range ({})", index,
                  mCommittedInstances.size());
        return mCommittedInstances[index];
    }
    [[nodiscard]] uint32_t GetInstanceCount() const { return static_cast<uint32_t>(mCommittedInstances.size()); }
    [[nodiscard]] uint32_t ResolvePickedInstance(uint32_t pickID) const
    {
        // pickID is a TLAS instanceID = index into the last build's written (ready) set.
        if (pickID >= mPickMap.size())
            return UINT32_MAX;
        return mPickMap[pickID];
    }
    [[nodiscard]] GSLight GetLight(uint32_t index) const
    {
        CHECK_MSG(index < mCommittedLights.size(), "GetLight index {} out of range ({})", index,
                  mCommittedLights.size());
        return mCommittedLights[index];
    }
    [[nodiscard]] uint32_t GetLightCount() const { return static_cast<uint32_t>(mCommittedLights.size()); }
    [[nodiscard]] GSMaterial GetMaterial(uint32_t index) const
    {
        CHECK_MSG(index < mCommittedMaterials.size(), "GetMaterial index {} out of range ({})", index,
                  mCommittedMaterials.size());
        return mCommittedMaterials[index];
    }
    [[nodiscard]] uint32_t GetMaterialCount() const { return static_cast<uint32_t>(mCommittedMaterials.size()); }
 
    /* Geometry */
    [[nodiscard]] RHIBuffer* GetPrimitiveBuffer() const { return mPrimitiveBuffer.Get(); }
    [[nodiscard]] RHIBuffer* GetDynamicPrimitiveBuffer() const;
    [[nodiscard]] RHIBuffer* GetInstanceBuffer() const;
    [[nodiscard]] RHIBuffer* GetMaterialBuffer() const;
    [[nodiscard]] RHIBuffer* GetLightBuffer() const;
    [[nodiscard]] RHIBuffer* GetLightAliasTableBuffer() const;
    /* Textures */
    [[nodiscard]] BindlessPool* GetTexture2DPool();
    [[nodiscard]] BindlessPool* GetTexture3DPool();
    [[nodiscard]] uint32_t GetGGXLutEIndex() const { return mLUTGGXEIndex.index; }
    [[nodiscard]] uint32_t GetGGXLutEavgIndex() const { return mLUTGGXEavgIndex.index; }
    [[nodiscard]] uint32_t GetGGXLutEIORIndex() const { return mLUTGGXEIORIndex.index; }
    [[nodiscard]] uint32_t GetGGXLutEIORavgIndex() const { return mLUTGGXEIORavgIndex.index; }
    [[nodiscard]] uint32_t GetGGXLutEIORInvIndex() const { return mLUTGGXEIORInvIndex.index; }
    [[nodiscard]] uint32_t GetGGXLutEIORInvavgIndex() const { return mLUTGGXEIORInvavgIndex.index; }
    [[nodiscard]] uint32_t GetSheenLtcIndex() const { return mLUTSheenLTCIndex.index; }
    [[nodiscard]] uint32_t GetViewLutSdrIndex() const { return mLUTViewSdrIndex.index; }
    [[nodiscard]] uint32_t GetViewLutHdrIndex() const { return mLUTViewHdrIndex.index; }
    [[nodiscard]] RHITexture* GetFoundationDefaultTexture2D() const;
    [[nodiscard]] RHITexture* GetFoundationDefaultTexture2DFloat() const;
    [[nodiscard]] RHIBuffer* GetFoundationDefaultBufferFloat() const { return mFoundationDefaultBufferFloat.Get(); }
    // Environment map
    [[nodiscard]] bool HasEnvMap() const { return mEnvMapIndex.IsValid(); }
    [[nodiscard]] uint32_t GetEnvMapIndexOrDefault() const
    {
        return HasEnvMap() ? mEnvMapIndex.index : mFoundationDefaultTexture2DIndex.index;
    }
    [[nodiscard]] uint32_t GetEnvMapMarginalCDFIndexOrDefault() const
    {
        return mEnvMapMarginalCDFIndex.IsValid() ? mEnvMapMarginalCDFIndex.index : mFoundationDefaultTexture2DFloatIndex.index;
    }
    [[nodiscard]] uint32_t GetEnvMapConditionalCDFIndexOrDefault() const
    {
        return mEnvMapConditionalCDFIndex.IsValid() ? mEnvMapConditionalCDFIndex.index : mFoundationDefaultTexture2DFloatIndex.index;
    }
    /* AS */
    [[nodiscard]] RHIAccelerationStructure* GetTLAS() const
    {
        // Returns the allocated TLAS whenever the scene has one, independent of how many
        // instances are currently resident. This lets ray passes be built into the render
        // graph up front; BuildTLAS keeps it valid (an empty 0-instance TLAS) while geometry
        // streams in, so instances appear without a renderer rebuild.
        return mTLAS.IsValid() ? mTLAS.Get() : nullptr;
    }
    /* Samplers */
    [[nodiscard]] RHIBuffer* GetSobolMatricesBuffer() const { return mSobolMatricesBuffer.Get(); }
 
    void Reset();
 
private:
    friend struct GPUSceneImpl;
 
    // Committed table snapshots (filled via BeginScene/EndScene). These are the
    // authoritative CPU-side scene used by BuildTLAS, picking, and Collect(); they do
    // not depend on ring memory that may be overwritten by a later commit.
    Vector<GSInstance> mCommittedInstances;
    Vector<GSLight> mCommittedLights;
    Vector<GSMaterial> mCommittedMaterials;
    // TLAS instanceID -> committed instance index, rebuilt each BuildTLAS. When some
    // referenced geometry is not yet Ready those instances are skipped, so the TLAS id
    // is no longer identical to the committed index and picking must go through this map.
    Vector<uint32_t> mPickMap;
 
    // Plain handles backing the hot inline getters above; created/managed by GPUSceneImpl.
    RHIDeviceScopedHandle<RHIBuffer> mPrimitiveBuffer;
    RHIDeviceScopedHandle<RHIAccelerationStructure> mTLAS;
    uint32_t mLastTLASInstancesCount{0};
    RHIDeviceScopedHandle<RHIBuffer> mSobolMatricesBuffer;
    RHIDeviceScopedHandle<RHIBuffer> mFoundationDefaultBufferFloat;
    // Precomputed LUTs (texture2D pool)
    TextureHandle mLUTGGXEIndex;
    TextureHandle mLUTGGXEavgIndex;
    TextureHandle mLUTGGXEIORavgIndex;
    TextureHandle mLUTGGXEIORInvavgIndex;
    // Precomputed LUTs (texture3D pool)
    TextureHandle mLUTGGXEIORIndex;
    TextureHandle mLUTGGXEIORInvIndex;
    TextureHandle mLUTSheenLTCIndex;
    // Display transform 3D LUTs (texture3D pool)
    TextureHandle mLUTViewSdrIndex, mLUTViewHdrIndex;
    // Shared default resources (texture2D pool)
    TextureHandle mFoundationDefaultTexture2DIndex;
    TextureHandle mFoundationDefaultTexture2DFloatIndex;
    // Environment map (texture2D pool)
    TextureHandle mEnvMapIndex;
    TextureHandle mEnvMapMarginalCDFIndex;
    TextureHandle mEnvMapConditionalCDFIndex;
 
    UniquePtr<GPUSceneImpl> mImpl;
};
 
ENUM_NAME_CONV_BEGIN(GPUScene::Result)
    ENUM_NAME(Ready)
    ENUM_NAME(InProgress)
    ENUM_NAME(InvalidInput)
    ENUM_NAME(InvalidHandle)
    ENUM_NAME(OutOfMemory)
    ENUM_NAME(DecodeFailed)
    ENUM_NAME(SubmitFailed)
    ENUM_NAME(Cancelled)
ENUM_NAME_CONV_END()