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#include "gfxTextureHandle.h"
 46
 47
 48namespace Torque
 49{
 50   class Path;
 51}
 52
 53class GFXCubemap;
 54
 55
 56class GFXTextureManager 
 57{   
 58public:
 59   enum
 60   {
 61      AA_MATCH_BACKBUFFER = -1
 62   };
 63
 64   GFXTextureManager();
 65   virtual ~GFXTextureManager();
 66
 67   /// Set up some global script interface stuff.
 68   static void init();
 69
 70   /// Provide the path to the texture to use when the requested one is missing
 71   static const String& getMissingTexturePath() { return smMissingTexturePath; }
 72
 73   /// Provide the path to the texture to use when the requested one is unavailable.
 74   static const String& getUnavailableTexturePath() { return smUnavailableTexturePath; }
 75
 76   /// Provide the path to the texture used to warn the developer
 77   static const String& getWarningTexturePath() { return smWarningTexturePath; }
 78
 79   static const String& getDefaultIrradianceCubemapPath() { return smDefaultIrradianceCubemapPath; }
 80   static const String& getDefaultPrefilterCubemapPath() { return smDefaultPrefilterCubemapPath; }
 81
 82   static const String& getBRDFTexturePath() { return smBRDFTexturePath; }
 83
 84   /// Update width and height based on available resources.
 85   ///
 86   /// We provide a simple interface for managing texture memory usage. Specifically,
 87   /// if the total video memory is below a certain threshold, we scale all texture
 88   /// resolutions down by a specific factor (you can specify different scale factors
 89   /// for different types of textures).
 90   ///
 91   /// @note The base GFXTextureManager class provides all the logic to do this scaling. 
 92   ///       Subclasses need only implement getTotalVideoMemory().
 93   ///
 94   /// @param  type     Type of the requested texture. This is used to determine scaling factors.
 95   /// @param  width    Requested width - is changed to the actual width that should be used.
 96   /// @param  height   Requested height - is changed to the actual height that should be used.
 97   /// @return True if the texture request should be granted, false otherwise.
 98   virtual bool validateTextureQuality(GFXTextureProfile *profile, U32 &width, U32 &height);
 99
100   ///
101   static U32 getTextureDownscalePower( GFXTextureProfile *profile );
102
103   virtual GFXTextureObject *createTexture(  GBitmap *bmp,
104      const String &resourceName,
105      GFXTextureProfile *profile,
106      bool deleteBmp);
107
108   virtual GFXTextureObject *createTexture(  DDSFile *dds,
109      GFXTextureProfile *profile,
110      bool deleteDDS);
111
112   virtual GFXTextureObject *createTexture(  const Torque::Path &path,
113      GFXTextureProfile *profile );
114
115   virtual GFXTextureObject *createTexture(  U32 width,
116      U32 height,
117      void *pixels,
118      GFXFormat format,
119      GFXTextureProfile *profile);
120
121   virtual GFXTextureObject *createTexture(  U32 width,
122      U32 height,
123      U32 depth,
124      GFXFormat format,
125      GFXTextureProfile *profile,
126      U32 numMipLevels = 1);
127
128   virtual GFXTextureObject *createTexture(  U32 width,
129      U32 height,
130      GFXFormat format,
131      GFXTextureProfile *profile,
132      U32 numMipLevels,
133      S32 antialiasLevel);
134
135   Torque::Path validatePath(const Torque::Path &path);
136   GBitmap *loadUncompressedTexture(const Torque::Path& path, GFXTextureProfile* profile, U32 width, U32 height, bool genMips = false);
137   GBitmap *loadUncompressedTexture(const Torque::Path &path, GFXTextureProfile *profile);
138   virtual GFXTextureObject *createCompositeTexture(const Torque::Path &pathR, const Torque::Path &pathG, const Torque::Path &pathB, const Torque::Path &pathA, U32 inputKey[4],
139      GFXTextureProfile *profile);
140
141   void saveCompositeTexture(const Torque::Path &pathR, const Torque::Path &pathG, const Torque::Path &pathB, const Torque::Path &pathA, U32 inputKey[4],
142      const Torque::Path &saveAs,GFXTextureProfile *profile);
143
144   virtual GFXTextureObject *createCompositeTexture(GBitmap*bmp[4], U32 inputKey[4],
145      const String &resourceName,
146      GFXTextureProfile *profile,
147      bool deleteBmp);
148
149   void deleteTexture( GFXTextureObject *texture );
150   void reloadTexture( GFXTextureObject *texture );
151
152   /// Request that the texture be deleted which will
153   /// either occur immediately or delayed if its cached.
154   void requestDeleteTexture( GFXTextureObject *texture );
155
156   /// @name Texture Necromancy
157   /// 
158   /// Texture necromancy in three easy steps:
159   /// - If you want to destroy the texture manager, call kill().
160   /// - If you want to switch resolutions, or otherwise reset the device, call zombify().
161   /// - When you want to bring the manager back from zombie state, call resurrect().
162   /// @{
163
164   ///
165   void kill();
166   void zombify();
167   void resurrect();
168
169   /// This releases any pooled textures which are 
170   /// currently unused freeing up video memory.
171   void cleanupPool();
172
173   ///
174   void reloadTextures();
175
176   /// This releases cached textures that have not
177   /// been referenced for a period of time.
178   void cleanupCache( U32 secondsToLive = 0 );
179
180   /// Registers a callback for texture zombify and resurrect events.
181   /// @see GFXTexCallbackCode
182   /// @see removeEventDelegate
183   template <class T,class U>
184   static void addEventDelegate( T obj, U func );
185
186   /// Unregisteres a texture event callback.
187   /// @see addEventDelegate
188   template <class T,class U>
189   static void removeEventDelegate( T obj, U func ) { smEventSignal.remove( obj, func ); }
190
191   /// @}
192
193   /// Load a cubemap from a texture file.
194   GFXCubemap* createCubemap( const Torque::Path &path );
195
196   /// Used to remove a cubemap from the cache.
197   void releaseCubemap( GFXCubemap *cubemap );
198
199public:
200   /// The amount of texture mipmaps to skip when loading a
201   /// texture that allows downscaling.
202   ///
203   /// Exposed to script via $pref::Video::textureReductionLevel.
204   ///
205   /// @see GFXTextureProfile::PreserveSize
206   /// 
207   static S32 smTextureReductionLevel;
208
209protected:
210
211   /// File path to the missing texture
212   static String smMissingTexturePath;
213
214   /// File path to the unavailable texture.  Often used by GUI controls
215   /// when the requested image is not available.
216   static String smUnavailableTexturePath;
217
218   /// File path to the warning texture
219   static String smWarningTexturePath;
220
221   static String smDefaultIrradianceCubemapPath;
222   static String smDefaultPrefilterCubemapPath;
223   static String smBRDFTexturePath;
224
225   GFXTextureObject *mListHead;
226   GFXTextureObject *mListTail;
227
228   // We have a hash table for fast texture lookups
229   GFXTextureObject **mHashTable;
230   U32                mHashCount;
231   GFXTextureObject *hashFind( const String &name );
232   void              hashInsert(GFXTextureObject *object);
233   void              hashRemove(GFXTextureObject *object);
234
235   // The cache of loaded cubemap textures.
236   typedef HashTable<String,GFXCubemap*> CubemapTable;
237   CubemapTable mCubemapTable;
238
239   /// The textures waiting to be deleted.
240   Vector<GFXTextureObject*> mToDelete;
241
242   enum TextureManagerState
243   {
244      Living,
245      Zombie,
246      Dead
247
248   } mTextureManagerState;
249
250   /// The texture pool collection type.
251   typedef HashTable<GFXTextureProfile*,StrongRefPtr<GFXTextureObject> > TexturePoolMap;
252
253   /// All the allocated texture pool textures.
254   TexturePoolMap mTexturePool;
255
256   //-----------------------------------------------------------------------
257   // Protected methods
258   //-----------------------------------------------------------------------
259
260   /// Returns a free texture of the requested attributes from
261   /// from the shared texture pool.  It returns NULL if no match
262   /// is found.
263   GFXTextureObject* _findPooledTexure(   U32 width, 
264                                          U32 height, 
265                                          GFXFormat format, 
266                                          GFXTextureProfile *profile,
267                                          U32 numMipLevels,
268                                          S32 antialiasLevel );
269
270   GFXTextureObject *_createTexture(   GBitmap *bmp,
271                                       const String &resourceName,
272                                       GFXTextureProfile *profile,
273                                       bool deleteBmp,
274                                       GFXTextureObject *inObj );
275
276   GFXTextureObject *_createTexture(   DDSFile *dds,
277                                       GFXTextureProfile *profile,
278                                       bool deleteDDS,
279                                       GFXTextureObject *inObj );
280
281   /// Frees the API handles to the texture, for D3D this is a release call
282   ///
283   /// @note freeTexture MUST NOT DELETE THE TEXTURE OBJECT
284   virtual void freeTexture( GFXTextureObject *texture, bool zombify = false );
285
286   virtual void refreshTexture( GFXTextureObject *texture );
287
288   /// @group Internal Texture Manager Interface
289   ///
290   /// These pure virtual functions are overloaded by each API-specific
291   /// subclass.
292   ///
293   /// The order of calls is:
294   /// @code
295   /// _createTexture()
296   /// _loadTexture
297   /// _refreshTexture()
298   /// _refreshTexture()
299   /// _refreshTexture()
300   /// ...
301   /// _freeTexture()
302   /// @endcode
303   ///
304   /// @{
305
306   /// Allocate a texture with the internal API.
307   ///
308   /// @param  height   Height of the texture.
309   /// @param  width    Width of the texture.
310   /// @param  depth    Depth of the texture. (Will normally be 1 unless
311   ///                  we are doing a cubemap or volumetexture.)
312   /// @param  format   Pixel format of the texture.
313   /// @param  profile  Profile for the texture.
314   /// @param  numMipLevels   If not-NULL, then use that many mips.
315   ///                        If NULL create the full mip chain
316   /// @param  antialiasLevel, Use GFXTextureManager::AA_MATCH_BACKBUFFER to match the backbuffer settings (for render targets that want to share
317   ///                         the backbuffer z buffer.  0 for no antialiasing, > 0 for levels that match the GFXVideoMode struct.
318   virtual GFXTextureObject *_createTextureObject( U32 height, 
319                                                   U32 width, 
320                                                   U32 depth, 
321                                                   GFXFormat format, 
322                                                   GFXTextureProfile *profile, 
323                                                   U32 numMipLevels, 
324                                                   bool forceMips = false, 
325                                                   S32 antialiasLevel = 0, 
326                                                   GFXTextureObject *inTex = NULL ) = 0;
327
328   /// Load a texture from a proper DDSFile instance.
329   virtual bool _loadTexture(GFXTextureObject *texture, DDSFile *dds)=0;
330
331   /// Load data into a texture from a GBitmap using the internal API.
332   virtual bool _loadTexture(GFXTextureObject *texture, GBitmap *bmp)=0;
333
334   /// Load data into a texture from a raw buffer using the internal API.
335   ///
336   /// Note that the size of the buffer is assumed from the parameters used
337   /// for this GFXTextureObject's _createTexture call.
338   virtual bool _loadTexture(GFXTextureObject *texture, void *raw)=0;
339
340   /// Refresh a texture using the internal API.
341   virtual bool _refreshTexture(GFXTextureObject *texture)=0;
342
343   /// Free a texture (but do not delete the GFXTextureObject) using the internal
344   /// API.
345   ///
346   /// This is only called during zombification for textures which need it, so you
347   /// don't need to do any internal safety checks.
348   virtual bool _freeTexture(GFXTextureObject *texture, bool zombify=false)=0;
349
350   /// @}
351
352   /// Store texture into the hash table cache and linked list.
353   void _linkTexture( GFXTextureObject *obj );
354
355   /// Validate the parameters for creating a texture.
356   void _validateTexParams( const U32 width, const U32 height, const GFXTextureProfile *profile, 
357      U32 &inOutNumMips, GFXFormat &inOutFormat );
358
359   // New texture manager methods for the cleanup work:
360   GFXTextureObject *_lookupTexture( const char *filename, const GFXTextureProfile *profile  );
361   GFXTextureObject *_lookupTexture( const DDSFile *ddsFile, const GFXTextureProfile *profile  );
362
363   void _onFileChanged( const Torque::Path &path );
364
365   /// The texture event signal type.
366   typedef Signal<void(GFXTexCallbackCode code)> EventSignal;
367
368   /// The texture event signal.
369   static EventSignal smEventSignal;
370};
371
372
373template <class T,class U>
374inline void GFXTextureManager::addEventDelegate( T obj, U func ) 
375{
376   EventSignal::DelegateSig d( obj, func );
377   
378   AssertFatal( !smEventSignal.contains( d ), 
379      "GFXTextureManager::addEventDelegate() - This is already registered!" );
380
381   smEventSignal.notify( d ); 
382}
383
384inline void GFXTextureManager::reloadTexture( GFXTextureObject *texture )
385{
386   refreshTexture( texture );
387}
388
389/// Returns the GFXTextureManager singleton.  Should only be
390/// called after the GFX device has been initialized.
391#define TEXMGR GFXDevice::get()->getTextureManager()
392
393#endif // _GFXTEXTUREMANAGER_H_
394