OGRE-Next  2.3
Object-Oriented Graphics Rendering Engine
Ogre::MetalTextureGpuRenderTarget Class Reference

#include <OgreMetalTextureGpu.h>

+ Inheritance diagram for Ogre::MetalTextureGpuRenderTarget:

Public Member Functions

 MetalTextureGpuRenderTarget (GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, VaoManager *vaoManager, IdString name, uint32 textureFlags, TextureTypes::TextureTypes initialType, TextureGpuManager *textureManager)
 
void _addPendingResidencyChanges (uint32 value)
 
void _autogenerateMipmaps (CopyEncTransitionMode::CopyEncTransitionMode transitionMode=CopyEncTransitionMode::Auto) override
 Tells the API to let the HW autogenerate mipmaps. More...
 
uint8_getSysRamCopy (uint8 mipLevel)
 
TextureBox _getSysRamCopyAsBox (uint8 mipLevel)
 
size_t _getSysRamCopyBytesPerImage (uint8 mipLevel)
 Note: Returns non-zero even if there is no system ram copy. More...
 
size_t _getSysRamCopyBytesPerRow (uint8 mipLevel)
 Note: Returns non-zero even if there is no system ram copy. More...
 
bool _isDataReadyImpl () const override
 For internal use. More...
 
bool _isManualTextureFlagPresent () const
 
void _notifySysRamDownloadIsReady (uint8 *sysRamPtr, bool resyncOnly)
 Do not call directly. More...
 
void _notifyTextureSlotChanged (const TexturePool *newPool, uint16 slice) override
 
void _resetTextureManager ()
 
void _resolveTo (TextureGpu *resolveTexture)
 Immediately resolves this texture to the resolveTexture argument. More...
 
void _setDepthBufferDefaults (uint16 depthBufferPoolId, bool preferDepthTexture, PixelFormatGpu desiredDepthBufferFormat) override
 These 3 values are used as defaults for the compositor to use, but they may be explicitly overriden by a RenderPassDescriptor. More...
 
virtual void _setNextLayout (ResourceLayout::Layout layout)
 Sets the layout the texture should be transitioned to after the next copy operation (once the copy encoder gets closed) More...
 
void _setNextResidencyStatus (GpuResidency::GpuResidency nextResidency)
 
void _setSampleDescription (SampleDescription desc, SampleDescription validatedSampleDesc)
 For internal use. More...
 
void _setSourceType (uint8 type)
 
void _setToDisplayDummyTexture () override
 
void _syncGpuResidentToSystemRam ()
 Forces downloading data from GPU to CPU, usually because the data on GPU changed and we're in strategy AlwaysKeepSystemRamCopy. More...
 
