cinder::SurfaceT< T > Class Template Reference

An in-memory representation of an image. Implicitly shared object. More...

#include <Surface.h>

List of all members.

Classes

class  ConstIter
 Convenience class for iterating the pixels of a Surface. The iteration is const, performing read-only operations on the Surface. More...
class  Iter
 Convenience class for iterating the pixels of a Surface. More...

Public Member Functions

 SurfaceT ()
 Constructs an empty Surface, which is the equivalent of NULL and should not be used directly.
 SurfaceT (int32_t width, int32_t height, bool alpha, SurfaceChannelOrder channelOrder=SurfaceChannelOrder::UNSPECIFIED)
 Creates a Surface object that is height and width pixels, an alpha channel based on alpha, and the channel order channelOrder.
 SurfaceT (int32_t width, int32_t height, bool alpha, const SurfaceConstraints &constraints)
 SurfaceT (T *data, int32_t width, int32_t height, int32_t rowBytes, SurfaceChannelOrder channelOrder)
 Constructs a surface from the memory pointed to by data. Does not assume ownership of the memory in data, which consequently should not be freed while the Surface is still in use.
 SurfaceT (ImageSourceRef imageSource, const SurfaceConstraints &constraints=SurfaceConstraintsDefault(), boost::tribool alpha=boost::logic::indeterminate)
 Creates a Surface object from an ImageSource, for instance from the result of a loadImage() call.
 operator ImageSourceRef () const
 operator ImageTargetRef ()
int32_t getWidth () const
 Returns the width of the Surface in pixels.
int32_t getHeight () const
 Returns the height of the Surface in pixels.
Vec2i getSize () const
 Returns the size of the Surface in pixels.
float getAspectRatio () const
 Returns the Surface aspect ratio, which is its width / height.
Area getBounds () const
 Returns the bounding Area of the Surface in pixels: [0,0]-(width,height)
bool hasAlpha () const
 Returns whether the Surface contains an alpha channel.
bool isPremultiplied () const
 Returns whether the Surface color data is premultiplied by its alpha channel or not.
bool setPremultiplied (bool premult=true) const
 Sets whether the Surface color data should be interpreted as being premultiplied by its alpha channel or not.
int32_t getRowBytes () const
 Returns the width of a row of the Surface measured in bytes, which is not necessarily getWidth() * getPixelInc()
uint8_t getPixelInc () const
 Returns the amount to increment a T* to increment by a pixel. Analogous to the number of channels, which is either 3 or 4.
SurfaceT clone (bool copyPixels=true) const
 Returns a new Surface which is a duplicate. If copyPixels the pixel values are copied, otherwise the clone's pixels remain uninitialized.
SurfaceT clone (const Area &area, bool copyPixels=true) const
 Returns a new Surface which is a duplicate of an Area area. If copyPixels the pixel values are copied, otherwise the clone's pixels remain uninitialized.
T * getData ()
 Retuns the raw data of an image as a pointer to either uin8t_t values in the case of a Surface8u or floats in the case of a Surface32f.
const T * getData () const
T * getData (const Vec2i &offset)
const T * getData (const Vec2i &offset) const
T * getDataRed (const Vec2i &offset)
 Returns a pointer to the red channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f.
const T * getDataRed (const Vec2i &offset) const
T * getDataGreen (const Vec2i &offset)
 Returns a pointer to the green channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f.
const T * getDataGreen (const Vec2i &offset) const
T * getDataBlue (const Vec2i &offset)
 Returns a pointer to the blue channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f.
const T * getDataBlue (const Vec2i &offset) const
T * getDataAlpha (const Vec2i &offset)
 Returns a pointer to the alpha channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f. Undefined for Surfaces without an alpha channel.
const T * getDataAlpha (const Vec2i &offset) const
void setDeallocator (void(*aDeallocatorFunc)(void *), void *aDeallocatorRefcon)
const SurfaceChannelOrdergetChannelOrder () const
 Returns the channel order of the Surface, the in-memory ordering of the channels of each pixel.
uint8_t getRedOffset () const
 Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 0.
uint8_t getGreenOffset () const
 Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 1.
uint8_t getBlueOffset () const
 Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 2.
uint8_t getAlphaOffset () const
 Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 3. Returns SurfaceChannelOrder::INVALID in the absence of an alpha channel.
void setChannelOrder (const SurfaceChannelOrder &aChannelOrder)
 Sets the channel order of the Surface, the in-memory ordering of the channels of each pixel. Call does not modify any pixel data, but does modify its interpretation.
ChannelT< T > & getChannel (uint8_t channelIndex)
 Returns a reference to a Channel channelIndex indexed according to how the channels are arranged per the SurfaceChannelOrder.
