man icetImageCopyColor (3): retrieve pixel data from image

Other Alias

icetImageCopyDepth

Synopsis

#include <IceT.h>

void	icetImageCopyColorub(	const IceTImage	image,
		IceTUByte *	color_buffer,
		IceTEnum	color_format );

void	icetImageCopyColorf(	const IceTImage	image,
		IceTFloat *	color_buffer,
		IceTEnum	color_format );

void	icetImageCopyDepthf(	const IceTImage	image,
		IceTFloat *	depth_buffer,
		IceTEnum	depth_format );

Description

The icetImageCopyColorsuite of functions retrieve color data from images and the icetImageCopyDepthfunctions retrieve depth data from images. Each function takes a pointer to an existing buffer that must be large enough to hold all pixels in the image. The data from the images is copied into these buffers, performing format conversions as necessary. Because data is copied into the provided buffer, subsequently changing values in the buffer has no effect on the image object (as opposed to the behavior of icetImageGetColorand icetImageGetDepth).

The pixel data is always tightly packed in horizontal major order. Color data that comprises tuples such as RGBA have the components for each pixel packed together in that order. The first entry in the array corresponds to the pixel in the lower left corner of the image. The next entry is immediately to the right of the first pixel, and so on. The dimensions of the array can be retrieved with the icetImageGetWidthand icetImageGetHeightfunctions.

Each of these functions provides a typed version of the image data array. They can only succeed if the type the request matches the type specified by the color_format or depth_format argument. It is an error, for example, to request unsigned byte color data for a floating point color format. Although specifying the format may be redundant (it could be implied by the type being retrieved), IceT requires it for completeness and to support possible future data formats.

Use icetImageCopyColorubto retrieve an array of 8-bit unsigned bytes. Using this function is only valid if color_format is ICET_IMAGE_COLOR_RGBA_UBYTE.

Use icetImageCopyColorfto retrieve an array of floating point color values. Using this function is only valid if color_format is ICET_IMAGE_COLOR_RGBA_FLOAT.

Use icetImageGetDepthfto retrieve an array of floating point depth values. Using this function is only valid if depth_format is ICET_IMAGE_DEPTH_FLOAT.

Errors

ICET_INVALID_OPERATION: The image object does not have a color or depth buffer from which to copy data.
ICET_INVALID_ENUM: The requested color_format or depth_format is incompatible with the type of the buffer.

Warnings

None.

Bugs

None known.

Copyright

Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain rights in this software.

This source code is released under the New BSD License.