ofPixels

class methods

global functions

ofPixels is an object for working with blocks of pixels, those pixels can be copied from an image that you've loaded, something that you've drawn using ofGraphics, or a ofVideoGrabber instance. You can create an image from pixels, using on ofPixels object like so:

ofPixels p;
ofLoadImage(p, "pathToImage.jpg");

ofPixels represents pixels data on the CPU as opposed to an ofTexture which represents pixel data on the GPU. They can easily be made inter-operational though:

ofTexture tex;
// do some stuff with t
ofPixels pix;
tex.readToPixels(pix); // now all the pixels from tex are in pix

You can access the pixels in an ofPixels object with the [] operator.

ofPixels pix;
// put some stuff in the pixels
int i = 0;
while( i < pix.size()) {
    char c = pix[i];
    i++;
}

You can think of the ofPixels as the CPU side representation of pixel data that can be sent to the GPU as an ofTexture object. To draw pixels, you need to put them into an ofTexture and to manipulate an ofTextures pixel data you need an ofPixels object.

Documentation from code comments


A class representing a collection of pixels.

ofPixels_()

ofPixels_::ofPixels_()

Documentation from code comments


\name Construction And Allocation {

ofPixels_(...)

ofPixels_::ofPixels_(const ofPixels_< PixelType > &mom)

ofPixels_(...)

ofPixels_::ofPixels_(const ofPixels_< SrcType > &mom)

ofPixels_(...)

ofPixels_::ofPixels_(ofPixels_< PixelType > &&mom)

~ofPixels_()

ofPixels_::~ofPixels_()

allocate(...)

void ofPixels_::allocate(size_t w, size_t h, ofImageType imageType)

ofImageType:

OF_IMAGE_GRAYSCALE

OF_IMAGE_COLOR

OF_IMAGE_COLOR_ALPHA

Documentation from code comments


Allocates space for pixel data

The imageType can be one of the following:

OF_IMAGE_GRAYSCALE
OF_IMAGE_COLOR
OF_IMAGE_COLOR_ALPHA

Parameters:

w Width of pixel array

h Height of pixel array

imageType ofImageType defining number of channels per pixel

allocate(...)

void ofPixels_::allocate(size_t w, size_t h, ofPixelFormat pixelFormat)

ofPixelFormat:

OF_PIXELS_RGB

OF_PIXELS_RGBA

OF_PIXELS_BGRA

OF_PIXELS_MONO

Documentation from code comments


Allocates space for pixel data

The pixelFormat can be one of the following:

OF_PIXELS_RGB
OF_PIXELS_RGBA
OF_PIXELS_BGRA
OF_PIXELS_MONO

Parameters:

w Width of pixel array

h Height of pixel array

pixelFormat ofPixelFormat defining number of channels per pixel

allocate(...)

void ofPixels_::allocate(size_t w, size_t h, size_t channels)

Allocates space for pixel data of the given width (w), height (h) and number of channels (channels). If an ofImageType or ofPixelFormat is passed in, it will allocate based on the required number of channels.

Documentation from code comments


Allocates space for pixel data

Parameters:

w Width of pixel array

h Height of pixel array

channels Number of channels per pixel

begin()

ofPixels_::iterator ofPixels_::begin()

begin()

ofPixels_::const_iterator ofPixels_::begin()

blendInto(...)

bool ofPixels_::blendInto(ofPixels_< PixelType > &dst, size_t x, size_t y)

bytesFromPixelFormat(...)

size_t ofPixels_::bytesFromPixelFormat(size_t w, size_t h, ofPixelFormat format)

clear()

void ofPixels_::clear()

This clears all the data from the ofPixels objects. After calling this you'll need to allocate the ofPixels object again to use it.

crop(...)

void ofPixels_::crop(size_t x, size_t y, size_t width, size_t height)

This crops the pixels to a new width and height. As a word of caution this reallocates memory and can be a bit expensive if done a lot.

cropTo(...)

void ofPixels_::cropTo(ofPixels_< PixelType > &toPix, size_t x, size_t y, size_t width, size_t height)

This crops the pixels into the ofPixels reference passed in by toPix. at the x and y and with the new width and height. As a word of caution this reallocates memory and can be a bit expensive if done a lot.

end()

ofPixels_::iterator ofPixels_::end()

end()

ofPixels_::const_iterator ofPixels_::end()

getBitsPerChannel()

size_t ofPixels_::getBitsPerChannel()

This is how large each channel of a pixels is, ofPixels objects that store pixel data as unsigned char are smaller than ofPixels objects that store pixel data as floats. This returns bit, not bytes, so you'll probably see ofPixels as 32 and ofPixels as 8.

getBitsPerPixel()

size_t ofPixels_::getBitsPerPixel()

Documentation from code comments


Get number of bits per pixel

If you have RGB pixel data, this will return 24, if you have RGBA, you'll have 32, if you have grayscale, this will return 8.

getBytesPerChannel()

size_t ofPixels_::getBytesPerChannel()

This is how large each channel of a pixels is, ofPixels objects that store pixel data as unsigned char are smaller than ofPixels objects that store pixel data as floats. This returns bytes, not bits, so you'll probably see ofPixels as 4 and ofPixels as 1.

getBytesPerPixel()

size_t ofPixels_::getBytesPerPixel()

Returns the number of the pixels.

getBytesStride()

size_t ofPixels_::getBytesStride()

getChannel(...)

ofPixels_< PixelType > ofPixels_::getChannel(size_t channel)

This returns a single channel, for instance, the Red pixel values, from the ofPixels object, this gives you a grayscale representation of that one channel.

    ofPixels rpix = pix.getChannel(0);
    ofPixels gpix = pix.getChannel(1);
    ofPixels bpix = pix.getChannel(2);

getColor(...)

ofColor_< PixelType > ofPixels_::getColor(size_t index)

Documentation from code comments


Get the color at a specific index

getColor(...)

ofColor_< PixelType > ofPixels_::getColor(size_t x, size_t y)

This method returns the ofColor that the pixels contains at an x, y pair:

ofColor c = pix.getColor(mouseX, mouseY);

Documentation from code comments


Get the color at a x,y position

getConstLine(...)

ofPixels_::ConstLine ofPixels_::getConstLine(size_t line)

getConstLines()

ofPixels_::ConstLines ofPixels_::getConstLines()

getConstLines(...)

ofPixels_::ConstLines ofPixels_::getConstLines(size_t first, size_t numLines)

getConstPixelsIter()

ofPixels_::ConstPixels ofPixels_::getConstPixelsIter()

getData()

PixelType * ofPixels_::getData()

Documentation from code comments


Retrieves pixel data from the ofPixel object.

Returns: A raw pointer to the pixel data.

getData()

const PixelType * ofPixels_::getData()

getHeight()

size_t ofPixels_::getHeight()

Returns the height of the pixels.

getImageType()

ofImageType ofPixels_::getImageType()

Returns what image type the ofPixels object is.

Documentation from code comments


Get the type of the image

Returns: One of the following types: OF_IMAGE_GRAYSCALE, OF_IMAGE_COLOR, OF_IMAGE_COLOR_ALPHA

getLine(...)

ofPixels_::Line ofPixels_::getLine(size_t line)

getLines()

ofPixels_::Lines ofPixels_::getLines()

getLines(...)

ofPixels_::Lines ofPixels_::getLines(size_t first, size_t numLines)

getNumChannels()

size_t ofPixels_::getNumChannels()

This returns the number of channels that the ofPixels object contains. RGB is 3 channels, RGBA is 4, and grayscale is 1.

getNumPlanes()

size_t ofPixels_::getNumPlanes()

getPixelFormat()

ofPixelFormat ofPixels_::getPixelFormat()

getPixelIndex(...)

size_t ofPixels_::getPixelIndex(size_t x, size_t y)

This method gives you the index of the pixel at x,y. For instance:

ofColor yellow = ofColor::yellow;
int ind = pix.getPixelIndex(mouseX, mouseY);
pix.setColor(ind, yellow);

getPixelsIter()

ofPixels_::Pixels ofPixels_::getPixelsIter()

getPlane(...)

ofPixels_< PixelType > ofPixels_::getPlane(size_t plane)

getTotalBytes()

size_t ofPixels_::getTotalBytes()

getWidth()

size_t ofPixels_::getWidth()

Returns the width of the pixels.

isAllocated()

bool ofPixels_::isAllocated()

Returns whether memory has been allocated for an ofPixels object or not. Many operations like copying pixels, etc, automatically allocate the memory needed, but it's sometimes good to check.

mirror(...)

void ofPixels_::mirror(bool vertically, bool horizontal)

This reflects the pixels across the vertical and/or horizontal axis.

Documentation from code comments


Mirror the pixels across the vertical and/or horizontal axis.

Parameters:

vertically Set to true to mirror vertically

horizontal Set to true to mirror horizontal

mirrorTo(...)

void ofPixels_::mirrorTo(ofPixels_< PixelType > &dst, bool vertically, bool horizontal)

operator=(...)

ofPixels_< PixelType > & ofPixels_::operator=(const ofPixels_< PixelType > &mom)

operator=(...)

ofPixels_< PixelType > & ofPixels_::operator=(const ofPixels_< SrcType > &mom)

operator=(...)

ofPixels_< PixelType > & ofPixels_::operator=(ofPixels_< PixelType > &&mom)

operator[](...)

const PixelType & ofPixels_::operator[](size_t pos)

Documentation from code comments


Provides access to each channel of each pixel. If you have RGB pixel data, then you'll have 3 values for each pixel, if you have RGBA, you'll have 4

operator[](...)

PixelType & ofPixels_::operator[](size_t pos)

Provides access to each channel of each pixel. If you have RGB pixel data, then you'll have 3 values for each pixel, if you have RGBA, you'll have 4.

pasteInto(...)

bool ofPixels_::pasteInto(ofPixels_< PixelType > &dst, size_t x, size_t y)

This pastes the ofPixels object into another ofPixels object at the specified index, copying data from the ofPixels that the method is being called on to the ofPixels object at &dst. If the data being copied doesn't fit into the dst then the image is cropped.

ofLoadImage(footballPixels, "two.jpg");
ofLoadImage(fujiPixels, "one.jpg");
fujiTex.loadData(footballPixels);
footballTex.loadData(fujiPixels);
footballPixels.pasteInto(fujiPixels, 150, 100); // now fujiPixels is altered
mixtureTex.loadData(fujiPixels);

Drawing the three textures here you can see the ball cropped into the mountain: crop_demo

Documentation from code comments


Paste the ofPixels object into another ofPixels object at the specified index, copying data from the ofPixels that the method is being called on to the ofPixels object at &dst. If the data being copied doesn't fit into the destination then the image is cropped.

pixelBitsFromPixelFormat(...)

size_t ofPixels_::pixelBitsFromPixelFormat(ofPixelFormat format)

rbegin()

ofPixels_::reverse_iterator ofPixels_::rbegin()

rbegin()

ofPixels_::const_reverse_iterator ofPixels_::rbegin()

rend()

ofPixels_::reverse_iterator ofPixels_::rend()

rend()

ofPixels_::const_reverse_iterator ofPixels_::rend()

resize(...)

bool ofPixels_::resize(size_t dstWidth, size_t dstHeight, ofInterpolationMethod interpMethod=OF_INTERPOLATE_NEAREST_NEIGHBOR)

This resizes the ofPixels instance to the dstHeight and dstWidth. The options for the interpolation methods are as follows: OF_INTERPOLATE_NEAREST_NEIGHBOR =1 OF_INTERPOLATE_BILINEAR =2 OF_INTERPOLATE_BICUBIC =3

resizeTo(...)

bool ofPixels_::resizeTo(ofPixels_< PixelType > &dst, ofInterpolationMethod interpMethod=OF_INTERPOLATE_NEAREST_NEIGHBOR)

This resizes the ofPixels instance to the size of the ofPixels object passed in dst. The options for the interpolation methods are as follows: OF_INTERPOLATE_NEAREST_NEIGHBOR =1 OF_INTERPOLATE_BILINEAR =2 OF_INTERPOLATE_BICUBIC =3

rotate90(...)

void ofPixels_::rotate90(int nClockwiseRotations)

crop to a new width and height, this reallocates memory.

rotate90To(...)

void ofPixels_::rotate90To(ofPixels_< PixelType > &dst, int nClockwiseRotations)

set(...)

void ofPixels_::set(PixelType val)

Documentation from code comments


} \name Set Pixel Data {

set(...)

void ofPixels_::set(size_t channel, PixelType val)

setChannel(...)

void ofPixels_::setChannel(size_t channel, const ofPixels_< PixelType > channelPixels)

This sets all the pixel data for a single channel, for instance, the Red pixel values, from an ofPixels object assumed to be a grayscale representation of the data that should go into that one channel.

setColor(...)

void ofPixels_::setColor(const ofColor_< PixelType > &color)

Documentation from code comments


Set the color of all pixels

setColor(...)

void ofPixels_::setColor(size_t index, const ofColor_< PixelType > &color)

Documentation from code comments


Set the color of the pixel at a specific index

setColor(...)

void ofPixels_::setColor(size_t x, size_t y, const ofColor_< PixelType > &color)

Sets the color of the pixel at the x,y location.

setFromAlignedPixels(...)

void ofPixels_::setFromAlignedPixels(const PixelType *newPixels, size_t width, size_t height, ofPixelFormat pixelFormat, int strides)

Documentation from code comments


used to copy i420 pixels from gstreamer when (width % 4) != 0

setFromAlignedPixels(...)

void ofPixels_::setFromAlignedPixels(const PixelType *newPixels, size_t width, size_t height, ofPixelFormat pixelFormat, size_t stride)

setFromAlignedPixels(...)

void ofPixels_::setFromAlignedPixels(const PixelType *newPixels, size_t width, size_t height, size_t channels, size_t stride)

setFromExternalPixels(...)

void ofPixels_::setFromExternalPixels(PixelType *newPixels, size_t w, size_t h, ofPixelFormat pixelFormat)

setFromExternalPixels(...)

void ofPixels_::setFromExternalPixels(PixelType *newPixels, size_t w, size_t h, size_t channels)

setFromPixels(...)

void ofPixels_::setFromPixels(const PixelType *newPixels, size_t w, size_t h, ofImageType type)

setFromPixels(...)

void ofPixels_::setFromPixels(const PixelType *newPixels, size_t w, size_t h, ofPixelFormat pixelFormat)

setFromPixels(...)

void ofPixels_::setFromPixels(const PixelType *newPixels, size_t w, size_t h, size_t channels)

setImageType(...)

void ofPixels_::setImageType(ofImageType imageType)

Documentation from code comments


Changes the image type for the ofPixels object

Parameters:

imageType Can be one of the following: OF_IMAGE_GRAYSCALE, OF_IMAGE_COLOR, OF_IMAGE_COLOR_ALPHA

setNumChannels(...)

void ofPixels_::setNumChannels(size_t numChannels)

size()

size_t ofPixels_::size()

This gives you the number of values that the ofPixels object contains, so an RGB data 400x400 would be 480,000, whereas RGBA data of the same dimensions would be 640,000.

swap(...)

void ofPixels_::swap(ofPixels_< PixelType > &pix)

swapRgb()

void ofPixels_::swapRgb()

As implemented right now, this method swaps the R and B channels of an image, leaving the G and A channels as is.

Documentation from code comments


Swaps the R and B channels of an image, leaving the G and A channels as is.

ofToString(...)

string ofToString(const ofPixelFormat &pixelType)

ofToString(...)

string ofToString(const T &v)

Documentation from code comments


\section String Conversion Convert a value to a string.

ofToString does its best to convert any value to a string. If the data type implements a stream << operator, then it will be converted.

Example:

        std::string str = "framerate is ";
        str += ofToString(ofGetFrameRate()) + " fps";
        // The string now containes something like "framerate is 60 fps".

\tparam T The data type of the value to convert to a string.

Parameters:

value The value to convert to a string.

Returns: A string representing the value or an empty string on failure.

If you have any doubt about the usage of this module you can ask in the forum.

If you want to contribute better documentation or start documenting this section you can do so here

If you find anything wrong with this docs you can report any error by opening an issue