VisuTwin Canvas
C++ 3D Engine — Metal Backend
Loading...
Searching...
No Matches
visutwin::canvas::MetalTextureStream Class Reference

#include <platform/graphics/metal/metalTextureStream.h>

Classes

struct  Descriptor

Public Member Functions

MTL::Texture * acquireForRead ()
MTL::Texture * beginWrite ()
void endFrame (MTL::CommandBuffer *commandBuffer)
void endWrite ()
MTL::PixelFormat format () const
uint64_t framesDropped () const
 Number of frames dropped (overwritten in Ready before GPU consumed them).
uint64_t framesPublished () const
 Total number of frames published by the producer.
bool hasNewFrame () const
 True if at least one frame has been published.
uint32_t height () const
 MetalTextureStream (const MetalTextureStream &)=delete
 MetalTextureStream (MetalTextureStream &&)=delete
 MetalTextureStream (MTL::Device *device, const Descriptor &desc)
MetalTextureStream & operator= (const MetalTextureStream &)=delete
MetalTextureStream & operator= (MetalTextureStream &&)=delete
void publishExternal (MTL::Texture *externalTexture)
uint32_t width () const
void writeRegion (const void *data, size_t bytesPerRow, MTL::Region region, uint32_t mipLevel=0)
 ~MetalTextureStream ()

Static Public Attributes

static constexpr int kNumSlots = 3

Detailed Description

Triple-buffered texture streaming for real-time data ingestion.

Three MTL::Texture instances rotate through Write / Ready / Read states:

  • Write: CPU actively writes new pixel data
  • Ready: Most recent completed frame, waiting for GPU pickup
  • Read: GPU reads from this texture during the current render pass

Critical invariant: CPU never writes to a texture the GPU is currently reading. The Ready slot decouples producer from consumer.

Thread safety: Single producer, single consumer. The producer calls beginWrite/writeRegion/endWrite; the consumer calls acquireForRead/endFrame. For multiple producers, wrap beginWrite/endWrite in a mutex.

Definition at line 53 of file metalTextureStream.h.

Constructor & Destructor Documentation

◆ MetalTextureStream() [1/3]

visutwin::canvas::MetalTextureStream::MetalTextureStream ( MTL::Device * device,
const Descriptor & desc )

Definition at line 14 of file metalTextureStream.cpp.

References visutwin::canvas::MetalTextureStream::Descriptor::format, visutwin::canvas::MetalTextureStream::Descriptor::height, kNumSlots, visutwin::canvas::MetalTextureStream::Descriptor::label, visutwin::canvas::MetalTextureStream::Descriptor::width, and visutwin::canvas::MetalTextureStream::Descriptor::writeCombined.

Referenced by MetalTextureStream(), MetalTextureStream(), operator=(), and operator=().

◆ ~MetalTextureStream()

visutwin::canvas::MetalTextureStream::~MetalTextureStream ( )

Definition at line 57 of file metalTextureStream.cpp.

◆ MetalTextureStream() [2/3]

visutwin::canvas::MetalTextureStream::MetalTextureStream ( const MetalTextureStream & )
delete

References MetalTextureStream().

◆ MetalTextureStream() [3/3]

visutwin::canvas::MetalTextureStream::MetalTextureStream ( MetalTextureStream && )
delete

References MetalTextureStream().

Member Function Documentation

◆ acquireForRead()

MTL::Texture * visutwin::canvas::MetalTextureStream::acquireForRead ( )

Get the most recently completed texture for GPU reading. Atomically swaps ready and read slots. Returns nullptr if no frame has been published yet.

Definition at line 117 of file metalTextureStream.cpp.

◆ beginWrite()

MTL::Texture * visutwin::canvas::MetalTextureStream::beginWrite ( )

Begin writing to the next available texture slot. Returns the texture to write into. Blocks if all 3 slots are in-flight (GPU back-pressure).

Definition at line 73 of file metalTextureStream.cpp.

◆ endFrame()

void visutwin::canvas::MetalTextureStream::endFrame ( MTL::CommandBuffer * commandBuffer)

Register GPU completion on the command buffer so that the read texture slot can be recycled. Must be called on the LAST command buffer committed per frame. Same pattern as MetalUniformRingBuffer::endFrame().

Definition at line 139 of file metalTextureStream.cpp.

◆ endWrite()

void visutwin::canvas::MetalTextureStream::endWrite ( )

Finish writing. The texture becomes the new "ready" frame. Atomically swaps write and ready slots.

Definition at line 92 of file metalTextureStream.cpp.

◆ format()

MTL::PixelFormat visutwin::canvas::MetalTextureStream::format ( ) const
inlinenodiscard

Definition at line 115 of file metalTextureStream.h.

◆ framesDropped()

uint64_t visutwin::canvas::MetalTextureStream::framesDropped ( ) const
inlinenodiscard

Number of frames dropped (overwritten in Ready before GPU consumed them).

Definition at line 121 of file metalTextureStream.h.

◆ framesPublished()

uint64_t visutwin::canvas::MetalTextureStream::framesPublished ( ) const
inlinenodiscard

Total number of frames published by the producer.

Definition at line 118 of file metalTextureStream.h.

◆ hasNewFrame()

bool visutwin::canvas::MetalTextureStream::hasNewFrame ( ) const
inlinenodiscard

True if at least one frame has been published.

Definition at line 124 of file metalTextureStream.h.

◆ height()

uint32_t visutwin::canvas::MetalTextureStream::height ( ) const
inlinenodiscard

Definition at line 114 of file metalTextureStream.h.

◆ operator=() [1/2]

MetalTextureStream & visutwin::canvas::MetalTextureStream::operator= ( const MetalTextureStream & )
delete

References MetalTextureStream().

◆ operator=() [2/2]

MetalTextureStream & visutwin::canvas::MetalTextureStream::operator= ( MetalTextureStream && )
delete

References MetalTextureStream().

◆ publishExternal()

void visutwin::canvas::MetalTextureStream::publishExternal ( MTL::Texture * externalTexture)

Publish an externally-owned texture (e.g., from CVMetalTextureCache). The stream does NOT own this texture; caller must keep it alive until the next publishExternal() or endWrite() call.

Definition at line 107 of file metalTextureStream.cpp.

◆ width()

uint32_t visutwin::canvas::MetalTextureStream::width ( ) const
inlinenodiscard

Definition at line 113 of file metalTextureStream.h.

◆ writeRegion()

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

Write pixel data into a region of the current write texture. Convenience wrapper around MTL::Texture::replaceRegion(). Must be called between beginWrite() and endWrite().

Definition at line 83 of file metalTextureStream.cpp.

Member Data Documentation

◆ kNumSlots

int visutwin::canvas::MetalTextureStream::kNumSlots = 3
staticconstexpr

Definition at line 56 of file metalTextureStream.h.

Referenced by MetalTextureStream().

The documentation for this class was generated from the following files: