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 or ICET_IMAGE_COLOR_RGB_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                                   March 13, 2018                            icetImageCopyColor(3)