Mitsuba Renderer  0.5.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
gputexture.h
Go to the documentation of this file.
1 /*
2  This file is part of Mitsuba, a physically based rendering system.
3 
4  Copyright (c) 2007-2014 by Wenzel Jakob and others.
5 
6  Mitsuba is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License Version 3
8  as published by the Free Software Foundation.
9 
10  Mitsuba is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License
16  along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18 
19 #pragma once
20 #if !defined(__MITSUBA_HW_GPUTEXTURE_H_)
21 #define __MITSUBA_HW_GPUTEXTURE_H_
22 
23 #include <mitsuba/core/bitmap.h>
24 #include <set>
25 
27 
28 /** \brief A data structure for 1/2/3D and cube texture mapping. Also
29  * has optional render-to-texture functionality.
30  * \ingroup libhw
31  */
33 public:
34  /// Available texture types
35  enum ETextureType {
36  /**
37  * \brief 1-D texture, useful for the storage of pre-calculated functions
38  * in conjunction with pixel shaders. Needs 1D texture coordinates
39  */
40  ETexture1D = 0,
41 
42  /// Default 2D texture format, needs 2D texture coordinates
44 
45  /// 3D volume texture format, needs 3D texture coordinates
47 
48  /// 3D cube map texture format, needs 3D texture coordinates
49  ETextureCubeMap
50  };
51 
52  /** \brief If the texture type is set to EFrameBuffer, the
53  * configuration must be one of the following constants */
55  /// This is not a framebuffer
56  ENone = 0x00,
57 
58  /**
59  * \brief Color framebuffer (\a including an internal depth
60  * buffer that cannot be accessed as a texture)
61  */
62  EColorBuffer = 0x01,
63 
64  /// Depth-only framebuffer (e.g. for shadow mapping)
65  EDepthBuffer = 0x02,
66 
67  /// Color and texture framebuffer (both exposed as textures)
68  EColorAndDepthBuffer = 0x03
69  };
70 
71  /// Supported per-component data formats
73  /// 8-bit unsigned integer (\c uint8_t) component encoding
75 
76  /// 16-bit unsigned integer (\c uint16_t) component encoding
78 
79  /// 32-bit unsigned integer (\c uint32_t) component encoding
81 
82  /// 16-bit floating point (\c half) HDR component encoding
84 
85  /// 32-bit floating point (\c float) HDR component encoding
87 
88  /// 64-bit floating point (\c float) HDR component encoding
89  EFloat64
90  };
91 
92  /// Supported pixel format types
93  enum EPixelFormat {
94  /// Single-channel depth map
95  EDepth = 0,
96 
97  /// Single-channel luminance bitmap
99 
100  /// Two-channel luminance + alpha bitmap
102 
103  /// RGB bitmap
105 
106  /// RGB bitmap + alpha channel
107  ERGBA
108  };
109 
110  /// A texture has one more slots into which bitmaps can be placed
112  /// Default slot for 1,2,3D textures
113  EDefaultPosition = 0,
114  /// Cube map: +X plane, Right
115  ECubeMapPositiveX = 0,
116  /// Cube map: -X plane, Left
118  /// Cube map: +Y plane, Top
120  /// Cube map: -Y plane, Bottom
122  /// Cube map: +Z plane, Front
124  /// Cube map: -Z plane, Back
126  ELastPosition
127  };
128 
129  /** \brief Texture wrapping mode when texture coordinates
130  * exit the [0, 1] range
131  */
132  enum EWrapType {
133  /// Clamp the coordinates to [0, 1]
134  EClamp = 0,
135  /// Similar to EClamp, but prevents mixing at the edges
137  /// Similar to EClamp
139  /// Modulo 1 operation (default)
141  /// Mirror the coordinates at the edges
142  EMirror
143  };
144 
145  /** \brief The interpolation filter determines which texture
146  * pixels are considered when shading a fragment
147  */
148  enum EFilterType {
149  /// Use the color value of the closest pixel
150  ENearest = 0,
151  /// Use 4 surrounding pixels and weigh them
153  /**
154  * Blend the color values of the closest matching
155  * mipmaps and use nearest filtering
156  */
158  /**
159  * Blend the color values of the closest matching
160  * mipmaps and use linear filtering (aka. bilinear)
161  */
162  EMipMapLinear
163  };
164 
165  /**
166  * \brief When this texture contains a depth buffer, the
167  * following modes control the read behavior of the
168  * associated texture unit. 'ENormal' means that texture
169  * values are returned as with any other texture, whereas
170  * 'ECompare' causes a depth comparison to take place
171  * (this is the default).
172  */
173  enum EDepthMode {
175  ECompare
176  };
177 
178  /** \brief Construct a new texture.
179  *
180  * If bitmap is non-NULL, the texture type, format
181  * will be automatically set
182  *
183  * \param name A human-readable name (for debugging)
184  * \param bitmap An bitmap to be put into the first
185  * slot. A NULL value will be ignored.
186  */
187  GPUTexture(const std::string &name, Bitmap *bitmap);
188 
189  /// Set the texture name
190  inline void setName(const std::string &name) { m_name = name; }
191 
192  /// Get the texture name
193  inline const std::string &getName() const { return m_name; }
194 
195  /// Set the texture type
196  inline void setType(ETextureType textureType) { m_type = textureType; }
197 
198  /// Return the texture type
199  inline ETextureType getType() const { return m_type; }
200 
201  /// Set the pixel format of this texture
202  inline void setPixelFormat(EPixelFormat fmt) { m_pixelFormat = fmt; }
203 
204  /// Return the pixel format of this texture
205  inline EPixelFormat getPixelFormat() const { return m_pixelFormat; }
206 
207  /// Set the component format of this texture
208  inline void setComponentFormat(EComponentFormat fmt) { m_componentFormat = fmt; }
209 
210  /// Return the component format of this texture
211  inline EComponentFormat getComponentFormat() const { return m_componentFormat; }
212 
213  /// Set the framebuffer type (applies only if type==EFrameBuffer)
214  void setFrameBufferType(EFrameBufferType frameBufferType);
215 
216  /// Return the framebuffer type (applies only if type==EFrameBuffer)
217  inline EFrameBufferType getFrameBufferType() const { return m_fbType; }
218 
219  /// Set the filter type
220  inline void setFilterType(EFilterType filterType) { m_filterType = filterType; }
221 
222  /// Return the filter type
223  inline EFilterType getFilterType() const { return m_filterType; }
224 
225  /// Set the wrap type
226  inline void setWrapType(EWrapType wrapType) {
227  setWrapTypeU(wrapType); setWrapTypeV(wrapType);
228  }
229 
230  /// Set the wrap type along the U axis
231  inline void setWrapTypeU(EWrapType wrapType) { m_wrapTypeU = wrapType; }
232 
233  /// Return the wrap type along the U axis
234  inline EWrapType getWrapTypeU() { return m_wrapTypeU; }
235 
236  /// Set the wrap type along the V axis
237  inline void setWrapTypeV(EWrapType wrapType) { m_wrapTypeV = wrapType; }
238 
239  /// Return the wrap type along the V axis
240  inline EWrapType getWrapTypeV() { return m_wrapTypeV; }
241 
242  /// Return the size in pixels
243  inline Point3i getSize() const { return m_size; }
244 
245  /// Set the size in pixels
246  inline void setSize(const Point3i &size) { m_size = size; }
247 
248  /// Get the maximal anisotropy
249  inline Float getMaxAnisotropy() const { return m_maxAnisotropy; }
250 
251  /** \brief Set the maximal anisotropy.
252  *
253  * A value of 1 will result in isotropic
254  * texture filtering. A value of 0 (default) will
255  * use the global max. anisotropy value
256  */
257  inline void setMaxAnisotropy(Float maxAnisotropy) { m_maxAnisotropy = maxAnisotropy; }
258 
259  /// Return whether mipmapping is enabled
260  inline bool isMipMapped() const { return m_mipmapped; }
261 
262  /// Define whether mipmapping is enabled
263  inline void setMipMapped(bool mipMapped) { m_mipmapped = mipMapped; }
264 
265  /// Return the depth map read mode
266  inline EDepthMode getDepthMode() const { return m_depthMode; }
267 
268  /// Set the depth map read mode
269  inline void setDepthMode(EDepthMode mode) { m_depthMode = mode; }
270 
271  /// Store a bitmap in a bitmap slot
272  void setBitmap(unsigned int slot, Bitmap *bitmap);
273 
274  /// Retrieve a bitmap from the given slot
275  Bitmap *getBitmap(unsigned int slot = EDefaultPosition);
276 
277  /// Retrieve a bitmap from the given slot
278  const Bitmap *getBitmap(unsigned int slot = EDefaultPosition) const;
279 
280  /// Return the number of stored bitmaps
281  inline int getBitmapCount() const { return (int) m_bitmaps.size(); }
282 
283  /// Upload the texture
284  virtual void init() = 0;
285 
286  /// Dereference the CPU bitmap associated with the texture
287  void release();
288 
289  /// Run \ref init, followed by \ref release
290  void initAndRelease();
291 
292  /// Refresh (re-upload) the texture
293  virtual void refresh() = 0;
294 
295  /**
296  * \brief Refresh (re-upload) a subregion of the texture
297  *
298  * Note: this is only implemented for 2D textures
299  */
300  virtual void refresh(const Point2i &offset, const Vector2i &size) = 0;
301 
302  /// Free the texture from GPU memory
303  virtual void cleanup() = 0;
304 
305  /**
306  * \brief Bind the texture and enable texturing
307  *
308  * \param textureUnit
309  * Specifies the unit to which this texture should be bound
310  * \param textureIndex
311  * When this texture has multiple sub-textures (e.g.
312  * a color and depth map in the case of a
313  * \ref EColorAndDepthBuffer texture), this parameter
314  * specifies the one to be bound
315  */
316  virtual void bind(int textureUnit = 0, int textureIndex = 0) const = 0;
317 
318  /// Unbind the texture and disable texturing
319  virtual void unbind() const = 0;
320 
321  /**
322  * Download the texture (only for render target textures).
323  * When the 'bitmap' parameter is NULL, the destination is
324  * the internal bitmap given by getTexture(0)
325  */
326  virtual void download(Bitmap *bitmap = NULL) = 0;
327 
328  /// Activate the render target
329  virtual void activateTarget() = 0;
330 
331  /// Activate a certain face of a cube map as render target
332  virtual void activateSide(int side) = 0;
333 
334  /// Restrict rendering to a sub-region of the texture
335  virtual void setTargetRegion(const Point2i &offset, const Vector2i &size) = 0;
336 
337  /// Deactivate the render target
338  virtual void releaseTarget() = 0;
339 
340  /// Return the texture units, to which this texture is currently bound
341  inline const std::set<int> &getTextureUnits() const { return m_textureUnits.get(); }
342 
343  /// Set the number of samples (for multisample color render targets)
344  inline void setSampleCount(int samples) { m_samples = samples; }
345 
346  /// Return the number of samples (for multisample color render targets)
347  inline int getSampleCount() const { return m_samples; }
348 
349  /// Set the border color (applicable if <tt>wrapMode=EClamp/EClampToBorder</tt>)
350  inline void setBorderColor(const Color3 &borderColor) { m_borderColor = borderColor; }
351 
352  /// Return the border color
353  inline const Color3 &getBorderColor() const { return m_borderColor; }
354 
355  /**
356  * \brief Blit a render buffer into another render buffer
357  *
358  * \param target
359  * Specifies the target render buffer
360  * \param what
361  * A bitwise-OR of the components in \ref EFrameBufferType to copy
362  */
363  virtual void blit(GPUTexture *target, int what) const = 0;
364 
365  /**
366  * \brief Blit a render buffer into another render buffer
367  *
368  * \param target
369  * Specifies the target render buffer (or NULL for the framebuffer)
370  * \param what
371  * A bitwise-OR of the components in \ref EFrameBufferType to copy
372  * \param sourceOffset
373  * Offset in the source render buffer
374  * \param sourceOffset
375  * Size of the region to be copied from the source render buffer
376  * \param destOffset
377  * Offset in the destination render buffer
378  * \param destOffset
379  * Size of the region to be copied into the dest destination buffer
380  */
381  virtual void blit(GPUTexture *target, int what, const Point2i &sourceOffset,
382  const Vector2i &sourceSize, const Point2i &destOffset,
383  const Vector2i &destSize) const = 0;
384 
385  /// Clear (assuming that this is a render buffer)
386  virtual void clear() = 0;
387 
388  /// Assuming that this is a 2D RGB framebuffer, read a single pixel from the GPU
389  virtual Color3 getPixel(int x, int y) const = 0;
390 
391  /// Return a string representation
392  std::string toString() const;
393 
395 protected:
396  /// Virtual destructor
397  virtual ~GPUTexture();
398 protected:
399  std::string m_name;
400  ETextureType m_type;
401  EPixelFormat m_pixelFormat;
402  EComponentFormat m_componentFormat;
403  EFilterType m_filterType;
404  EWrapType m_wrapTypeU, m_wrapTypeV;
406  EDepthMode m_depthMode;
407  bool m_mipmapped;
408  mutable PrimitiveThreadLocal<std::set<int> > m_textureUnits;
409  Float m_maxAnisotropy;
410  int m_samples;
411  std::vector<Bitmap *> m_bitmaps;
412  Point3i m_size;
413  Color3 m_borderColor;
414 };
415 
417 
418 #endif /* __MITSUBA_HW_GPUTEXTURE_H_ */
bool isMipMapped() const
Return whether mipmapping is enabled.
Definition: gputexture.h:260
Two-channel luminance + alpha bitmap.
Definition: gputexture.h:101
EDepthMode
When this texture contains a depth buffer, the following modes control the read behavior of the assoc...
Definition: gputexture.h:173
const std::set< int > & getTextureUnits() const
Return the texture units, to which this texture is currently bound.
Definition: gputexture.h:341
EDepthMode getDepthMode() const
Return the depth map read mode.
Definition: gputexture.h:266
EFilterType
The interpolation filter determines which texture pixels are considered when shading a fragment...
Definition: gputexture.h:148
void setWrapTypeU(EWrapType wrapType)
Set the wrap type along the U axis.
Definition: gputexture.h:231
General-purpose bitmap class with read and write support for several common file formats.
Definition: bitmap.h:50
void setMipMapped(bool mipMapped)
Define whether mipmapping is enabled.
Definition: gputexture.h:263
int getSampleCount() const
Return the number of samples (for multisample color render targets)
Definition: gputexture.h:347
Definition: gputexture.h:157
#define MTS_EXPORT_HW
Definition: platform.h:114
RGB bitmap.
Definition: gputexture.h:104
Modulo 1 operation (default)
Definition: gputexture.h:140
void setDepthMode(EDepthMode mode)
Set the depth map read mode.
Definition: gputexture.h:269
Definition: gputexture.h:174
void setPixelFormat(EPixelFormat fmt)
Set the pixel format of this texture.
Definition: gputexture.h:202
void setName(const std::string &name)
Set the texture name.
Definition: gputexture.h:190
ETexturePosition
A texture has one more slots into which bitmaps can be placed.
Definition: gputexture.h:111
3D volume texture format, needs 3D texture coordinates
Definition: gputexture.h:46
Point3i getSize() const
Return the size in pixels.
Definition: gputexture.h:243
#define MTS_NAMESPACE_BEGIN
Definition: platform.h:137
16-bit unsigned integer (uint16_t) component encoding
Definition: gputexture.h:77
EFrameBufferType
If the texture type is set to EFrameBuffer, the configuration must be one of the following constants...
Definition: gputexture.h:54
void setType(ETextureType textureType)
Set the texture type.
Definition: gputexture.h:196
Cube map: -X plane, Left.
Definition: gputexture.h:117
ETextureType getType() const
Return the texture type.
Definition: gputexture.h:199
ETextureType
Available texture types.
Definition: gputexture.h:35
RGB color data type.
Definition: spectrum.h:612
Cube map: +Z plane, Front.
Definition: gputexture.h:123
Default 2D texture format, needs 2D texture coordinates.
Definition: gputexture.h:43
EComponentFormat
Supported per-component data formats.
Definition: gputexture.h:72
EPixelFormat getPixelFormat() const
Return the pixel format of this texture.
Definition: gputexture.h:205
void setWrapTypeV(EWrapType wrapType)
Set the wrap type along the V axis.
Definition: gputexture.h:237
const std::string & getName() const
Get the texture name.
Definition: gputexture.h:193
int getBitmapCount() const
Return the number of stored bitmaps.
Definition: gputexture.h:281
Cube map: -Z plane, Back.
Definition: gputexture.h:125
EFrameBufferType getFrameBufferType() const
Return the framebuffer type (applies only if type==EFrameBuffer)
Definition: gputexture.h:217
8-bit unsigned integer (uint8_t) component encoding
Definition: gputexture.h:74
EWrapType getWrapTypeU()
Return the wrap type along the U axis.
Definition: gputexture.h:234
#define MTS_DECLARE_CLASS()
This macro must be used in the initial definition in classes that derive from Object.
Definition: class.h:158
Definition: fwd.h:99
Similar to EClamp.
Definition: gputexture.h:138
A data structure for 1/2/3D and cube texture mapping. Also has optional render-to-texture functionali...
Definition: gputexture.h:32
Thin wrapper around posix thread local storage. Stores heap-allocated data other than Object instance...
Definition: tls.h:115
void setSampleCount(int samples)
Set the number of samples (for multisample color render targets)
Definition: gputexture.h:344
EWrapType getWrapTypeV()
Return the wrap type along the V axis.
Definition: gputexture.h:240
void setFilterType(EFilterType filterType)
Set the filter type.
Definition: gputexture.h:220
void setComponentFormat(EComponentFormat fmt)
Set the component format of this texture.
Definition: gputexture.h:208
Cube map: +Y plane, Top.
Definition: gputexture.h:119
Use 4 surrounding pixels and weigh them.
Definition: gputexture.h:152
void setBorderColor(const Color3 &borderColor)
Set the border color (applicable if wrapMode=EClamp/EClampToBorder)
Definition: gputexture.h:350
void setSize(const Point3i &size)
Set the size in pixels.
Definition: gputexture.h:246
void setMaxAnisotropy(Float maxAnisotropy)
Set the maximal anisotropy.
Definition: gputexture.h:257
32-bit unsigned integer (uint32_t) component encoding
Definition: gputexture.h:80
Definition: fwd.h:100
No filtering, nearest neighbor lookups.
Definition: mipmap.h:56
Parent of all Mitsuba classes.
Definition: object.h:38
Similar to EClamp, but prevents mixing at the edges.
Definition: gputexture.h:136
Float getMaxAnisotropy() const
Get the maximal anisotropy.
Definition: gputexture.h:249
void setWrapType(EWrapType wrapType)
Set the wrap type.
Definition: gputexture.h:226
EPixelFormat
Supported pixel format types.
Definition: gputexture.h:93
virtual std::string toString() const
Return a human-readable string representation of the object&#39;s contents.
EFilterType getFilterType() const
Return the filter type.
Definition: gputexture.h:223
EWrapType
Texture wrapping mode when texture coordinates exit the [0, 1] range.
Definition: gputexture.h:132
Definition: fwd.h:95
const Color3 & getBorderColor() const
Return the border color.
Definition: gputexture.h:353
#define MTS_NAMESPACE_END
Definition: platform.h:138
16-bit floating point (half) HDR component encoding
Definition: gputexture.h:83
Cube map: -Y plane, Bottom.
Definition: gputexture.h:121
Single-channel luminance bitmap.
Definition: gputexture.h:98
EComponentFormat getComponentFormat() const
Return the component format of this texture.
Definition: gputexture.h:211
32-bit floating point (float) HDR component encoding
Definition: gputexture.h:86