const ChannelT< T > & getChannel (uint8_t channelIndex) const
 Returns a const reference to a Channel channelIndex indexed according to how the channels are arranged per the SurfaceChannelOrder.
ChannelT< T > & getChannelRed ()
 Returns a reference to the red Channel of the Surface.
ChannelT< T > & getChannelGreen ()
 Returns a reference to the green Channel of the Surface.
ChannelT< T > & getChannelBlue ()
 Returns a reference to the blue Channel of the Surface.
ChannelT< T > & getChannelAlpha ()
 Returns a reference to the alpha Channel of the Surface.
const ChannelT< T > & getChannelRed () const
 Returns a const reference to the red Channel of the Surface.
const ChannelT< T > & getChannelGreen () const
 Returns a const reference to the green Channel of the Surface.
const ChannelT< T > & getChannelBlue () const
 Returns a const reference to the blue Channel of the Surface.
const ChannelT< T > & getChannelAlpha () const
 Returns a const reference to the alpha Channel of the Surface.
ColorAT< T > getPixel (Vec2i pos) const
 Convenience method for getting a single pixel. For performance-sensitive code consider Surface::Iter instead.
void setPixel (Vec2i pos, const ColorT< T > &c)
 Convenience method for setting a single pixel. For performance-sensitive code consider Surface::Iter instead.
void setPixel (Vec2i pos, const ColorAT< T > &c)
 Convenience method for setting a single pixel. For performance-sensitive code consider Surface::Iter instead.
void copyFrom (const SurfaceT< T > &srcSurface, const Area &srcArea, const Vec2i &relativeOffset=Vec2i::zero())
 Copies the Area srcArea of the Surface srcSurface to this Surface. The destination Area is srcArea offset by relativeOffset.
ColorT< T > areaAverage (const Area &area) const
 Returns an averaged color for the Area defined by area.
Iter getIter ()
 Returns an Iter which iterates the entire Surface.
Iter getIter (const Area &area)
 Returns an Iter which iterates the Area area.
ConstIter getIter () const
 Returns a ConstIter which iterates the entire Surface.
ConstIter getIter (const Area &area) const
 Returns a ConstIter which iterates the Area area.

Detailed Description

template<typename T>
class cinder::SurfaceT< T >

An in-memory representation of an image. Implicitly shared object.

A Surface always contains red, green and blue data, along with an optional alpha channel.

Surfaces come in two primary configurations, the traditional 8-bits per channel represented by Surface8u, and a float per channel, suitable for high dynamic range images, represented by Surface32f. Surface is a short-hand synonym for Surface8u.

Surfaces are a CPU-based image representation, and must be converted appropriately to be drawn using the GPU. For example, to be used with OpenGL, the gl::Texture is a natural choice, and it can be constructed directly from a Surface.

To manipulate individual pixels of a Surface, the Surface::Iter class can be used.

To allocate a Surface that is 640x480 and has an alpha channel, use:
Surface mySurface( 640, 480, true );
A Surface can be created from an image file using the result of loadImage():
Surface bitmap( loadImage( "image.jpg" ) );

The pixels of each row of a Surface are stored in contiguous memory, and the start of each row is offset from the previous by the stride (measured in bytes) returned by getRowBytes(). Pixels can be ordered in memory in a number of configurations, specified using the SurfaceChannelOrder class.

See also:
Images in Cinder

Constructor & Destructor Documentation

template<typename T>
cinder::SurfaceT< T >::SurfaceT (  )

Constructs an empty Surface, which is the equivalent of NULL and should not be used directly.

template<typename T >
cinder::SurfaceT< T >::SurfaceT ( int32_t  width,
int32_t  height,
bool  alpha,
SurfaceChannelOrder  channelOrder = SurfaceChannelOrder::UNSPECIFIED 
)

Creates a Surface object that is height and width pixels, an alpha channel based on alpha, and the channel order channelOrder.

As an example, the following would create a 640x480 pixel surface with an alpha channel, and an RGBA channel order Surface32f mySurface( 640, 480, true, SurfaceChannelOrder::RGBA );

template<typename T >
cinder::SurfaceT< T >::SurfaceT ( int32_t  width,
int32_t  height,
bool  alpha,
const SurfaceConstraints constraints 
)
template<typename T>
cinder::SurfaceT< T >::SurfaceT ( T *  data,
int32_t  width,
int32_t  height,
int32_t  rowBytes,
SurfaceChannelOrder  channelOrder 
)

Constructs a surface from the memory pointed to by data. Does not assume ownership of the memory in data, which consequently should not be freed while the Surface is still in use.

