OGRE: Ogre::MetalStagingBuffer Class Reference

| OGRE 2.2.4 Object-Oriented Graphics Rendering Engine

Classes | Public Types | Public Member Functions | List of all members
Ogre::MetalStagingBuffer Class Reference

A staging buffer is a buffer that resides on the GPU and be written to/from both CPU & GPU However the access in both cases is limited. More...

`#include <OgreMetalStagingBuffer.h>`

Inheritance diagram for Ogre::MetalStagingBuffer:
[legend]

## Public Types
typedef vector< Destination >::type | DestinationVec

## Public Member Functions
| MetalStagingBuffer (size_t internalBufferStart, size_t sizeBytes, VaoManager *vaoManager, bool uploadOnly, id< MTLBuffer > vboName, MetalDevice *device)
virtual | ~MetalStagingBuffer ()
virtual size_t | _asyncDownload (BufferPacked *source, size_t srcOffset, size_t srcLength)
| Copies the GPU data in BufferPacked to the StagingBuffer so that it can be later read by the CPU using an AsyncTicket. More...
virtual size_t | _asyncDownloadV1 (v1::MetalHardwareBufferCommon *source, size_t srcOffset, size_t srcLength)
virtual void | _cancelDownload (size_t offset, size_t sizeBytes)
| Releases memory assigned to a download that hasn't been mapped yet, to make space for another _asyncDownload call. More...
const void * | _mapForRead (size_t offset, size_t sizeBytes)
| Maps the buffer for read acces for the CPU. More...
void | _notifyDeviceStalled (void)
void | _unmapToV1 (v1::MetalHardwareBufferCommon *hwBuffer, size_t lockStart, size_t lockSize)
void | addReferenceCount (void)
| Adds a reference count to the StagingBuffer. @See removeReferenceCount. More...
virtual bool | canDownload (size_t length) const
| Checks if this staging buffer has enough free space to use _asyncDownload. More...
void | cleanUnfencedHazards (void)
id< MTLBuffer > | getBufferName (void) const
uint64 | getLastUsedTimestamp (void) const
| Returns the time in millisecond when the ref. count became 0. More...
uint32 | getLifetimeThreshold (void) const
| Returns the time in milliseconds in which a StagingBuffer should live with a reference count of 0 before being deleted. More...
MappingState | getMappingState (void) const
size_t | getMaxSize (void)
int16 | getReferenceCount (void) const
uint32 | getUnfencedTimeThreshold (void) const
| Returns the time in milliseconds in which a StagingBuffer should hazards unfenced while with a reference count of 0. More...
bool | getUploadOnly (void) const
| When true, this buffer can only be used for uploading to GPU. More...
void * | map (size_t sizeBytes)
| Maps the given amount of bytes. More...
void | operator delete (void *ptr)
void | operator delete (void *ptr, const char *, int, const char *)
void | operator delete (void *ptr, void *)
void | operator delete[] (void *ptr)
void | operator delete[] (void *ptr, const char *, int, const char *)
void * | operator new (size_t sz)
void * | operator new (size_t sz, const char *file, int line, const char *func)
| operator new, with debug line info More...
void * | operator new (size_t sz, void *ptr)
| placement operator new More...
void * | operator new[] (size_t sz)
void * | operator new[] (size_t sz, const char *file, int line, const char *func)
| array operator new, with debug line info More...
void | removeReferenceCount (void)
| Decreases the reference count by one. More...
void | unmap (const Destination &destination)
| Unmaps the mapped region and copies the data to the given region. @See Destination. More...
void | unmap (const Destination *destinations, size_t numDestinations)
void | unmap (const DestinationVec &destinations)
| Unmaps the mapped region and copies the data to multiple buffers. More...
virtual StagingStallType | uploadWillStall (size_t sizeBytes)
| Returns true if our next call to @map() with the same parameters will stall. More...

## Detailed Description

A staging buffer is a buffer that resides on the GPU and be written to/from both CPU & GPU However the access in both cases is limited.

