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)