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