]>
Commit | Line | Data |
---|---|---|
1 | <!-- Creator : groff version 1.18.1 --> | |
2 | <!-- CreationDate: Mon Mar 13 18:03:10 2006 --> | |
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, | |
33 | TIFFRGBAImageEnd − read and decode an image into a | |
34 | raster</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 <tiffio.h></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> | |
52 | int TIFFRGBAImageBegin(TIFFRGBAImage *</b><i>img</i><b>, | |
53 | TIFF*</b> <i>tif</i><b>, int</b> <i>stopOnError</i><b>, | |
54 | char</b> <i>emsg[1024]</i><b>)<br> | |
55 | int TIFFRGBAImageGet(TIFFRGBAImage *</b><i>img</i><b>, | |
56 | uint32*</b> <i>raster</i><b>, uint32</b> <i>width</i> <b>, | |
57 | uint32</b> <i>height</i><b>)<br> | |
58 | void 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 | |
71 | interface through which <small>TIFF</small> images may be | |
72 | read into memory. Images may be strip- or tile-based and | |
73 | have a variety of different characteristics: bits/sample, | |
74 | samples/pixel, photometric, etc. Decoding state is | |
75 | encapsulated in a <i>TIFFRGBAImage</i> structure making it | |
76 | possible to capture state for multiple images and quickly | |
77 | switch between them. The target raster format can be | |
78 | customized to a particular application’s needs by | |
79 | installing custom routines that manipulate image data | |
80 | according to application requirements.</p> | |
81 | <!-- INDENTATION --> | |
82 | <p>The default usage for these routines is: check if an | |
83 | image can be processed using <i>TIFFRGBAImageOK</i>, | |
84 | construct a decoder state block using | |
85 | <i>TIFFRGBAImageBegin</i>, read and decode an image into a | |
86 | target raster using <i>TIFFRGBAImageGet</i>, and then | |
87 | release resources using <i>TIFFRGBAImageEnd</i>. | |
88 | <i>TIFFRGBAImageGet</i> can be called multiple times to | |
89 | decode an image using different state parameters. If | |
90 | multiple images are to be displayed and there is not enough | |
91 | space for each of the decoded rasters, multiple state blocks | |
92 | can 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 | |
98 | image (<i>height</i> may be any non-zero size). If the | |
99 | raster dimensions are smaller than the image, the image data | |
100 | is cropped to the raster bounds. If the raster height is | |
101 | greater than that of the image, then the image data are | |
102 | placed in the lower part of the raster. (Note that the | |
103 | raster is assume to be organized such that the pixel at | |
104 | location (<i>x</i>,<i>y</i>) is | |
105 | <i>raster</i>[<i>y</i>*<i>width</i>+<i>x</i>]; with the | |
106 | raster origin in the <b>lower-left</b> hand corner.)</p> | |
107 | <!-- INDENTATION --> | |
108 | <p>Raster pixels are 8-bit packed red, green, blue, alpha | |
109 | samples. The macros <i>TIFFGetR</i>, <i>TIFFGetG</i>, | |
110 | <i>TIFFGetB</i>, and <i>TIFFGetA</i> should be used to | |
111 | access individual samples. Images without Associated Alpha | |
112 | matting information have a constant Alpha of 1.0 (255).</p> | |
113 | <!-- INDENTATION --> | |
114 | <p><i>TIFFRGBAImageGet</i> converts non-8-bit images by | |
115 | scaling sample values. Palette, grayscale, bilevel, | |
116 | <small>CMYK</small> , and YCbCr images are converted to | |
117 | <small>RGB</small> transparently. Raster pixels are returned | |
118 | uncorrected by any colorimetry information present in the | |
119 | directory.</p> | |
120 | <!-- INDENTATION --> | |
121 | <p>The parameter <i>stopOnError</i> specifies how to act if | |
122 | an error is encountered while reading the image. If | |
123 | <i>stopOnError</i> is non-zero, then an error will terminate | |
124 | the operation; otherwise <i>TIFFRGBAImageGet</i> will | |
125 | continue processing data until all the possible data in the | |
126 | image 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 | |
139 | data in a different format one need only override the | |
140 | ‘‘<i>put methods</i>’’ used to store | |
141 | raster 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 | |
144 | raster data in the default <small>ABGR</small> pixel format. | |
145 | Two different routines are used according to the physical | |
146 | organization of the image data in the file: | |
147 | <i>PlanarConfiguration</i>=1 (packed samples), and | |
148 | <i>PlanarConfiguration</i>=2 (separated samples). Note that | |
149 | this mechanism can be used to transform the data before | |
150 | storing it in the raster. For example one can convert data | |
151 | to 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 | |
163 | memory by overriding the put methods as described above for | |
164 | supporting alternate raster formats. Simply keep a reference | |
165 | to the default put methods setup by | |
166 | <i>TIFFRGBAImageBegin</i> and then invoke them before or | |
167 | after each display operation. For example, the | |
168 | <i>tiffgt</i>(1) utility uses the following put method to | |
169 | update the display as the raster is being filled:</p> | |
170 | <!-- INDENTATION --> | |
171 | <pre>static void | |
172 | putContigAndDraw(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->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 | |
189 | the 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 | |
201 | commonly encountered flavors of <small>TIFF.</small> It is | |
202 | possible to extend this support by overriding the | |
203 | ‘‘<i>get method</i>’’ invoked by | |
204 | <i>TIFFRGBAImageGet</i> to read <small>TIFF</small> image | |
205 | data. Details of doing this are a bit involved, it is best | |
206 | to make a copy of an existing get method and modify it to | |
207 | suit 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. | |
219 | Colorimetric 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 | |
223 | written as 8-bit values are automatically scaled to | |
224 | 16-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. | |
236 | Otherwise, 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 | |
252 | had <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 | |
255 | had <i>SamplesPerPixel</i> other than 1, 3, or 4.</p> | |
256 | <!-- INDENTATION --> | |
257 | <p><b>Missing needed "PhotometricInterpretation" | |
258 | tag</b>. The image did not have a tag that describes how to | |
259 | display the data.</p> | |
260 | <!-- INDENTATION --> | |
261 | <p><b>No "PhotometricInterpretation" tag, assuming | |
262 | RGB</b>. The image was missing a tag that describes how to | |
263 | display it, but because it has 3 or 4 samples/pixel, it is | |
264 | assumed to be <small>RGB.</small></p> | |
265 | <!-- INDENTATION --> | |
266 | <p><b>No "PhotometricInterpretation" tag, assuming | |
267 | min-is-black</b>. The image was missing a tag that describes | |
268 | how to display it, but because it has 1 sample/pixel, it is | |
269 | assumed to be a grayscale or bilevel image.</p> | |
270 | <!-- INDENTATION --> | |
271 | <p><b>No space for photometric conversion table</b>. There | |
272 | was insufficient memory for a table used to convert image | |
273 | samples to 8-bit <small>RGB.</small></p> | |
274 | <!-- INDENTATION --> | |
275 | <p><b>Missing required "Colormap" tag</b>. A | |
276 | Palette image did not have a required <i>Colormap</i> | |
277 | tag.</p> | |
278 | <!-- INDENTATION --> | |
279 | <p><b>No space for tile buffer</b>. There was insufficient | |
280 | memory to allocate an i/o buffer.</p> | |
281 | <!-- INDENTATION --> | |
282 | <p><b>No space for strip buffer</b>. There was insufficient | |
283 | memory 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 | |
289 | handled.</p> | |
290 | <!-- INDENTATION --> | |
291 | <p><b>No space for B&W mapping table</b>. There was | |
292 | insufficient memory to allocate a table used to map | |
293 | grayscale data to <small>RGB.</small></p> | |
294 | <!-- INDENTATION --> | |
295 | <p><b>No space for Palette mapping table</b>. There was | |
296 | insufficient memory to allocate a table used to map data to | |
297 | 8-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> |