cinder::ChannelT< T > Class Template Reference

A single channel of image data, either a color channel of a Surface or a grayscale image. Implicitly shared object. More...

#include <Channel.h>

List of all members.

Classes

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

Public Member Functions

 ChannelT ()
 Constructs an empty Channel, which is the equivalent of NULL and should not be used directly.
 ChannelT (int32_t width, int32_t height)
 Allocates and owns a contiguous block of memory that is sizeof(T) * width * height.
 ChannelT (int32_t width, int32_t height, int32_t rowBytes, uint8_t increment, T *data)
 Does not allocate or own memory pointed to by data.
 ChannelT (ImageSourceRef imageSource)
 Creates a ChannelT by loading from an ImageSource imageSource.
 operator ImageSourceRef () const
ChannelT clone (bool copyPixels=true) const
 Returns a new Channel which is a duplicate. If copyPixels the pixel values are copied, otherwise the clone's pixels remain uninitialized.
ChannelT clone (const Area &area, bool copyPixels=true) const
 Returns a new Channel which is a duplicate of an Area area. If copyPixels the pixel values are copied, otherwise the clone's pixels remain uninitialized.
int32_t getWidth () const
 Returns the width of the Channel in pixels.
int32_t getHeight () const
 Returns the height of the Channel in pixels.
Vec2i getSize () const
 Returns the size of the Channel in pixels.
float getAspectRatio () const
 Returns the Channel aspect ratio, which is its width / height.
Area getBounds () const
 Returns the bounding Area of the Channel in pixels: [0,0]-(width,height).
int32_t getRowBytes () const
 Returns the width of a row of the Channel measured in bytes, which is not necessarily getWidth() * getPixelInc().
uint8_t getIncrement () const
 Returns the amount to increment a T* to increment by a pixel. For a planar channel this is 1, but for a Channel of a Surface this might be 3 or 4.
bool isPlanar () const
 Returns whether the Channel represents a tightly packed array of values. This will be false if the Channel is a member of a Surface. Analogous to getIncrement() == 1
T * getData ()
 Returns a pointer to the data of the Channel's first pixel. Result is a uint8_t* for Channel8u and a float* for Channel32f.
const T * getData () const
 Returns a const pointer to the data of the Channel's first pixel. Result is a uint8_t* for Channel8u and a float* for Channel32f.
T * getData (const Vec2i &offset)
 Returns a pointer to the data of the Channel's pixel at offset. Result is a uint8_t* for Channel8u and a float* for Channel32f.
const T * getData (const Vec2i &offset) const
 Returns a const pointer to the data of the Channel's pixel at offset. Result is a uint8_t* for Channel8u and a float* for Channel32f.
T * getData (int32_t x, int32_t y)
 Returns a pointer to the data of the Channel's pixel at (x, y). Result is a uint8_t* for Channel8u and a float* for Channel32f.
const T * getData (int32_t x, int32_t y) const
 Returns a const pointer to the data of the Channel's pixel at (x, y). Result is a uint8_t* for Channel8u and a float* for Channel32f.
getValue (Vec2i pos) const
 Convenience method for getting a single value at pixel pos. For performance-sensitive code consider Channel::Iter instead. Exhibits clamping behavior when outside Channel boundaries.
void setValue (Vec2i pos, T v)
 Convenience method for setting a single value v at pixel pos. For performance-sensitive code consider Channel::Iter instead. Exhibits clamping behavior when outside Channel boundaries.
void copyFrom (const ChannelT< T > &srcChannel, const Area &srcArea, const Vec2i &relativeOffset=Vec2i::zero())
 Copies the Area srcArea of the Channel srcChannel to this Channel. The destination Area is srcArea offset by relativeOffset.
areaAverage (const Area &area) const
 Returns an averaged value for the Area defined by area.
void setDeallocator (void(*aDeallocatorFunc)(void *), void *aDeallocatorRefcon)
Iter getIter ()
 Returns an Iter which iterates the entire Channel.
Iter getIter (const Area &area)
 Returns an Iter which iterates the Area area.
ConstIter getIter () const
 Returns a ConstIter which iterates the entire Channel.
ConstIter getIter (const Area &area) const
 Returns a ConstIter which iterates the Area area.

Protected Attributes

std::shared_ptr< Obj > mObj

Detailed Description

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

A single channel of image data, either a color channel of a Surface or a grayscale image. Implicitly shared object.

A Channel can be thought of as a grayscale image, and frequently is simply that. Its name comes from the most common use case, which is to represent a single color channel of an image, such as the red, green, blue or alpha channel of a Surface. To acquire one of these color channels from a Surface, use getChannelRed(), getChannelBlue(), getChannelGreen() or getChannelAlpha().

