metalParticleComputePass.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025-2026 Arnis Lektauers
//
// Metal compute pass for GPU particle advection.
//
// Advects millions of particles through a 3D velocity field entirely
// on the GPU using a Metal compute kernel.  The output particle buffer
// can be rendered directly as point primitives.
//
// Pipeline (per frame):
//   1. Encode compute command: bind particle buffer, velocity 3D texture,
//      uniforms, dispatch one thread per particle.
//   2. Commit command buffer.  Metal's implicit barriers ensure the
//      vertex read in the subsequent render pass sees the compute output.
//
// Double-buffered particle storage avoids read/write hazards when
// the previous frame's render pass hasn't finished yet.
//
// Follows the MetalLICPass / MetalTaaPass decomposition 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
// particle advection.
//
#pragma once
 
#include <cstdint>
#include <memory>
#include <Metal/Metal.hpp>
 
namespace visutwin::canvas
{
    class MetalGraphicsDevice;
    class Texture;

    struct alignas(16) ParticleComputeUniforms
    {
        float domainMin[3];     
        float dt;               
        float domainMax[3];     
        uint32_t particleCount; 
        float invDomainSize[3]; 
        float time;             
        float speedMin;         
        float speedMax;         
        float fadeStart;        
        float padding;          
    };
    static_assert(sizeof(ParticleComputeUniforms) == 64,
        "ParticleComputeUniforms must be 64 bytes");

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

        void initialize(uint32_t maxParticles);

        void uploadParticles(const void* data, uint32_t count);

        void advect(Texture* velocityTexture, const ParticleComputeUniforms& uniforms);

        [[nodiscard]] MTL::Buffer* currentParticleBuffer() const;

        [[nodiscard]] uint32_t maxParticles() const { return maxParticles_; }

        [[nodiscard]] bool isInitialized() const { return initialized_; }
 
    private:
        void ensureResources();
 
        MetalGraphicsDevice* device_;
 
        MTL::ComputePipelineState* computePipeline_ = nullptr;
        MTL::Buffer* particleBufferA_ = nullptr;   // ping
        MTL::Buffer* particleBufferB_ = nullptr;   // pong
        MTL::Buffer* uniformBuffer_ = nullptr;
        MTL::SamplerState* fieldSampler_ = nullptr;
 
        uint32_t maxParticles_ = 0;
        uint32_t currentBuffer_ = 0;               // 0 = A is current, 1 = B
        bool initialized_ = false;
        bool resourcesReady_ = false;
    };
 
} // namespace visutwin::canvas