HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
RE_OGLTexture.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_OGLTexture.h ( RE Library, C++)
7  *
8  * COMMENTS:
9  * Base class for various OpenGL texture types: 1D, 2D, 3D, Cube,
10  * 2D rectangles, 1D arrays and 2D arrays.
11  *
12  */
13 #ifndef RE_OGLTexture_h
14 #define RE_OGLTexture_h
15 
16 class RE_Render;
17 class RE_TextureMap;
18 
19 #include <UT/UT_ValArray.h>
20 #include <UT/UT_Rect.h>
21 
22 #include "RE_CachedObject.h"
23 #include "RE_Types.h"
24 #include "RE_TextureTypes.h"
25 #include "RE_TextureFilter.h"
26 #include <IMG/IMG_FileTypes.h>
27 
28 #include <iosfwd>
29 
31 {
32 public:
33  virtual ~RE_OGLTexture();
34 
35  /// Returns the amount of main memory (NOT graphics memory!)
36  /// owned by this RE_OGLTexture.
37  virtual int64 getMemoryUsage(bool inclusive) const;
38 
39  virtual const char *className() const;
40 
41  // Texture type (dimensions)
42  RE_TextureDimension getTextureType() const;
43 
44  // Returns true if this texture type is supported.
45  virtual bool hasTextureSupport(RE_Render *r);
46 
47  // True if this texture type supports mipmapping (all but tex rectangles)
48  virtual bool hasMipMapSupport(RE_Render *);
49 
50  // Returns the maximum size of a texture edge of the given texture type
51  virtual int getMaxTextureSize(RE_Render *r) = 0;
52 
53  // Returns the maximum index that can be used for arrays and cube maps
54  virtual int getMaxTextureIndex(RE_Render *r);
55 
56  // True if GL can compress textures itself.
57  bool hasAutoCompression(RE_Render *r);
58 
59  // true if this has a valid texture created for it.
60  virtual bool isValid() const;
61 
62  // true if the texture res, format, mip levels can be changed on the fly
63  bool isMutable() const { return myMutableFlag; }
64 
65  // Texture identifier - opaque handle.
66  RE_TextureID getID() const;
67 
68  // Releases the texture on the GPU; this object becomes invalid.
69  virtual void free();
70 
71  // Returns a new texture with no attributes of the given type.
72  static RE_OGLTexture *newTexture(RE_TextureDimension t);
73 
74  // Returns a new, blank texture with the same attributes as this texture.
75  RE_OGLTexture *copyAttributes() const;
76 
77  // -----------------------------------------------------------------
78  // Basic Texture data (modifying will invalidate texture,
79  // requiring a setTexture() call)
80 
81  // The texture type can be color, stencil, or depth. Stencil and depth
82  // textures are more restrictive with the types that can be sent to them.
83  // They must be single channel textures; depth can be FLOAT16,24 or 32,
84  // while stencil must be UINT1,2,4,8 or 16. The default is Color.
85  // This must be set before calling setFormat().
86  void setDataType(RE_TextureDataType type);
87  RE_TextureDataType getDataType() const;
88 
89  // The data type is the CPU-side data format, vectorsize can be 1-4.
90  // To use leaner GPU-side data formats, set a texture compression.
91  void setFormat(RE_GPUType data, int vectorsize,
92  RE_TextureFormatExtra format_extra =
94  RE_GPUType getFormatType() const;
95  int getFormatSize() const;
96  RE_TextureFormatExtra getFormatExtra() const;
97 
98  // returns the GL internal format of the texture (ie, RGBA8).
99  int getInternalFormat() const { return myGLInternal; }
100 
101  // You can pass the data in a different format than the texture type.
102  // This must be called after setFormat().
103  void setClientFormat(RE_GPUType data, int vectorsize);
104 
105  // Compress the texture on the GPU, default is to use the same format as
106  // the CPU format (RE_COMPRESS_NONE). If auto_compress is false, it is
107  // assumed that the data passed to this texture object is already
108  // compressed.
109  void setCompression(RE_TextureCompress comp,
110  bool auto_compress);
111  RE_TextureCompress getCompression() const;
112  bool getAutoCompression() const;
113 
114  // Texture Resolution
115  // Height/depth may not be required, depending on texture dimension.
116  void setResolution(int w, int h = 1, int depth = 1,
117  bool force_pow2 = false);
118  int getWidth() const;
119  int getHeight() const;
120  int getDepth() const;
121 
122  // GL may differ from getWidth/Height/Depth if GPU requires pow2 textures
123  // These sizes will never be smaller than the above sizes.
124  int getGLWidth() const;
125  int getGLHeight() const;
126  int getGLDepth() const;
127 
128  // If the texture size differs from the GL size, this will return a value
129  // less than 1 to represent the coord where the image ends in the texture
130  float getTexS() const;
131  float getTexT() const;
132  float getTexR() const;
133 
134  // For multisample textures (2D)
135  virtual void setSamples(int samples);
136  int getSamples() const;
137 
138  // Enables mipmapping and auto-generation of mipmaps. Not all texture data
139  // formats can be mipmapped (specifically floating point). This also sets
140  // the minify filter to RE_FILT_LINEAR_MIPMAP_LINEAR if not set to a MIPMAP
141  // filter and it is enabled, or back to RE_FILT_LINEAR if disabled.
142  void setMipMap(bool m, bool autogen = true);
143  bool getMipMap() const;
144  bool getMipMapAutoGenerate() const;
145 
146  // Returns true if the texture actually is mipmapped, not just requested
147  // to be (some formats don't mipmap).
148  bool isMipMapped() const;
149 
150  // This can be called before the texture is created to determine if it's
151  // possible to use. Returns false if it's not possible to create. If the
152  // texture is already created, it returns the actual OpenGL texture values.
153  // 'format' is an internal OpenGL format specification (like GL_RGBA8).
154  bool queryTextureStats(RE_Render *r,
155  int *width, int *height, int *depth,
156  int *format);
157 
158  void setLabel(RE_Render *r, const char *label);
159 
160 
161  // ---------------------------------------------------------------------
162  // Texture transfer methods (CPU/GPU).
163 
164  // set/getTexture() writes or reads the entire texture.
165  // It is assumed that data points to a chunk of memory large enough for the
166  // texture. A set method must be called afterwards to reinitialize the
167  // texture if the above parameters are changed.
168  // If non-pow2 textures are not supported and you set the resolution to a
169  // non-pow2 size, you still pass in non-pow2 data and it will be written
170  // properly (do not pad to pow2). If you do not wish this to be the case,
171  // set a pow2 resolution insteead. When rendering a non-pow2 emulated
172  // texture, use the getTexS/T/R() methods to determine the edge of the data.
173 
174  // 'level' is the texture mipmap level.Must be -1 if mipmapping is disabled.
175  // 'index' varies by texture type; face for cube maps and index for arrays.
176  // 'proxy' does a texture proxy call, merely seeing if the texture can be
177  // created without generating any errors.
178  virtual void setTexture(RE_Render *r, const void *data,
179  int level=-1, int index=-1,
180  bool proxy=false) = 0;
181 
182  // How large a block is required to initialize or fetch this texture.
183  virtual int64 getSizeBytes() const;
184 
185  // The size of one scanline in the image. The second version using sublen
186  // instead of GLwidth
187  int64 getScanBytes() const;
188  int64 getScanBytes(int sublen) const;
189 
190  // Number of bits in a full pixel (ie, fp16 RGB has 48b).
191  int64 getBitsPerPixel() const;
192 
193  // Actual size of texture in GPU mem.
194  int64 getTextureSize() const;
195 
196  // Write to or read from a portion of the texture. Not all dimensions may
197  // be used. See derived classes for the meaning of 'z'. These can only be
198  // used after setTexture(), though it can be called with data=NULL to set
199  // up the texture for setSubTexture().
200  virtual void setSubTexture(RE_Render *r,
201  const void *data, int level,
202  int xoffset, int xsize,
203  int yoffset=0, int ysize=1,
204  int zoffset=0, int zsize=1) = 0;
205 
206  // Reads the entire texture at 'level' back into 'data'. 'data' must point
207  // to a block of at least 'getSizeBytes()' in size.
208  // Note that a non-pow2 emulated texture will return the entire GL pow2
209  // size, since there is no way to read a portion of a texture.
210  virtual void getTexture(RE_Render *r, void *data,
211  int level=0, int index=-1);
212 
213  // copies 'area' block of pixels from the read buffer to this texture,
214  // in screen coords (if NULL, the entire area) at offset (x,y,z) and
215  // miplevel 'level'. The pixels are converted to this texture's data format
216  virtual bool copyFromBuffer(RE_Render *r, int x, int y, int z = 0,
217  const UT_DimRect *bufferarea = NULL,
218  int level = 0) = 0;
219 
220  // Build mip-maps from mip level 0 of the texture. Useful for
221  // filtering render-to-texture targets. Returns true if mipmaps were
222  // generated.
223  bool generateMipMaps(RE_Render *r);
224 
225  // ---------------------------------------------------------------------
226  // Texture Parameters (changing will modify, does not require setTexture)
227 
228  // Filter to use when displaying the texture at less than 100% zoom
229  void setMinFilter( RE_Render *r, RE_TexFiltType t );
230  RE_TexFiltType getMinFilter() const;
231 
232  // Filter to use when displaying the texture at greater than 100% zoom
233  void setMagFilter( RE_Render *r, RE_TexFiltType t );
234  RE_TexFiltType getMagFilter() const;
235 
236  void setMaxAnisotropy(RE_Render *r, int atf);
237  int getMaxAnisotropy() const;
238 
239  // Fixed bias value that is added to the level-of-detail parameter for
240  // the texture before texture sampling (when mipmapping).
241  void setLodBias(RE_Render *r, float bias);
242  float getLodBias() const;
243 
244  // Texture wrapping - clamp or repeat. Not all dimension may be used.
245  void setTextureWrap(RE_Render *r,
246  RE_TexClampType clamp_s,
247  RE_TexClampType clamp_t = RE_CLAMP_EDGE,
248  RE_TexClampType clamp_r = RE_CLAMP_EDGE);
249  bool getWrapS() const;
250  bool getWrapT() const;
251  bool getWrapR() const;
252 
253  void setBorder(RE_Render *r,
255  const UT_Vector4F *color_alpha = NULL);
256  UT_Vector4F getBorderColor() const;
257 
258  // Sets all of the above in one go.
259  void setTextureFilter(RE_Render *r,
260  const RE_TextureFilter &filter);
261 
262  // When on, depth comparison is used. When used in a shader, a shadow
263  // sampler must be used. If disabled, the raw depth value is returned and
264  // a normal texture sampler must be used. 'compare' can be set to a
265  // negative, positive or zero value, indicating less/equal, greater/equal or
266  // equal compare mode.
267  void setDepthCompareMode(RE_Render *r, bool enabled,
268  RE_TextureCompare compare
270 
271  // If RE_EXT_TEXTURE_SWIZZLE is supported, texture components can be
272  // shuffled about or set to a constant 0 or 1 value.
273  bool setTextureSwizzle(RE_Render *r,
278 
279  void setAlphaInfo(IMG_FileAlphaInfo a) { myAlphaInfo = a; }
280  IMG_FileAlphaInfo getAlphaInfo() const { return myAlphaInfo;}
281 
282  // --------------------------------------------------------------------
283  // Bindless Textures (requires RE_EXT_TEXTURE_BINDLESS)
284 
285  // Creates a bindless handle for the texture. Once this is done, the texture
286  // is immutable - its texel contents can change, but nothing else.
287  // Will return false if bindless texture is unsupported.
288  bool createTextureHandle(RE_Render *r);
289 
290  // returns the bindless texture handle. createTextureHandle() must be called
291  // first. If bindless is unsupported or create was not called, returns 0.
292  uint64 getTextureHandle() const { return myBindlessHandle; }
293 
294  // Before a bindless texture can be used, it must be made resident.
295  bool makeResidentTexture(RE_Render *r);
296 
297  // When a bindless texture is no longer needed, it should be removed from
298  // resident status to free up resources.
299  bool removeResidentTexture(RE_Render *r);
300 
301  // --------------------------------------------------------------------
302 
303  static int getGLTextureType(RE_TextureDimension t);
304  static RE_TextureDimension getRETextureType(int gl_type);
305  static RE_OGLTexture *findTextureWithID(RE_TextureID id);
306 
307  // Mostly for debug, this writes the texture out to a file (any supported
308  // image format, determined by the extension). 3D textures are best written
309  // as deep raster formats, like .pic.
310  bool writeToFile(RE_Render *r, const char *name,
311  int level = 0);
312 
313  // Expands a 2D multisample texture into a 2D texture with dimensions
314  // increased by the sampling factor: 2x (2,1), 4x (2,2), 6x (3,2), 8x (4,2)
315  RE_OGLTexture * expandMultisampleTexture(RE_Render *r);
316 
317  static void adjustPow2(int &w, int &h, int &d);
318 
319 
320  // References on this texture by other objects
321  void addReference(void (*cb)(void *, RE_OGLTexture *),
322  void *ref_obj);
323  void removeReference(void *ref_obj);
324 
325  // print a summary of this texture. If os is NULL, use std::cerr.
326  void print(std::ostream *os = NULL);
327 
328  // Dump all textures currently in use by Houdini. If min_tex_size is
329  // specified, only those textures >= the size will be printed. The summary
330  // line will always include stats from all textures.
331  static void dumpTextureTable(std::ostream &os,
332  int64 min_tex_size = -1);
333 protected:
334 
336 
337  void deleteObject();
338  void setupTextureParameters(RE_Render *r, bool force);
339  void validate();
340 
341  // These return various GL types (ie, GL_TEXTURE_2D, GL_PROXY_TEXTURE_2D,
342  // GL_TEXTURE_BINDING_2D)
343  virtual int getGLType() const = 0;
344  virtual int getGLProxy() const = 0;
345  virtual int getGLTypeBinding() const = 0;
346  virtual int getGLCreateType() const { return getGLType(); }
347 
348  // These methods must be called from within a locked context
349  virtual bool buildMipMaps(RE_Render *r, const void *data) = 0;
350 
351  bool createTextureID();
352 
353  RE_GPUType getClientType() const;
354 
355  // returns a malloc'ed image with the compressed data, which must be freed.
356  // If no compression is necessary, this will return NULL.
357  void * compressTexData(const void *src, int &w, int &h);
358  void determineCompressionInternal();
359  void determineTextureSize(RE_Render *r);
360 
361  // OpenGL data
363  int myGLType;
370 
371  void updateTextureWrap(RE_Render *r, bool force);
372  void updateFilters(RE_Render *r, bool force);
373 
374 private:
375  void buildFormatTable();
376 
377  // RE data
378  RE_TextureDataType myTextureDataType;
379  RE_GPUType myDataType;
380  RE_GPUType myClientType;
381  RE_TextureFormatExtra myFormatExtra;
382  RE_TextureDimension myTexDimension;
383  int myVectorSize;
384  int myWidth;
385  int myHeight;
386  int myDepth;
387  RE_TextureCompress myCompression;
388  bool myMipMapFlag;
389  bool myMipMapAutoGenFlag;
390  bool myAutoCompressFlag;
391  bool myCompressFlag;
392  bool myValidFlag;
393  bool myMutableFlag;
394  RE_TextureFilter myCurrentFilterState;
395  RE_TextureFilter myFilter;
396  int64 myTexSize;
397  IMG_FileAlphaInfo myAlphaInfo;
398  UT_ValArray<void *> myReferences;
400 
401  uint64 myBindlessHandle;
402  int myResidentCount;
403 
404 protected:
406  friend class RE_OGLRender;
407  friend class RE_OGLFramebuffer;
408  friend class RE_TextureMap;
409 };
410 
411 inline RE_TextureDimension
413 {
414  return myTexDimension;
415 }
416 
417 inline void
419 {
420  myTextureDataType = type;
421 
422  if(myVectorSize > 0)
423  setFormat(myDataType, myVectorSize, myFormatExtra);
424 }
425 
426 inline RE_TextureDataType
428 {
429  return myTextureDataType;
430 }
431 
432 inline bool
434 {
435  return myID != 0 && myValidFlag;
436 }
437 
438 inline RE_TextureID
440 {
441  return myID;
442 }
443 
444 inline RE_GPUType
446 {
447  return myDataType;
448 }
449 
450 inline RE_GPUType
452 {
453  return myClientType;
454 }
455 
456 inline int
458 {
459  return myVectorSize;
460 }
461 
464 {
465  return myFormatExtra;
466 }
467 
468 inline int
470 {
471  return myWidth;
472 }
473 
474 inline int
476 {
477  return myHeight;
478 }
479 
480 inline int
482 {
483  return myDepth;
484 }
485 
486 inline int
488 {
489  return myGLWidth;
490 }
491 
492 inline int
494 {
495  return myGLHeight;
496 }
497 
498 inline int
500 {
501  return myGLDepth;
502 }
503 
504 inline RE_TextureCompress
506 {
507  return myCompression;
508 }
509 
510 inline bool
512 {
513  return myAutoCompressFlag;
514 }
515 
516 inline bool
518 {
519  return true;
520 }
521 
522 inline bool
524 {
525  return myMipMapFlag;
526 }
527 
528 inline bool
530 {
531  return myMipMapFlag && myCanMipMap;
532 }
533 
534 inline bool
536 {
537  return myMipMapAutoGenFlag;
538 }
539 
540 inline RE_TexFiltType
542 {
543  return myCurrentFilterState.getMinFilter();
544 }
545 
546 inline RE_TexFiltType
548 {
549  return myCurrentFilterState.getMagFilter();
550 }
551 
552 inline float
554 {
555  return myCurrentFilterState.getLodBias();
556 }
557 
558 inline int
560 {
561  return myCurrentFilterState.getMaxAnisotropy();
562 }
563 
564 inline bool
566 {
567  return myCurrentFilterState.getWrapS();
568 }
569 
570 inline bool
572 {
573  return myCurrentFilterState.getWrapT();
574 }
575 
576 inline bool
578 {
579  return myCurrentFilterState.getWrapR();
580 }
581 
582 inline const char *
584 {
585  return "RE_OGLTexture";
586 }
587 
588 inline bool
590 {
591  return true;
592 }
593 
594 inline void
596 {
597  myValidFlag = true;
598 }
599 
600 inline int
602 {
603  return 1;
604 }
605 
606 inline float
608 {
609  return float(myWidth) / float(myGLWidth);
610 }
611 
612 inline float
614 {
615  return float(myHeight) / float(myGLHeight);
616 }
617 
618 inline float
620 {
621  return float(myDepth) / float(myGLDepth);
622 }
623 
624 inline int64
626 {
627  return myTexSize;
628 }
629 
630 inline int64
632 {
633  return getScanBytes(myGLWidth);
634 }
635 
636 
637 #endif
int getGLHeight() const
virtual int getMaxTextureIndex(RE_Render *r)
float getTexR() const
bool isMipMapped() const
GLint GLint GLint yoffset
Definition: glcorearb.h:411
bool getMipMapAutoGenerate() const
int getGLDepth() const
RE_GPUType getClientType() const
GLuint GLsizei const GLchar * label
Definition: glcorearb.h:2544
bool getWrapS() const
virtual const char * className() const
#define RE_API
Definition: RE_API.h:10
int64 getTextureSize() const
RE_TextureFormatExtra getFormatExtra() const
RE_TextureSwizzle
int getWidth() const
GLdouble GLdouble GLdouble z
Definition: glcorearb.h:847
RE_TexFiltType getMagFilter() const
RE_TextureID myID
GLint level
Definition: glcorearb.h:107
GLboolean GLboolean GLboolean GLboolean a
Definition: glcorearb.h:1221
GLint y
Definition: glcorearb.h:102
GLenum GLenum GLsizei const GLuint GLboolean enabled
Definition: glcorearb.h:2538
RE_TextureDimension
bool getAutoCompression() const
int getDepth() const
int getMaxAnisotropy() const
float getLodBias() const
virtual int getGLCreateType() const
virtual bool hasMipMapSupport(RE_Render *)
RE_TexFiltType getMagFilter() const
GLint GLsizei width
Definition: glcorearb.h:102
int getInternalFormat() const
Definition: RE_OGLTexture.h:99
RE_TextureDimension getTextureType() const
RE_TexFiltType
long long int64
Definition: SYS_Types.h:100
RE_GPUType
Definition: RE_Types.h:42
bool getWrapR() const
unsigned long long uint64
Definition: SYS_Types.h:101
GLint GLint GLsizei GLsizei GLsizei depth
Definition: glcorearb.h:475
RE_TextureID getID() const
RE_TextureCompress myCompression
unsigned int RE_TextureID
bool getWrapT() const
RE_TextureFormatExtra
RE_TexClampType
int getFormatSize() const
virtual bool hasTextureSupport(RE_Render *r)
GLfloat GLfloat GLfloat alpha
Definition: glcorearb.h:111
RE_TextureCompress getCompression() const
RE_TextureBorder
int64 getScanBytes() const
GLint GLint xoffset
Definition: glcorearb.h:410
GLboolean * data
Definition: glcorearb.h:130
GLuint const GLchar * name
Definition: glcorearb.h:785
int getMaxAnisotropy() const
virtual int64 getMemoryUsage(bool inclusive) const
int getHeight() const
RE_TexFiltType getMinFilter() const
GLsizei samples
Definition: glcorearb.h:1297
GLint GLsizei GLsizei height
Definition: glcorearb.h:102
uint64 getTextureHandle() const
IMG_FileAlphaInfo
RE_TextureDataType
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:107
GLfloat GLfloat GLfloat GLfloat h
Definition: glcorearb.h:2001
virtual bool isValid() const
Cached object implementation for RE_TextureCache.
float getTexS() const
float getLodBias() const
GLint GLint GLsizei GLint border
Definition: glcorearb.h:107
RE_TexClampType getWrapR() const
RE_TexClampType getWrapS() const
RE_TextureDataType getDataType() const
GLfloat green
Definition: glcorearb.h:111
GLuint index
Definition: glcorearb.h:785
GLint GLenum GLint x
Definition: glcorearb.h:408
RE_GPUType getFormatType() const
RE_TexFiltType getMinFilter() const
void setAlphaInfo(IMG_FileAlphaInfo a)
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
IMG_FileAlphaInfo getAlphaInfo() const
int getGLWidth() const
void setDataType(RE_TextureDataType type)
GLubyte GLubyte GLubyte GLubyte w
Definition: glcorearb.h:856
float getTexT() const
GLboolean r
Definition: glcorearb.h:1221
GLfloat GLfloat blue
Definition: glcorearb.h:111
int double red
Definition: png.h:1705
RE_TextureCompress
RE_TexClampType getWrapT() const
bool getMipMap() const
RE_TextureCompare
bool isMutable() const
Definition: RE_OGLTexture.h:63
GLint GLint GLint GLint zoffset
Definition: glcorearb.h:476
void setFormat(RE_GPUType data, int vectorsize, RE_TextureFormatExtra format_extra=RE_TEXTURE_FORMAT_EXTRA_NONE)
GLint GLint GLint GLint GLint GLint GLint GLbitfield GLenum filter
Definition: glcorearb.h:1296
GLenum src
Definition: glcorearb.h:1792