metalInstanceCullPass.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025-2026 Arnis Lektauers
//
// Metal compute pass for GPU frustum culling of instanced draws.
//
// Two-kernel pipeline:
//   Kernel 1 (instanceCull): Each thread tests one instance's bounding sphere
//     against 6 frustum planes. Visible instances are compacted into an output
//     buffer via atomic_fetch_add.
//   Kernel 2 (writeIndirectArgs): A single thread reads the atomic counter and
//     writes MTLDrawIndexedPrimitivesIndirectArguments (20 bytes).
//
// Follows the MetalMarchingCubesPass pattern:
//   - Embedded MSL source as string literal
//   - Lazy resource creation
//   - Friend access to MetalGraphicsDevice for command queue
//
// Custom shader -- no upstream GLSL equivalent exists for GPU instance culling.
// Upstream GPU culling is GSplat-specific; this is a general-purpose extension.
//
#pragma once
 
#include <cstdint>
#include <Metal/Metal.hpp>
 
namespace visutwin::canvas
{
    class MetalGraphicsDevice;

    struct alignas(16) InstanceCullParams
    {
        float frustumPlanes[6][4];  
        float boundingSphereRadius; 
        uint32_t instanceCount;     
        uint32_t indexCount;        
        uint32_t indexStart;        
        int32_t  baseVertex;        
        uint32_t baseInstance;      
        float    _pad[2];
    };
    static_assert(sizeof(InstanceCullParams) == 128,
        "InstanceCullParams must be 128 bytes to match MSL layout");

    class MetalInstanceCullPass
    {
    public:
        explicit MetalInstanceCullPass(MetalGraphicsDevice* device);
        ~MetalInstanceCullPass();
 
        // Non-copyable
        MetalInstanceCullPass(const MetalInstanceCullPass&) = delete;
        MetalInstanceCullPass& operator=(const MetalInstanceCullPass&) = delete;

        void reserve(uint32_t maxInstances);

        void cull(MTL::Buffer* inputBuffer, const InstanceCullParams& params);

        [[nodiscard]] MTL::Buffer* compactedBuffer() const { return compactedBuffer_; }

        [[nodiscard]] MTL::Buffer* indirectArgsBuffer() const { return indirectArgsBuffer_; }

        [[nodiscard]] bool isReady() const { return resourcesReady_; }

        static void extractFrustumPlanes(const float* vpMatrix4x4ColMajor, float outPlanes[6][4]);
 
    private:
        void ensureResources();
 
        MetalGraphicsDevice* device_;
 
        // Compute pipelines
        MTL::ComputePipelineState* cullPipeline_      = nullptr;
        MTL::ComputePipelineState* writeArgsPipeline_  = nullptr;
 
        // Buffers (reused across frames)
        MTL::Buffer* compactedBuffer_    = nullptr;  // Visible instances (maxInstances * 80)
        MTL::Buffer* indirectArgsBuffer_ = nullptr;  // 20 bytes (MTLDrawIndexedPrimitivesIndirectArguments)
        MTL::Buffer* counterBuffer_      = nullptr;  // atomic_uint (4 bytes)
        MTL::Buffer* uniformBuffer_      = nullptr;  // InstanceCullParams (128 bytes)
 
        uint32_t maxInstances_ = 0;
 
        bool resourcesReady_ = false;
    };
 
} // namespace visutwin::canvas