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