1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
'\" t
.\" Manual page created with latex2man on Mon Sep 22 15:51:54 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "icetImageGetColor" "3" "November 18, 2010" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetImageGetColor , \fBicetImageGetDepth\fP\-\- retrieve pixel data buffer from image\fP
.PP
.PP
.SH Synopsis
.PP
#include <IceT.h>
.PP
.TS H
l l l l .
IceTUByte * \fBicetImageGetColorub\fP ( \fBIceTImage\fP \fIimage\fP );
IceTUInt * \fBicetImageGetColorui\fP ( \fBIceTImage\fP \fIimage\fP );
IceTFloat * \fBicetImageGetColorf\fP ( \fBIceTImage\fP \fIimage\fP );
IceTFloat * \fBicetImageGetDepthf\fP ( \fBIceTImage\fP \fIimage\fP );
.TE
.PP
.TS H
l l l l .
const IceTUByte * \fBicetImageGetColorcub\fP (
const \fBIceTImage\fP \fIimage\fP );
const IceTUInt * \fBicetImageGetColorcui\fP (
const \fBIceTImage\fP \fIimage\fP );
const IceTFloat * \fBicetImageGetColorcf\fP (
const \fBIceTImage\fP \fIimage\fP );
const IceTFloat * \fBicetImageGetDepthcf\fP (
const \fBIceTImage\fP \fIimage\fP );
.TE
.PP
.SH Description
.PP
The \fBicetImageGetColor\fPsuite of functions retrieve color data from images
and the \fBicetImageGetDepth\fPfunctions 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 \fBicetImageGetColor\fPand \fBicetImageGetDepth\fPfunctions from within
drawing callbacks to pass image data back to \fBIceT \fP\&.
.PP
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 \fBicetImageGetWidth\fPand
\fBicetImageGetHeight\fPfunctions.
.PP
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 \fBicetImageGetColorFormat\fPand \fBicetImageGetDepthFormat\fPto
retrieve the format for the internal data storage (which also implies the
base data type). You can also use the \fBicetImageCopyColor\fPand
\fBicetImageCopyDepth\fPfunctions to convert the image data to whatever
format you like.
.PP
Use \fBicetImageGetColorub\fPto retrieve an array of 8\-bit unsigned bytes.
Using this function is only valid if the color format is
\fBICET_IMAGE_COLOR_RGBA_UBYTE\fP\&.
.PP
Use \fBicetImageGetColorui\fPto retrieve an array of 32\-bit unsigned
integers. Using this function is only valid if the color format is
\fBICET_IMAGE_COLOR_RGBA_UBYTE\fP\&.
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.
.PP
Use \fBicetImageGetColorf\fPto retrieve an array of floating point color
values. Using this function is only valid if the color format is
\fBICET_IMAGE_COLOR_RGBA_FLOAT\fP\&.
.PP
Use \fBicetImageGetDepthf\fPto retrieve an array of floating point depth
values. Using this function is only valid if the depth format is
\fBICET_IMAGE_DEPTH_FLOAT\fP\&.
.PP
.SH Return Value
.PP
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.
.PP
The memory returned should not be freed. It is managed internally by
\fBIceT \fP\&.
.PP
.SH Errors
.PP
.TP
\fBICET_INVALID_OPERATION\fP
The internal color or depth format is incompatible with the type of
array the function retrieves.
.PP
.SH Warnings
.PP
None.
.PP
.SH Bugs
.PP
None known.
.PP
.SH Notes
.PP
There is no mechanism to automatically determine the data type from the
color or depth format enumeration (returned from \fBicetImageGetColorFormat\fP
or \fBicetImageGetDepthFormat\fP).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
\fBicetImageCopyColor\fP
and \fBicetImageCopyDepth\fP
functions to
copy the data to a known format.
.PP
.SH Copyright
Copyright (C)2010 Sandia Corporation
.PP
Under the terms of Contract DE\-AC04\-94AL85000 with Sandia Corporation, the
U.S. Government retains certain rights in this software.
.PP
This source code is released under the New BSD License.
.PP
.SH See Also
.PP
\fIicetImageCopyColor\fP(3),
\fIicetImageCopyDepth\fP(3),
\fIicetImageGetColorFormat\fP(3),
\fIicetImageGetDepthFormat\fP(3)
.PP
.PP
.\" NOTE: This file is generated, DO NOT EDIT.
|
