OGRE-Next: Ogre::AsyncTextureTicket Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | List of all members
Ogre::AsyncTextureTicket Class Referenceabstract

In Ogre 2.2 reading data from GPU back to CPU is asynchronous. More...

`#include <OgreAsyncTextureTicket.h>`

Inheritance diagram for Ogre::AsyncTextureTicket:
[legend]

## Classes
struct | DelayedDownload

## Public Types
enum | Status { Ready , Downloading , Mapped }
Public Types inherited from Ogre::TextureGpuListener
enum | Reason { Unknown , FromStorageToSysRam , FromSysRamToStorage , GainedResidency , LostResidency , PoolTextureSlotChanged , ResidentToSysRamSync , MetadataCacheOutOfDate , ExceptionThrown , FsaaSettingAlteredByApi , ReadyForRendering , Deleted }

## Public Member Functions
| AsyncTextureTicket (uint32 width, uint32 height, uint32 depthOrSlices, TextureTypes::TextureTypes textureType, PixelFormatGpu pixelFormatFamily)
| ~AsyncTextureTicket () override
virtual bool | canMapMoreThanOneSlice () const
| See Image2::convertFromTexture for an example of how to use AyncTextureTicket.
void | download (TextureGpu *textureSrc, uint8 mipLevel, bool accurateTracking, TextureBox *srcBox=0, bool bImmediate=false)
| Downloads textureSrc into this ticket.
size_t | getBytesPerImage () const
uint32 | getBytesPerRow () const
uint32 | getDepth () const
| For TypeCube & TypeCubeArray, this value returns 1.
uint32 | getDepthOrSlices () const
uint32 | getHeight () const
uint32 | getNumSlices () const
| For TypeCube this value returns 6.
PixelFormatGpu | getPixelFormatFamily () const
uint32 | getWidth () const
TextureBox | map (uint32 slice)
| Maps the buffer for CPU access.
void | notifyTextureChanged (TextureGpu *texture, TextureGpuListener::Reason reason, void *extraData) override
| TextureGpuListener overload.
virtual bool | queryIsTransferDone ()
void | unmap ()
| Unmaps the pointer mapped with map().
Public Member Functions inherited from Ogre::TextureGpuListener
virtual | ~TextureGpuListener ()
virtual bool | shouldStayLoaded (TextureGpu *texture)
| Return true if this TextureGpu should likely stay loaded or else graphical changes could occur.

## Detailed Description

In Ogre 2.2 reading data from GPU back to CPU is asynchronous.

See TextureGpuManager::createAsyncTextureTicket to generate a ticket. While the async transfer is being performed, you should be doing something else.

Remarks
  If you call map() before the transfer is done, it will produce a stall as the CPU must wait for the GPU to finish all its pending operations.

  Use queryIsTransferDone to query if the transfer has finished. Beware not all APIs support querying async transfer status. In those cases there is no reliable way to determine when the transfer is done. An almost safe bet is to wait two frames before mapping.

  Call TextureGpuManager::destroyAsyncTextureTicket when you're done with this ticket.

## Member Enumeration Documentation

## ◆ Status

enum Ogre::AsyncTextureTicket::Status

Enumerator
Ready |
Downloading |
Mapped |

## Constructor & Destructor Documentation

## ◆ AsyncTextureTicket()

Ogre::AsyncTextureTicket::AsyncTextureTicket | ( | uint32 | width,
|  | uint32 | height,
|  | uint32 | depthOrSlices,
|  | TextureTypes::TextureTypes | textureType,
|  | PixelFormatGpu | pixelFormatFamily )

## ◆ ~AsyncTextureTicket()

Ogre::AsyncTextureTicket::~AsyncTextureTicket | ( |  | ) |
| override

## Member Function Documentation

## ◆ canMapMoreThanOneSlice()

virtual bool Ogre::AsyncTextureTicket::canMapMoreThanOneSlice | ( |  | ) | const
| inlinevirtual

See Image2::convertFromTexture for an example of how to use AyncTextureTicket.

## ◆ download()

void Ogre::AsyncTextureTicket::download | ( | TextureGpu * | textureSrc,
|  | uint8 | mipLevel,
|  | bool | accurateTracking,
|  | TextureBox * | srcBox = 0,
|  | bool | bImmediate = false )