template<typename T>
cinder::SurfaceT< T >::SurfaceT ( ImageSourceRef  imageSource,
const SurfaceConstraints constraints = SurfaceConstraintsDefault(),
boost::tribool  alpha = boost::logic::indeterminate 
)

Creates a Surface object from an ImageSource, for instance from the result of a loadImage() call.

To load an image from a resource, pass the result of the loadImage() call to the Surface constructor as shown below Surface mySurface = Surface( loadImage( loadResource( RES ) );


Member Function Documentation

template<typename T >
cinder::SurfaceT< T >::operator ImageSourceRef (  ) const
template<typename T >
cinder::SurfaceT< T >::operator ImageTargetRef (  )
template<typename T>
int32_t cinder::SurfaceT< T >::getWidth (  ) const

Returns the width of the Surface in pixels.

template<typename T>
int32_t cinder::SurfaceT< T >::getHeight (  ) const

Returns the height of the Surface in pixels.

template<typename T>
Vec2i cinder::SurfaceT< T >::getSize (  ) const

Returns the size of the Surface in pixels.

template<typename T>
float cinder::SurfaceT< T >::getAspectRatio (  ) const

Returns the Surface aspect ratio, which is its width / height.

template<typename T>
Area cinder::SurfaceT< T >::getBounds (  ) const

Returns the bounding Area of the Surface in pixels: [0,0]-(width,height)

template<typename T>
bool cinder::SurfaceT< T >::hasAlpha (  ) const

Returns whether the Surface contains an alpha channel.

template<typename T>
bool cinder::SurfaceT< T >::isPremultiplied (  ) const

Returns whether the Surface color data is premultiplied by its alpha channel or not.

template<typename T>
bool cinder::SurfaceT< T >::setPremultiplied ( bool  premult = true ) const

Sets whether the Surface color data should be interpreted as being premultiplied by its alpha channel or not.

template<typename T>
int32_t cinder::SurfaceT< T >::getRowBytes (  ) const

Returns the width of a row of the Surface measured in bytes, which is not necessarily getWidth() * getPixelInc()

template<typename T>
uint8_t cinder::SurfaceT< T >::getPixelInc (  ) const

Returns the amount to increment a T* to increment by a pixel. Analogous to the number of channels, which is either 3 or 4.

template<typename T >
SurfaceT< T > cinder::SurfaceT< T >::clone ( bool  copyPixels = true ) const

Returns a new Surface which is a duplicate. If copyPixels the pixel values are copied, otherwise the clone's pixels remain uninitialized.

template<typename T >
SurfaceT< T > cinder::SurfaceT< T >::clone ( const Area area,
bool  copyPixels = true 
) const

Returns a new Surface which is a duplicate of an Area area. If copyPixels the pixel values are copied, otherwise the clone's pixels remain uninitialized.

template<typename T>
T* cinder::SurfaceT< T >::getData (  )

Retuns the raw data of an image as a pointer to either uin8t_t values in the case of a Surface8u or floats in the case of a Surface32f.

template<typename T>
const T* cinder::SurfaceT< T >::getData (  ) const
template<typename T>
T* cinder::SurfaceT< T >::getData ( const Vec2i offset )
template<typename T>
const T* cinder::SurfaceT< T >::getData ( const Vec2i offset ) const
template<typename T>
T* cinder::SurfaceT< T >::getDataRed ( const Vec2i offset )

Returns a pointer to the red channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f.

template<typename T>
const T* cinder::SurfaceT< T >::getDataRed ( const Vec2i offset ) const
template<typename T>
T* cinder::SurfaceT< T >::getDataGreen ( const Vec2i offset )

Returns a pointer to the green channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f.

template<typename T>
const T* cinder::SurfaceT< T >::getDataGreen ( const Vec2i offset ) const
template<typename T>
T* cinder::SurfaceT< T >::getDataBlue ( const Vec2i offset )

Returns a pointer to the blue channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f.

template<typename T>
const T* cinder::SurfaceT< T >::getDataBlue ( const Vec2i offset ) const
template<typename T>
T* cinder::SurfaceT< T >::getDataAlpha ( const Vec2i offset )

Returns a pointer to the alpha channel data of the pixel located at offset. Result is a uint8_t* for Surface8u and a float* for Surface32f. Undefined for Surfaces without an alpha channel.

template<typename T>
const T* cinder::SurfaceT< T >::getDataAlpha ( const Vec2i offset ) const
template<typename T >
void cinder::SurfaceT< T >::setDeallocator ( void(*)(void *)  aDeallocatorFunc,
void *  aDeallocatorRefcon 
)

Sets the deallocator, an optional callback which will fire upon the Surface::Obj's destruction. This is useful when a Surface is wrapping another API's image data structure whose lifetime is tied to the Surface's.

template<typename T>
const SurfaceChannelOrder& cinder::SurfaceT< T >::getChannelOrder (  ) const

Returns the channel order of the Surface, the in-memory ordering of the channels of each pixel.

template<typename T>
uint8_t cinder::SurfaceT< T >::getRedOffset (  ) const

Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 0.

template<typename T>
uint8_t cinder::SurfaceT< T >::getGreenOffset (  ) const

Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 1.

template<typename T>
uint8_t cinder::SurfaceT< T >::getBlueOffset (  ) const

Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 2.

template<typename T>
uint8_t cinder::SurfaceT< T >::getAlphaOffset (  ) const

Returns the in-memory offset relative to a pixel for the red data. For example, for RGBA, returns 3. Returns SurfaceChannelOrder::INVALID in the absence of an alpha channel.

template<typename T >
void cinder::SurfaceT< T >::setChannelOrder ( const SurfaceChannelOrder aChannelOrder )

Sets the channel order of the Surface, the in-memory ordering of the channels of each pixel. Call does not modify any pixel data, but does modify its interpretation.

template<typename T>
ChannelT<T>& cinder::SurfaceT< T >::getChannel ( uint8_t  channelIndex )

Returns a reference to a Channel channelIndex indexed according to how the channels are arranged per the SurfaceChannelOrder.

template<typename T>
const ChannelT<T>& cinder::SurfaceT< T >::getChannel ( uint8_t  channelIndex ) const

Returns a const reference to a Channel channelIndex indexed according to how the channels are arranged per the SurfaceChannelOrder.

template<typename T>
ChannelT<T>& cinder::SurfaceT< T >::getChannelRed (  )

Returns a reference to the red Channel of the Surface.

template<typename T>
ChannelT<T>& cinder::SurfaceT< T >::getChannelGreen (  )

Returns a reference to the green Channel of the Surface.

template<typename T>
ChannelT<T>& cinder::SurfaceT< T >::getChannelBlue (  )

Returns a reference to the blue Channel of the Surface.

template<typename T>
ChannelT<T>& cinder::SurfaceT< T >::getChannelAlpha (  )

Returns a reference to the alpha Channel of the Surface.

Undefined in the absence of an alpha channel.

template<typename T>
const ChannelT<T>& cinder::SurfaceT< T >::getChannelRed (  ) const

Returns a const reference to the red Channel of the Surface.

template<typename T>
const ChannelT<T>& cinder::SurfaceT< T >::getChannelGreen (  ) const

Returns a const reference to the green Channel of the Surface.

template<typename T>
const ChannelT<T>& cinder::SurfaceT< T >::getChannelBlue (  ) const

Returns a const reference to the blue Channel of the Surface.

template<typename T>
const ChannelT<T>& cinder::SurfaceT< T >::getChannelAlpha (  ) const

Returns a const reference to the alpha Channel of the Surface.

Undefined in the absence of an alpha channel.

template<typename T>
ColorAT<T> cinder::SurfaceT< T >::getPixel ( Vec2i  pos ) const

Convenience method for getting a single pixel. For performance-sensitive code consider Surface::Iter instead.

template<typename T>
void cinder::SurfaceT< T >::setPixel ( Vec2i  pos,
const ColorT< T > &  c 
)

Convenience method for setting a single pixel. For performance-sensitive code consider Surface::Iter instead.

template<typename T>
void cinder::SurfaceT< T >::setPixel ( Vec2i  pos,
const ColorAT< T > &  c 
)

Convenience method for setting a single pixel. For performance-sensitive code consider Surface::Iter instead.

template<typename T>
void cinder::SurfaceT< T >::copyFrom ( const SurfaceT< T > &  srcSurface,
const Area srcArea,
const Vec2i relativeOffset = Vec2i::zero() 
)

Copies the Area srcArea of the Surface srcSurface to this Surface. The destination Area is srcArea offset by relativeOffset.

template<typename T >
ColorT< T > cinder::SurfaceT< T >::areaAverage ( const Area area ) const

Returns an averaged color for the Area defined by area.

template<typename T>
Iter cinder::SurfaceT< T >::getIter (  )

Returns an Iter which iterates the entire Surface.

template<typename T>
Iter cinder::SurfaceT< T >::getIter ( const Area area )

Returns an Iter which iterates the Area area.

template<typename T>
ConstIter cinder::SurfaceT< T >::getIter (  ) const

Returns a ConstIter which iterates the entire Surface.

template<typename T>
ConstIter cinder::SurfaceT< T >::getIter ( const Area area ) const

Returns a ConstIter which iterates the Area area.


The documentation for this class was generated from the following files: