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