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, 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

       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)