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, \a 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.

The Iter class can be used to walk the pixels of a Channel using a nested for-loop, where the outer loop calls line(), and the inner calls pixel().

The code below implements an invert on the Area \a area of \a channel:


Channel::Iter iter = channel.getIter( area );
while( iter.line() ) {
	while( iter.pixel() ) {
		iter.v() = 255 - iter.v();
	}
}

In addition to v(), the Iter provides an accessor which accepts an offset in x & y relative to the current location:


inputIter.v(1, 1); // will return the value of the pixel to the lower right of the current pixel
inputIter.v(0, -1); // will return the value of the pixel directly above the current pixel

A final accessor, vClamped() also accepts an x & y relative offset, but will not sample outside of the bounds of the iterator.


inputIter.vClamped(-2,0); // when called on the left edge of a row,
						  // this will simply return the left-most pixel's value

The ConstIter class can be used to walk the pixels of a Channel using a nested for-loop, where the outer loop calls line(), and the inner calls pixel().

The code below finds the maximum value in the Area \a area of \a channel:


Channel::ConstIter iter = channel.getIter( area );
uint8_t maxValue = 0;
while( iter.line() ) {
	while( iter.pixel() ) {
		if( iter.v() > maxValue )
			maxValue = iter.v();
	}
}

In addition to v(), the Iter provides an accessor which accepts an offset in x & y relative to the current location:


inputIter.v(1, 1);  // will return the value of the pixel to the lower right of the current pixel
inputIter.v(0, -1); // will return the value of the pixel directly above the current pixel

A final accessor, vClamped() also accepts an x & y relative offset, but will not sample outside of the bounds of the iterator.


inputIter.vClamped(-2,0); // when called on the left edge of a row,
						  // this will simply return the left-most pixel's value