A single channel of image data, either a color channel of a Surface or a grayscale image. Implicitly shared object. More...
#include <Channel.h>
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. | |
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. | |
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. | |
T | 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 |
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":
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.
cinder::ChannelT< T >::ChannelT | ( | ) |
Constructs an empty Channel, which is the equivalent of NULL and should not be used directly.
cinder::ChannelT< T >::ChannelT | ( | int32_t | width, |
int32_t | height | ||
) |
Allocates and owns a contiguous block of memory that is sizeof(T) * width * height.
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.
cinder::ChannelT< T >::ChannelT | ( | ImageSourceRef | imageSource | ) |
Creates a ChannelT by loading from an ImageSource imageSource.
cinder::ChannelT< T >::operator ImageSourceRef | ( | ) | const |
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.
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.
int32_t cinder::ChannelT< T >::getWidth | ( | ) | const |
Returns the width of the Channel in pixels.
int32_t cinder::ChannelT< T >::getHeight | ( | ) | const |
Returns the height of the Channel in pixels.
Vec2i cinder::ChannelT< T >::getSize | ( | ) | const |
Returns the size of the Channel in pixels.
float cinder::ChannelT< T >::getAspectRatio | ( | ) | const |
Returns the Channel aspect ratio, which is its width / height.
Area cinder::ChannelT< T >::getBounds | ( | ) | const |
Returns the bounding Area of the Channel in pixels: [0,0]-(width,height)
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()
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
.
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
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.
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.
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.
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.
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.
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.
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.
void cinder::ChannelT< T >::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 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.
T cinder::ChannelT< T >::areaAverage | ( | const Area & | area | ) | const |
Returns an averaged value for the Area defined by area.
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.
Iter cinder::ChannelT< T >::getIter | ( | ) |
Returns an Iter which iterates the entire Channel.
Iter cinder::ChannelT< T >::getIter | ( | const Area & | area | ) |
Returns an Iter which iterates the Area area.
ConstIter cinder::ChannelT< T >::getIter | ( | ) | const |
Returns a ConstIter which iterates the entire Channel.
ConstIter cinder::ChannelT< T >::getIter | ( | const Area & | area | ) | const |
Returns a ConstIter which iterates the Area area.
std::shared_ptr<Obj> cinder::ChannelT< T >::mObj [protected] |