Downloads textureSrc into this ticket.

The size (resolution) of this ticket must match exactly of the region to download.

Remarks
  The texture must either be Resident, or being streamed (i.e. scheduled to become Resident) If the texture isn't done streaming, the ticket will automatically schedule itself to perform the actual download once the streaming is done. If the Texture has a SystemRAM copy, it won't be used. You must access that directly, not via AsyncTextureTicket.

Parameters

  textureSrc | Texture to download from. Must be resident.
  mipLevel | Mip level to download.
  accurateTracking | When false, you will be mapping this texture much further along (i.e. after 2-3 frames) Useful when constantly streaming GPU content to the CPU with 3 frames delay. When true, we will accurately track the status of this transfer, which has higher driver overhead.
  srcBox | When nullptr, we'll download the whole texture (its selected mip level) When not nullptr, we'll download the region within the texture. This region must resolution must match exactly that of this ticket (e.g. bytesPerRow may be much bigger than you expect!)
  bImmediate | When bImmediate is true, we will download from the GPU if texture is currently resident and ready; even if there are pending residency changes. If it's not ready, we'll listen for when it is.

## ◆ getBytesPerImage()

size_t Ogre::AsyncTextureTicket::getBytesPerImage | ( |  | ) | const

## ◆ getBytesPerRow()

uint32 Ogre::AsyncTextureTicket::getBytesPerRow | ( |  | ) | const

## ◆ getDepth()

uint32 Ogre::AsyncTextureTicket::getDepth | ( |  | ) | const

For TypeCube & TypeCubeArray, this value returns 1.

## ◆ getDepthOrSlices()

uint32 Ogre::AsyncTextureTicket::getDepthOrSlices | ( |  | ) | const

## ◆ getHeight()

uint32 Ogre::AsyncTextureTicket::getHeight | ( |  | ) | const

## ◆ getNumSlices()

uint32 Ogre::AsyncTextureTicket::getNumSlices | ( |  | ) | const

For TypeCube this value returns 6.

For TypeCubeArray, value returns numSlices * 6u.

## ◆ getPixelFormatFamily()

PixelFormatGpu Ogre::AsyncTextureTicket::getPixelFormatFamily | ( |  | ) | const

## ◆ getWidth()

uint32 Ogre::AsyncTextureTicket::getWidth | ( |  | ) | const

## ◆ map()

TextureBox Ogre::AsyncTextureTicket::map | ( | uint32 | slice | ) |

Maps the buffer for CPU access.

Will stall if transfer from GPU memory to staging area hasn't finished yet. See queryIsTransferDone.

Remarks
  Attempting to write to the returned pointer is undefined behavior. Be careful of TextureBox::bytesPerRow & bytesPerImage, when downloading a subregion of a texture, these values may not always be what you expect.

  NOTE: When mapping a texture bigger than 2048x2048; in D3D11 the the returned pointer will return TextureBox::numSlices = 1, In this case you will have to use that slice, unmap this ticket, and map it again with the next slice.

  See Image2::convertFromTexture for an example of how to use AyncTextureTicket

Parameters

  slice | First slice to map. Textures below 2048x2048 are guaranteed to be able to access [slice; getNumSlices). Textures above that will only be able to access [slice; slice+1)

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

## ◆ notifyTextureChanged()

void Ogre::AsyncTextureTicket::notifyTextureChanged | ( | TextureGpu * | texture,
|  | TextureGpuListener::Reason | reason,
|  | void * | extraData )
| overridevirtual

TextureGpuListener overload.

Implements Ogre::TextureGpuListener.

## ◆ queryIsTransferDone()

virtual bool Ogre::AsyncTextureTicket::queryIsTransferDone | ( |  | ) |
| virtual

Reimplemented in Ogre::D3D11AsyncTextureTicket, Ogre::GL3PlusAsyncTextureTicket, Ogre::MetalAsyncTextureTicket, Ogre::NULLAsyncTextureTicket, and Ogre::VulkanAsyncTextureTicket.

## ◆ unmap()

void Ogre::AsyncTextureTicket::unmap | ( |  | ) |

Unmaps the pointer mapped with map().

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

- OgreAsyncTextureTicket.h