void _transitionTo (GpuResidency::GpuResidency newResidency, uint8 *sysRamCopy, bool autoDeleteSysRamCopy=true)
 This function may be called manually (if user is manually managing a texture) or automatically (e.g. More...
 
void addListener (TextureGpuListener *listener)
 
bool allowsAutoMipmaps () const
 
void copyContentsToMemory (TextureBox src, TextureBox dst, PixelFormatGpu dstFormat, bool automaticResolve=true)
 Writes the current contents of the render target to the memory. More...
 
void copyParametersFrom (TextureGpu *src)
 
void copyTo (TextureGpu *dst, const TextureBox &dstBox, uint8 dstMipLevel, const TextureBox &srcBox, uint8 srcMipLevel, bool keepResolvedTexSynced=true, CopyEncTransitionMode::CopyEncTransitionMode srcTransitionMode=CopyEncTransitionMode::Auto, CopyEncTransitionMode::CopyEncTransitionMode dstTransitionMode=CopyEncTransitionMode::Auto) override
 
virtual ResourceLayout::Layout getCurrentLayout () const
 
virtual void getCustomAttribute (IdString name, void *pData) override
 
ResourceLayout::Layout getDefaultLayout (bool bIgnoreDiscardableFlag=false) const
 
uint32 getDepth () const
 For TypeCube & TypeCubeArray, this value returns 1. More...
 
uint16 getDepthBufferPoolId () const override
 
uint32 getDepthOrSlices () const
 
PixelFormatGpu getDesiredDepthBufferFormat () const override
 
id< MTLTexture > getDisplayTextureName () const
 
TextureBox getEmptyBox (uint8 mipLevel)
 
id< MTLTexture > getFinalTextureName () const
 
GpuPageOutStrategy::GpuPageOutStrategy getGpuPageOutStrategy () const
 
uint32 getHeight () const
 
uint32 getInternalHeight () const
 Real API height accounting for TextureGpu::getOrientationMode. See getInternalWidth. More...
 
uint32 getInternalSliceStart () const
 
TextureTypes::TextureTypes getInternalTextureType () const
 
uint32 getInternalWidth () const
 Real API width accounting for TextureGpu::getOrientationMode If orientation mode is 90° or 270° then getInternalWidth returns the height and getInternalHeight returns the width. More...
 
const vector< TextureGpuListener * >::type & getListeners () const
 
id< MTLTexture > getMsaaFramebufferName () const
 
IdString getName () const
 
String getNameStr () const override
 Note: This returns the alias name of the texture. More...
 
GpuResidency::GpuResidency getNextResidencyStatus () const
 When getResidencyStatus() != getNextResidencyStatus(), residency changes happen in the main thread, while some preparation may be happening in the background. More...
 
uint8 getNumMipmaps () const
 
uint32 getNumSlices () const
 For TypeCube this value returns 6. More...
 
OrientationMode getOrientationMode () const override
 
uint32 getPendingResidencyChanges () const
 Returns the number of pending residency changes. More...
 
PixelFormatGpu getPixelFormat () const
 
bool getPreferDepthTexture () const override
 
virtual String getRealResourceNameStr () const
 Returns the real name (e.g. disk in file) of the resource. More...
 
SampleDescription getRequestedSampleDescription () const
 Returns original requested sample description, i.e. the raw input to setSampleDescription. More...
 
GpuResidency::GpuResidency getResidencyStatus () const
 
virtual String getResourceGroupStr () const
 
SampleDescription getSampleDescription () const
 Returns effective sample description supported by the API. More...
 
String getSettingsDesc () const
 
size_t getSizeBytes () const
 Returns total size in bytes used in GPU by this texture (not by its pool) including mipmaps. More...
 
uint8 getSourceType () const
 
void getSubsampleLocations (vector< Vector2 >::type locations) override
 Get the MSAA subsample locations. More...
 
TextureGpuManagergetTextureManager () const
 
const TexturePoolgetTexturePool () const
 
uint32 getTexturePoolId () const
 
TextureTypes::TextureTypes getTextureType () const
 
id< MTLTexture > getView (DescriptorSetTexture2::TextureSlot texSlot)
 
id< MTLTexture > getView (DescriptorSetUav::TextureSlot uavSlot)
 
id< MTLTexture > getView (PixelFormatGpu pixelFormat, uint8 mipLevel, uint8 numMipmaps, uint16 arraySlice, bool cubemapsAs2DArrays, bool forUav)
 
uint32 getWidth () const
 
bool hasAutomaticBatching () const
 
bool hasAutoMipmapAuto () const
 
bool hasEquivalentParameters (TextureGpu *other) const
 
bool hasMsaaExplicitResolves () const
 
bool isDataReady () const
 True if this texture is fully ready to be used for displaying. More...
 
bool isDiscardableContent () const
 
bool isManualTexture () const
 
bool isMetadataReady () const
 It is threadsafe to call this function from main thread. More...
 
virtual bool isMsaaPatternSupported (MsaaPatterns::MsaaPatterns pattern)
 
bool isMultisample () const
 
virtual bool isOpenGLRenderWindow () const
 OpenGL RenderWindows are a bit specific: More...
 
bool isPoolOwner () const
 
bool isReinterpretable () const
 
bool isRenderToTexture () const
 
bool isRenderWindowSpecific () const
 
bool isTexture () const
 
bool isTextureGpu () const override
 
bool isUav () const
 
void notifyAllListenersTextureChanged (uint32 reason, void *extraData=0)
 
void notifyDataIsReady () override
 Notifies it is safe to use the real data. Everything has been uploaded. 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...
 
bool prefersLoadingFromFileAsSRGB () const
 
void removeListener (TextureGpuListener *listener)
 
bool requiresTextureFlipping () const
 
void scheduleReupload (Image2 *image=0, bool autoDeleteImage=true)
 There are times where you want to reload a texture again (e.g. More...
 
void scheduleTransitionTo (GpuResidency::GpuResidency nextResidency, Image2 *image=0, bool autoDeleteImage=true)
 Same as unsafeScheduleTransitionTo, but first checks if we're already in the residency state we want to go to, or if it has already been scheduled; thus it can be called multiple times. More...
 
void setNumMipmaps (uint8 numMipmaps)
 
void setOrientationMode (OrientationMode orientationMode) override
 Sets the given orientation. More...
 
void setPixelFormat (PixelFormatGpu pixelFormat)
 Sets the pixel format. More...
 
void setResolution (uint32 width, uint32 height, uint32 depthOrSlices=1u)
 
void setSampleDescription (SampleDescription desc)
 
void setTexturePoolId (uint32 poolId)
 2D Texture with automatic batching will be merged with other textures into the same pool as one big 2D Array texture behind the scenes. More...
 
void setTextureType (TextureTypes::TextureTypes textureType) override
 
virtual bool supportsAsDepthBufferFor (TextureGpu *colourTarget) const
 
virtual void swapBuffers ()
 Only valid for TextureGpu classes. More...
 
void unsafeScheduleTransitionTo (GpuResidency::GpuResidency nextResidency, Image2 *image=0, bool autoDeleteImage=true)
 Schedules an async transition in residency. More...
 
void waitForData ()
 Blocks main thread until data is ready. More...
 
void waitForMetadata ()
 Blocks main thread until metadata is ready. More...
 
void writeContentsToFile (const String &filename, uint8 minMip, uint8 maxMip, bool automaticResolve=true)
 Writes the current contents of the render target to the named file. More...
 

Static Public Attributes

static OrientationMode msDefaultOrientationMode
 PUBLIC VARIABLE. More...
 
static const IdString msFinalTextureBuffer
 
static const IdString msMsaaTextureBuffer
 

Constructor & Destructor Documentation

◆ MetalTextureGpuRenderTarget()

Ogre::MetalTextureGpuRenderTarget::MetalTextureGpuRenderTarget ( GpuPageOutStrategy::GpuPageOutStrategy  pageOutStrategy,
VaoManager vaoManager,
IdString  name,
uint32  textureFlags,
TextureTypes::TextureTypes  initialType,
TextureGpuManager textureManager 
)

Member Function Documentation

◆ _addPendingResidencyChanges()

void Ogre::GpuResource::_addPendingResidencyChanges ( uint32  value)
inherited

◆ _autogenerateMipmaps()

void Ogre::MetalTextureGpu::_autogenerateMipmaps ( CopyEncTransitionMode::CopyEncTransitionMode  transitionMode = CopyEncTransitionMode::Auto)
overridevirtualinherited

Tells the API to let the HW autogenerate mipmaps.

Assumes allowsAutoMipmaps() == true and isRenderToTexture() == true

Parameters
transitionModeSee CopyEncTransitionMode::CopyEncTransitionMode

Implements Ogre::TextureGpu.

◆ _getSysRamCopy()

uint8* Ogre::TextureGpu::_getSysRamCopy ( uint8  mipLevel)
inherited

◆ _getSysRamCopyAsBox()

TextureBox Ogre::TextureGpu::_getSysRamCopyAsBox ( uint8  mipLevel)
inherited

◆ _getSysRamCopyBytesPerImage()

size_t Ogre::TextureGpu::_getSysRamCopyBytesPerImage ( uint8  mipLevel)
inherited

Note: Returns non-zero even if there is no system ram copy.

◆ _getSysRamCopyBytesPerRow()

size_t Ogre::TextureGpu::_getSysRamCopyBytesPerRow ( uint8  mipLevel)
inherited

Note: Returns non-zero even if there is no system ram copy.

◆ _isDataReadyImpl()

bool Ogre::MetalTextureGpu::_isDataReadyImpl ( ) const
overridevirtualinherited

For internal use.

Do not call directly.

This function is the same isDataReady except it ignores pending residency changes, which is important when TextureGpuManager needs to know this information but the TextureGpu is transitioning (thus mPendingResidencyChanges is in an inconsistent state)

Implements Ogre::TextureGpu.

Reimplemented in Ogre::MetalTextureGpuWindow.

◆ _isManualTextureFlagPresent()

bool Ogre::TextureGpu::_isManualTextureFlagPresent ( ) const
inherited

◆ _notifySysRamDownloadIsReady()

void Ogre::TextureGpu::_notifySysRamDownloadIsReady ( uint8 sysRamPtr,
bool  resyncOnly 
)
inherited

Do not call directly.

Will change mResidencyStatus from GpuResidency::Resident to GpuResidency::OnSystemRam

◆ _notifyTextureSlotChanged()

void Ogre::MetalTextureGpu::_notifyTextureSlotChanged ( const TexturePool newPool,
uint16  slice 
)
overridevirtualinherited

Reimplemented from Ogre::TextureGpu.

Reimplemented in Ogre::MetalTextureGpuWindow.

◆ _resetTextureManager()

void Ogre::TextureGpu::_resetTextureManager ( )
inherited

◆ _resolveTo()

void Ogre::TextureGpu::_resolveTo ( TextureGpu resolveTexture)
inherited

Immediately resolves this texture to the resolveTexture argument.

Source must be MSAA texture, destination must be non-MSAA.

Remarks
This function may be slow on some APIs and should only be used when required, for example, to capture the screen from an explicit MSAA target and save it to disk only on user demand. If you need to call this often (like once per frame or more), then consider setting a Compositor with CompositorNode::mLocalRtvs::resolveTextureName set so that the compositor automatically resolves the texture every frame as efficiently as possible.

◆ _setDepthBufferDefaults()

void Ogre::MetalTextureGpuRenderTarget::_setDepthBufferDefaults ( uint16  depthBufferPoolId,
bool  preferDepthTexture,
PixelFormatGpu  desiredDepthBufferFormat 
)
overridevirtual

These 3 values are used as defaults for the compositor to use, but they may be explicitly overriden by a RenderPassDescriptor.

Particularly required when passing the textures between nodes as input and output (since only the TextureGpu pointer is passed, and thus this information is lost)

Remarks
Changing these settings won't take immediate effect because they're only used when creating the compositor.
Parameters
depthBufferPoolIdSets the pool ID this RenderTarget should query from. Default value is POOL_DEFAULT. Set to POOL_NO_DEPTH to avoid using a DepthBuffer (or manually controlling it)
preferDepthTextureWhether this RT should be attached to a depth texture, or a regular depth buffer. On older GPUs, preferring depth textures may result in certain depth precisions to not be available (or use integer precision instead of floating point, etc). True to use depth textures. False otherwise (default).
desiredDepthBufferFormatOgre will try to honour this request, but if it's not supported, you may get lower precision. All formats will try to fallback to PF_D24_UNORM_S8_UINT if not supported. Must be one of the following: PFG_D24_UNORM_S8_UINT PFG_D16_UNORM PFG_D32_FLOAT PFG_D32_FLOAT_X24_S8_UINT

Reimplemented from Ogre::TextureGpu.

◆ _setNextLayout()

virtual void Ogre::TextureGpu::_setNextLayout ( ResourceLayout::Layout  layout)
virtualinherited

Sets the layout the texture should be transitioned to after the next copy operation (once the copy encoder gets closed)

This is specific to Vulkan & D3D12

Reimplemented in Ogre::VulkanTextureGpu.

◆ _setNextResidencyStatus()

void Ogre::GpuResource::_setNextResidencyStatus ( GpuResidency::GpuResidency  nextResidency)
inherited

◆ _setSampleDescription()

void Ogre::TextureGpu::_setSampleDescription ( SampleDescription  desc,
SampleDescription  validatedSampleDesc 
)
inherited

For internal use.

◆ _setSourceType()

void Ogre::TextureGpu::_setSourceType ( uint8  type)
inherited

◆ _setToDisplayDummyTexture()

void Ogre::MetalTextureGpu::_setToDisplayDummyTexture ( )
overridevirtualinherited

Implements Ogre::TextureGpu.

Reimplemented in Ogre::MetalTextureGpuWindow.

◆ _syncGpuResidentToSystemRam()

void Ogre::TextureGpu::_syncGpuResidentToSystemRam ( )
inherited

Forces downloading data from GPU to CPU, usually because the data on GPU changed and we're in strategy AlwaysKeepSystemRamCopy.

May stall.

◆ _transitionTo()

void Ogre::TextureGpu::_transitionTo ( GpuResidency::GpuResidency  newResidency,
uint8 sysRamCopy,
bool  autoDeleteSysRamCopy = true 
)
inherited

This function may be called manually (if user is manually managing a texture) or automatically (e.g.

loading from file, or automatic batching is enabled) Once you call this function, you're no longer in OnStorage mode; and will transition to either OnSystemRam or Resident depending on whether auto batching is enabled.

Remarks
Do NOT call this function yourself if you've created this function with AutomaticBatching as Ogre will call this, from a worker thread!

Make sure you're done using mSysRamCopy before calling this function, as we may free that pointer (unless autoDeleteSysRamCopyOnResident = false).

If you're calling _transitionTo yourself (i.e. you're not using scheduleTransitionTo) then you'll need to call _setNextResidencyStatus too, so that both getResidencyStatus and getNextResidencyStatus agree.

Parameters
sysRamCopySystem RAM copy that backs this GPU data. May be null. Must've been allocated with OGRE_MALLOC_SIMD( size, MEMCATEGORY_RESOURCE ); We will deallocate it. MUST respect _getSysRamCopyBytesPerRow & _getSysRamCopyBytesPerImage. If in doubt, use PixelFormatGpuUtils::getSizeBytes with rowAlignment = 4u;

This param must be nullptr or equal to get_getSysRamCopy when going from Resident to OnSystemRam and strategy is not AlwaysKeepSystemRamCopy; as we will async download the content from the GPU.

Parameters
autoDeleteSysRamCopyWhen true, we free mSysRamCopy as we should. When false, caller is responsible for deleting this pointer else it will leak!

◆ addListener()

void Ogre::TextureGpu::addListener ( TextureGpuListener listener)
inherited

◆ allowsAutoMipmaps()

bool Ogre::TextureGpu::allowsAutoMipmaps ( ) const
inherited

◆ copyContentsToMemory()

void Ogre::TextureGpu::copyContentsToMemory ( TextureBox  src,
TextureBox  dst,
PixelFormatGpu  dstFormat,
bool  automaticResolve = true 
)
inherited

Writes the current contents of the render target to the memory.

◆ copyParametersFrom()

void Ogre::TextureGpu::copyParametersFrom ( TextureGpu src)
inherited

◆ copyTo()

void Ogre::MetalTextureGpu::copyTo ( TextureGpu dst,
const TextureBox dstBox,
uint8  dstMipLevel,
const TextureBox srcBox,
uint8  srcMipLevel,
bool  keepResolvedTexSynced = true,
CopyEncTransitionMode::CopyEncTransitionMode  srcTransitionMode = CopyEncTransitionMode::Auto,
CopyEncTransitionMode::CopyEncTransitionMode  dstTransitionMode = CopyEncTransitionMode::Auto 
)
overridevirtualinherited
Parameters
dst
dstBox
dstMipLevel
srcBox
srcMipLevel
keepResolvedTexSyncedWhen true, if dst is an MSAA texture and is implicitly resolved (i.e. dst->hasMsaaExplicitResolves() == false); the resolved texture is also kept up to date.

Typically the reason to set this to false is if you plane on rendering more stuff to dst texture and then resolve.

Parameters
srcTransitionModeTransition mode for 'this'
dstTransitionModeTransition mode for 'dst'

Reimplemented from Ogre::TextureGpu.

◆ getCurrentLayout()

virtual ResourceLayout::Layout Ogre::TextureGpu::getCurrentLayout ( ) const
virtualinherited

Reimplemented in Ogre::VulkanTextureGpu.

◆ getCustomAttribute()

virtual void Ogre::MetalTextureGpu::getCustomAttribute ( IdString  name,
void *  pData 
)
overridevirtualinherited

Reimplemented from Ogre::TextureGpu.

Reimplemented in Ogre::MetalTextureGpuWindow.

◆ getDefaultLayout()

ResourceLayout::Layout Ogre::TextureGpu::getDefaultLayout ( bool  bIgnoreDiscardableFlag = false) const
inherited

◆ getDepth()

uint32 Ogre::TextureGpu::getDepth ( ) const
inherited

For TypeCube & TypeCubeArray, this value returns 1.

◆ getDepthBufferPoolId()

uint16 Ogre::MetalTextureGpuRenderTarget::getDepthBufferPoolId ( ) const
overridevirtual

Reimplemented from Ogre::TextureGpu.

◆ getDepthOrSlices()

uint32 Ogre::TextureGpu::getDepthOrSlices ( ) const
inherited

◆ getDesiredDepthBufferFormat()

PixelFormatGpu Ogre::MetalTextureGpuRenderTarget::getDesiredDepthBufferFormat ( ) const
overridevirtual

Reimplemented from Ogre::TextureGpu.

◆ getDisplayTextureName()

id<MTLTexture> Ogre::MetalTextureGpu::getDisplayTextureName ( ) const
inlineinherited

◆ getEmptyBox()

TextureBox Ogre::TextureGpu::getEmptyBox ( uint8  mipLevel)
inherited

◆ getFinalTextureName()

id<MTLTexture> Ogre::MetalTextureGpu::getFinalTextureName ( ) const
inlineinherited

◆ getGpuPageOutStrategy()

GpuPageOutStrategy::GpuPageOutStrategy Ogre::GpuResource::getGpuPageOutStrategy ( ) const
inherited

◆ getHeight()

uint32 Ogre::TextureGpu::getHeight ( ) const
inherited

◆ getInternalHeight()

uint32 Ogre::TextureGpu::getInternalHeight ( ) const
inherited

Real API height accounting for TextureGpu::getOrientationMode. See getInternalWidth.

◆ getInternalSliceStart()

uint32 Ogre::TextureGpu::getInternalSliceStart ( ) const
inherited

◆ getInternalTextureType()

TextureTypes::TextureTypes Ogre::TextureGpu::getInternalTextureType ( ) const
inherited

◆ getInternalWidth()

uint32 Ogre::TextureGpu::getInternalWidth ( ) const
inherited

Real API width accounting for TextureGpu::getOrientationMode If orientation mode is 90° or 270° then getInternalWidth returns the height and getInternalHeight returns the width.

◆ getListeners()

const vector<TextureGpuListener*>::type& Ogre::TextureGpu::getListeners ( ) const
inherited

◆ getMsaaFramebufferName()

id<MTLTexture> Ogre::MetalTextureGpu::getMsaaFramebufferName ( ) const
inlineinherited

◆ getName()

IdString Ogre::GpuResource::getName ( ) const
inherited

◆ getNameStr()

String Ogre::TextureGpu::getNameStr ( ) const
overridevirtualinherited

Note: This returns the alias name of the texture.

See TextureGpuManager::createOrRetrieveTexture

Reimplemented from Ogre::GpuResource.

◆ getNextResidencyStatus()

GpuResidency::GpuResidency Ogre::GpuResource::getNextResidencyStatus ( ) const
inherited

When getResidencyStatus() != getNextResidencyStatus(), residency changes happen in the main thread, while some preparation may be happening in the background.

For example when a texture is not resident but getNextResidencyStatus says it will, a background thread is loading the texture file from disk, but the actual transition won't happen until the main thread changes it. You can call texture->waitForData() which will stall, as the main thread will be communicating back and forth with the background to see if it's ready; and when it is, the main thread will perform the transition inside waitForData

Likewise, if that texture is resident but will soon not be, it is still legal to access its contents as long as you access them from the main thread before that main thread changes the residency. This gives you a strong serialization guarantee, but be careful with async tickets such as AsyncTextureTickets:

If you call AsyncTextureTicket *asyncTicket = textureManager->createAsyncTextureTicket( ... ); assert( texture->getResidencyStatus() == GpuResidency::Resident ); ... do something else that calls Ogre functionality ... assert( texture->getResidencyStatus() == GpuResidency::Resident ); asyncTicket->download( texture, mip, true ); Then the second assert may trigger because that "do something else" ended up calling a function inside Ogre that finalized the transition. Once you've called download and the resource was still Resident, you are safe that your data integrity will be kept.

Remarks
Beware of the ABA problem. If the following transitions are scheduled: OnStorage -> Resident -> OnStorage Then both getResidencyStatus & getNextResidencyStatus will return OnStorage. Use GpuResource::getPendingResidencyChanges to fix the ABA problem.

◆ getNumMipmaps()

uint8 Ogre::TextureGpu::getNumMipmaps ( ) const
inherited

◆ getNumSlices()

uint32 Ogre::TextureGpu::getNumSlices ( ) const
inherited

For TypeCube this value returns 6.

For TypeCubeArray, value returns numSlices * 6u.

◆ getOrientationMode()

OrientationMode Ogre::MetalTextureGpuRenderTarget::getOrientationMode ( ) const
overridevirtual

Reimplemented from Ogre::TextureGpu.

◆ getPendingResidencyChanges()

uint32 Ogre::GpuResource::getPendingResidencyChanges ( ) const
inherited

Returns the number of pending residency changes.

Residency changes may not be immediate and thus be delayed (e.g. see TextureGpu::scheduleTransitionTo).

When this value is 0 it implies that mResidencyStatus == mNextResidencyStatus

◆ getPixelFormat()

PixelFormatGpu Ogre::TextureGpu::getPixelFormat ( ) const
inherited

◆ getPreferDepthTexture()

bool Ogre::MetalTextureGpuRenderTarget::getPreferDepthTexture ( ) const
overridevirtual

Reimplemented from Ogre::TextureGpu.

◆ getRealResourceNameStr()

virtual String Ogre::TextureGpu::getRealResourceNameStr ( ) const
virtualinherited

Returns the real name (e.g. disk in file) of the resource.

◆ getRequestedSampleDescription()

SampleDescription Ogre::TextureGpu::getRequestedSampleDescription ( ) const
inherited

Returns original requested sample description, i.e. the raw input to setSampleDescription.

◆ getResidencyStatus()

GpuResidency::GpuResidency Ogre::GpuResource::getResidencyStatus ( ) const
inherited

◆ getResourceGroupStr()

virtual String Ogre::TextureGpu::getResourceGroupStr ( ) const
virtualinherited

◆ getSampleDescription()

SampleDescription Ogre::TextureGpu::getSampleDescription ( ) const
inherited

Returns effective sample description supported by the API.

Note it's only useful after having transitioned to resident.

◆ getSettingsDesc()

String Ogre::TextureGpu::getSettingsDesc ( ) const
inherited

◆ getSizeBytes()

size_t Ogre::TextureGpu::getSizeBytes ( ) const
inherited

Returns total size in bytes used in GPU by this texture (not by its pool) including mipmaps.

◆ getSourceType()

uint8 Ogre::TextureGpu::getSourceType ( ) const
inherited

◆ getSubsampleLocations()

void Ogre::MetalTextureGpu::getSubsampleLocations ( vector< Vector2 >::type  locations)
overridevirtualinherited

Get the MSAA subsample locations.

mSampleDescription.pattern must not be MsaaPatterns::Undefined.

Parameters
locationsOutputs an array with the locations for each subsample. Values are in range [-1; 1]

Implements Ogre::TextureGpu.

◆ getTextureManager()

TextureGpuManager* Ogre::TextureGpu::getTextureManager ( ) const
inherited

◆ getTexturePool()

const TexturePool* Ogre::TextureGpu::getTexturePool ( ) const
inlineinherited

◆ getTexturePoolId()

uint32 Ogre::TextureGpu::getTexturePoolId ( ) const
inlineinherited

◆ getTextureType()

TextureTypes::TextureTypes Ogre::TextureGpu::getTextureType ( ) const
inherited

◆ getView() [1/3]

id<MTLTexture> Ogre::MetalTextureGpu::getView ( DescriptorSetTexture2::TextureSlot  texSlot)
inherited

◆ getView() [2/3]

id<MTLTexture> Ogre::MetalTextureGpu::getView ( DescriptorSetUav::TextureSlot  uavSlot)
inherited

◆ getView() [3/3]

id<MTLTexture> Ogre::MetalTextureGpu::getView ( PixelFormatGpu  pixelFormat,
uint8  mipLevel,
uint8  numMipmaps,
uint16  arraySlice,
bool  cubemapsAs2DArrays,
bool  forUav 
)
inherited

◆ getWidth()

uint32 Ogre::TextureGpu::getWidth ( ) const
inherited

◆ hasAutomaticBatching()

bool Ogre::TextureGpu::hasAutomaticBatching ( ) const
inherited

◆ hasAutoMipmapAuto()

bool Ogre::TextureGpu::hasAutoMipmapAuto ( ) const
inherited

◆ hasEquivalentParameters()

bool Ogre::TextureGpu::hasEquivalentParameters ( TextureGpu other) const
inherited

◆ hasMsaaExplicitResolves()

bool Ogre::TextureGpu::hasMsaaExplicitResolves ( ) const
inherited

◆ isDataReady()

bool Ogre::TextureGpu::isDataReady ( ) const
inherited

True if this texture is fully ready to be used for displaying.

IMPORTANT: Always returns true if getResidencyStatus != GpuResidency::Resident and there are no pending residency transitions.

Returns false while there are pending residency status

If this is true, then isMetadataReady is also true. See isMetadataReady.

◆ isDiscardableContent()

bool Ogre::TextureGpu::isDiscardableContent ( ) const
inherited

◆ isManualTexture()

bool Ogre::TextureGpu::isManualTexture ( ) const
inherited

◆ isMetadataReady()

bool Ogre::TextureGpu::isMetadataReady ( ) const
inherited

It is threadsafe to call this function from main thread.

If this returns false, then the following functions are not threadsafe: Setters must not be called, and getters may change from a worker thread: setResolution getWidth, getHeight, getDepth, getDepthOrSlices, getNumSlices set/getPixelFormat set/getNumMipmaps set/getTextureType getTexturePool Note that this function may return true but the worker thread may still be uploading to this texture. Use isDataReady to see if the worker thread is fully done with this texture.

Remarks
Function for querying/waiting for data and metadata to be ready are for blocking the main thread when a worker thread is loading the texture from file or a listener (i.e. isManualTexture returns false) otherwise you don't need to call these functions.

◆ isMsaaPatternSupported()

virtual bool Ogre::TextureGpu::isMsaaPatternSupported ( MsaaPatterns::MsaaPatterns  pattern)
virtualinherited

Reimplemented in Ogre::D3D11TextureGpu.

◆ isMultisample()

bool Ogre::TextureGpu::isMultisample ( ) const
inherited

◆ isOpenGLRenderWindow()

virtual bool Ogre::TextureGpu::isOpenGLRenderWindow ( ) const
virtualinherited

OpenGL RenderWindows are a bit specific:

  • Their origins are upside down. Which means we need to flip Y.
  • They can access resolved contents of MSAA even if hasMsaaExplicitResolves = true
  • Headless windows return false since internally they're FBOs. However isRenderWindowSpecific will return true

Reimplemented in Ogre::VulkanTextureGpuWindow, Ogre::GL3PlusTextureGpuHeadlessWindow, and Ogre::GL3PlusTextureGpuWindow.

◆ isPoolOwner()

bool Ogre::TextureGpu::isPoolOwner ( ) const
inherited

◆ isReinterpretable()

bool Ogre::TextureGpu::isReinterpretable ( ) const
inherited

◆ isRenderToTexture()

bool Ogre::TextureGpu::isRenderToTexture ( ) const
inherited

◆ isRenderWindowSpecific()

bool Ogre::TextureGpu::isRenderWindowSpecific ( ) const
inherited

◆ isTexture()

bool Ogre::TextureGpu::isTexture ( ) const
inherited

◆ isTextureGpu()

bool Ogre::TextureGpu::isTextureGpu ( ) const
overridevirtualinherited

Reimplemented from Ogre::GpuTrackedResource.

◆ isUav()

bool Ogre::TextureGpu::isUav ( ) const
inherited

◆ notifyAllListenersTextureChanged()

void Ogre::TextureGpu::notifyAllListenersTextureChanged ( uint32  reason,
void *  extraData = 0 
)
inherited

◆ notifyDataIsReady()

void Ogre::MetalTextureGpu::notifyDataIsReady ( )
overridevirtualinherited

Notifies it is safe to use the real data. Everything has been uploaded.

Implements Ogre::TextureGpu.

Reimplemented in Ogre::MetalTextureGpuWindow.

◆ 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

◆ prefersLoadingFromFileAsSRGB()

bool Ogre::TextureGpu::prefersLoadingFromFileAsSRGB ( ) const
inherited

◆ removeListener()

void Ogre::TextureGpu::removeListener ( TextureGpuListener listener)
inherited

◆ requiresTextureFlipping()

bool Ogre::TextureGpu::requiresTextureFlipping ( ) const
inherited

◆ scheduleReupload()

void Ogre::TextureGpu::scheduleReupload ( Image2 image = 0,
bool  autoDeleteImage = true 
)
inherited

There are times where you want to reload a texture again (e.g.

file on disk changed, uploading a new Image2, etc) without visual disruption.

e.g. if you were to call:

tex->scheduleTransitionTo( GpuResidency::OnStorage );
tex->scheduleTransitionTo( GpuResidency::Resident, ... );
@ Resident
VRAM and other GPU resources have been allocated for this resource.
Definition: OgreGpuResource.h:65
@ OnStorage
Texture is on storage (i.e.
Definition: OgreGpuResource.h:48

you'll achieve the same result, however the texture becomes immediately unavailable causing a few frames were all the user sees is a blank texture until it is fully reloaded.

This routine allows for an in-place hot-reload, where the old texture is swapped for the new one once it's done loading.

This is also faster because DescriptorTextureSets don't change

Remarks
  1. Assumes the last queued transition to perform is into Resident or OnSystemRam
  2. Visual hitches are unavoidable if metadata changes (e.g. new texture is of different pixel format, different number of mipmaps, resolution, etc) If that's the case, it is faster to transition to OnStorage, remove the metadata entry from cache, then to Resident again
Parameters
imageSee TextureGpu::unsafeScheduleTransitionTo
autoDeleteImageSame TextureGpu::unsafeScheduleTransitionTo

◆ scheduleTransitionTo()

void Ogre::TextureGpu::scheduleTransitionTo ( GpuResidency::GpuResidency  nextResidency,
Image2 image = 0,
bool  autoDeleteImage = true 
)
inherited

Same as unsafeScheduleTransitionTo, but first checks if we're already in the residency state we want to go to, or if it has already been scheduled; thus it can be called multiple times.

◆ setNumMipmaps()

void Ogre::TextureGpu::setNumMipmaps ( uint8  numMipmaps)
inherited

◆ setOrientationMode()

void Ogre::MetalTextureGpuRenderTarget::setOrientationMode ( OrientationMode  orientationMode)
overridevirtual

Sets the given orientation.

'this' must be a RenderTexture If Ogre wasn't build with OGRE_CONFIG_ENABLE_VIEWPORT_ORIENTATIONMODE, calls to this function will not stick (i.e. getOrientationMode always returns the same value)

See also
TextureGpu::msDefaultOrientationMode
TextureGpu::getInternalWidth
TextureGpu::getInternalHeight
Remarks
Must be OnStorage.

If OrientationMode == OR_DEGREE_90 or OR_DEGREE_270, the internal resolution if flipped. i.e. swap( width, height ). This is important if you need to perform copyTo operations or AsyncTextureTickets

This setting has only been tested with Vulkan and is likely to malfunction with the other APIs if set to anything other than OR_DEGREE_0

Reimplemented from Ogre::TextureGpu.

◆ setPixelFormat()

void Ogre::TextureGpu::setPixelFormat ( PixelFormatGpu  pixelFormat)
inherited

Sets the pixel format.

Remarks
If prefersLoadingFromFileAsSRGB() returns true, the format may not be fully honoured (as we'll use the equivalent _SRGB variation).

◆ setResolution()

void Ogre::TextureGpu::setResolution ( uint32  width,
uint32  height,
uint32  depthOrSlices = 1u 
)
inherited

◆ setSampleDescription()

void Ogre::TextureGpu::setSampleDescription ( SampleDescription  desc)
inherited

◆ setTexturePoolId()

void Ogre::TextureGpu::setTexturePoolId ( uint32  poolId)
inherited

2D Texture with automatic batching will be merged with other textures into the same pool as one big 2D Array texture behind the scenes.

For two textures to be placed in the same pool (assuming it's not full) the following must match: Width, Height, PixelFormat, number of mipmaps, poolID

Pool ID is an arbitrary value with no actual meaning. This is ID allows you to prevent certain textures from being group together. For example, you may want all textures from Level 0 to be grouped together while Level 1 gets grouped together in a different pool

See also
TextureFlags::AutomaticBatching
TextureGpuManager::reservePoolId
Remarks
This value cannot be changed while the texture is resident (i.e. because it has already been assigned to a pool)
Parameters
poolIdArbitrary value. Default value is 0.

◆ setTextureType()

void Ogre::MetalTextureGpu::setTextureType ( TextureTypes::TextureTypes  textureType)
overridevirtualinherited

Reimplemented from Ogre::TextureGpu.

Reimplemented in Ogre::MetalTextureGpuWindow.

◆ supportsAsDepthBufferFor()

virtual bool Ogre::TextureGpu::supportsAsDepthBufferFor ( TextureGpu colourTarget) const
virtualinherited

◆ swapBuffers()

virtual void Ogre::TextureGpu::swapBuffers ( )
inlinevirtualinherited

◆ unsafeScheduleTransitionTo()

void Ogre::TextureGpu::unsafeScheduleTransitionTo ( GpuResidency::GpuResidency  nextResidency,
Image2 image = 0,
bool  autoDeleteImage = true 
)
inherited

Schedules an async transition in residency.

If transitioning from OnStorage to Resident, it will read from file (ResourceGroup was set in createTexture) If transitioning from OnSystemRam to Resident, it will read from the pointer it has. Multiple transitions can be stack together.

Remarks
If you're not loading from file (i.e. you're creating it programatically), call _transitionTo & _setNextResidencyStatus directly. Once you've called scheduleTransitionTo at least once, calling _transitionTo is very dangerous, as there are race conditions.
See also
TextureGpu::scheduleTransitionTo
Parameters
nextResidencyThe residency to change to.
imagePointer to image if you want to load the texture from memory instead of loading it from file or a listener. Pointer must be null if this is a manual texture. Pointer must NOT be a stack variable nor be deleted immediately. The actual loading is postponed until the request reaches the worker thread. That means the image pointer is safe to delete once you receive the TextureGpuListener::Reason::ReadyForRendering message.
autoDeleteImageWhether we should call "delete image" once we're done using the image. Otherwise you must listen for TextureGpuListener::ReadyForRendering message to know when we're done using the image.

◆ waitForData()

void Ogre::TextureGpu::waitForData ( )
inherited

Blocks main thread until data is ready.

Afterwards isDataReady should return true. If it doesn't, then there was a problem loading the texture. See isMetadataReady remarks.

Q: What's the penalty for calling this function?

A: We need to wait for the worker thread to finish all previous textures until it processes this one. The manager only has broad resolution so it may be also possible that we even have to wait the worker thread to process a few textures that came after this one too.

Thus the cost can be anywhere from "very little" to "a lot" depending on the order in which other textures have been loaded.

The real cost is that you lose valuable ability to hide loading times. If you must call this function, you can mitigate the problem:

1. All textures you need to wait for, load them *first* together, then
   call TextureGpuManager::waitForStreamingCompletion (preferred) or
   this function. Then proceed to load the rest of the textures.
2. If you can't do the above, call this function as late as possible 

◆ waitForMetadata()

void Ogre::TextureGpu::waitForMetadata ( )
inherited

Blocks main thread until metadata is ready.

Afterwards isMetadataReady should return true. If it doesn't, then there was a problem loading the texture. See isMetadataReady remarks.

◆ writeContentsToFile()

void Ogre::TextureGpu::writeContentsToFile ( const String filename,
uint8  minMip,
uint8  maxMip,
bool  automaticResolve = true 
)
inherited

Writes the current contents of the render target to the named file.

Member Data Documentation

◆ msDefaultOrientationMode

OrientationMode Ogre::TextureGpu::msDefaultOrientationMode
staticinherited

PUBLIC VARIABLE.

This variable can be altered directly.

Changes are reflected immediately for new TextureGpus. Existing TextureGpus won't be affected

◆ msFinalTextureBuffer

const IdString Ogre::TextureGpu::msFinalTextureBuffer
staticinherited

◆ msMsaaTextureBuffer

const IdString Ogre::TextureGpu::msMsaaTextureBuffer
staticinherited

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