HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
RE_TextureMap.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: RE_TextureMap.h ( RE Library, C++)
7  *
8  * COMMENTS:
9  * Base class for the RE texture map interface to RE_Textures. This class
10  * is basically a handle to a texture map. It allows you to load textures
11  * from images transparently, and cache generated textures.
12  */
13 
14 #ifndef __RE_TextureMap_h__
15 #define __RE_TextureMap_h__
16 
17 #include <UT/UT_String.h>
18 
19 #include "RE_API.h"
20 #include "RE_Texture.h"
21 #include <UT/UT_Functor.h>
22 #include <IMG/IMG_FileTypes.h>
23 
24 class RE_TextureCache;
25 class re_AutoTextureSource;
26 class TIL_Raster;
27 class RE_Render;
28 class IMG_File;
29 class IMG_FileParms;
30 
32 {
33 public:
34  RE_TextureHolder() : myTexture(NULL) {}
36  : myTexture(tex)
37  {
38  if(myTexture)
39  myTexture->setInUse(true);
40  }
42  : myTexture(src.myTexture)
43  {
44  if(myTexture)
45  myTexture->setInUse(true);
46  }
48  {
49  if(myTexture)
50  myTexture->setInUse(false);
51  }
52 
53  bool isValid() const { return myTexture != NULL; }
54  RE_Texture * operator*() const { return myTexture; }
55  RE_Texture * operator->() const { UT_ASSERT(myTexture); return myTexture; }
56 
57  void operator=(RE_Texture *tex)
58  {
59  if(myTexture)
60  myTexture->setInUse(false);
61  myTexture = tex;
62  if(myTexture)
63  myTexture->setInUse(true);
64  }
65  void operator=(const RE_TextureHolder &tex)
66  {
67  *this = tex.myTexture;
68  }
69 
70  void clear()
71  {
72  if(myTexture)
73  {
74  myTexture->setInUse(false);
75  myTexture=NULL;
76  }
77  }
78 
79  bool operator==(const RE_Texture *tex) const
80  { return myTexture == tex; }
81  bool operator!=(const RE_Texture *tex) const
82  { return myTexture != tex; }
83  bool operator==(const RE_TextureHolder &tex) const
84  { return myTexture == tex.myTexture; }
85  bool operator!=(const RE_TextureHolder &tex) const
86  { return myTexture != tex.myTexture; }
87 
88  int usageCount() const
89  { return myTexture ? myTexture->getUsage() : 0; }
90 
91 private:
92  RE_Texture *myTexture;
93 };
94 
95 
97 {
98 public:
99  virtual ~RE_TextureMap();
100 
101  /// Returns the amount of main memory (NOT graphics memory!)
102  /// owned by this RE_TextureMap.
103  virtual int64 getMemoryUsage(bool inclusive) const;
104 
105  virtual const char *className() const;
106 
107  // The texture dimension and type of this map (1D, 2D, Cube, 3D, etc)
108  virtual RE_TextureDimension getMapType() = 0;
109 
110  // Create an exact replica of this texture map.
111  virtual RE_TextureMap *clone() const = 0;
112 
113  // Create a new texture map of the given type.
114  static RE_TextureMap *newTextureMap(RE_TextureDimension type);
115 
116  // These may return false if the dimension of the texture does not match
117  // what this map is, or if a file or node reference cannot be resolved.
118 
119  // Find an image from a disk file or node.
120  bool setSource(const char *mapname,
121  const char *relativeTo);
122 
123  // Find an image from a disk file which is opened by the file_resolver
124  // function: IMG_File *fp = file_resolver(mapname);
125  bool setSource(
126  const char *mapname,
128  UT_Functor1<void, IMG_File *> file_close);
129 
130  // Store a generated texture in the cache. You cannot set the translation
131  // options with this method, it just uses the map class as a container.
132  // The filtering can be set, however. You are responsible for clearing the
133  // texture if it is deleted. This allows the texture to be counted as used
134  // when computing the #maps and total texture size for a render.
135  bool setSource(const char *mapname,
136  const char *relativeTo,
138  bool (*releaseCB)(RE_Texture *, void *),
139  void *releaseObject);
140 
141  // This is an optional callback which will modify the map before being used
142  // to create the texture. Any of the image parameters can be changed except
143  // for the basic type of the texture (ie 2D, cube). The operation must be
144  // done inplace. 'pixeldata' will be NULL when querying for type/size
145  // changes and non-NULL when about to generate the texture. In the non-NULL
146  // case, none of the image parameters should be altered (they will be the
147  // values returned from the previous pixeldata=NULL pass.
149  {
150  public:
152  : pixels(NULL),type(RE_GPU_FLOAT32),vector_size(1),w(0),h(0),d(0),
153  option(RE_TEXTURE_FORMAT_EXTRA_NONE), texture(NULL)
154  {}
157  int w,h,d;
159  void *pixels;
161  };
162  void setSourceModifyCallback(const char *opname,
163  bool (*modifyCallback)(RE_TextureMap *map,
164  TexCBPixelData &pixdata,
165  void *user_data),
166  void *user_data);
167 
168  // Clears the texture stored in the map, if the first setSource() method
169  // was called.
170  void clearStoredTexture();
171 
172  // Clears the texture and removes it from the cache. Useful if you're about
173  // to delete the texture.
174  void deleteTexRef(RE_Texture *tex);
175 
176  /// Access to the texture itself. This method may actually build it.
177  RE_TextureHolder getTexture(RE_Render *r, bool deferred_load = false);
178 
179  /// Access to the texture itself, this method will only check the cache.
180  RE_TextureHolder getCachedTexture(RE_Render *r);
181 
182  /// Return a texture that is not cached in the GL cache. You own it.
183  RE_Texture *getUncachedTexture(RE_Render *r);
184 
185  // Returns true if this map has a tagged texture, setSource(.., RE_Texture)
186  bool hasTaggedTexture() const { return myTaggedTexture != NULL; }
187 
188  // When the version changes, the texture
189  void setVersion(RE_CacheVersion v) { myVersion = v; }
190  void bumpVersion();
191  RE_CacheVersion getVersion() const { return myVersion; }
192 
193  // clear any cached data.
194  virtual void invalidateCached();
195 
196  // Basic information about the map
197  const char *getMapName() const { return myMapName; }
198  const char *getRelativePath() const { return myRelative; }
199 
200  // Set the source to NULL without changing any of the other parameters.
201  void reset();
202 
203  // Set the source to NULL and remove it from the cache.
204  void clear(const char *clear_name = NULL);
205 
206  // returns true if the map/relative names point to a valid source. This
207  // allows you to use the methods below to query the data.
208  bool isSourceValid();
209 
210  // Mark the texture as properly resolved (file loaded, op cooked) or not
211  // (file failed to load)
212  void setValidSourceResolve(bool valid)
213  { myValidSourceResolve = valid; }
214  bool hasValidSourceResolve() const { return myValidSourceResolve; }
215 
216  /// Return trues if a load request has been queued for this texture, but it
217  /// isn't yet loaded.
218  bool isLoadPending() const { return myLoadPending; }
219 
220  // Returns the resolution of the image
221  void getResolution(int &w, int &h, int &d);
222 
223  // The data format of the pixel (8b, 32 FP)
224  RE_GPUType getFormatType();
225 
226  // The number of components in a pixels (1-4)
227  int getFormatSize();
228 
229  // Returns the original aspect ratio of the image (before scaling or sizing)
230  float getAspectRatio();
231  // For 3D textures, X:Z ratio.
232  float getAspectRatioXZ();
233 
234 
235  // Accessors to the filter options for the texture. A single texture map
236  // be referenced by several maps with different filter options.
237  RE_TextureFilter &filter() { return myFilter; }
238  const RE_TextureFilter &filter() const { return myFilter; }
239 
240  // Set the texture colorspace. PXL_CS_CUSTOM_GAMMA is unsupported.
241  void setColorSpace(PXL_ColorSpace space);
242  PXL_ColorSpace getColorSpace() const;
243 
244  // Image to Texture translation. These parameters are used to convert an
245  // image (1D, 2D or 3D) to a texture.
246 
247  // explicitly scale to the given resolution. If scale is specified as well,
248  // it further scales this size down. Setting to 0,0,0 will disable this.
249  void sizeTo(int w, int h, int d=1);
250 
251  // Scale the map up or down by a factor. By default, a uniform scale is
252  // used (h/d = -1.0f)
253  void scaleTo(fpreal w, fpreal h = -1.0f, fpreal d = -1.0f);
254 
255  // Cap the size at these maximums, scaling down uniformly to fit. This is
256  // applied after the sizeTo() and scaleTo() methods. Setting to 0,0,0 will
257  // disable the max size.
258  void maxSize(int w, int h, int d);
259 
260  // Cap the resulting texture so that it doesn't use more than this limit.
261  // A limit of 0 will disable the texture memory limit.
262  void maxMemSize(int mem_limit_mb);
263 
264  // If enabled, this will round the texture to the next power of two if a
265  // dimension is not a power of two.
266  void makePow2(bool pow2);
267 
268  // By default, the map uses the same format as the image.
269  void setCompression(RE_TextureCompress comp);
270 
271  // By default, the texture is not mipmapped.
272  void setMipMap(bool mip);
273 
274  // No options by default. Can currently set a 1chan texture to be
275  // interpreted as A, and 2chan texture RG instead of Lum-A.
277  { myFormatOption = opt; }
278 
279  // Texture Component to sample from when using a single channel from
280  // packed maps. -1 indicates that no mapping is done.
281  void setTextureComponent(int texcomp)
282  { myTextureComponent = SYSclamp(texcomp, -1, 3); }
283 
284  // Sample texture map as { R, R, R, A }. If the texture component is given
285  // above, use that component (eg. texcomp=2 would sample B,B,B,A).
286  void fillRGBFromSingle(bool fill_rgb_mono)
287  { myTextureRGBMono = fill_rgb_mono; }
288 
289  // If true, set A to 1. Otherwise, use A from the map.
290  void setOpaqueAlpha(bool opaque_alpha)
291  { myOpaqueAlpha = opaque_alpha; }
292  // returns the opaque alpha setting, not whether the texture itself
293  // actually has fully opaque alpha.
294  bool getOpaqueAlpha() const { return myOpaqueAlpha; }
295 
296  // When loading the map, look for details about the alpha matte. Currently
297  // only implemented for 2D maps.
298  void checkAlphaDetails(bool check) { myAlphaDetails = check; }
299  IMG_FileAlphaInfo getAlphaDetails() const { return myAlphaInfo; }
300 
301  void allowPreload(bool preload) { myAllowPreloadFlag = preload; }
302  bool allowsPreload() const { return myAllowPreloadFlag; }
303 
304  // If this map references an OP, this returns the unique OP ID.
305  virtual int getSourceOpID() const { return -999; }
306 
307  static void backgroundTextureLoadThreads(int n);
308 
309  // Called when the texture this map references was deleted.
310  static void textureReferenceDeleted(void *, RE_Texture *t);
311 
312  // Texture cache interface
313  static void setTextureCacheSize(int64 size_in_mb);
314  static int64 getTextureCacheSize();
315 
316  static int64 getTextureCacheUsage();
317  static int64 get2DTextureUsage();
318  static int64 get3DTextureUsage();
319  static int64 getMipMapUsage();
320  static int64 get3DTextureFP32Size();
321  static int64 get3DTextureFP16Size();
322  static int64 get2DTextureFP32Size();
323  static int64 get2DTextureFP16Size();
324  static int64 getOrig3DTextureFP32Size();
325  static int64 getOrig3DTextureFP16Size();
326  static int64 getOrig2DTextureFP32Size();
327  static int64 getOrig2DTextureFP16Size();
328 
329  static void pruneTextureCache();
330  static void clearTextureCache(bool full_clear);
331  static void debugDumpCache();
332 
333  // These methods can be used to query texture map usage over a long period
334  // of time (such as a single redraw). The query methods must be called
335  // *before* recording is disabled.
336  static void recordTextureMapUsage(bool enable);
337  static bool recordingTextureUsage();
338  static void textureUsed(RE_Texture *tex);
339  static void textureDeleted(RE_Texture *tex);
340 
341  static int getNumUsedTextureMaps();
342  static int64 getUsedTextureMemory();
343 
344 protected:
345  // You can't create an RE_TextureMap directly; you have to use one of the
346  // derived classes to define a type.
347  RE_TextureMap();
348 
349  virtual void buildSourceName(UT_String &cachedname,
350  const char *map, const char *rel);
351  virtual void buildTextureName(UT_String &cachedname,
352  const char *map, const char *rel);
353  re_AutoTextureSource getTextureSource(const char *map, const char *relto,
354  void **tex_data,
355  bool deferred_load=false,
356  bool preload_only=false);
357 
358  // Adjusts a resolution based on the maxSize, sizeTo and scaleTo settings.
359  // 1D and 2D maps can set the extra dimensions to NULL.
360  void getDesiredResolution(RE_GPUType type, int vsize,
361  int *w, int *h, int *d);
362 
363  // Override to actually create the texture from the data returned in
364  // mapptr from getNodeSource() and getFileSource().
365  virtual bool buildTexture(RE_Render *r, RE_Texture *tex,
366  void *data) = 0;
367 
368  // Override if you're interested in when a texture is retrieved from the
369  // cache instead of built.
370  virtual void cachedTextureFound(RE_Texture *tex) {}
371 
372  // Note that mapptr may be NULL if the actual data of the image is not
373  // required yet.
374  virtual bool getNodeSource(const char *map, const char *rel,
375  void **mapptr,
376  RE_TextureDimension &textype,
377  RE_GPUType &datatype,
378  int &vectorsize,
379  int &w, int &h, int &d);
380  virtual bool getFileSource(const char *map,
381  void **mapptr,
382  RE_TextureDimension &textype,
383  RE_GPUType &datatype,
384  int &vectorsize,
385  int &w, int &h, int &d,
386  bool preload_only);
387 
388  void setPendingLoad(bool pend) { myLoadPending = pend; }
389 
390  // override to return false if the derived class will call the callback to
391  // modify the pixel data.
392  void * callModifyCallback(RE_Texture *tex, void *data);
393 
394  // Can be called after the source is set.
395  bool isNodeSource();
396 
397  RE_TextureCompress getCompression() const { return myCompression; }
398  bool getMipMap() const { return myMipMap; }
399 
400  // Returns a empty texture object with the desired attributes.
401  RE_Texture *getTextureStub(bool preload);
402 
403  void copy(const RE_TextureMap *src);
404 
406  { return myFormatOption; }
407 
408  void setupGammaCorrect(IMG_FileParms &parms,
409  const char *filename,
410  RE_GPUType datatype);
411 
412  RE_TextureHolder fetchTexture(RE_Render *r,
413  bool build_if_missing,
414  bool preload_only);
415 
416  // Translation options
418  fpreal myScale[3];
419  int myRes[3];
420  int myMaxRes[3];
422  int myMipMap;
427 
428  // Custom file resolver
431 
432 private:
433  void init(RE_Texture *t);
434 
435  static bool cachedMapReleased(void *tex, void *map);
436  bool clearTexture(RE_Texture *tex);
437 
438  bool updateFileModTime(const char *filename, int &mod);
439 
440  UT_String myRelative;
441  UT_String myOpName;
442  RE_TextureFilter myFilter;
443  bool myMapOwned;
444  RE_CacheVersion myVersion;
445  PXL_ColorSpace myColorSpace;
446  RE_TextureFormatExtra myFormatOption;
447  int myTextureComponent;
448  bool myTextureRGBMono;
449  bool myOpaqueAlpha;
450  bool myAllowPreloadFlag;
451  bool myPrevSourceResult;
452 
453  UT_String myModifyOp;
454  bool (*myModifyCallback)(RE_TextureMap*, TexCBPixelData&,
455  void*);
456  void *myModifyCallbackData;
457 
458  // Only for the setSource(src, rel, tex, version) call.
459  RE_TextureHolder myTaggedTexture;
460  RE_TextureCache *myCache;
461  RE_TextureHolder myCachedTexture;
462  bool myLoadPending;
463  bool myVolatileFlag;
464  bool myValidSourceResolve;
465 
466 
467  bool (*myReleaseCB)(RE_Texture *, void *);
468  void *myReleaseObject;
469 };
470 
471 
472 inline const char *
474 {
475  return "RE_TextureMap";
476 }
477 
478 #endif
RE_TextureFormatExtra getTextureFormatOption() const
bool operator==(const RE_TextureHolder &tex) const
Definition: RE_TextureMap.h:83
GT_API const UT_StringHolder filename
GLenum src
Definition: glew.h:2410
void allowPreload(bool preload)
const RE_TextureFilter & filter() const
#define RE_API
Definition: RE_API.h:10
UT_Functor1< void, IMG_File * > myFileClose
virtual const char * className() const
UT_String myMapName
void checkAlphaDetails(bool check)
GLuint GLenum option
Definition: glew.h:3288
void operator=(RE_Texture *tex)
Definition: RE_TextureMap.h:57
bool getOpaqueAlpha() const
const GLdouble * v
Definition: glew.h:1391
RE_TextureDimension
void setTextureFormatOption(RE_TextureFormatExtra opt)
GLboolean reset
Definition: glew.h:4959
RE_TextureCompress getCompression() const
const char * getRelativePath() const
RE_TextureFilter & filter()
RE_TextureFormatExtra option
int usageCount() const
Definition: RE_TextureMap.h:88
bool isLoadPending() const
bool operator!=(const RE_TextureHolder &tex) const
Definition: RE_TextureMap.h:85
RE_GPUType
Definition: RE_Types.h:44
void setInUse(bool inc)
RE_Texture * operator->() const
Definition: RE_TextureMap.h:55
GLclampf f
Definition: glew.h:3499
void setTextureComponent(int texcomp)
virtual void cachedTextureFound(RE_Texture *tex)
RE_TextureCompress myCompression
GLint GLenum GLsizei GLint GLsizei const void * data
Definition: glew.h:1379
RE_TextureFormatExtra
GLubyte GLubyte GLubyte GLubyte w
Definition: glew.h:1890
UT_Vector3T< T > SYSclamp(const UT_Vector3T< T > &v, const UT_Vector3T< T > &min, const UT_Vector3T< T > &max)
Definition: UT_Vector3.h:836
GLsizei n
Definition: glew.h:4040
RE_CacheVersion getVersion() const
long long int64
Definition: SYS_Types.h:116
void operator=(const RE_TextureHolder &tex)
Definition: RE_TextureMap.h:65
bool getMipMap() const
IMG_FileAlphaInfo myAlphaInfo
bool operator!=(const RE_Texture *tex) const
Definition: RE_TextureMap.h:81
Generic interface for reading and writing image files. This class handles the reading and writing of ...
Definition: IMG_File.h:55
RE_Texture * operator*() const
Definition: RE_TextureMap.h:54
GLfloat GLfloat GLfloat GLfloat h
Definition: glew.h:8011
void fillRGBFromSingle(bool fill_rgb_mono)
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
GLint GLint GLsizei GLsizei GLsizei GLint GLenum GLenum const void * pixels
Definition: glew.h:1254
UT_Functor2< IMG_File *, const char *, const IMG_FileParms & > myFileOpen
bool isValid() const
Definition: RE_TextureMap.h:53
RE_TextureHolder(const RE_TextureHolder &src)
Definition: RE_TextureMap.h:41
GT_API const UT_StringHolder version
RE_TextureHolder(RE_Texture *tex)
Definition: RE_TextureMap.h:35
IMG_FileAlphaInfo
void setOpaqueAlpha(bool opaque_alpha)
bool hasValidSourceResolve() const
fpreal64 fpreal
Definition: SYS_Types.h:277
virtual int getSourceOpID() const
GLenum GLuint texture
Definition: glew.h:2361
IMG_FileAlphaInfo getAlphaDetails() const
File options for manipulating image data on load or save. This class allows you to modify the incomin...
Definition: IMG_FileParms.h:34
PXL_ColorSpace
Definition: PXL_Common.h:68
GLdouble GLdouble GLdouble r
Definition: glew.h:1406
OIIO_API bool copy(string_view from, string_view to, std::string &err)
bool operator==(const RE_Texture *tex) const
Definition: RE_TextureMap.h:79
void setVersion(RE_CacheVersion v)
bool allowsPreload() const
Simple class for a mutli-integer cache tag.
#define UT_ASSERT(ZZ)
Definition: UT_Assert.h:135
void setPendingLoad(bool pend)
int setSource(int source) override
const char * getMapName() const
RE_TextureCompress
void setValidSourceResolve(bool valid)
GLboolean enable
Definition: glew.h:2745
GLdouble GLdouble t
Definition: glew.h:1398
bool hasTaggedTexture() const