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