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)