icetImageGetColor(3)						  IceT Reference					      icetImageGetColor(3)

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 icetIm-
       ageGetWidthand 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  inter-
       nal type of the array. It is an error, for example, to request unsigned byte color data when the image stores images as floating point col-
       ors. 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 mem-
       ory 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 icetImageGetColor-
       Format 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  ice-
       tImageCopyColor 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)