GPUs can only copy (i.e. memcpy) to another real buffer (can't be used directly as i.e. texture or vertex buffer) and CPUs can only map it. In other words, a staging buffer is an intermediate buffer to transfer data between CPU & GPU

## Member Typedef Documentation

## ◆ DestinationVec

typedef vector<Destination>::type Ogre::StagingBuffer::DestinationVec
| inherited

## Constructor & Destructor Documentation

## ◆ MetalStagingBuffer()

Ogre::MetalStagingBuffer::MetalStagingBuffer | ( | size_t | internalBufferStart,
|  | size_t | sizeBytes,
|  | VaoManager * | vaoManager,
|  | bool | uploadOnly,
|  | id< MTLBuffer > | vboName,
|  | MetalDevice * | device
| ) |  |

## ◆ ~MetalStagingBuffer()

virtual Ogre::MetalStagingBuffer::~MetalStagingBuffer | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ _asyncDownload()

virtual size_t Ogre::MetalStagingBuffer::_asyncDownload | ( | BufferPacked * | source,
|  | size_t | srcOffset,
|  | size_t | srcLength
| ) |  |
| virtual

Copies the GPU data in BufferPacked to the StagingBuffer so that it can be later read by the CPU using an AsyncTicket.

See also
  AsyncTicket.

Remarks
  For internal use. May throw if it can't handle the request (i.e. requested size is too big, or too many _asyncDownload operations are pending until calling _mapForRead)

See also
  canDownload mUploadOnly must be true.

Parameters

  source | The buffer to copy from.
  srcOffset | The offset, in bytes, of the buffer to copy from.
  srcLength | The size in bytes, of the data to transfer to this staging buffer.

Returns
  The offset in bytes that will be used by

See also
  _mapForRead

Implements Ogre::StagingBuffer.

## ◆ _asyncDownloadV1()

virtual size_t Ogre::MetalStagingBuffer::_asyncDownloadV1 | ( | v1::MetalHardwareBufferCommon * | source,
|  | size_t | srcOffset,
|  | size_t | srcLength
| ) |  |
| virtual

## ◆ _cancelDownload()

virtual void Ogre::MetalStagingBuffer::_cancelDownload | ( | size_t | offset,
|  | size_t | sizeBytes
| ) |  |
| virtual

Releases memory assigned to a download that hasn't been mapped yet, to make space for another _asyncDownload call.

Useful when you suddenly don't intend to call _mapForRead.

Reimplemented from Ogre::StagingBuffer.

## ◆ _mapForRead()

const void* Ogre::StagingBuffer::_mapForRead | ( | size_t | offset,
|  | size_t | sizeBytes
| ) |  |
| inherited

Maps the buffer for read acces for the CPU.

Remarks
  For internal use. mUploadOnly must be true. Attempting to const cast the returned pointer and write to it is undefined behavior. Call unmap( 0, 0 ) to unmap. Once mapped and unmapped, the same region shouldn't be remapped.

Parameters

  offset | The returned value from _asyncDownload.
  sizeBytes | The size in bytes of the data to map. Should be parameter 'srcLength' passed to _asyncDownload.

Returns
  The pointer with the data read from the GPU. Read only.

## ◆ _notifyDeviceStalled()

void Ogre::MetalStagingBuffer::_notifyDeviceStalled | ( | void |  | ) |

## ◆ _unmapToV1()

void Ogre::MetalStagingBuffer::_unmapToV1 | ( | v1::MetalHardwareBufferCommon * | hwBuffer,
|  | size_t | lockStart,
|  | size_t | lockSize
| ) |  |

## ◆ addReferenceCount()

void Ogre::StagingBuffer::addReferenceCount | ( | void |  | ) |
| inherited

Adds a reference count to the StagingBuffer. @See removeReferenceCount.

## ◆ canDownload()

virtual bool Ogre::MetalStagingBuffer::canDownload | ( | size_t | length | ) | const
| virtual

Checks if this staging buffer has enough free space to use _asyncDownload.

Otherwise such function would raise an exception.

Remarks
  mUploadOnly must be true. It is the counter side of

See also
  uploadWillStall

Parameters

  length | The size in bytes that need to be downloaded.

Reimplemented from Ogre::StagingBuffer.

## ◆ cleanUnfencedHazards()

void Ogre::MetalStagingBuffer::cleanUnfencedHazards | ( | void |  | ) |

## ◆ getBufferName()

id<MTLBuffer> Ogre::MetalStagingBuffer::getBufferName | ( | void |  | ) | const
| inline

## ◆ getLastUsedTimestamp()

uint64 Ogre::StagingBuffer::getLastUsedTimestamp | ( | void |  | ) | const
| inlineinherited

Returns the time in millisecond when the ref. count became 0.

## ◆ getLifetimeThreshold()

uint32 Ogre::StagingBuffer::getLifetimeThreshold | ( | void |  | ) | const
| inlineinherited

Returns the time in milliseconds in which a StagingBuffer should live with a reference count of 0 before being deleted.

## ◆ getMappingState()

MappingState Ogre::StagingBuffer::getMappingState | ( | void |  | ) | const
| inlineinherited

## ◆ getMaxSize()

size_t Ogre::StagingBuffer::getMaxSize | ( | void |  | ) |
| inlineinherited

## ◆ getReferenceCount()

int16 Ogre::StagingBuffer::getReferenceCount | ( | void |  | ) | const
| inlineinherited

## ◆ getUnfencedTimeThreshold()

uint32 Ogre::StagingBuffer::getUnfencedTimeThreshold | ( | void |  | ) | const
| inlineinherited

Returns the time in milliseconds in which a StagingBuffer should hazards unfenced while with a reference count of 0.

See also
  getLifetimeThreshold

## ◆ getUploadOnly()

bool Ogre::StagingBuffer::getUploadOnly | ( | void |  | ) | const
| inlineinherited

When true, this buffer can only be used for uploading to GPU.

When false, can only be used for downloading from GPU

## ◆ map()

void* Ogre::StagingBuffer::map | ( | size_t | sizeBytes | ) |
| inherited

Maps the given amount of bytes.

May block if not ready. @See uploadWillStall if you wish to know.

Remarks
  Will throw if sizeBytes > this->getMaxSize()

## ◆ operator delete() [1/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr | ) |
| inlineinherited

## ◆ operator delete() [2/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |
| inlineinherited

## ◆ operator delete() [3/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | void * |
| ) |  |
| inlineinherited

