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)