1<!-- Creator     : groff version 1.18.1 -->
2<!-- CreationDate: Sun Mar  6 13:59:53 2005 -->
3<html>
4<head>
5<meta name="generator" content="groff -Thtml, see www.gnu.org">
6<meta name="Content-Style" content="text/css">
7<title>TIFFReadRGBAImage</title>
8</head>
9<body>
10
11<h1 align=center>TIFFReadRGBAImage</h1>
12<a href="#NAME">NAME</a><br>
13<a href="#SYNOPSIS">SYNOPSIS</a><br>
14<a href="#DESCRIPTION">DESCRIPTION</a><br>
15<a href="#NOTES">NOTES</a><br>
16<a href="#RETURN VALUES">RETURN VALUES</a><br>
17<a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
18<a href="#SEE ALSO">SEE ALSO</a><br>
19
20<hr>
21<a name="NAME"></a>
22<h2>NAME</h2>
23<!-- INDENTATION -->
24<table width="100%" border=0 rules="none" frame="void"
25       cols="2" cellspacing="0" cellpadding="0">
26<tr valign="top" align="left">
27<td width="8%"></td>
28<td width="91%">
29<p>TIFFReadRGBAImage, TIFFReadRGBAImageOriented &minus; read
30and decode an image into a fixed-format raster</p>
31</td>
32</table>
33<a name="SYNOPSIS"></a>
34<h2>SYNOPSIS</h2>
35<!-- INDENTATION -->
36<table width="100%" border=0 rules="none" frame="void"
37       cols="2" cellspacing="0" cellpadding="0">
38<tr valign="top" align="left">
39<td width="8%"></td>
40<td width="91%">
41<p><b>#include &lt;tiffio.h&gt;</b></p>
42</td>
43</table>
44<!-- TABS -->
45<table width="100%" border=0 rules="none" frame="void"
46       cols="5" cellspacing="0" cellpadding="0">
47<tr valign="top" align="left">
48<td width="8%"></td>
49<td width="-2%">
50
51<p><b>#define TIFFGetR(abgr)</b></p>
52</td>
53<td width="25%"></td>
54<td width="6%"></td>
55<td width="61%">
56
57<p><b>((abgr) &amp; 0xff)</b></p>
58</td>
59<tr valign="top" align="left">
60<td width="8%"></td>
61<td width="-2%">
62
63<p><b>#define TIFFGetG(abgr)</b></p>
64</td>
65<td width="25%"></td>
66<td width="6%"></td>
67<td width="61%">
68
69<p><b>(((abgr) &gt;&gt; 8) &amp; 0xff)</b></p>
70</td>
71<tr valign="top" align="left">
72<td width="8%"></td>
73<td width="-2%">
74
75<p><b>#define TIFFGetB(abgr)</b></p>
76</td>
77<td width="25%"></td>
78<td width="6%"></td>
79<td width="61%">
80
81<p><b>(((abgr) &gt;&gt; 16) &amp; 0xff)</b></p>
82</td>
83<tr valign="top" align="left">
84<td width="8%"></td>
85<td width="-2%">
86
87<p><b>#define TIFFGetA(abgr)</b></p>
88</td>
89<td width="25%"></td>
90<td width="6%"></td>
91<td width="61%">
92
93<p><b>(((abgr) &gt;&gt; 24) &amp; 0xff)</b></p>
94</td>
95</table>
96<!-- INDENTATION -->
97<table width="100%" border=0 rules="none" frame="void"
98       cols="2" cellspacing="0" cellpadding="0">
99<tr valign="top" align="left">
100<td width="8%"></td>
101<td width="91%">
102<p><b>int TIFFReadRGBAImage(TIFF *</b><i>tif</i><b>,
103u_long</b> <i>width</i><b>, u_long</b> <i>height</i><b>,
104u_long *</b><i>raster</i><b>, int</b>
105<i>stopOnError</i><b>)<br>
106int TIFFReadRGBAImageOriented(TIFF *</b><i>tif</i><b>,
107u_long</b> <i>width</i><b>, u_long</b> <i>height</i><b>,
108u_long *</b><i>raster</i><b>, int</b> <i>orientation</i><b>,
109int</b> <i>stopOnError</i><b>)</b></p>
110</td>
111</table>
112<a name="DESCRIPTION"></a>
113<h2>DESCRIPTION</h2>
114<!-- INDENTATION -->
115<table width="100%" border=0 rules="none" frame="void"
116       cols="2" cellspacing="0" cellpadding="0">
117<tr valign="top" align="left">
118<td width="8%"></td>
119<td width="91%">
120<p><i>TIFFReadRGBAImage</i> reads a strip- or tile-based
121image into memory, storing the result in the user supplied
122<i>raster</i>. The raster is assumed to be an array of
123<i>width</i> times <i>height</i> 32-bit entries, where
124<i>width</i> must be less than or equal to the width of the
125image (<i>height</i> may be any non-zero size). If the
126raster dimensions are smaller than the image, the image data
127is cropped to the raster bounds. If the raster height is
128greater than that of the image, then the image data are
129placed in the lower part of the raster. (Note that the
130raster is assume to be organized such that the pixel at
131location (<i>x</i>,<i>y</i>) is
132<i>raster</i>[<i>y</i>*<i>width</i>+<i>x</i>]; with the
133raster origin in the lower-left hand corner.)</p>
134<!-- INDENTATION -->
135<p><i>TIFFReadRGBAImageOriented</i> works like
136<i>TIFFReadRGBAImage</i> with except of that user can
137specify the raster origin position with the
138<i>orientation</i> parameter. Four orientations
139supported:</p>
140</td>
141</table>
142<!-- INDENTATION -->
143<table width="100%" border=0 rules="none" frame="void"
144       cols="2" cellspacing="0" cellpadding="0">
145<tr valign="top" align="left">
146<td width="8%"></td>
147<td width="91%">
148<p><b>ORIENTATION_TOPLEFT</b></p></td>
149</table>
150<!-- INDENTATION -->
151<table width="100%" border=0 rules="none" frame="void"
152       cols="2" cellspacing="0" cellpadding="0">
153<tr valign="top" align="left">
154<td width="19%"></td>
155<td width="80%">
156<p>origin in top-left corner,</p>
157</td>
158</table>
159<!-- INDENTATION -->
160<table width="100%" border=0 rules="none" frame="void"
161       cols="2" cellspacing="0" cellpadding="0">
162<tr valign="top" align="left">
163<td width="8%"></td>
164<td width="91%">
165<p><b>ORIENTATION_TOPRIGHT</b></p></td>
166</table>
167<!-- INDENTATION -->
168<table width="100%" border=0 rules="none" frame="void"
169       cols="2" cellspacing="0" cellpadding="0">
170<tr valign="top" align="left">
171<td width="19%"></td>
172<td width="80%">
173<p>origin in top-right corner,</p>
174</td>
175</table>
176<!-- INDENTATION -->
177<table width="100%" border=0 rules="none" frame="void"
178       cols="2" cellspacing="0" cellpadding="0">
179<tr valign="top" align="left">
180<td width="8%"></td>
181<td width="91%">
182<p><b>ORIENTATION_BOTLEFT</b></p></td>
183</table>
184<!-- INDENTATION -->
185<table width="100%" border=0 rules="none" frame="void"
186       cols="2" cellspacing="0" cellpadding="0">
187<tr valign="top" align="left">
188<td width="19%"></td>
189<td width="80%">
190<p>origin in bottom-left corner and</p>
191</td>
192</table>
193<!-- INDENTATION -->
194<table width="100%" border=0 rules="none" frame="void"
195       cols="2" cellspacing="0" cellpadding="0">
196<tr valign="top" align="left">
197<td width="8%"></td>
198<td width="91%">
199<p><b>ORIENTATION_BOTRIGHT</b></p></td>
200</table>
201<!-- INDENTATION -->
202<table width="100%" border=0 rules="none" frame="void"
203       cols="2" cellspacing="0" cellpadding="0">
204<tr valign="top" align="left">
205<td width="19%"></td>
206<td width="80%">
207<p>origin in bottom-right corner.</p>
208</td>
209</table>
210<!-- INDENTATION -->
211<table width="100%" border=0 rules="none" frame="void"
212       cols="2" cellspacing="0" cellpadding="0">
213<tr valign="top" align="left">
214<td width="8%"></td>
215<td width="91%">
216<p>If you choose <b>ORIENTATION_BOTLEFT</b> result will be
217the same as returned by the <i>TIFFReadRGBAImage.</i></p>
218<!-- INDENTATION -->
219<p>Raster pixels are 8-bit packed red, green, blue, alpha
220samples. The macros <i>TIFFGetR</i>, <i>TIFFGetG</i>,
221<i>TIFFGetB</i>, and <i>TIFFGetA</i> should be used to
222access individual samples. Images without Associated Alpha
223matting information have a constant Alpha of 1.0 (255).</p>
224<!-- INDENTATION -->
225<p><i>TIFFReadRGBAImage</i> converts non-8-bit images by
226scaling sample values. Palette, grayscale, bilevel,
227<small>CMYK</small> , and YCbCr images are converted to
228<small>RGB</small> transparently. Raster pixels are returned
229uncorrected by any colorimetry information present in the
230directory.</p>
231<!-- INDENTATION -->
232<p>The paramater <i>stopOnError</i> specifies how to act if
233an error is encountered while reading the image. If
234<i>stopOnError</i> is non-zero, then an error will terminate
235the operation; otherwise <i>TIFFReadRGBAImage</i> will
236continue processing data until all the possible data in the
237image have been requested.</p>
238</td>
239</table>
240<a name="NOTES"></a>
241<h2>NOTES</h2>
242<!-- INDENTATION -->
243<table width="100%" border=0 rules="none" frame="void"
244       cols="2" cellspacing="0" cellpadding="0">
245<tr valign="top" align="left">
246<td width="8%"></td>
247<td width="91%">
248<p>In C++ the <i>stopOnError</i> parameter defaults to
2490.</p>
250<!-- INDENTATION -->
251<p>Samples must be either 1, 2, 4, 8, or 16 bits.
252Colorimetric samples/pixel must be either 1, 3, or 4 (i.e.
253<i>SamplesPerPixel</i> minus <i>ExtraSamples</i>).</p>
254<!-- INDENTATION -->
255<p>Palettte image colormaps that appear to be incorrectly
256written as 8-bit values are automatically scaled to
25716-bits.</p>
258<!-- INDENTATION -->
259<p><i>TIFFReadRGBAImage</i> is just a wrapper around the
260more general <i>TIFFRGBAImage</i>(3TIFF) facilities.</p>
261</td>
262</table>
263<a name="RETURN VALUES"></a>
264<h2>RETURN VALUES</h2>
265<!-- INDENTATION -->
266<table width="100%" border=0 rules="none" frame="void"
267       cols="2" cellspacing="0" cellpadding="0">
268<tr valign="top" align="left">
269<td width="8%"></td>
270<td width="91%">
271<p>1 is returned if the image was successfully read and
272converted. Otherwise, 0 is returned if an error was
273encountered and <i>stopOnError</i> is zero.</p>
274</td>
275</table>
276<a name="DIAGNOSTICS"></a>
277<h2>DIAGNOSTICS</h2>
278<!-- INDENTATION -->
279<table width="100%" border=0 rules="none" frame="void"
280       cols="2" cellspacing="0" cellpadding="0">
281<tr valign="top" align="left">
282<td width="8%"></td>
283<td width="91%">
284<p>All error messages are directed to the
285<i>TIFFError</i>(3TIFF) routine.</p>
286<!-- INDENTATION -->
287<p><b>Sorry, can not handle %d-bit pictures</b>. The image
288had <i>BitsPerSample</i> other than 1, 2, 4, 8, or 16.</p>
289<!-- INDENTATION -->
290<p><b>Sorry, can not handle %d-channel images</b>. The image
291had <i>SamplesPerPixel</i> other than 1, 3, or 4.</p>
292<!-- INDENTATION -->
293<p><b>Missing needed &quot;PhotometricInterpretation&quot;
294tag</b>. The image did not have a tag that describes how to
295display the data.</p>
296<!-- INDENTATION -->
297<p><b>No &quot;PhotometricInterpretation&quot; tag, assuming
298RGB</b>. The image was missing a tag that describes how to
299display it, but because it has 3 or 4 samples/pixel, it is
300assumed to be <small>RGB.</small></p>
301<!-- INDENTATION -->
302<p><b>No &quot;PhotometricInterpretation&quot; tag, assuming
303min-is-black</b>. The image was missing a tag that describes
304how to display it, but because it has 1 sample/pixel, it is
305assumed to be a grayscale or bilevel image.</p>
306<!-- INDENTATION -->
307<p><b>No space for photometric conversion table</b>. There
308was insufficient memory for a table used to convert image
309samples to 8-bit <small>RGB.</small></p>
310<!-- INDENTATION -->
311<p><b>Missing required &quot;Colormap&quot; tag</b>. A
312Palette image did not have a required <i>Colormap</i>
313tag.</p>
314<!-- INDENTATION -->
315<p><b>No space for tile buffer</b>. There was insufficient
316memory to allocate an i/o buffer.</p>
317<!-- INDENTATION -->
318<p><b>No space for strip buffer</b>. There was insufficient
319memory to allocate an i/o buffer.</p>
320<!-- INDENTATION -->
321<p><b>Can not handle format</b>. The image has a format
322(combination of <i>BitsPerSample</i>,
323<i>SamplesPerPixel</i>, and
324<i>PhotometricInterpretation</i>) that
325<i>TIFFReadRGBAImage</i> can not handle.</p>
326<!-- INDENTATION -->
327<p><b>No space for B&amp;W mapping table</b>. There was
328insufficient memory to allocate a table used to map
329grayscale data to <small>RGB.</small></p>
330<!-- INDENTATION -->
331<p><b>No space for Palette mapping table</b>. There was
332insufficient memory to allocate a table used to map data to
3338-bit <small>RGB.</small></p>
334</td>
335</table>
336<a name="SEE ALSO"></a>
337<h2>SEE ALSO</h2>
338<!-- INDENTATION -->
339<table width="100%" border=0 rules="none" frame="void"
340       cols="2" cellspacing="0" cellpadding="0">
341<tr valign="top" align="left">
342<td width="8%"></td>
343<td width="91%">
344<p><i>libtiff</i>(3TIFF), <i>TIFFOpen</i>(3TIFF),
345<i>TIFFRGBAImage</i>(3TIFF),
346<i>TIFFReadRGBAStrip</i>(3TIFF),
347<i>TIFFReadRGBATile</i>(3TIFF)</p>
348</td>
349</table>
350<hr>
351</body>
352</html>
353