gfxTextureManager.h

Public Defines

TEXMGR() ()->getTextureManager()

Public Defines

TEXMGR() ()->getTextureManager()

Returns the GFXTextureManager singleton.

Should only be called after the GFX device has been initialized.

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _GFXTEXTUREMANAGER_H_
 25#define _GFXTEXTUREMANAGER_H_
 26
 27#ifndef _GFXTEXTUREOBJECT_H_
 28#include "gfx/gfxTextureObject.h"
 29#endif 
 30#ifndef _GBITMAP_H_
 31#include "gfx/bitmap/gBitmap.h"
 32#endif 
 33#ifndef _DDSFILE_H_
 34#include "gfx/bitmap/ddsFile.h"
 35#endif
 36#ifndef _RESOURCEMANAGER_H_
 37#include "core/resourceManager.h"
 38#endif
 39#ifndef _TDICTIONARY_H_
 40#include "core/util/tDictionary.h"
 41#endif
 42#ifndef _TSIGNAL_H_
 43#include "core/util/tSignal.h"
 44#endif
 45
 46
 47namespace Torque
 48{
 49   class Path;
 50}
 51
 52class GFXCubemap;
 53
 54
 55class GFXTextureManager 
 56{   
 57public:
 58   enum
 59   {
 60      AA_MATCH_BACKBUFFER = -1
 61   };
 62
 63   GFXTextureManager();
 64   virtual ~GFXTextureManager();
 65
 66   /// Set up some global script interface stuff.
 67   static void init();
 68
 69   /// Provide the path to the texture to use when the requested one is missing
 70   static const String& getMissingTexturePath() { return smMissingTexturePath; }
 71
 72   /// Provide the path to the texture to use when the requested one is unavailable.
 73   static const String& getUnavailableTexturePath() { return smUnavailableTexturePath; }
 74
 75   /// Provide the path to the texture used to warn the developer
 76   static const String& getWarningTexturePath() { return smWarningTexturePath; }
 77
 78   /// Update width and height based on available resources.
 79   ///
 80   /// We provide a simple interface for managing texture memory usage. Specifically,
 81   /// if the total video memory is below a certain threshold, we scale all texture
 82   /// resolutions down by a specific factor (you can specify different scale factors
 83   /// for different types of textures).
 84   ///
 85   /// @note The base GFXTextureManager class provides all the logic to do this scaling. 
 86   ///       Subclasses need only implement getTotalVideoMemory().
 87   ///
 88   /// @param  type     Type of the requested texture. This is used to determine scaling factors.
 89   /// @param  width    Requested width - is changed to the actual width that should be used.
 90   /// @param  height   Requested height - is changed to the actual height that should be used.
 91   /// @return True if the texture request should be granted, false otherwise.
 92   virtual bool validateTextureQuality(GFXTextureProfile *profile, U32 &width, U32 &height);
 93
 94   ///
 95   static U32 getTextureDownscalePower( GFXTextureProfile *profile );
 96
 97   virtual GFXTextureObject *createTexture(  GBitmap *bmp,
 98      const String &resourceName,
 99      GFXTextureProfile *profile,
100      bool deleteBmp);
101
102   virtual GFXTextureObject *createTexture(  DDSFile *dds,
103      GFXTextureProfile *profile,
104      bool deleteDDS);
105
106   virtual GFXTextureObject *createTexture(  const Torque::Path &path,
107      GFXTextureProfile *profile );
108
109   virtual GFXTextureObject *createTexture(  U32 width,
110      U32 height,
111      void *pixels,
112      GFXFormat format,
113      GFXTextureProfile *profile);
114
115   virtual GFXTextureObject *createTexture(  U32 width,
116      U32 height,
117      U32 depth,
118      void *pixels,
119      GFXFormat format,
120      GFXTextureProfile *profile );
121
122   virtual GFXTextureObject *createTexture(  U32 width,
123      U32 height,
124      GFXFormat format,
125      GFXTextureProfile *profile,
126      U32 numMipLevels,
127      S32 antialiasLevel);
128
129   void deleteTexture( GFXTextureObject *texture );
130   void reloadTexture( GFXTextureObject *texture );
131
132   /// Request that the texture be deleted which will
133   /// either occur immediately or delayed if its cached.
134   void requestDeleteTexture( GFXTextureObject *texture );
135
136   /// @name Texture Necromancy
137   /// 
138   /// Texture necromancy in three easy steps:
139   /// - If you want to destroy the texture manager, call kill().
140   /// - If you want to switch resolutions, or otherwise reset the device, call zombify().
141   /// - When you want to bring the manager back from zombie state, call resurrect().
142   /// @{
143
144   ///
145   void kill();
146   void zombify();
147   void resurrect();
148
149   /// This releases any pooled textures which are 
150   /// currently unused freeing up video memory.
151   void cleanupPool();
152
153   ///
154   void reloadTextures();
155
156   /// This releases cached textures that have not
157   /// been referenced for a period of time.
158   void cleanupCache( U32 secondsToLive = 0 );
159
160   /// Registers a callback for texture zombify and resurrect events.
161   /// @see GFXTexCallbackCode
162   /// @see removeEventDelegate
163   template <class T,class U>
164   static void addEventDelegate( T obj, U func );
165
166   /// Unregisteres a texture event callback.
167   /// @see addEventDelegate
168   template <class T,class U>
169   static void removeEventDelegate( T obj, U func ) { smEventSignal.remove( obj, func ); }
170
171   /// @}
172
173   /// Load a cubemap from a texture file.
174   GFXCubemap* createCubemap( const Torque::Path &path );
175
176   /// Used to remove a cubemap from the cache.
177   void releaseCubemap( GFXCubemap *cubemap );
178
179protected:
180
181   /// The amount of texture mipmaps to skip when loading a
182   /// texture that allows downscaling.
183   ///
184   /// Exposed to script via $pref::Video::textureReductionLevel.
185   ///
186   /// @see GFXTextureProfile::PreserveSize
187   /// 
188   static S32 smTextureReductionLevel;
189
190   /// File path to the missing texture
191   static String smMissingTexturePath;
192
193   /// File path to the unavailable texture.  Often used by GUI controls
194   /// when the requested image is not available.
195   static String smUnavailableTexturePath;
196
197   /// File path to the warning texture
198   static String smWarningTexturePath;
199
200   GFXTextureObject *mListHead;
201   GFXTextureObject *mListTail;
202
203   // We have a hash table for fast texture lookups
204   GFXTextureObject **mHashTable;
205   U32                mHashCount;
206   GFXTextureObject *hashFind( const String &name );
207   void              hashInsert(GFXTextureObject *object);
208   void              hashRemove(GFXTextureObject *object);
209
210   // The cache of loaded cubemap textures.
211   typedef HashTable<String,GFXCubemap*> CubemapTable;
212   CubemapTable mCubemapTable;
213
214   /// The textures waiting to be deleted.
215   Vector<GFXTextureObject*> mToDelete;
216
217   enum TextureManagerState
218   {
219      Living,
220      Zombie,
221      Dead
222
223   } mTextureManagerState;
224
225   /// The texture pool collection type.
226   typedef HashTable<GFXTextureProfile*,StrongRefPtr<GFXTextureObject> > TexturePoolMap;
227
228   /// All the allocated texture pool textures.
229   TexturePoolMap mTexturePool;
230
231   //-----------------------------------------------------------------------
232   // Protected methods
233   //-----------------------------------------------------------------------
234
235   /// Returns a free texture of the requested attributes from
236   /// from the shared texture pool.  It returns NULL if no match
237   /// is found.
238   GFXTextureObject* _findPooledTexure(   U32 width, 
239                                          U32 height, 
240                                          GFXFormat format, 
241                                          GFXTextureProfile *profile,
242                                          U32 numMipLevels,
243                                          S32 antialiasLevel );
244
245   GFXTextureObject *_createTexture(   GBitmap *bmp,
246                                       const String &resourceName,
247                                       GFXTextureProfile *profile,
248                                       bool deleteBmp,
249                                       GFXTextureObject *inObj );
250
251   GFXTextureObject *_createTexture(   DDSFile *dds,
252                                       GFXTextureProfile *profile,
253                                       bool deleteDDS,
254                                       GFXTextureObject *inObj );
255
256   /// Frees the API handles to the texture, for D3D this is a release call
257   ///
258   /// @note freeTexture MUST NOT DELETE THE TEXTURE OBJECT
259   virtual void freeTexture( GFXTextureObject *texture, bool zombify = false );
260
261   virtual void refreshTexture( GFXTextureObject *texture );
262
263   /// @group Internal Texture Manager Interface
264   ///
265   /// These pure virtual functions are overloaded by each API-specific
266   /// subclass.
267   ///
268   /// The order of calls is:
269   /// @code
270   /// _createTexture()
271   /// _loadTexture
272   /// _refreshTexture()
273   /// _refreshTexture()
274   /// _refreshTexture()
275   /// ...
276   /// _freeTexture()
277   /// @endcode
278   ///
279   /// @{
280
281   /// Allocate a texture with the internal API.
282   ///
283   /// @param  height   Height of the texture.
284   /// @param  width    Width of the texture.
285   /// @param  depth    Depth of the texture. (Will normally be 1 unless
286   ///                  we are doing a cubemap or volumetexture.)
287   /// @param  format   Pixel format of the texture.
288   /// @param  profile  Profile for the texture.
289   /// @param  numMipLevels   If not-NULL, then use that many mips.
290   ///                        If NULL create the full mip chain
291   /// @param  antialiasLevel, Use GFXTextureManager::AA_MATCH_BACKBUFFER to match the backbuffer settings (for render targets that want to share
292   ///                         the backbuffer z buffer.  0 for no antialiasing, > 0 for levels that match the GFXVideoMode struct.
293   virtual GFXTextureObject *_createTextureObject( U32 height, 
294                                                   U32 width, 
295                                                   U32 depth, 
296                                                   GFXFormat format, 
297                                                   GFXTextureProfile *profile, 
298                                                   U32 numMipLevels, 
299                                                   bool forceMips = false, 
300                                                   S32 antialiasLevel = 0, 
301                                                   GFXTextureObject *inTex = NULL ) = 0;
302
303   /// Load a texture from a proper DDSFile instance.
304   virtual bool _loadTexture(GFXTextureObject *texture, DDSFile *dds)=0;
305
306   /// Load data into a texture from a GBitmap using the internal API.
307   virtual bool _loadTexture(GFXTextureObject *texture, GBitmap *bmp)=0;
308
309   /// Load data into a texture from a raw buffer using the internal API.
310   ///
311   /// Note that the size of the buffer is assumed from the parameters used
312   /// for this GFXTextureObject's _createTexture call.
313   virtual bool _loadTexture(GFXTextureObject *texture, void *raw)=0;
314
315   /// Refresh a texture using the internal API.
316   virtual bool _refreshTexture(GFXTextureObject *texture)=0;
317
318   /// Free a texture (but do not delete the GFXTextureObject) using the internal
319   /// API.
320   ///
321   /// This is only called during zombification for textures which need it, so you
322   /// don't need to do any internal safety checks.
323   virtual bool _freeTexture(GFXTextureObject *texture, bool zombify=false)=0;
324
325   /// @}
326
327   /// Store texture into the hash table cache and linked list.
328   void _linkTexture( GFXTextureObject *obj );
329
330   /// Validate the parameters for creating a texture.
331   void _validateTexParams( const U32 width, const U32 height, const GFXTextureProfile *profile, 
332      U32 &inOutNumMips, GFXFormat &inOutFormat );
333
334   // New texture manager methods for the cleanup work:
335   GFXTextureObject *_lookupTexture( const char *filename, const GFXTextureProfile *profile  );
336   GFXTextureObject *_lookupTexture( const DDSFile *ddsFile, const GFXTextureProfile *profile  );
337
338   void _onFileChanged( const Torque::Path &path );
339
340   /// The texture event signal type.
341   typedef Signal<void(GFXTexCallbackCode code)> EventSignal;
342
343   /// The texture event signal.
344   static EventSignal smEventSignal;
345};
346
347
348template <class T,class U>
349inline void GFXTextureManager::addEventDelegate( T obj, U func ) 
350{
351   EventSignal::DelegateSig d( obj, func );
352   
353   AssertFatal( !smEventSignal.contains( d ), 
354      "GFXTextureManager::addEventDelegate() - This is already registered!" );
355
356   smEventSignal.notify( d ); 
357}
358
359inline void GFXTextureManager::reloadTexture( GFXTextureObject *texture )
360{
361   refreshTexture( texture );
362}
363
364/// Returns the GFXTextureManager singleton.  Should only be
365/// called after the GFX device has been initialized.
366#define TEXMGR GFXDevice::get()->getTextureManager()
367
368#endif // _GFXTEXTUREMANAGER_H_
369