NAME

       icetImageGetColor , icetImageGetDepth-- retrieve pixel data buffer from image

Synopsis

       #include <IceT.h>

       IceTUByte *   icetImageGetColorub   (  IceTImage   image  );
       IceTUInt *    icetImageGetColorui   (  IceTImage   image  );
       IceTFloat *   icetImageGetColorf    (  IceTImage   image  );
       IceTFloat *   icetImageGetDepthf    (  IceTImage   image  );

       const IceTUByte *   icetImageGetColorcub   (
         const IceTImage   image  );
       const IceTUInt *    icetImageGetColorcui   (
         const IceTImage   image  );
       const IceTFloat *   icetImageGetColorcf    (
         const IceTImage   image  );
       const IceTFloat *   icetImageGetDepthcf    (
         const IceTImage   image  );

Description

       The   icetImageGetColorsuite  of  functions  retrieve  color  data  from  images  and  the
       icetImageGetDepthfunctions retrieve depth data  from  images.   Each  function  returns  a
       pointer  to  an  internal  buffer within the image.  Writing to this data changes the data
       within the image object itself.  Use the  icetImageGetColorand  icetImageGetDepthfunctions
       from within drawing callbacks to pass image data back to IceT .

       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 returns a typed version of the image data array.   They  can  only
       succeed  if  the  type the request matches the internal type of the array. It is an error,
       for example, to request unsigned byte color data when the image stores images as  floating
       point   colors.  You  can  use  the  icetImageGetColorFormatand  icetImageGetDepthFormatto
       retrieve the format for the internal data storage (which also implies the base data type).
       You  can  also  use  the  icetImageCopyColorand icetImageCopyDepthfunctions to convert the
       image data to whatever format you like.

       Use icetImageGetColorubto retrieve an array of 8-bit unsigned bytes.  Using this  function
       is only valid if the color format is ICET_IMAGE_COLOR_RGBA_UBYTE.

       Use  icetImageGetColoruito  retrieve  an  array  of  32-bit  unsigned integers. Using this
       function is only valid if the color format is ICET_IMAGE_COLOR_RGBA_UBYTE.  In this  case,
       each 32-bit integer represents all four RGBA channels. Accessing each pixel's color values
       as a single 32-bit integer is often faster  than  accessing  it  as  4  independent  8-bit
       integers  as  most  modern  architectures  can access 32-bit memory boundaries faster than
       independent 8-bit boundaries.

       Use icetImageGetColorfto retrieve an array of floating  point  color  values.  Using  this
       function is only valid if the 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 the depth format is ICET_IMAGE_DEPTH_FLOAT.

Return Value

       Returns an appropriately typed array pointing to the internal color or depth values stored
       in the image object. If there is an error, NULL is returned.

       The memory returned should not be freed. It is managed internally by IceT .

Errors

       ICET_INVALID_OPERATION
               The  internal  color  or  depth  format is incompatible with the type of array the
              function retrieves.

Warnings

       None.

Bugs

       None known.

Notes

       There is no mechanism to automatically determine the data type from  the  color  or  depth
       format       enumeration       (returned       from       icetImageGetColorFormat       or
       icetImageGetDepthFormat).Instead, you must code internal logic to  use  an  array  of  the
       appropriate  type.  The reasoning behind this decision is that the format encodes the data
       layout in addition to the data type, and your code most understand the basic semantics  of
       the  data to do anything worthwhile with it. If you want to write code that is indifferent
       to the underlying format of the image, use the icetImageCopyColor  and  icetImageCopyDepth
       functions to copy the data to a known format.

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

       icetImageCopyColor(3),         icetImageCopyDepth(3),          icetImageGetColorFormat(3),
       icetImageGetDepthFormat(3)

IceT Reference                          November 18, 2010                    icetImageGetColor(3)