## ◆ operator delete[]() [1/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr | ) |
| inlineinherited

## ◆ operator delete[]() [2/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |
| inlineinherited

## ◆ operator new() [1/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz | ) |
| inlineinherited

## ◆ operator new() [2/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |
| inlineinherited

operator new, with debug line info

## ◆ operator new() [3/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | void * | ptr
| ) |  |
| inlineinherited

placement operator new

## ◆ operator new[]() [1/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz | ) |
| inlineinherited

## ◆ operator new[]() [2/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |
| inlineinherited

array operator new, with debug line info

## ◆ removeReferenceCount()

void Ogre::StagingBuffer::removeReferenceCount | ( | void |  | ) |
| inherited

Decreases the reference count by one.

StagingBuffers are manually reference counted. The first reason is performance. The second main reason is that the pointer doesn't get immediately deleted when the reference hits 0.

  Instead, a reference count of 0 means the Vao manager will monitor its lifetime. If it has been 0 for too long (past certain time threshold) the Vao manager will destroy this staging buffer.

  Meanwhile, the Staging Buffer will live in a pool until it's requested again or the time threshold is met. This prevents unwanted hiccups due to buffers getting recreated and destroyed all the time. Keep a non-zero ref. count to ensure the StagingBuffer won't be deleted due to timeouts (i.e. you know this buffer will get used at long regular intervals, like once every 15 minutes)

  Having a non-zero reference count doesn't mean the pointer will live forever though, as the memory is owned by the VaoManager: if the VaoManager is shutdown, this StagingBuffer will be freed.

## ◆ unmap() [1/3]

void Ogre::StagingBuffer::unmap | ( | const Destination & | destination | ) |
| inlineinherited

Unmaps the mapped region and copies the data to the given region. @See Destination.

References Ogre::StagingBuffer::unmap().

Referenced by Ogre::StagingBuffer::unmap().

## ◆ unmap() [2/3]

void Ogre::StagingBuffer::unmap | ( | const Destination * | destinations,
|  | size_t | numDestinations
| ) |  |
| inherited

## ◆ unmap() [3/3]

void Ogre::StagingBuffer::unmap | ( | const DestinationVec & | destinations | ) |
| inlineinherited

Unmaps the mapped region and copies the data to multiple buffers.

Useful when loading many meshes or textures at once (i.e. from multiple threads)

## ◆ uploadWillStall()

virtual StagingStallType Ogre::MetalStagingBuffer::uploadWillStall | ( | size_t | sizeBytes | ) |
| virtual

Returns true if our next call to @map() with the same parameters will stall.

@See StagingStallType

Remarks
  Not all RenderSystems can accurately give this information and will always return STALL_PARTIAL (i.e. GLES2) The chances of getting a STALL_FULL get higher as sizeBytes gets closer to this->getMaxSize() mUploadOnly must be false. It is the counter side of

See also
  canDownload

Reimplemented from Ogre::StagingBuffer.

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

- OgreMetalStagingBuffer.h