An in-memory representation of an image. Implicitly shared object. More...
#include <Surface.h>
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 SurfaceChannelOrder & | getChannelOrder () 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. |
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.
cinder::SurfaceT< T >::SurfaceT | ( | ) |
Constructs an empty Surface, which is the equivalent of NULL and should not be used directly.
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 );
cinder::SurfaceT< T >::SurfaceT | ( | int32_t | width, |
int32_t | height, | ||
bool | alpha, | ||
const SurfaceConstraints & | constraints | ||
) |
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.
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 ) );
cinder::SurfaceT< T >::operator ImageSourceRef | ( | ) | const |
cinder::SurfaceT< T >::operator ImageTargetRef | ( | ) |
int32_t cinder::SurfaceT< T >::getWidth | ( | ) | const |
Returns the width of the Surface in pixels.
int32_t cinder::SurfaceT< T >::getHeight | ( | ) | const |
Returns the height of the Surface in pixels.
Vec2i cinder::SurfaceT< T >::getSize | ( | ) | const |
Returns the size of the Surface in pixels.
float cinder::SurfaceT< T >::getAspectRatio | ( | ) | const |
Returns the Surface aspect ratio, which is its width / height.
Area cinder::SurfaceT< T >::getBounds | ( | ) | const |
Returns the bounding Area of the Surface in pixels: [0,0]-(width,height)
bool cinder::SurfaceT< T >::hasAlpha | ( | ) | const |
Returns whether the Surface contains an alpha channel.
bool cinder::SurfaceT< T >::isPremultiplied | ( | ) | const |
Returns whether the Surface color data is premultiplied by its alpha channel or not.
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.
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()
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.
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.
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.
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.
const T* cinder::SurfaceT< T >::getData | ( | ) | const |
T* cinder::SurfaceT< T >::getData | ( | const Vec2i & | offset ) |
const T* cinder::SurfaceT< T >::getData | ( | const Vec2i & | offset ) | const |
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.
const T* cinder::SurfaceT< T >::getDataRed | ( | const Vec2i & | offset ) | const |
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.
const T* cinder::SurfaceT< T >::getDataGreen | ( | const Vec2i & | offset ) | const |
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.
const T* cinder::SurfaceT< T >::getDataBlue | ( | const Vec2i & | offset ) | const |
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.
const T* cinder::SurfaceT< T >::getDataAlpha | ( | const Vec2i & | offset ) | const |
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.
const SurfaceChannelOrder& cinder::SurfaceT< T >::getChannelOrder | ( | ) | const |
Returns the channel order of the Surface, the in-memory ordering of the channels of each pixel.
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.
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.
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.
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.
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.
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.
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.
ChannelT<T>& cinder::SurfaceT< T >::getChannelRed | ( | ) |
Returns a reference to the red Channel of the Surface.
ChannelT<T>& cinder::SurfaceT< T >::getChannelGreen | ( | ) |
Returns a reference to the green Channel of the Surface.
ChannelT<T>& cinder::SurfaceT< T >::getChannelBlue | ( | ) |
Returns a reference to the blue Channel of the Surface.
ChannelT<T>& cinder::SurfaceT< T >::getChannelAlpha | ( | ) |
Returns a reference to the alpha Channel of the Surface.
Undefined in the absence of an alpha channel.
const ChannelT<T>& cinder::SurfaceT< T >::getChannelRed | ( | ) | const |
Returns a const reference to the red Channel of the Surface.
const ChannelT<T>& cinder::SurfaceT< T >::getChannelGreen | ( | ) | const |
Returns a const reference to the green Channel of the Surface.
const ChannelT<T>& cinder::SurfaceT< T >::getChannelBlue | ( | ) | const |
Returns a const reference to the blue Channel of the Surface.
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.
ColorAT<T> cinder::SurfaceT< T >::getPixel | ( | Vec2i | pos ) | const |
Convenience method for getting a single pixel. For performance-sensitive code consider Surface::Iter instead.
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.
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.
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.
ColorT< T > cinder::SurfaceT< T >::areaAverage | ( | const Area & | area ) | const |
Returns an averaged color for the Area defined by area.
Iter cinder::SurfaceT< T >::getIter | ( | ) |
Returns an Iter which iterates the entire Surface.
Iter cinder::SurfaceT< T >::getIter | ( | const Area & | area ) |
Returns an Iter which iterates the Area area.
ConstIter cinder::SurfaceT< T >::getIter | ( | ) | const |
Returns a ConstIter which iterates the entire Surface.
ConstIter cinder::SurfaceT< T >::getIter | ( | const Area & | area ) | const |
Returns a ConstIter which iterates the Area area.