icetImageCopyColor(3)						  IceT Reference					     icetImageCopyColor(3)

NAME

       icetImageCopyColor,icetImageCopyDepth-- retrieve pixel data from image

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, subse-
       quently changing values in the buffer has no effect on the image object (as opposed to the behavior of  icetImageGetColorand  icetImageGet-
       Depth).

       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 icetIm-
       ageGetWidthand 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
       Copyright (C)2010 Sandia Corporation

       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.

See Also
       icetImageGetColor(3), icetImageGetDepth(3)

IceT Reference							September 20, 2010					     icetImageCopyColor(3)