OGRE: Ogre::MetalTextureGpuManager Class Reference

| OGRE 2.2.4 Object-Oriented Graphics Rendering Engine

Public Types | Public Member Functions | List of all members
Ogre::MetalTextureGpuManager Class Reference
Core » Resources

`#include <OgreMetalTextureGpuManager.h>`

Inheritance diagram for Ogre::MetalTextureGpuManager:
[legend]

## Public Types
typedef vector< BudgetEntry >::type | BudgetEntryVec
typedef map< IdString, MetadataCacheEntry >::type | MetadataCacheMap
enum | Reason { Unknown, FromStorageToSysRam, FromSysRamToStorage, GainedResidency, LostResidency, PoolTextureSlotChanged, ResidentToSysRamSync, MetadataCacheOutOfDate, ExceptionThrown, FsaaSettingAlteredByApi, ReadyForRendering, Deleted }
typedef map< IdString, ResourceEntry >::type | ResourceEntryMap

## Public Member Functions
| MetalTextureGpuManager (VaoManager *vaoManager, RenderSystem *renderSystem, MetalDevice *device)
virtual | ~MetalTextureGpuManager ()
void | _queueDownloadToRam (TextureGpu *texture, bool resyncOnly)
void | _releaseSlotFromTexture (TextureGpu *texture)
| Must be called from main thread. More...
void | _removeMetadataCacheEntry (TextureGpu *texture)
void | _reserveSlotForTexture (TextureGpu *texture)
| Must be called from main thread. More...
void | _scheduleTransitionTo (TextureGpu *texture, GpuResidency::GpuResidency targetResidency, Image2 *image, bool autoDeleteImage)
void | _setIgnoreScheduledTasks (bool ignoreSchedTasks)
| When true we will ignore all tasks in mScheduledTasks and execute transitions immediately Caller is responsible for ensuring this is safe to do. More...
bool | _update (bool syncWithWorkerThread)
| Returns true if there is no more streaming work to be done yet (if false, calls to _update could be needed once again) See waitForStreamingCompletion. More...
void | _updateMetadataCache (TextureGpu *texture)
void | _updateStreaming (void)
unsigned long | _updateStreamingWorkerThread (ThreadHandle *threadHandle)
void | _waitFor (TextureGpu *texture, bool metadataOnly)
| Do not use directly. See TextureGpu::waitForMetadata & TextureGpu::waitForDataReady. More...
void | _waitForPendingGpuToCpuSyncs (TextureGpu *texture)
| Do not use directly. See TextureGpu::waitForPendingSyncs. More...
AsyncTextureTicket * | createAsyncTextureTicket (uint32 width, uint32 height, uint32 depthOrSlices, TextureTypes::TextureTypes textureType, PixelFormatGpu pixelFormatFamily)
| Creates an AsyncTextureTicket that can be used to download data GPU -> CPU from a TextureGpu. More...
TextureGpu * | createOrRetrieveTexture (const String &name, const String &aliasName, GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, CommonTextureTypes::CommonTextureTypes type, const String &resourceGroup=BLANKSTRING, uint32 poolId=0)
| Helper function to call createOrRetrieveTexture with common parameters used for 2D diffuse textures loaded from file. More...
TextureGpu * | createOrRetrieveTexture (const String &name, const String &aliasName, GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, uint32 textureFlags, TextureTypes::TextureTypes initialType, const String &resourceGroup=BLANKSTRING, uint32 filters=0, uint32 poolId=0)
TextureGpu * | createOrRetrieveTexture (const String &name, GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, CommonTextureTypes::CommonTextureTypes type, const String &resourceGroup=BLANKSTRING, uint32 poolId=0)
TextureGpu * | createOrRetrieveTexture (const String &name, GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, uint32 textureFlags, TextureTypes::TextureTypes initialType, const String &resourceGroup=BLANKSTRING, uint32 filters=0, uint32 poolId=0)
TextureGpu * | createTexture (const String &name, const String &aliasName, GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, uint32 textureFlags, TextureTypes::TextureTypes initialType, const String &resourceGroup=BLANKSTRING, uint32 filters=0, uint32 poolId=0)
TextureGpu * | createTexture (const String &name, GpuPageOutStrategy::GpuPageOutStrategy pageOutStrategy, uint32 textureFlags, TextureTypes::TextureTypes initialType, const String &resourceGroup=BLANKSTRING, uint32 filters=0, uint32 poolId=0)
TextureGpu * | createTextureGpuWindow (MetalWindow *window)
| Creates a special MetalTextureGpuWindow pointer, to be used by Ogre::Window. More...
TextureGpu * | createWindowDepthBuffer (void)
void | destroyAllAsyncTextureTicket (void)
void | destroyAsyncTextureTicket (AsyncTextureTicket *ticket)
void | destroyTexture (TextureGpu *texture)
| Destroys a texture. More...
void | dumpMemoryUsage (Log *log) const
void | dumpStats (void) const
bool | executeTask (TextureGpu *texture, TextureGpuListener::Reason reason, const ScheduledTasks &task)
void | exportTextureMetadataCache (String &outJson)
const String * | findAliasNameStr (IdString idName) const
| This function CAN be called from any thread. More...
const String * | findResourceGroupStr (IdString idName) const
| This function CAN be called from any thread. More...
const String * | findResourceNameStr (IdString idName) const
| This function CAN be called from any thread. More...
TextureGpu * | findTextureNoThrow (IdString name) const
id< MTLTexture > | getBlankTextureMetalName (TextureTypes::TextureTypes textureType) const
const BudgetEntryVec & | getBudget (void) const
DefaultMipmapGen::DefaultMipmapGen | getDefaultMipmapGeneration (void) const
DefaultMipmapGen::DefaultMipmapGen | getDefaultMipmapGenerationCubemaps (void) const
MetalDevice * | getDevice (void) const
const ResourceEntryMap & | getEntries (void) const
void | getMemoryStats (size_t &outTextureBytesCpu, size_t &outTextureBytesGpu, size_t &outUsedStagingTextureBytes, size_t &outAvailableStagingTextureBytes)
RenderSystem * | getRenderSystem (void) const
StagingTexture * | getStagingTexture (uint32 width, uint32 height, uint32 depth, uint32 slices, PixelFormatGpu pixelFormat, size_t minConsumptionRatioThreshold=25u)
| Creates a StagingTexture which is required to upload data CPU -> GPU into a TextureGpu. More...
VaoManager * | getVaoManager (void) const
bool | hasPoolId (uint32 poolId, uint32 width, uint32 height, uint8 numMipmaps, PixelFormatGpu pixelFormat) const
bool | hasTextureResource (const String &aliasName, const String &resourceGroup) const
| Returns true if a texture with the given aliasName exists, or if a ResourceGroupListener provides such texture, or if such texture exists (i.e. More...
void | importTextureMetadataCache (const String &filename, const char *jsonString, bool bCreateReservedPools)
virtual void | notifyTextureChanged (TextureGpu *texture, TextureGpuListener::Reason reason, void *extraData)
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 | removeStagingTexture (StagingTexture *stagingTexture)
TextureGpu * | reservePoolId (uint32 poolId, uint32 width, uint32 height, uint32 numSlices, uint8 numMipmaps, PixelFormatGpu pixelFormat)
| Reserves and preallocates a pool with the given parameters Returns the master texture that owns the pool. More...
void | saveTexture (TextureGpu *texture, const String &folderPath, set< String >::type &savedTextures, bool saveOitd, bool saveOriginal, HlmsTextureExportListener *listener)
void | setDefaultMipmapGeneration (DefaultMipmapGen::DefaultMipmapGen defaultMipmapGen, DefaultMipmapGen::DefaultMipmapGen defaultMipmapGenCubemaps)
| Whether to use HW or SW mipmap generation when specifying TextureFilter::TypeGenerateDefaultMipmaps for loading files from textures. More...
void | setStagingTextureMaxBudgetBytes (size_t stagingTextureMaxBudgetBytes)
| At a high level, texture loading works like this: More...
void | setTextureGpuManagerListener (TextureGpuManagerListener *listener)
| Sets a new listener. More...
void | setTrylockMutexFailureLimit (uint32 tryLockFailureLimit)
| The main thread tries to acquire a lock from the background thread, do something very quick, and release it. More...
void | setWorkerThreadMaxPerStagingTextureRequestBytes (size_t maxPerStagingTextureRequestBytes)
| The worker thread tracks how many data it is loading so the Main thread can request additional StagingTextures if necessary. More...
void | setWorkerThreadMaxPreloadBytes (size_t maxPreloadBytes)
| The worker thread first loads the texture from disk to RAM (aka "preload", and then copies from RAM to StagingTexture. More...
void | setWorkerThreadMinimumBudget (const BudgetEntryVec &budget, size_t maxSplitResolution=0)
| Background streaming works by having a bunch of preallocated StagingTextures so we're ready to start uploading as soon as we see a request to load a texture from file. More...
virtual bool | shouldStayLoaded (TextureGpu *texture)
| Return true if this TextureGpu should likely stay loaded or else graphical changes could occur. More...
void | taskLoadToSysRamOrResident (TextureGpu *texture, const ScheduledTasks &task)
| Implements TaskTypeResidencyTransition when doing any of the following transitions: OnStorage -> Resident OnStorage -> OnSystemRam OnSystemRam -> Resident. More...
void | taskToUnloadOrDestroy (TextureGpu *texture, const ScheduledTasks &task)
| Implements TaskTypeResidencyTransition when doing any of the following transitions: Resident -> OnStorage Resident -> OnSystemRam OnSystemRam -> OnStorage. More...
void | waitForStreamingCompletion (void)
| Blocks main thread until are pending textures are fully loaded. More...

## Member Typedef Documentation

## ◆ BudgetEntryVec

typedef vector<BudgetEntry>::type Ogre::TextureGpuManager::BudgetEntryVec
| inherited

## ◆ MetadataCacheMap

typedef map<IdString, MetadataCacheEntry>::type Ogre::TextureGpuManager::MetadataCacheMap
| inherited

## ◆ ResourceEntryMap

typedef map<IdString, ResourceEntry>::type Ogre::TextureGpuManager::ResourceEntryMap
| inherited

## Member Enumeration Documentation

## ◆ Reason

enum Ogre::TextureGpuListener::Reason
| inherited

Enumerator
Unknown |
FromStorageToSysRam | OnStorage -> OnSystemRam.
FromSysRamToStorage | OnSystemRam -> OnStorage.
GainedResidency | OnStorage -> Resident OnSystemRam -> Resident See ReadyForRendering.
LostResidency | Resident -> OnStorage Resident -> OnSystemRam.
PoolTextureSlotChanged |
ResidentToSysRamSync | Only called while TextureGpu is still Resident, and strategy is AlwaysKeepSystemRamCopy. This listener happens when something was done to the TextureGpu that modifies its contents in the GPU, and were thus forced to sync those values back to SystemRam. This listener calls tells that sync is over.
MetadataCacheOutOfDate | The Metadata cache was out of date and we had to do a ping-pong. Expect this to be followed by at least LostResidency and GainedResidency calls This is very important, because if you were expecting certain sequence of calls (e.g. you were expecting a LostResidency soon to arrive), expect that to be changed. See TextureGpuManager for details about the metadata cache.
ExceptionThrown | Called when the worker thread caught an exception. This exception has already been logged, and the texture resumed loading normally with a white 2x2 RGBA8 fallback. This listener will get called from the main thread. The texture may still have pending residency transitions (e.g. it may still be loading the 2x2 fallback) Cast Exception e = reinterpret_cast<Exception>( extraData ); to know more info
FsaaSettingAlteredByApi | Requested FSAA (MSAA / CSAA / EQAA / etc) is not supported by the API, and thus the setting had to be downgraded. Note this may happen on device lost, and a new GPU became in use; thus it's possible for a TextureGpu to initially support certain FSAA but later change.
ReadyForRendering | This Reason is called when TextureGpu::notifyDataIsReady is called. This normally means worker thread is done loading texture from file and uploading it to GPU; and can now be used for rendering. It does NOT mean that Ogre has finished issueing rendering commands to a RenderTexture and is now ready to be presented to the monitor.
Deleted |

## Constructor & Destructor Documentation

## ◆ MetalTextureGpuManager()

Ogre::MetalTextureGpuManager::MetalTextureGpuManager | ( | VaoManager * | vaoManager,
|  | RenderSystem * | renderSystem,
|  | MetalDevice * | device
| ) |  |

## ◆ ~MetalTextureGpuManager()

virtual Ogre::MetalTextureGpuManager::~MetalTextureGpuManager | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ _queueDownloadToRam()

void Ogre::TextureGpuManager::_queueDownloadToRam | ( | TextureGpu * | texture,
|  | bool | resyncOnly
| ) |  |
| inherited

## ◆ _releaseSlotFromTexture()

void Ogre::TextureGpuManager::_releaseSlotFromTexture | ( | TextureGpu * | texture | ) |
| inherited

Must be called from main thread.

## ◆ _removeMetadataCacheEntry()

void Ogre::TextureGpuManager::_removeMetadataCacheEntry | ( | TextureGpu * | texture | ) |
| inherited

## ◆ _reserveSlotForTexture()

void Ogre::TextureGpuManager::_reserveSlotForTexture | ( | TextureGpu * | texture | ) |
| inherited

Must be called from main thread.

## ◆ _scheduleTransitionTo()

void Ogre::TextureGpuManager::_scheduleTransitionTo | ( | TextureGpu * | texture,
|  | GpuResidency::GpuResidency | targetResidency,
|  | Image2 * | image,
|  | bool | autoDeleteImage
| ) |  |
| inherited

## ◆ _setIgnoreScheduledTasks()

void Ogre::TextureGpuManager::_setIgnoreScheduledTasks | ( | bool | ignoreSchedTasks | ) |
| inherited

When true we will ignore all tasks in mScheduledTasks and execute transitions immediately Caller is responsible for ensuring this is safe to do.

The main reason for this function is that when the metadata cache is proven to be out of date and comes back to the main thread, we need to perform a Resident -> OnStorage -> Resident transition that bypasses pending operations, and pretend the texture has been in Resident all along.

## ◆ _update()

bool Ogre::TextureGpuManager::_update | ( | bool | syncWithWorkerThread | ) |
| inherited

Returns true if there is no more streaming work to be done yet (if false, calls to _update could be needed once again) See waitForStreamingCompletion.

Parameters

  syncWithWorkerThread | When true, we will wait for the worker thread to release the main mutex instead of just continuing and trying again next time we get called. This is important for waitForStreamingCompletion & _waitFor because otherwise main thread may not see worker thread has finished because it's also grabbing the main mutex; and waitForStreamingCompletion will go to sleep thinking worker thread has yet to finish, and worker thread won't wake up the main thread because it has already notified it.

## ◆ _updateMetadataCache()

void Ogre::TextureGpuManager::_updateMetadataCache | ( | TextureGpu * | texture | ) |
| inherited

## ◆ _updateStreaming()

void Ogre::TextureGpuManager::_updateStreaming | ( | void |  | ) |
| inherited

## ◆ _updateStreamingWorkerThread()

unsigned long Ogre::TextureGpuManager::_updateStreamingWorkerThread | ( | ThreadHandle * | threadHandle | ) |
| inherited

## ◆ _waitFor()

void Ogre::TextureGpuManager::_waitFor | ( | TextureGpu * | texture,
|  | bool | metadataOnly
| ) |  |
| inherited

Do not use directly. See TextureGpu::waitForMetadata & TextureGpu::waitForDataReady.

## ◆ _waitForPendingGpuToCpuSyncs()

void Ogre::TextureGpuManager::_waitForPendingGpuToCpuSyncs | ( | TextureGpu * | texture | ) |
| inherited

Do not use directly. See TextureGpu::waitForPendingSyncs.

## ◆ createAsyncTextureTicket()

AsyncTextureTicket* Ogre::TextureGpuManager::createAsyncTextureTicket | ( | uint32 | width,
|  | uint32 | height,
|  | uint32 | depthOrSlices,
|  | TextureTypes::TextureTypes | textureType,
|  | PixelFormatGpu | pixelFormatFamily
| ) |  |
| inherited

Creates an AsyncTextureTicket that can be used to download data GPU -> CPU from a TextureGpu.

To upload data CPU -> GPU see getStagingTexture

Parameters

  width |
  height |
  depthOrSlices |
  pixelFormatFamily | If the value is not a family value, it will automatically be converted to one.

Returns

## ◆ createOrRetrieveTexture() [1/4]

TextureGpu* Ogre::TextureGpuManager::createOrRetrieveTexture | ( | const String & | name,
|  | const String & | aliasName,
|  | GpuPageOutStrategy::GpuPageOutStrategy | pageOutStrategy,
|  | CommonTextureTypes::CommonTextureTypes | type,
|  | const String & | resourceGroup = `BLANKSTRING`,
|  | uint32 | poolId = `0`
| ) |  |
| inherited

Helper function to call createOrRetrieveTexture with common parameters used for 2D diffuse textures loaded from file.

## ◆ createOrRetrieveTexture() [2/4]

TextureGpu* Ogre::TextureGpuManager::createOrRetrieveTexture | ( | const String & | name,
|  | const String & | aliasName,
|  | GpuPageOutStrategy::GpuPageOutStrategy | pageOutStrategy,
|  | uint32 | textureFlags,
|  | TextureTypes::TextureTypes | initialType,
|  | const String & | resourceGroup = `BLANKSTRING`,
|  | uint32 | filters = `0`,
|  | uint32 | poolId = `0`
| ) |  |
| inherited

## ◆ createOrRetrieveTexture() [3/4]

TextureGpu* Ogre::TextureGpuManager::createOrRetrieveTexture | ( | const String & | name,
|  | GpuPageOutStrategy::GpuPageOutStrategy | pageOutStrategy,
|  | CommonTextureTypes::CommonTextureTypes | type,
|  | const String & | resourceGroup = `BLANKSTRING`,
|  | uint32 | poolId = `0`
| ) |  |
| inherited

## ◆ createOrRetrieveTexture() [4/4]

TextureGpu* Ogre::TextureGpuManager::createOrRetrieveTexture | ( | const String & | name,
|  | GpuPageOutStrategy::GpuPageOutStrategy | pageOutStrategy,
|  | uint32 | textureFlags,
|  | TextureTypes::TextureTypes | initialType,
|  | const String & | resourceGroup = `BLANKSTRING`,
|  | uint32 | filters = `0`,
|  | uint32 | poolId = `0`
| ) |  |
| inherited

## ◆ createTexture() [1/2]

TextureGpu* Ogre::TextureGpuManager::createTexture | ( | const String & | name,
|  | const String & | aliasName,
|  | GpuPageOutStrategy::GpuPageOutStrategy | pageOutStrategy,
|  | uint32 | textureFlags,
|  | TextureTypes::TextureTypes | initialType,
|  | const String & | resourceGroup = `BLANKSTRING`,
|  | uint32 | filters = `0`,
|  | uint32 | poolId = `0`
| ) |  |
| inherited

Parameters

  name | Name of the resource. For example TreeWood.png
  aliasName | Usually aliasName = name. An alias name allows you to load the same texture (e.g. TreeWood.png) with different settings. For example: Alias 0 - "Tree Wood With Mipmaps" Alias 1 - "Tree Wood Without Mipmaps" Alias 2 - "Tree Wood Without TextureFlags::AutomaticBatching" This lets you have 3 copies of the same file in memory.
  pageOutStrategy |
  textureFlags | See TextureFlags::TextureFlags
  initialType | Strictly not required (i.e. can be left TextureTypes::Unknown) however it can be needed if set to a material before it is fully loaded; and the shader expects a particular type (e.g. it expects a cubemap). While it's not yet loaded, a dummy texture will that matches the type will be used; and it's important that the right dummy texture is selected. So if you know in advance a particular type is needed, this parameter tells Ogre what dummy to use.
  resourceGroup | Optional, but required if you want to load files from disk (or anything provided by the ResourceGroupManager)
  poolId | Optional. See TextureGpu::setTexturePoolId This parameter informs which pool ID you wish the texture to be assigned for. Note however, if you're using createOrRetrieveTexture and the texture has already been created (i.e. it's being retrieved) then the pool ID parameter will be ignored, as the texture was already created with a pool ID.

Returns

## ◆ createTexture() [2/2]

TextureGpu* Ogre::TextureGpuManager::createTexture | ( | const String & | name,
|  | GpuPageOutStrategy::GpuPageOutStrategy | pageOutStrategy,
|  | uint32 | textureFlags,
|  | TextureTypes::TextureTypes | initialType,
|  | const String & | resourceGroup = `BLANKSTRING`,
|  | uint32 | filters = `0`,
|  | uint32 | poolId = `0`
| ) |  |
| inherited

## ◆ createTextureGpuWindow()

TextureGpu* Ogre::MetalTextureGpuManager::createTextureGpuWindow | ( | MetalWindow * | window | ) |

Creates a special MetalTextureGpuWindow pointer, to be used by Ogre::Window.

The pointer can be freed by a regular OGRE_DELETE. We do not track this pointer. If caller doesnt' delete it, it will leak.

## ◆ createWindowDepthBuffer()

TextureGpu* Ogre::MetalTextureGpuManager::createWindowDepthBuffer | ( | void |  | ) |

## ◆ destroyAllAsyncTextureTicket()

void Ogre::TextureGpuManager::destroyAllAsyncTextureTicket | ( | void |  | ) |
| inherited

## ◆ destroyAsyncTextureTicket()

void Ogre::TextureGpuManager::destroyAsyncTextureTicket | ( | AsyncTextureTicket * | ticket | ) |
| inherited

## ◆ destroyTexture()

void Ogre::TextureGpuManager::destroyTexture | ( | TextureGpu * | texture | ) |
| inherited

Destroys a texture.

Classes who wish to hold a weak reference should listen for TextureGpuListener::Deleted events and clear their pointers when the texture gets destroyed.

Classes who wish to hold a stronger reference (note: it says 'stronger', not 'strong') should return true in TextureGpuListener::shouldStayLoaded, but it is not guaranteed to be honoured.

Users should iterate through listeners and see if any listener's shouldStayLoaded returns true. If you still want to destroy the texture, the class should still be able to handle TextureGpuListener::Deleted gracefully.

See MemoryGameState::unloadUnusedTextures in Tutorial_MemoryGameState.cpp

Ogre doesn't call destroyTexture unless it's on shutdown or a specific Ogre-controlled texture (e.g. something related to PBS, Irradiance Fields, etc)

Users are the ones in control of which textures get unloaded. It is suggested users group textures by criteria so that they can be loaded and unloaded in bulk (i.e. by relation to a level, or area in an open world game, by scene, etc)

Parameters

  texture |

## ◆ dumpMemoryUsage()

void Ogre::TextureGpuManager::dumpMemoryUsage | ( | Log * | log | ) | const
| inherited

## ◆ dumpStats()

void Ogre::TextureGpuManager::dumpStats | ( | void |  | ) | const
| inherited

## ◆ executeTask()

bool Ogre::TextureGpuManager::executeTask | ( | TextureGpu * | texture,
|  | TextureGpuListener::Reason | reason,
|  | const ScheduledTasks & | task
| ) |  |
| inherited

## ◆ exportTextureMetadataCache()

void Ogre::TextureGpuManager::exportTextureMetadataCache | ( | String & | outJson | ) |
| inherited

## ◆ findAliasNameStr()

const String* Ogre::TextureGpuManager::findAliasNameStr | ( | IdString | idName | ) | const
| inherited

This function CAN be called from any thread.

## ◆ findResourceGroupStr()

const String* Ogre::TextureGpuManager::findResourceGroupStr | ( | IdString | idName | ) | const
| inherited

This function CAN be called from any thread.

## ◆ findResourceNameStr()

const String* Ogre::TextureGpuManager::findResourceNameStr | ( | IdString | idName | ) | const
| inherited

This function CAN be called from any thread.

## ◆ findTextureNoThrow()

TextureGpu* Ogre::TextureGpuManager::findTextureNoThrow | ( | IdString | name | ) | const
| inherited

## ◆ getBlankTextureMetalName()

id<MTLTexture> Ogre::MetalTextureGpuManager::getBlankTextureMetalName | ( | TextureTypes::TextureTypes | textureType | ) | const

## ◆ getBudget()

const BudgetEntryVec& Ogre::TextureGpuManager::getBudget | ( | void |  | ) | const
| inherited

## ◆ getDefaultMipmapGeneration()

DefaultMipmapGen::DefaultMipmapGen Ogre::TextureGpuManager::getDefaultMipmapGeneration | ( | void |  | ) | const
| inherited

## ◆ getDefaultMipmapGenerationCubemaps()

DefaultMipmapGen::DefaultMipmapGen Ogre::TextureGpuManager::getDefaultMipmapGenerationCubemaps | ( | void |  | ) | const
| inherited

## ◆ getDevice()

MetalDevice* Ogre::MetalTextureGpuManager::getDevice | ( | void |  | ) | const
| inline

## ◆ getEntries()

const ResourceEntryMap& Ogre::TextureGpuManager::getEntries | ( | void |  | ) | const
| inlineinherited

## ◆ getMemoryStats()

void Ogre::TextureGpuManager::getMemoryStats | ( | size_t & | outTextureBytesCpu,
|  | size_t & | outTextureBytesGpu,
|  | size_t & | outUsedStagingTextureBytes,
|  | size_t & | outAvailableStagingTextureBytes
| ) |  |
| inherited

## ◆ getRenderSystem()

RenderSystem* Ogre::TextureGpuManager::getRenderSystem | ( | void |  | ) | const
| inherited

## ◆ getStagingTexture()

StagingTexture* Ogre::TextureGpuManager::getStagingTexture | ( | uint32 | width,
|  | uint32 | height,
|  | uint32 | depth,
|  | uint32 | slices,
|  | PixelFormatGpu | pixelFormat,
|  | size_t | minConsumptionRatioThreshold = `25u`
| ) |  |
| inherited

Creates a StagingTexture which is required to upload data CPU -> GPU into a TextureGpu.

To download data GPU -> CPU see readRequest

Remarks
  We try to find the smallest available texture (won't stall) that can fit the request.

Parameters

  minConsumptionRatioThreshold | Value in range [0; 100]. The smallest available texture we find may still be too big (e.g. you need to upload 64x64 texture RGBA8 and we return a 8192x8192x4 staging texture which is overkill). For these cases, here you can specify how much "is too big". For example by specifying a consumptionRatio of 50; it means that the data you asked for must occupy at least 50% of the space; otherwise we'll create a new StagingTexture.

A value of 100 means the StagingTexture must fit exactly (fully used). A value of 0 means any StagingTexture will do, no matter how large.

StagingTextures that haven't been using in a while will be destroyed. However if for some reason we end up returning a huge texture every frame for small workloads, we'll be keeping that waste potentially forever.

Returns
  StagingTexture that meets the criteria. When you're done, remove it by calling removeStagingTexture.

## ◆ getVaoManager()

VaoManager* Ogre::TextureGpuManager::getVaoManager | ( | void |  | ) | const
| inherited

## ◆ hasPoolId()

bool Ogre::TextureGpuManager::hasPoolId | ( | uint32 | poolId,
|  | uint32 | width,
|  | uint32 | height,
|  | uint8 | numMipmaps,
|  | PixelFormatGpu | pixelFormat
| ) |  | const
| inherited

## ◆ hasTextureResource()

bool Ogre::TextureGpuManager::hasTextureResource | ( | const String & | aliasName,
|  | const String & | resourceGroup
| ) |  | const
| inherited

Returns true if a texture with the given aliasName exists, or if a ResourceGroupListener provides such texture, or if such texture exists (i.e.

as a file) in the ResourceGroupManager.

This can return true regardless of whether the texture has been loaded or created.

Not to be confused with findTextureNoThrow which only looks for already created textures.

Parameters

  aliasName |
  resourceGroup |

Returns
  True if there is such texture (loaded or not) False if there is no such texture

## ◆ importTextureMetadataCache()

void Ogre::TextureGpuManager::importTextureMetadataCache | ( | const String & | filename,
|  | const char * | jsonString,
|  | bool | bCreateReservedPools
| ) |  |
| inherited

## ◆ notifyTextureChanged()

virtual void Ogre::TextureGpuManager::notifyTextureChanged | ( | TextureGpu * | texture,
|  | TextureGpuListener::Reason | reason,
|  | void * | extraData
| ) |  |
| virtualinherited

See also
  TextureGpuListener::notifyTextureChanged

Implements Ogre::TextureGpuListener.

## ◆ 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

## ◆ removeStagingTexture()

void Ogre::TextureGpuManager::removeStagingTexture | ( | StagingTexture * | stagingTexture | ) |
| inherited

## ◆ reservePoolId()

TextureGpu* Ogre::TextureGpuManager::reservePoolId | ( | uint32 | poolId,
|  | uint32 | width,
|  | uint32 | height,
|  | uint32 | numSlices,
|  | uint8 | numMipmaps,
|  | PixelFormatGpu | pixelFormat
| ) |  |
| inherited

Reserves and preallocates a pool with the given parameters Returns the master texture that owns the pool.

Destroy this pool with TextureGpuManager::destroyTexture

## ◆ saveTexture()

void Ogre::TextureGpuManager::saveTexture | ( | TextureGpu * | texture,
|  | const String & | folderPath,
|  | set< String >::type & | savedTextures,
|  | bool | saveOitd,
|  | bool | saveOriginal,
|  | HlmsTextureExportListener * | listener
| ) |  |
| inherited

## ◆ setDefaultMipmapGeneration()

void Ogre::TextureGpuManager::setDefaultMipmapGeneration | ( | DefaultMipmapGen::DefaultMipmapGen | defaultMipmapGen,
|  | DefaultMipmapGen::DefaultMipmapGen | defaultMipmapGenCubemaps
| ) |  |
| inherited

Whether to use HW or SW mipmap generation when specifying TextureFilter::TypeGenerateDefaultMipmaps for loading files from textures.

This setting has no effect for filters explicitly asking for HW mipmap generation.

Parameters

  hwMipmapGen | Whether to enable HW mipmap generation for textures. Default is true.
  hwMipmapGenCubemaps | Whether to enable HW mipmap generation for cubemap textures. Default is false.

## ◆ setStagingTextureMaxBudgetBytes()

void Ogre::TextureGpuManager::setStagingTextureMaxBudgetBytes | ( | size_t | stagingTextureMaxBudgetBytes | ) |
| inherited

At a high level, texture loading works like this:

1. Grab a free StagingTexture from "available" pool in main thread
2. Load image from file in secondary thread and fill the StagingTexture
3. Copy from StagingTexture to final TextureGpu in main thread
4. Release the StagingTexture so it goes back to "available" pool.
5. Repeat from step 1 for next batch of images to load.
     All is well except for one little detail in steps 1 and 4: The StagingTexture released at step 4 can't become immediately available as the GPU could still be performing the copy from step 3, so we must wait a few frames until it's safe to map it again.
     That means at step 1, there may be StagingTextures in the "available" pool, yet however none of them are actually ready to grab; so we create a new one instead.
     In other words, if the CPU produces textures faster than the GPU can consume them, we may keep creating more and more StagingTextures until we run out of memory.
     That's where this function comes in. This function limits how much we let the "available" pool grow. If the threshold is exceeded, instead of creating a new StagingTexture at step 1; we'll begin to stall and wait for the GPU to catch up; so we can reuse these StagingTextures again. If no StagingTexture is capable of performing the upload (e.g. they're of incompatible format) we'll start deleting StagingTextures to make room for the one we need. The details are explained in checkStagingTextureLimits.
     This limit is tightly respected by Ogre but not a hard one. For example if you set the limit on 256MB and we require a StagingTexture of 326MB to load a very, very big texture, then Ogre has no other choice but to delete all textures in mAvailableStagingTextures and create one of 326MB that can perform the operation; but Ogre won't error out because 326 > 256MB. (though in such scenario the process may run out of memory and crash)
   Remarks
     This limit only counts for textures that are in zero-referenced in mAvailableStagingTextures. For example if you've set the limit in 256MB and you've created 1GB worth of StagingTextures (i.e. via getStagingTexture) and never released them via removeStagingTexture; those textures don't count. We only check the limit against the released textures in mAvailableStagingTextures.
   Parameters

     stagingTextureMaxBudgetBytes | Limit in bytes, on how much memory we let in mAvailableStagingTextures before we start stalling the GPU and/or aggressively destroying them.

## ◆ setTextureGpuManagerListener()

void Ogre::TextureGpuManager::setTextureGpuManagerListener | ( | TextureGpuManagerListener * | listener | ) |
| inherited

Sets a new listener.

The old one will be destroyed with OGRE_DELETE See TextureGpuManagerListener. Pointer cannot be null.

## ◆ setTrylockMutexFailureLimit()

void Ogre::TextureGpuManager::setTrylockMutexFailureLimit | ( | uint32 | tryLockFailureLimit | ) |
| inherited

The main thread tries to acquire a lock from the background thread, do something very quick, and release it.

If the lock failed to acquire, we try again next time _update is called. However if this happens too often in a row, we should stall and wait indefinitely for the background thread.

This function allows you to specify how many failures we have to let pass before we stall.

Remarks
  This is a failsafe mechanism for edge case behaviors that should never happen. It is rare for the tryLock() to fail more than twice in a row.

However if loading a several big files (e.g. large cubemaps) or loading from a slow medium (e.g. from the internet directly) many tryLock() failures could be common.

If failure to acquire the lock is common and expected, small limit values could cause a lot of stutter, because e.g. a value of 3 could cause fps lag spikes every 3 frames.

A sensible value such as 1200 means that a stall would only happen after 20 seconds of repeated failure if running at constant 60 fps.

Parameters

  tryLockFailureLimit | How many failures we have to wait for a stall, expressed in calls TextureGpuManager::_update. Usually there's one call to _update per frame, but there can be more. Use 0 to always stall Use std::numeric_limits<uint32>::max() for no failure limits (i.e. never stall)

## ◆ setWorkerThreadMaxPerStagingTextureRequestBytes()

void Ogre::TextureGpuManager::setWorkerThreadMaxPerStagingTextureRequestBytes | ( | size_t | maxPerStagingTextureRequestBytes | ) |
| inherited

The worker thread tracks how many data it is loading so the Main thread can request additional StagingTextures if necessary.

One big StagingTexture reduces the amount of time we map memory so we can upload.

However one big StagingTexture also means that if we've used 1 byte out of 200MB available, we have to wait until that byte has finished transferring (that usually means the StagingTexture becomes available 3 frames later); which can result in three big StagingTextures (one for each frame) which can be overkill.

This function allows you to specify when we decide to break these requests in smaller pieces, which by default is set at 64MB

Parameters

  maxPerStagingTextureRequestBytes |

## ◆ setWorkerThreadMaxPreloadBytes()

void Ogre::TextureGpuManager::setWorkerThreadMaxPreloadBytes | ( | size_t | maxPreloadBytes | ) |
| inherited

The worker thread first loads the texture from disk to RAM (aka "preload", and then copies from RAM to StagingTexture.

Later the main thread will copy from StagingTexture to actual texture.

  This value controls how many bytes are preloaded (i.e. from disk to RAM) by the worker thread until the next _update call from the main thread is issued.

  Higher values allows worker thread to keep loading textures while your main thread loads the rest of the scene. Lower values prevent Out of Memory conditions.

Remarks
  Due to how the code works, this value will also affect how much StagingTexture we ask to the main thread (because preloading becomes a bottleneck).

  Testing shows that very high values (i.e. >256MB) have the potential of uncovering driver bugs (even in 64-bit builds) and thus are not recommended.

  The value is an approximation and not a hard limit. e.g. if loading a 128MB cubemap and the limit is 1 byte; then we'll preload 128MBs. But we won't be loading anything else. Also due to how the code works, there is some broad granularity issues that can cause us to consume a bit more.

Parameters

  maxPreloadBytes |

## ◆ setWorkerThreadMinimumBudget()

void Ogre::TextureGpuManager::setWorkerThreadMinimumBudget | ( | const BudgetEntryVec & | budget,
|  | size_t | maxSplitResolution = `0`
| ) |  |
| inherited

Background streaming works by having a bunch of preallocated StagingTextures so we're ready to start uploading as soon as we see a request to load a texture from file.

  If there is no minimum budget or it is too small for the texture you're trying to load, background threads can't start as soon as possible and has to wait until the next call to _update (or to waitForStreamingCompletion). This controls how much memory we reserve.

Remarks
  Be careful on reserving too much memory, or else Out of Memory situations could arise. The amount of memory you can reserved is limited by the GTT (Graphics Translation Table) and the limit may be much lower than the total System RAM. For example my 16GB RAM system with a 2GB GPU, the GTT limit on Linux is of 3GB (use radeontop to find this information). See https://en.wikipedia.org/wiki/Graphics_address_remapping_table

Parameters

  budget | Array of parameters for the staging textures we'll reserve. The budget can be empty.
  maxSplitResolution | Textures bigger than this resolution in any axis will be taken as "exceptions" or "spikes" that won't last long. e.g. if maxSplitResolution = 2048 then a 2048x16, 67x2048, 2048x2048, and a 4096x4096 texture will all be considered abnormal.

This can significantly affect how much memory we consume while streaming. A value of 0 means to keep current value.

If an entry in the budget contains minNumSlices > 1 and minResolution >= maxSplitResolution then a lot of memory waste could end up being caused; thus we will warn to the Ogre.log if you set such setting.

The default value in 32-bit systems and mobile is 2048 The default value in 64-bit Desktop systems is 4096

This setting is closely related to setWorkerThreadMaxPerStagingTextureRequestBytes, because a texture whose resolution is >= maxSplitResolution will force us to use multiple StagingTextures, thus relieving the pressure on memory and memory fragmentation.

## ◆ shouldStayLoaded()

virtual bool Ogre::TextureGpuListener::shouldStayLoaded | ( | TextureGpu * | texture | ) |
| inlinevirtualinherited

Return true if this TextureGpu should likely stay loaded or else graphical changes could occur.

Return false if it is certainly safe to unload.

Reimplemented in Ogre::VctLighting, and Ogre::OGRE_HLMS_TEXTURE_BASE_CLASS.

## ◆ taskLoadToSysRamOrResident()

void Ogre::TextureGpuManager::taskLoadToSysRamOrResident | ( | TextureGpu * | texture,
|  | const ScheduledTasks & | task
| ) |  |
| inherited

Implements TaskTypeResidencyTransition when doing any of the following transitions: OnStorage -> Resident OnStorage -> OnSystemRam OnSystemRam -> Resident.

## ◆ taskToUnloadOrDestroy()

void Ogre::TextureGpuManager::taskToUnloadOrDestroy | ( | TextureGpu * | texture,
|  | const ScheduledTasks & | task
| ) |  |
| inherited

Implements TaskTypeResidencyTransition when doing any of the following transitions: Resident -> OnStorage Resident -> OnSystemRam OnSystemRam -> OnStorage.

Also implements TaskTypeDestroyTexture

## ◆ waitForStreamingCompletion()

void Ogre::TextureGpuManager::waitForStreamingCompletion | ( | void |  | ) |
| inherited

Blocks main thread until are pending textures are fully loaded.

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

- OgreMetalTextureGpuManager.h