source: trunk/src/3rdparty/libtiff/html/man/TIFFRGBAImage.3tiff.html

Last change on this file was 846, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 12.0 KB
Line 
1<!-- Creator : groff version 1.18.1 -->
2<!-- CreationDate: Fri Jul 13 17:43:16 2007 -->
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>TIFFRGBAImage</title>
8</head>
9<body>
10
11<h1 align=center>TIFFRGBAImage</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="#ALTERNATE RASTER FORMATS">ALTERNATE RASTER FORMATS</a><br>
16<a href="#SIMULTANEOUS RASTER STORE AND DISPLAY">SIMULTANEOUS RASTER STORE AND DISPLAY</a><br>
17<a href="#SUPPORTING ADDITIONAL TIFF FORMATS">SUPPORTING ADDITIONAL TIFF FORMATS</a><br>
18<a href="#NOTES">NOTES</a><br>
19<a href="#RETURN VALUES">RETURN VALUES</a><br>
20<a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
21<a href="#SEE ALSO">SEE ALSO</a><br>
22
23<hr>
24<a name="NAME"></a>
25<h2>NAME</h2>
26<!-- INDENTATION -->
27<table width="100%" border=0 rules="none" frame="void"
28 cols="2" cellspacing="0" cellpadding="0">
29<tr valign="top" align="left">
30<td width="8%"></td>
31<td width="91%">
32<p>TIFFRGBAImageOK, TIFFRGBAImageBegin, TIFFRGBAImageGet,
33TIFFRGBAImageEnd &minus; read and decode an image into a
34raster</p>
35</td>
36</table>
37<a name="SYNOPSIS"></a>
38<h2>SYNOPSIS</h2>
39<!-- INDENTATION -->
40<table width="100%" border=0 rules="none" frame="void"
41 cols="2" cellspacing="0" cellpadding="0">
42<tr valign="top" align="left">
43<td width="8%"></td>
44<td width="91%">
45<p><b>#include &lt;tiffio.h&gt;</b></p>
46<!-- INDENTATION -->
47<p><b>typedef unsigned char TIFFRGBValue; typedef struct
48_TIFFRGBAImage TIFFRGBAImage;</b></p>
49<!-- INDENTATION -->
50<p><b>int TIFFRGBAImageOK(TIFF *</b><i>tif</i><b>, char</b>
51<i>emsg[1024]</i><b>)<br>
52int TIFFRGBAImageBegin(TIFFRGBAImage *</b><i>img</i><b>,
53TIFF*</b> <i>tif</i><b>, int</b> <i>stopOnError</i><b>,
54char</b> <i>emsg[1024]</i><b>)<br>
55int TIFFRGBAImageGet(TIFFRGBAImage *</b><i>img</i><b>,
56uint32*</b> <i>raster</i><b>, uint32</b> <i>width</i> <b>,
57uint32</b> <i>height</i><b>)<br>
58void TIFFRGBAImageEnd(TIFFRGBAImage
59*</b><i>img</i><b>)</b></p>
60</td>
61</table>
62<a name="DESCRIPTION"></a>
63<h2>DESCRIPTION</h2>
64<!-- INDENTATION -->
65<table width="100%" border=0 rules="none" frame="void"
66 cols="2" cellspacing="0" cellpadding="0">
67<tr valign="top" align="left">
68<td width="8%"></td>
69<td width="91%">
70<p>The routines described here provide a high-level
71interface through which <small>TIFF</small> images may be
72read into memory. Images may be strip- or tile-based and
73have a variety of different characteristics: bits/sample,
74samples/pixel, photometric, etc. Decoding state is
75encapsulated in a <i>TIFFRGBAImage</i> structure making it
76possible to capture state for multiple images and quickly
77switch between them. The target raster format can be
78customized to a particular application&rsquo;s needs by
79installing custom routines that manipulate image data
80according to application requirements.</p>
81<!-- INDENTATION -->
82<p>The default usage for these routines is: check if an
83image can be processed using <i>TIFFRGBAImageOK</i>,
84construct a decoder state block using
85<i>TIFFRGBAImageBegin</i>, read and decode an image into a
86target raster using <i>TIFFRGBAImageGet</i>, and then
87release resources using <i>TIFFRGBAImageEnd</i>.
88<i>TIFFRGBAImageGet</i> can be called multiple times to
89decode an image using different state parameters. If
90multiple images are to be displayed and there is not enough
91space for each of the decoded rasters, multiple state blocks
92can be managed and then calls can be made to
93<i>TIFFRGBAImageGet</i> as needed to display an image.</p>
94<!-- INDENTATION -->
95<p>The generated raster is assumed to be an array of
96<i>width</i> times <i>height</i> 32-bit entries, where
97<i>width</i> must be less than or equal to the width of the
98image (<i>height</i> may be any non-zero size). If the
99raster dimensions are smaller than the image, the image data
100is cropped to the raster bounds. If the raster height is
101greater than that of the image, then the image data are
102placed in the lower part of the raster. (Note that the
103raster is assume to be organized such that the pixel at
104location (<i>x</i>,<i>y</i>) is
105<i>raster</i>[<i>y</i>*<i>width</i>+<i>x</i>]; with the
106raster origin in the <b>lower-left</b> hand corner.)</p>
107<!-- INDENTATION -->
108<p>Raster pixels are 8-bit packed red, green, blue, alpha
109samples. The macros <i>TIFFGetR</i>, <i>TIFFGetG</i>,
110<i>TIFFGetB</i>, and <i>TIFFGetA</i> should be used to
111access individual samples. Images without Associated Alpha
112matting information have a constant Alpha of 1.0 (255).</p>
113<!-- INDENTATION -->
114<p><i>TIFFRGBAImageGet</i> converts non-8-bit images by
115scaling sample values. Palette, grayscale, bilevel,
116<small>CMYK</small> , and YCbCr images are converted to
117<small>RGB</small> transparently. Raster pixels are returned
118uncorrected by any colorimetry information present in the
119directory.</p>
120<!-- INDENTATION -->
121<p>The parameter <i>stopOnError</i> specifies how to act if
122an error is encountered while reading the image. If
123<i>stopOnError</i> is non-zero, then an error will terminate
124the operation; otherwise <i>TIFFRGBAImageGet</i> will
125continue processing data until all the possible data in the
126image have been requested.</p>
127</td>
128</table>
129<a name="ALTERNATE RASTER FORMATS"></a>
130<h2>ALTERNATE RASTER FORMATS</h2>
131<!-- INDENTATION -->
132<table width="100%" border=0 rules="none" frame="void"
133 cols="2" cellspacing="0" cellpadding="0">
134<tr valign="top" align="left">
135<td width="8%"></td>
136<td width="91%">
137<p>To use the core support for reading and processing
138<small>TIFF</small> images, but write the resulting raster
139data in a different format one need only override the
140&lsquo;&lsquo;<i>put methods</i>&rsquo;&rsquo; used to store
141raster data. These methods are are defined in the
142<i>TIFFRGBAImage</i> structure and initially setup by
143<i>TIFFRGBAImageBegin</i> to point to routines that pack
144raster data in the default <small>ABGR</small> pixel format.
145Two different routines are used according to the physical
146organization of the image data in the file:
147<i>PlanarConfiguration</i>=1 (packed samples), and
148<i>PlanarConfiguration</i>=2 (separated samples). Note that
149this mechanism can be used to transform the data before
150storing it in the raster. For example one can convert data
151to colormap indices for display on a colormap display.</p>
152</td>
153</table>
154<a name="SIMULTANEOUS RASTER STORE AND DISPLAY"></a>
155<h2>SIMULTANEOUS RASTER STORE AND DISPLAY</h2>
156<!-- INDENTATION -->
157<table width="100%" border=0 rules="none" frame="void"
158 cols="2" cellspacing="0" cellpadding="0">
159<tr valign="top" align="left">
160<td width="8%"></td>
161<td width="91%">
162<p>It is simple to display an image as it is being read into
163memory by overriding the put methods as described above for
164supporting alternate raster formats. Simply keep a reference
165to the default put methods setup by
166<i>TIFFRGBAImageBegin</i> and then invoke them before or
167after each display operation. For example, the
168<i>tiffgt</i>(1) utility uses the following put method to
169update the display as the raster is being filled:</p>
170<!-- INDENTATION -->
171<pre>static void
172putContigAndDraw(TIFFRGBAImage* img, uint32* raster,
173 uint32 x, uint32 y, uint32 w, uint32 h,
174 int32 fromskew, int32 toskew,
175 unsigned char* cp)
176{
177 (*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp);
178 if (x+w == width) {
179 w = width;
180 if (img-&gt;orientation == ORIENTATION_TOPLEFT)
181 lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w);
182 else
183 lrectwrite(0, y, w-1, y+h-1, raster);
184 }
185}
186</pre>
187<!-- INDENTATION -->
188<p>(the original routine provided by the library is saved in
189the variable <i>putContig</i>.)</p>
190</td>
191</table>
192<a name="SUPPORTING ADDITIONAL TIFF FORMATS"></a>
193<h2>SUPPORTING ADDITIONAL TIFF FORMATS</h2>
194<!-- INDENTATION -->
195<table width="100%" border=0 rules="none" frame="void"
196 cols="2" cellspacing="0" cellpadding="0">
197<tr valign="top" align="left">
198<td width="8%"></td>
199<td width="91%">
200<p>The <i>TIFFRGBAImage</i> routines support the most
201commonly encountered flavors of <small>TIFF.</small> It is
202possible to extend this support by overriding the
203&lsquo;&lsquo;<i>get method</i>&rsquo;&rsquo; invoked by
204<i>TIFFRGBAImageGet</i> to read <small>TIFF</small> image
205data. Details of doing this are a bit involved, it is best
206to make a copy of an existing get method and modify it to
207suit the needs of an application.</p>
208</td>
209</table>
210<a name="NOTES"></a>
211<h2>NOTES</h2>
212<!-- INDENTATION -->
213<table width="100%" border=0 rules="none" frame="void"
214 cols="2" cellspacing="0" cellpadding="0">
215<tr valign="top" align="left">
216<td width="8%"></td>
217<td width="91%">
218<p>Samples must be either 1, 2, 4, 8, or 16 bits.
219Colorimetric samples/pixel must be either 1, 3, or 4 (i.e.
220<i>SamplesPerPixel</i> minus <i>ExtraSamples</i>).</p>
221<!-- INDENTATION -->
222<p>Palette image colormaps that appear to be incorrectly
223written as 8-bit values are automatically scaled to
22416-bits.</p>
225</td>
226</table>
227<a name="RETURN VALUES"></a>
228<h2>RETURN VALUES</h2>
229<!-- INDENTATION -->
230<table width="100%" border=0 rules="none" frame="void"
231 cols="2" cellspacing="0" cellpadding="0">
232<tr valign="top" align="left">
233<td width="8%"></td>
234<td width="91%">
235<p>All routines return 1 if the operation was successful.
236Otherwise, 0 is returned if an error was encountered and
237<i>stopOnError</i> is zero.</p>
238</td>
239</table>
240<a name="DIAGNOSTICS"></a>
241<h2>DIAGNOSTICS</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>All error messages are directed to the
249<i>TIFFError</i>(3TIFF) routine.</p>
250<!-- INDENTATION -->
251<p><b>Sorry, can not handle %d-bit pictures</b>. The image
252had <i>BitsPerSample</i> other than 1, 2, 4, 8, or 16.</p>
253<!-- INDENTATION -->
254<p><b>Sorry, can not handle %d-channel images</b>. The image
255had <i>SamplesPerPixel</i> other than 1, 3, or 4.</p>
256<!-- INDENTATION -->
257<p><b>Missing needed &quot;PhotometricInterpretation&quot;
258tag</b>. The image did not have a tag that describes how to
259display the data.</p>
260<!-- INDENTATION -->
261<p><b>No &quot;PhotometricInterpretation&quot; tag, assuming
262RGB</b>. The image was missing a tag that describes how to
263display it, but because it has 3 or 4 samples/pixel, it is
264assumed to be <small>RGB.</small></p>
265<!-- INDENTATION -->
266<p><b>No &quot;PhotometricInterpretation&quot; tag, assuming
267min-is-black</b>. The image was missing a tag that describes
268how to display it, but because it has 1 sample/pixel, it is
269assumed to be a grayscale or bilevel image.</p>
270<!-- INDENTATION -->
271<p><b>No space for photometric conversion table</b>. There
272was insufficient memory for a table used to convert image
273samples to 8-bit <small>RGB.</small></p>
274<!-- INDENTATION -->
275<p><b>Missing required &quot;Colormap&quot; tag</b>. A
276Palette image did not have a required <i>Colormap</i>
277tag.</p>
278<!-- INDENTATION -->
279<p><b>No space for tile buffer</b>. There was insufficient
280memory to allocate an i/o buffer.</p>
281<!-- INDENTATION -->
282<p><b>No space for strip buffer</b>. There was insufficient
283memory to allocate an i/o buffer.</p>
284<!-- INDENTATION -->
285<p><b>Can not handle format</b>. The image has a format
286(combination of <i>BitsPerSample</i>,
287<i>SamplesPerPixel</i>, and
288<i>PhotometricInterpretation</i>) that can not be
289handled.</p>
290<!-- INDENTATION -->
291<p><b>No space for B&amp;W mapping table</b>. There was
292insufficient memory to allocate a table used to map
293grayscale data to <small>RGB.</small></p>
294<!-- INDENTATION -->
295<p><b>No space for Palette mapping table</b>. There was
296insufficient memory to allocate a table used to map data to
2978-bit <small>RGB.</small></p>
298</td>
299</table>
300<a name="SEE ALSO"></a>
301<h2>SEE ALSO</h2>
302<!-- INDENTATION -->
303<table width="100%" border=0 rules="none" frame="void"
304 cols="2" cellspacing="0" cellpadding="0">
305<tr valign="top" align="left">
306<td width="8%"></td>
307<td width="91%">
308<p><b>TIFFOpen</b>(3TIFF), <b>TIFFReadRGBAImage</b>(3TIFF),
309<b>TIFFReadRGBAImageOriented</b>(3TIFF),
310<b>TIFFReadRGBAStrip</b>(3TIFF),
311<b>TIFFReadRGBATile</b>(3TIFF), <b>libtiff</b>(3TIFF)</p>
312<!-- INDENTATION -->
313<p>Libtiff library home page:
314<b>http://www.remotesensing.org/libtiff/</b></p>
315</td>
316</table>
317<hr>
318</body>
319</html>
Note: See TracBrowser for help on using the repository browser.