metalTextureStream.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025-2026 Arnis Lektauers
//
// Triple-buffered texture streaming for real-time data ingestion.
//
// Provides lock-free single-producer single-consumer texture rotation
// for tear-free real-time intraoperative display of endoscope video
// and simulation feeds.
//
// Uses dispatch_semaphore_t for GPU back-pressure, consistent with
// MetalUniformRingBuffer. StorageModeShared + WriteCombined for
// optimal Apple Silicon streaming throughput.
//
// Usage:
//   MetalTextureStream stream(device, {1920, 1080});
//
//   // Producer (any thread):
//   auto* tex = stream.beginWrite();
//   stream.writeRegion(pixels, bytesPerRow, region);
//   stream.endWrite();
//
//   // Consumer (render thread):
//   auto* readTex = stream.acquireForRead();
//   metalTexture->setExternalTexture(readTex);
//   // ... render ...
//   stream.endFrame(commandBuffer);
//
#pragma once
 
#include <Metal/Metal.hpp>
#include <dispatch/dispatch.h>
#include <array>
#include <atomic>
#include <cstdint>
 
namespace visutwin::canvas
{
    class MetalTextureStream
    {
    public:
        static constexpr int kNumSlots = 3;
 
        struct Descriptor
        {
            uint32_t width  = 1920;
            uint32_t height = 1080;
            MTL::PixelFormat format = MTL::PixelFormatBGRA8Unorm;
            bool writeCombined = true;   
            const char* label = "TextureStream";
        };
 
        MetalTextureStream(MTL::Device* device, const Descriptor& desc);
        ~MetalTextureStream();
 
        // Non-copyable, non-movable
        MetalTextureStream(const MetalTextureStream&) = delete;
        MetalTextureStream& operator=(const MetalTextureStream&) = delete;
        MetalTextureStream(MetalTextureStream&&) = delete;
        MetalTextureStream& operator=(MetalTextureStream&&) = delete;
 
        // ── Producer API (producer thread) ─────────────────────────────

        MTL::Texture* beginWrite();

        void writeRegion(const void* data, size_t bytesPerRow,
                         MTL::Region region, uint32_t mipLevel = 0);

        void endWrite();

        void publishExternal(MTL::Texture* externalTexture);
 
        // ── Consumer API (render thread) ───────────────────────────────

        MTL::Texture* acquireForRead();

        void endFrame(MTL::CommandBuffer* commandBuffer);
 
        // ── Accessors ──────────────────────────────────────────────────
 
        [[nodiscard]] uint32_t width() const { return _desc.width; }
        [[nodiscard]] uint32_t height() const { return _desc.height; }
        [[nodiscard]] MTL::PixelFormat format() const { return _desc.format; }

        [[nodiscard]] uint64_t framesPublished() const { return _publishCount.load(std::memory_order_relaxed); }

        [[nodiscard]] uint64_t framesDropped() const { return _dropCount.load(std::memory_order_relaxed); }

        [[nodiscard]] bool hasNewFrame() const { return _hasPublished; }
 
    private:
        MTL::Device* _device;
        Descriptor _desc;
 
        std::array<MTL::Texture*, kNumSlots> _textures{};
        dispatch_semaphore_t _slotSemaphore = nullptr;  
 
        // Atomic indices for lock-free SPSC rotation.
        // Each index is in [0, kNumSlots). All three are always distinct.
        std::atomic<int> _writeIndex{0};
        std::atomic<int> _readyIndex{1};
        std::atomic<int> _readIndex{2};
 
        // External texture path (CVMetalTexture zero-copy).
        // When non-null, acquireForRead() returns this instead of rotating.
        std::atomic<MTL::Texture*> _externalReady{nullptr};
 
        // Statistics
        std::atomic<uint64_t> _publishCount{0};
        std::atomic<uint64_t> _dropCount{0};
 
        bool _hasPublished = false;  
    };
 
}  // namespace visutwin::canvas