Channel rChan = surf.getChannelRed(); // references just the red values of surf's pixels


The code below constructs a Channel which is a grayscale image independent of a Surface that is 640x480 pixels:

Channel chan( 640, 480 );


You can also construct a Channel using an ImageSource, such as the result of loadImage(). In the code below, myImage will hold a grayscale version of the PNG file stored at the relative path "myImage.png":

Channel myImage = loadImage( "myImage.png" );

Channels come in two primary configurations, the traditional 8-bits unsigned integer represented by Channel8u, and a 32-bit float version suitable for high dynamic range images, represented by Channel32f. Channel is a short-hand synonym for Channel8u.

See also:
Images in Cinder

Constructor & Destructor Documentation

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

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

template<typename T >
cinder::ChannelT< T >::ChannelT ( int32_t  width,
int32_t  height 
)

Allocates and owns a contiguous block of memory that is sizeof(T) * width * height.

template<typename T>
cinder::ChannelT< T >::ChannelT ( int32_t  width,
int32_t  height,
int32_t  rowBytes,
uint8_t  increment,
T *  data 
)

Does not allocate or own memory pointed to by data.

template<typename T>
cinder::ChannelT< T >::ChannelT ( ImageSourceRef  imageSource  ) 

Creates a ChannelT by loading from an ImageSource imageSource.


Member Function Documentation

template<typename T >
cinder::ChannelT< T >::operator ImageSourceRef (  )  const
template<typename T >
ChannelT< T > cinder::ChannelT< T >::clone ( bool  copyPixels = true  )  const

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

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

Returns a new Channel 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>
int32_t cinder::ChannelT< T >::getWidth (  )  const

Returns the width of the Channel in pixels.

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

Returns the height of the Channel in pixels.

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

Returns the size of the Channel in pixels.

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

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

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

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

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

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

template<typename T>
uint8_t cinder::ChannelT< T >::getIncrement (  )  const

Returns the amount to increment a T* to increment by a pixel. For a planar channel this is 1, but for a Channel of a Surface this might be 3 or 4.

template<typename T>
bool cinder::ChannelT< T >::isPlanar (  )  const

Returns whether the Channel represents a tightly packed array of values. This will be false if the Channel is a member of a Surface. Analogous to getIncrement() == 1

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

Returns a pointer to the data of the Channel's first pixel. Result is a uint8_t* for Channel8u and a float* for Channel32f.

template<typename T>
const T* cinder::ChannelT< T >::getData (  )  const

Returns a const pointer to the data of the Channel's first pixel. Result is a uint8_t* for Channel8u and a float* for Channel32f.

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

Returns a pointer to the data of the Channel's pixel at offset. Result is a uint8_t* for Channel8u and a float* for Channel32f.

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

Returns a const pointer to the data of the Channel's pixel at offset. Result is a uint8_t* for Channel8u and a float* for Channel32f.

template<typename T>
T* cinder::ChannelT< T >::getData ( int32_t  x,
int32_t  y 
)

Returns a pointer to the data of the Channel's pixel at (x, y). Result is a uint8_t* for Channel8u and a float* for Channel32f.

template<typename T>
const T* cinder::ChannelT< T >::getData ( int32_t  x,
int32_t  y 
) const

Returns a const pointer to the data of the Channel's pixel at (x, y). Result is a uint8_t* for Channel8u and a float* for Channel32f.

template<typename T>
T cinder::ChannelT< T >::getValue ( Vec2i  pos  )  const

Convenience method for getting a single value at pixel pos. For performance-sensitive code consider Channel::Iter instead. Exhibits clamping behavior when outside Channel boundaries.

template<typename T>
void cinder::ChannelT< T >::setValue ( Vec2i  pos,
v 
)

Convenience method for setting a single value v at pixel pos. For performance-sensitive code consider Channel::Iter instead. Exhibits clamping behavior when outside Channel boundaries.

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

Copies the Area srcArea of the Channel srcChannel to this Channel. The destination Area is srcArea offset by relativeOffset.

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

Returns an averaged value for the Area defined by area.

template<typename T >
void cinder::ChannelT< T >::setDeallocator ( void(*)(void *)  aDeallocatorFunc,
void *  aDeallocatorRefcon 
)

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

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

Returns an Iter which iterates the entire Channel.

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

Returns an Iter which iterates the Area area.

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

Returns a ConstIter which iterates the entire Channel.

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

Returns a ConstIter which iterates the Area area.


Member Data Documentation

template<typename T>
std::shared_ptr<Obj> cinder::ChannelT< T >::mObj [protected]

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