Cinder  0.8.6
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
Texture.h
Go to the documentation of this file.
1 /*
2  Copyright (c) 2010, The Barbarian Group
3  All rights reserved.
4 
5  Redistribution and use in source and binary forms, with or without modification, are permitted provided that
6  the following conditions are met:
7 
8  * Redistributions of source code must retain the above copyright notice, this list of conditions and
9  the following disclaimer.
10  * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
11  the following disclaimer in the documentation and/or other materials provided with the distribution.
12 
13  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
14  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
15  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
16  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
17  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
18  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
19  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
20  POSSIBILITY OF SUCH DAMAGE.
21 */
22 
23 #pragma once
24 
25 #include "cinder/Cinder.h"
26 #include "cinder/gl/gl.h"
27 #include "cinder/Surface.h"
28 #include "cinder/Rect.h"
29 #include "cinder/Stream.h"
30 
31 #include <vector>
32 #include <utility>
33 
34 namespace cinder { namespace gl {
35 
36 class Texture;
37 typedef std::shared_ptr<Texture> TextureRef;
38 
41 class Texture {
42  public:
43  struct Format;
44 
45  // Create analogs for constructors
47  static TextureRef create( int width, int height, Format format = Format() ) { return std::make_shared<Texture>( width, height, format ); }
49  static TextureRef create( const unsigned char *data, int dataFormat, int width, int height, Format format = Format() ) { return std::make_shared<Texture>( data, dataFormat, width, height, format ); }
51  static TextureRef create( const Surface8u &surface, Format format = Format() ) { return std::make_shared<Texture>( surface, format ); }
53  static TextureRef create( const Surface32f &surface, Format format = Format() ) { return std::make_shared<Texture>( surface, format ); }
55  static TextureRef create( const Channel8u &channel, Format format = Format() ) { return std::make_shared<Texture>( channel, format ); }
57  static TextureRef create( const Channel32f &channel, Format format = Format() ) { return std::make_shared<Texture>( channel, format ); }
59  static TextureRef create( ImageSourceRef imageSource, Format format = Format() ) { return std::make_shared<Texture>( imageSource, format ); }
61  static TextureRef create( GLenum target, GLuint textureId, int width, int height, bool doNotDispose ) { return std::make_shared<Texture>( target, textureId, width, height, doNotDispose ); }
62 
63  public:
65  Texture() {}
67  Texture( int aWidth, int aHeight, Format format = Format() );
69  Texture( const unsigned char *data, int dataFormat, int aWidth, int aHeight, Format format = Format() );
71  Texture( const Surface8u &surface, Format format = Format() );
73  Texture( const Surface32f &surface, Format format = Format() );
75  Texture( const Channel8u &channel, Format format = Format() );
77  Texture( const Channel32f &channel, Format format = Format() );
79  Texture( ImageSourceRef imageSource, Format format = Format() );
81  Texture( GLenum aTarget, GLuint aTextureID, int aWidth, int aHeight, bool aDoNotDispose );
82 
83  public:
85  void setDoNotDispose( bool aDoNotDispose = true ) { mObj->mDoNotDispose = aDoNotDispose; }
87  void setDeallocator( void(*aDeallocatorFunc)( void * ), void *aDeallocatorRefcon );
89  void setWrap( GLenum wrapS, GLenum wrapT ) { setWrapS( wrapS ); setWrapT( wrapT ); }
92  void setWrapS( GLenum wrapS );
95  void setWrapT( GLenum wrapT );
98  void setMinFilter( GLenum minFilter );
101  void setMagFilter( GLenum magFilter );
102 
104  void setCleanTexCoords( float maxU, float maxV );
105 
107  void update( const Surface &surface );
109  void update( const Surface32f &surface );
112  void update( const Surface &surface, const Area &area );
114  void update( const Channel32f &channel );
116  void update( const Channel8u &channel, const Area &area );
117 
119  GLint getWidth() const;
121  GLint getHeight() const;
123  GLint getCleanWidth() const;
125  GLint getCleanHeight() const;
127  Vec2i getSize() const { return Vec2i( getWidth(), getHeight() ); }
129  float getAspectRatio() const { return getWidth() / (float)getHeight(); }
131  Area getBounds() const { return Area( 0, 0, getWidth(), getHeight() ); }
133  Area getCleanBounds() const { return Area( 0, 0, getCleanWidth(), getCleanHeight() ); }
135  bool hasAlpha() const;
137  float getLeft() const;
138  float getRight() const;
139  float getTop() const;
140  float getBottom() const;
142  float getMaxU() const;
143  float getMaxV() const;
145  Rectf getAreaTexCoords( const Area &area ) const;
147  GLint getInternalFormat() const;
149  GLuint getId() const { return mObj->mTextureID; }
151  GLenum getTarget() const { return mObj->mTarget; }
153  bool isFlipped() const { return mObj->mFlipped; }
155  void setFlipped( bool aFlipped = true ) { mObj->mFlipped = aFlipped; }
156 
159  void enableAndBind() const;
161  void disable() const;
163  void bind( GLuint textureUnit = 0 ) const;
165  void unbind( GLuint textureUnit = 0 ) const;
166 
168  static Texture loadDds( IStreamRef ddsStream, Format format );
169 
171  static void SurfaceChannelOrderToDataFormatAndType( const SurfaceChannelOrder &sco, GLint *dataFormat, GLenum *type );
173  static bool dataFormatHasAlpha( GLint dataFormat );
175  static bool dataFormatHasColor( GLint dataFormat );
176 
178  Texture weakClone() const;
179 
180 #if ! defined( CINDER_GLES )
181  operator ImageSourceRef() const;
183 #endif
184 
185  struct Format {
187  Format();
188 
192 #ifndef CINDER_GLES
194 #endif
195 
198 
203 
205  void setWrap( GLenum wrapS, GLenum wrapT ) { setWrapS( wrapS ); setWrapT( wrapT ); }
208  void setWrapS( GLenum wrapS ) { mWrapS = wrapS; }
211  void setWrapT( GLenum wrapT ) { mWrapT = wrapT; }
214  void setMinFilter( GLenum minFilter ) { mMinFilter = minFilter; }
217  void setMagFilter( GLenum magFilter ) { mMagFilter = magFilter; }
218 
220  GLenum getTarget() const { return mTarget; }
222  bool hasMipmapping() const { return mMipmapping; }
223 
227  bool isAutoInternalFormat() const { return mInternalFormat == -1; }
228 
230  GLenum getWrapS() const { return mWrapS; }
232  GLenum getWrapT() const { return mWrapT; }
234  GLenum getMinFilter() const { return mMinFilter; }
236  GLenum getMagFilter() const { return mMagFilter; }
237 
238  protected:
244 
245  friend class Texture;
246  };
247 
248  protected:
249  void init( const unsigned char *data, int unpackRowLength, GLenum dataFormat, GLenum type, const Format &format );
250  void init( const float *data, GLint dataFormat, const Format &format );
251  void init( ImageSourceRef imageSource, const Format &format );
252 
253  struct Obj {
254  Obj() : mWidth( -1 ), mHeight( -1 ), mCleanWidth( -1 ), mCleanHeight( -1 ), mInternalFormat( -1 ), mTextureID( 0 ), mFlipped( false ), mDeallocatorFunc( 0 ) {}
255  Obj( int aWidth, int aHeight ) : mInternalFormat( -1 ), mWidth( aWidth ), mHeight( aHeight ), mCleanWidth( aWidth ), mCleanHeight( aHeight ), mFlipped( false ), mTextureID( 0 ), mDeallocatorFunc( 0 ) {}
256  ~Obj();
257 
259  float mMaxU, mMaxV;
264  bool mFlipped;
265  void (*mDeallocatorFunc)(void *refcon);
267  };
268  std::shared_ptr<Obj> mObj;
269 
270  public:
272  typedef std::shared_ptr<Obj> Texture::*unspecified_bool_type;
274  operator unspecified_bool_type() const { return ( mObj.get() == 0 ) ? 0 : &Texture::mObj; }
275  void reset() { mObj.reset(); }
277 };
278 
280  public:
282  TextureCache( const Surface8u &prototypeSurface, const Texture::Format &format );
283 
284  gl::Texture cache( const Surface8u &data );
285 
286  protected:
287  struct Obj {
288  Obj( const Surface8u &prototypeSurface, const Texture::Format &format );
289 
290  void markTextureAsFree( int id );
291 
294 
295  int mNextId;
296  std::vector<std::pair<int,gl::Texture> > mTextures;
297 
298  static void TextureCacheDeallocator( void *aDeallocatorRefcon );
299  };
300 
301  std::shared_ptr<Obj> mObj;
302 
303  public:
305  typedef std::shared_ptr<Obj> TextureCache::*unspecified_bool_type;
307  operator unspecified_bool_type() const { return ( mObj.get() == 0 ) ? 0 : &TextureCache::mObj; }
308  void reset() { mObj.reset(); }
310 };
311 
312 
314  public:
316  virtual int32_t getRowBytes( int requestedWidth, const SurfaceChannelOrder &sco, int elementSize ) const { return requestedWidth * elementSize * sco.getPixelInc(); }
317 };
318 
319 class TextureDataExc : public std::exception {
320 public:
321  TextureDataExc( const std::string &log ) throw();
322  virtual const char* what() const throw()
323  {
324  return mMessage;
325  }
326 
327 private:
328  char mMessage[16001];
329  GLint mShaderType;
330 };
331 
332 
333 } } // namespace cinder::gl
Definition: Surface.h:64
void disable() const
Disables the Texture's target.
Definition: Texture.cpp:961
static void SurfaceChannelOrderToDataFormatAndType(const SurfaceChannelOrder &sco, GLint *dataFormat, GLenum *type)
Converts a SurfaceChannelOrder into an appropriate OpenGL dataFormat and type.
Definition: Texture.cpp:498
Base class for defining the properties of a Surface necessary to be interoperable with different APIs...
Definition: Surface.h:76
std::shared_ptr< Obj > Texture::* unspecified_bool_type
Emulates shared_ptr-like behavior.
Definition: Texture.h:273
static bool dataFormatHasColor(GLint dataFormat)
Returns whether a give OpenGL dataFormat contains color channels.
Definition: Texture.cpp:547
int mNextId
Definition: Texture.h:295
bool isFlipped() const
whether the texture is flipped vertically
Definition: Texture.h:153
void setWrapS(GLenum wrapS)
Sets the horizontal wrapping behavior when a texture coordinate falls outside the range of [0...
Definition: Texture.cpp:762
static TextureRef create(int width, int height, Format format=Format())
Constructs a Texture of size(width, height)
Definition: Texture.h:47
void setMinFilter(GLenum minFilter)
Sets the filtering behavior when a texture is displayed at a lower resolution than its native resolut...
Definition: Texture.h:214
Definition: Surface.h:64
Vec2i getSize() const
the size of the texture in pixels
Definition: Texture.h:127
Definition: Area.h:37
GLint mHeight
Definition: Texture.h:258
GLenum mWrapS
Definition: Texture.h:240
GLsizei const GLchar ** string
Definition: GLee.h:2427
bool mDoNotDispose
Definition: Texture.h:263
GLenum mMagFilter
Definition: Texture.h:241
void setWrap(GLenum wrapS, GLenum wrapT)
Sets the wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are GL_CLAMP, GL_REPEAT and GL_CLAMP_TO_EDGE. The default is GL_CLAMP.
Definition: Texture.h:205
GLenum internalFormat
Definition: GLee.h:7149
bool hasAlpha() const
whether the texture has an alpha channel
Definition: Texture.cpp:797
void setWrap(GLenum wrapS, GLenum wrapT)
Sets the wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are GL_CLAMP, GL_REPEAT and GL_CLAMP_TO_EDGE.
Definition: Texture.h:89
Definition: Texture.h:185
static TextureRef create(const Surface8u &surface, Format format=Format())
Constructs a Texture based on the contents of surface.
Definition: Texture.h:51
GLint getInternalFormat() const
Returns the Texture's internal format. A value of -1 implies automatic selection of the internal form...
Definition: Texture.h:225
GLenum GLsizei width
Definition: GLee.h:969
float mMaxV
Definition: Texture.h:259
#define GL_TEXTURE_RECTANGLE_ARB
Definition: gldx.h:1571
void setDoNotDispose(bool aDoNotDispose=true)
Determines whether the Texture will call glDeleteTextures() to free the associated texture objects on...
Definition: Texture.h:85
void setTarget(GLenum target)
Specifies the texture's target. The default is GL_TEXTURE_2D.
Definition: Texture.h:190
float getMaxU() const
These do not correspond to "top" and "right" when the texture is flipped.
Definition: Texture.cpp:931
static TextureRef create(ImageSourceRef imageSource, Format format=Format())
Constructs a texture based on imageSource.
Definition: Texture.h:59
GLenum getMagFilter() const
Returns the texture magnifying function, which is used whenever the pixel being textured maps to an a...
Definition: Texture.h:236
GLsizei GLsizei GLenum GLenum const GLvoid * data
Definition: GLee.h:1011
void reset()
Emulates shared_ptr-like behavior.
Definition: Texture.h:308
int mHeight
Definition: Texture.h:292
void setDeallocator(void(*aDeallocatorFunc)(void *), void *aDeallocatorRefcon)
Installs an optional callback which fires when the texture is destroyed. Useful for integrating with ...
Definition: Texture.cpp:756
GLenum target
Definition: GLee.h:13607
int mWidth
Definition: Texture.h:292
typedef void(APIENTRYP GLEEPFNGLBLENDCOLORPROC)(GLclampf red
void enableMipmapping(bool enableMipmapping=true)
Enables or disables mipmapping. Default is disabled.
Definition: Texture.h:197
GLint mCleanWidth
Definition: Texture.h:258
GLenum getTarget() const
Returns the texture's target.
Definition: Texture.h:220
GLenum mMinFilter
Definition: Texture.h:241
TextureCache()
Definition: Texture.h:281
Area getBounds() const
the Area defining the Texture's bounds in pixels: [0,0]-[width,height]
Definition: Texture.h:131
GLint mCleanHeight
Definition: Texture.h:258
GLint getCleanWidth() const
the width of the texture in pixels accounting for its "clean" area -
Definition: Texture.cpp:873
void enableAndBind() const
Enables the Texture's target and binds its associated texture. Equivalent to calling.
Definition: Texture.cpp:955
virtual int32_t getRowBytes(int requestedWidth, const SurfaceChannelOrder &sco, int elementSize) const
Definition: Texture.h:316
Specifies the in-memory ordering of the channels of a Surface.
Definition: Surface.h:42
void setWrapS(GLenum wrapS)
Sets the horizontal wrapping behavior when a texture coordinate falls outside the range of [0...
Definition: Texture.h:208
Area getCleanBounds() const
the Area defining the Texture's clean pixel bounds in pixels: [0,0]-[width*maxU,height*maxV] ...
Definition: Texture.h:133
static TextureRef create(const Channel8u &channel, Format format=Format())
Constructs a Texture based on the contents of channel.
Definition: Texture.h:55
bool hasMipmapping() const
Returns whether the texture has mipmapping enabled.
Definition: Texture.h:222
void setTargetRect()
Sets the texture's target to be GL_TEXTURE_RECTANGLE_ARB. Not available in OpenGL ES...
Definition: Texture.h:193
unsigned int GLuint
Definition: gldx.h:55
GLuint getId() const
the ID number for the texture, appropriate to pass to calls like glBindTexture()
Definition: Texture.h:149
float getMaxV() const
Definition: Texture.cpp:936
bool mFlipped
Definition: Texture.h:264
void setMagFilter(GLenum magFilter)
Definition: Texture.cpp:777
Obj(int aWidth, int aHeight)
Definition: Texture.h:255
GLint mWidth
Definition: Texture.h:258
void setFlipped(bool aFlipped=true)
Marks the texture as being flipped vertically or not.
Definition: Texture.h:155
std::shared_ptr< IStreamCinder > IStreamRef
Definition: Stream.h:142
Represents an OpenGL Texture. Implicitly shared object.
Definition: Texture.h:41
float getBottom() const
Definition: Texture.cpp:926
void * mDeallocatorRefcon
Definition: Texture.h:266
virtual const char * what() const
Definition: Texture.h:322
GLenum GLsizei GLsizei height
Definition: GLee.h:1029
GLclampf GLclampf GLclampf alpha
Definition: GLee.h:951
std::shared_ptr< Texture > TextureRef
Definition: gl.h:63
GLint getInternalFormat() const
the Texture's internal format, which is the format that OpenGL stores the texture data in memory...
Definition: Texture.cpp:833
std::shared_ptr< Obj > TextureCache::* unspecified_bool_type
Emulates shared_ptr-like behavior.
Definition: Texture.h:306
GLenum getTarget() const
the target associated with texture. Typical values are GL_TEXTURE_2D and GL_TEXTURE_RECTANGLE_ARB ...
Definition: Texture.h:151
GLint getHeight() const
the height of the texture in pixels
Definition: Texture.cpp:860
Texture weakClone() const
Creates a clone of this texture which does not have ownership, but points to the same resource...
Definition: Texture.cpp:748
GLint getWidth() const
the width of the texture in pixels
Definition: Texture.cpp:846
Definition: Texture.h:253
Obj(const Surface8u &prototypeSurface, const Texture::Format &format)
Definition: Texture.cpp:1003
void markTextureAsFree(int id)
Definition: Texture.cpp:1008
GLenum mWrapT
Definition: Texture.h:240
void init(const unsigned char *data, int unpackRowLength, GLenum dataFormat, GLenum type, const Format &format)
Definition: Texture.cpp:246
Definition: Texture.h:319
gl::Texture cache(const Surface8u &data)
Definition: Texture.cpp:974
void(* mDeallocatorFunc)(void *refcon)
Definition: Texture.h:265
std::vector< std::pair< int, gl::Texture > > mTextures
Definition: Texture.h:296
GLenum mTarget
Definition: Texture.h:239
static Texture loadDds(IStreamRef ddsStream, Format format)
Creates a new Texture from raw DirectDraw Stream data.
Definition: Texture.cpp:561
static TextureRef create(const Surface32f &surface, Format format=Format())
Constructs a Texture based on the contents of surface.
Definition: Texture.h:53
GLenum getWrapS() const
Returns the horizontal wrapping behavior for the texture coordinates.
Definition: Texture.h:230
void bind(GLuint textureUnit=0) const
Binds the Texture's texture to its target in the multitexturing unit GL_TEXTURE0 + textureUnit...
Definition: Texture.cpp:941
Definition: Texture.h:287
uint8_t getPixelInc() const
Definition: Surface.h:55
~Obj()
Definition: Texture.cpp:77
static TextureRef create(const unsigned char *data, int dataFormat, int width, int height, Format format=Format())
Constructs a Texture of size(width, height). Pixel data is provided by data and is expected to be int...
Definition: Texture.h:49
void setMagFilter(GLenum magFilter)
Definition: Texture.h:217
GLuint GLuint GLsizei GLenum type
Definition: GLee.h:963
int int channel
Definition: GLee.h:17150
float getAspectRatio() const
the aspect ratio of the texture (width / height)
Definition: Texture.h:129
void setInternalFormat(GLint internalFormat)
Sets the Texture's internal format. A value of -1 implies selecting the best format for the context...
Definition: Texture.h:200
bool isAutoInternalFormat() const
Returns whether the Texture's internal format will be automatically selected based on the context...
Definition: Texture.h:227
GLint mInternalFormat
Definition: Texture.h:260
GLenum mTarget
Definition: Texture.h:261
void setCleanTexCoords(float maxU, float maxV)
Definition: Texture.cpp:782
void setWrapT(GLenum wrapT)
Sets the verical wrapping behavior when a texture coordinate falls outside the range of [0...
Definition: Texture.cpp:767
void setWrapT(GLenum wrapT)
Sets the verical wrapping behavior when a texture coordinate falls outside the range of [0...
Definition: Texture.h:211
std::shared_ptr< Obj > mObj
Definition: Texture.h:268
Texture()
Default initializer. Points to a null Obj.
Definition: Texture.h:65
int GLint
Definition: gldx.h:51
GLenum GLsizei GLenum format
Definition: GLee.h:969
GLint getCleanHeight() const
the height of the texture in pixels accounting for its "clean" area -
Definition: Texture.cpp:889
Format()
Default constructor, sets the target to GL_TEXTURE_2D, wrap to GL_CLAMP, disables mipmapping...
Definition: Texture.cpp:64
void unbind(GLuint textureUnit=0) const
Unbinds the Texture currently bound in the Texture's target.
Definition: Texture.cpp:948
Definition: Texture.h:279
Rectf getAreaTexCoords(const Area &area) const
Returns the UV coordinates which correspond to the pixels contained in area. Does not compensate for ...
Definition: Texture.cpp:905
void update(const Surface &surface)
Replaces the pixels of a texture with contents of surface. Expects surface's size to match the Textur...
Definition: Texture.cpp:417
std::shared_ptr< class ImageSource > ImageSourceRef
Definition: Channel.h:33
Obj()
Definition: Texture.h:254
float getLeft() const
These return the right thing even when the texture coordinate space is flipped.
Definition: Texture.cpp:818
float mMaxU
Definition: Texture.h:259
Texture::Format mFormat
Definition: Texture.h:293
GLenum getMinFilter() const
Returns the texture minifying function, which is used whenever the pixel being textured maps to an ar...
Definition: Texture.h:234
virtual SurfaceChannelOrder getChannelOrder(bool alpha) const
Definition: Texture.h:315
void reset()
Emulates shared_ptr-like behavior.
Definition: Texture.h:275
static TextureRef create(GLenum target, GLuint textureId, int width, int height, bool doNotDispose)
Constructs a Texture based on an externally initialized OpenGL texture. doNotDispose specifies whethe...
Definition: Texture.h:61
static void TextureCacheDeallocator(void *aDeallocatorRefcon)
Definition: Texture.cpp:1018
static bool dataFormatHasAlpha(GLint dataFormat)
Returns whether a given OpenGL dataFormat contains an alpha channel.
Definition: Texture.cpp:531
bool mMipmapping
Definition: Texture.h:242
void setMinFilter(GLenum minFilter)
Sets the filtering behavior when a texture is displayed at a lower resolution than its native resolut...
Definition: Texture.cpp:772
std::shared_ptr< Obj > mObj
Definition: Texture.h:301
GLint mInternalFormat
Definition: Texture.h:243
unsigned int GLenum
Definition: gldx.h:46
GLenum getWrapT() const
Returns the vertical wrapping behavior for the texture coordinates.
Definition: Texture.h:232
float getRight() const
Definition: Texture.cpp:823
static TextureRef create(const Channel32f &channel, Format format=Format())
Constructs a Texture based on the contents of channel.
Definition: Texture.h:57
GLuint mTextureID
Definition: Texture.h:262
Vec2< int > Vec2i
Definition: Vector.h:1313
float getTop() const
Definition: Texture.cpp:828
TextureDataExc(const std::string &log)
Definition: Texture.cpp:36
void setAutoInternalFormat()
Sets the Texture's internal format to be automatically selected based on the context.
Definition: Texture.h:202