1 <!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [ |
|
2 <!--ArborText, Inc., 1988-1999, v.4002--> |
|
3 <!ENTITY exde-tt "EXTENDED DESCRIPTION"> |
|
4 <!ENTITY synp-tt "SYNOPSIS"> |
|
5 <!ENTITY cmd "TIFFRGBAImage"> |
|
6 <!ENTITY % commonents SYSTEM "smancommon.ent"> |
|
7 %commonents; |
|
8 <!ENTITY % gnomecommonents SYSTEM "gnomecommon.ent"> |
|
9 %gnomecommonents; |
|
10 <!ENTITY % booktitles SYSTEM "booktitles.ent"> |
|
11 %booktitles; |
|
12 <!ENTITY suncopy "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved."> |
|
13 ]> |
|
14 <?Pub UDT _bookmark _target> |
|
15 <?Pub Inc> |
|
16 <?PubInc> |
|
17 <refentry id="TIFFRGBAImage-3tiff"> |
|
18 <!-- %Z%%M% %I% %E% SMI; --> |
|
19 <refmeta><refentrytitle>TIFFRGBAImage</refentrytitle><manvolnum>3tiff</manvolnum> |
|
20 <refmiscinfo class="date">05 Apr 2004</refmiscinfo> |
|
21 <refmiscinfo class="sectdesc">&man3;</refmiscinfo> |
|
22 <refmiscinfo class="software">&release;</refmiscinfo> |
|
23 <refmiscinfo class="arch">generic</refmiscinfo> |
|
24 <refmiscinfo class="copyright">&suncopy;</refmiscinfo> |
|
25 </refmeta> |
|
26 <indexterm><primary>TIFFRGBAImage</primary></indexterm><indexterm><primary> |
|
27 read and decode an image into a raster</primary></indexterm> |
|
28 <refnamediv id="TIFFRGBAImage-3tiff-name"><refdescriptor>TIFFRGBAImage</refdescriptor> |
|
29 <refname>TIFFRGBAImageBegin</refname><refname>TIFFRGBAImageEnd</refname><refname> |
|
30 TIFFRGBAImageGet</refname><refname>TIFFRGBAImageOK</refname><refname>TIFFRGBAImageOriented<?Pub Caret> |
|
31 </refname><refpurpose>read and decode an image into a raster</refpurpose> |
|
32 </refnamediv> |
|
33 <refsect1 id="TIFFRGBAImage-3tiff-synp"><title>&synp-tt;</title> |
|
34 <programlisting>#include <tiffio.h> |
|
35 typedef unsigned char TIFFRGBValue; |
|
36 typedef struct _TIFFRGBAImage TIFFRGBAImage; |
|
37 int TIFFRGBAImageOK(TIFF* tif, char emsg[1024]); |
|
38 int TIFFRGBAImageBegin(TIFFRGBAImage* img, TIFF* tif, int stopOnError, char emsg[1024]); |
|
39 int TIFFRGBAImageGet(TIFFRGBAImage* img, uint32* raster, uint32 width, uint32 height); |
|
40 void TIFFRGBAImageEnd(TIFFRGBAImage* img);</programlisting> |
|
41 </refsect1> |
|
42 <refsect1 id="TIFFRGBAImage-3tiff-desc"><title>&desc-tt;</title> |
|
43 <para>The routines described here provide a high-level interface through which |
|
44 TIFF images may be read into memory. Images may be strip- or tile-based and |
|
45 have a variety of different characteristics: bits/sample, samples/pixel, photometric, |
|
46 and so on. Decoding state is encapsulated in a <literal>TIFFRGBAImage</literal> |
|
47 structure, which makes it possible to capture state for multiple images and |
|
48 quickly switch between them. The target raster format can be customized to |
|
49 the needs of a particular application by installing custom routines that manipulate |
|
50 image data according to application requirements.</para> |
|
51 <para>The default usage of these routines is as follows:</para> |
|
52 <orderedlist> |
|
53 <listitem><para>Use <literal>TIFFRGBAImageOK</literal> to check whether an |
|
54 image can be processed.</para></listitem> |
|
55 <listitem><para>Use <literal>TIFFRGBAImageBegin</literal> to construct a decoder |
|
56 state block.</para></listitem> |
|
57 <listitem><para>Use <literal>TIFFRGBAImageGet</literal> to read and decode |
|
58 an image into a target raster.</para></listitem> |
|
59 <listitem><para>Use <literal>TIFFRGBAImageEnd</literal> to release resources. |
|
60 </para></listitem> |
|
61 </orderedlist> |
|
62 <para><literal>TIFFRGBAImageGet</literal> can be called multiple times to |
|
63 decode an image using different state parameters. If multiple images are |
|
64 to be displayed and there is not enough space for each of the decoded rasters, |
|
65 multiple state blocks can be managed and then calls can be made to <literal> |
|
66 TIFFRGBAImageGet</literal> as needed to display an image.</para> |
|
67 <para>The generated raster is assumed to be an array of <replaceable>width |
|
68 </replaceable> times <replaceable>height</replaceable> 32-bit entries, where <replaceable> |
|
69 width</replaceable> must be less than or equal to the width of the image, |
|
70 and <replaceable>height</replaceable> may be any non-zero size. If the raster |
|
71 dimensions are smaller than the image, the image data is cropped to the raster |
|
72 bounds. If the raster height is greater than that of the image, then the image |
|
73 data is placed in the lower part of the raster. Note that the raster is assumed |
|
74 to be organized such that the pixel at location (<replaceable>x,y</replaceable>) |
|
75 is <replaceable>raster[y*width+x]</replaceable>, with the raster origin in |
|
76 the bottom-left corner.</para> |
|
77 </refsect1> |
|
78 <refsect1 id="TIFFRGBAImage-3tiff-exde"><title>&exde-tt;</title> |
|
79 <para>Raster pixels are 8-bit packed red, green, blue, alpha samples. The |
|
80 macros <literal>TIFFGetR</literal>, <literal>TIFFGetG</literal>, <literal> |
|
81 TIFFGetB</literal>, and <literal>TIFFGetA</literal> should be used to access |
|
82 individual samples. Images without Associated Alpha matting information have |
|
83 a constant Alpha of 1.0 (255).</para> |
|
84 <para><literal>TIFFRGBAImageGet</literal> converts non-8-bit images by scaling |
|
85 sample values. Palette, grayscale, bilevel, CMYK, and YCbCr images are converted |
|
86 to RGB transparently. Raster pixels are returned uncorrected by any colorimetry |
|
87 information present in the directory.</para> |
|
88 <para>The parameter <literal>stopOnError</literal> specifies how to act if |
|
89 an error is encountered while reading the image. If <literal>stopOnError</literal> |
|
90 is non-zero, then an error terminates the operation. Otherwise, <literal> |
|
91 TIFFRGBAImageGet</literal> continues to process data until all of the possible |
|
92 data in the image has been requested.</para> |
|
93 <refsect2 id="TIFFRGBAImage-3tiff-exde-raster"> |
|
94 <title>Alternate Raster Formats</title> |
|
95 <para>To use the core support for reading and processing TIFF images, but |
|
96 write the resulting raster data in a different format, you need only override |
|
97 the “put methods” used to store raster data. These methods are |
|
98 defined in the <literal>TIFFRGBAImage</literal> structure and initially set |
|
99 up by <literal>TIFFRGBAImageBegin</literal> to point to routines that pack |
|
100 raster data in the default ABGR pixel format. </para> |
|
101 <para>Two different routines are used according to the physical organization |
|
102 of the image data in the file:</para> |
|
103 <itemizedlist> |
|
104 <listitem><para>PlanarConfiguration=1 (packed samples)</para></listitem> |
|
105 <listitem><para>PlanarConfiguration=2 (separated samples). </para></listitem> |
|
106 </itemizedlist> |
|
107 <para>Note that this mechanism can be used to transform the data before storing |
|
108 the data in the raster. For example, you can convert data to colormap indices |
|
109 for display on a colormap display.</para> |
|
110 </refsect2> |
|
111 <refsect2 id="TIFFRGBAImage-3tiff-exde-display"> |
|
112 <title>Simultaneous Raster Store and Display</title> |
|
113 <para>An image can be displayed as the image is being into memory by overriding |
|
114 the put methods as described above to support alternate raster formats. Simply |
|
115 keep a reference to the default put methods set up by <literal>TIFFRGBAImageBegin |
|
116 </literal> and then invoke these methods before or after each display operation. |
|
117 For example, the <command>tiffgt(1)</command> utility uses the following put |
|
118 method to update the display as the raster is being filled:</para> |
|
119 <programlisting>static void |
|
120 putContigAndDraw(TIFFRGBAImage* img, uint32* raster, |
|
121 uint32 x, uint32 y, uint32 w, uint32 h, |
|
122 int32 fromskew, int32 toskew, |
|
123 unsigned char* cp) |
|
124 { |
|
125 (*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp); |
|
126 if (x+w == width) { |
|
127 w = width; |
|
128 if (img->orientation == ORIENTATION_TOPLEFT) |
|
129 lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w); |
|
130 else |
|
131 lrectwrite(0, y, w-1, y+h-1, raster); |
|
132 } |
|
133 } |
|
134 |
|
135 </programlisting> |
|
136 <para>The original routine provided by the library is saved in the variable <literal> |
|
137 putContig</literal>.</para> |
|
138 </refsect2> |
|
139 <refsect2 id="TIFFRGBAImage-3tiff-exde-tiff"> |
|
140 <title>Supporting Additional TIFF Formats</title> |
|
141 <para>The <literal>TIFFRGBAImage</literal> routines support the most commonly |
|
142 encountered flavors of TIFF. You can extend this support by overriding the “get |
|
143 method” invoked by <literal>TIFFRGBAImageGet</literal> to read TIFF |
|
144 image data. Details of how to do this can be quite involved, it is best to |
|
145 make a copy of an existing get method and modify to suit the needs of an application. |
|
146 </para> |
|
147 </refsect2> |
|
148 <refsect2 id="TIFFRGBAImage-3tiff-exde-diags"> |
|
149 <title>Diagnostics</title> |
|
150 <para>All error messages are directed to the <literal>TIFFError(3tiff)</literal> |
|
151 routine.</para> |
|
152 <variablelist termlength="wholeline"> |
|
153 <varlistentry><term>Sorry, can not handle %d-bit pictures.</term><listitem> |
|
154 <para>The image has a <literal>BitsPerSample</literal> value other than 1, |
|
155 2, 4, 8, or 16.</para> |
|
156 </listitem></varlistentry> |
|
157 <varlistentry><term>Sorry, can not handle %d-channel images.</term><listitem> |
|
158 <para>The image has a <literal>SamplesPerPixel</literal> value other than |
|
159 1, 3, or 4.</para> |
|
160 </listitem></varlistentry> |
|
161 <varlistentry><term>Missing needed "PhotometricInterpretation" tag.</term> |
|
162 <listitem><para>The image does not have a tag that describes how to display |
|
163 the data.</para> |
|
164 </listitem></varlistentry> |
|
165 <varlistentry><term>No "PhotometricInterpretation" tag, assuming RGB.</term> |
|
166 <listitem><para>The image does not have a tag that describes how to display |
|
167 the data, but is assumed to be RGB because the image has 3 or 4 samples/pixel. |
|
168 </para> |
|
169 </listitem></varlistentry> |
|
170 <varlistentry><term>No "PhotometricInterpretation" tag, assuming min-is-black. |
|
171 </term><listitem><para>The image does not have a tag that describes how to |
|
172 display the data, but is assumed to be a grayscale or bilevel image because |
|
173 the image has 1 sample/pixel.</para> |
|
174 </listitem></varlistentry> |
|
175 <varlistentry><term>No space for photometric conversion table.</term><listitem> |
|
176 <para>There is insufficient memory for a table needed to convert image samples |
|
177 to 8-bit RGB.</para> |
|
178 </listitem></varlistentry> |
|
179 <varlistentry><term>Missing required "Colormap" tag.</term><listitem><para> |
|
180 A Palette image does not have a required <literal>Colormap</literal> tag. |
|
181 </para> |
|
182 </listitem></varlistentry> |
|
183 <varlistentry><term>No space for tile buffer.</term><listitem><para>There |
|
184 is insufficient memory to allocate an i/o buffer.</para> |
|
185 </listitem></varlistentry> |
|
186 <varlistentry><term>No space for strip buffer.</term><listitem><para>There |
|
187 is insufficient memory to allocate an i/o buffer.</para> |
|
188 </listitem></varlistentry> |
|
189 <varlistentry><term>Can not handle format.</term><listitem><para>The image |
|
190 has a format (combination of <literal>BitsPerSample</literal>, <literal>SamplesPerPixel |
|
191 </literal>, and <literal>PhotometricInterpretation</literal>) that <literal> |
|
192 TIFFReadRGBAImage</literal> cannot process.</para> |
|
193 </listitem></varlistentry> |
|
194 <varlistentry><term>No space for B&W mapping table.</term><listitem><para> |
|
195 There is insufficient memory to allocate a table needed to map grayscale data |
|
196 to RGB.</para> |
|
197 </listitem></varlistentry> |
|
198 <varlistentry><term>No space for Palette mapping table.</term><listitem><para> |
|
199 There is insufficient memory to allocate a table needed to map data to 8-bit |
|
200 RGB.</para> |
|
201 </listitem></varlistentry> |
|
202 </variablelist></refsect2> |
|
203 </refsect1> |
|
204 <refsect1 id="TIFFRGBAImage-3tiff-rtrn"><title>&rtrn-tt;</title> |
|
205 <para>All routines return 1 if the operation was successful. Otherwise, 0 |
|
206 is returned if an error was encountered and <literal>stopOnError</literal> |
|
207 is zero.</para> |
|
208 </refsect1> |
|
209 <refsect1 id="TIFFRGBAImage-3tiff-attr"><title>&attr-tt;</title> |
|
210 <para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry> |
|
211 <refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink> |
|
212 for descriptions of the following attributes:</para> |
|
213 <informaltable frame="all"> |
|
214 <tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*"> |
|
215 <colspec colname="COLSPEC1" colwidth="1*"> |
|
216 <thead> |
|
217 <row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center" |
|
218 valign="middle">ATTRIBUTE VALUE</entry></row> |
|
219 </thead> |
|
220 <tbody> |
|
221 <row><entry><para>Availability</para></entry><entry><para>SUNWTiff</para></entry> |
|
222 </row> |
|
223 <row><entry colname="COLSPEC0"><para>Interface stability</para></entry><entry |
|
224 colname="COLSPEC1"><para>Evolving</para></entry></row> |
|
225 </tbody> |
|
226 </tgroup> |
|
227 </informaltable> |
|
228 </refsect1> |
|
229 <refsect1 id="TIFFRGBAImage-3tiff-also"><title>&also-tt;</title> |
|
230 <!--Reference to another man page--> |
|
231 <!--Reference to a Help manual--> |
|
232 <!--Reference to a book.--> |
|
233 <para><citerefentry><refentrytitle>libtiff</refentrytitle><manvolnum>3</manvolnum> |
|
234 </citerefentry>, <citerefentry><refentrytitle>TIFFOpen</refentrytitle><manvolnum> |
|
235 3tiff</manvolnum></citerefentry>, <citerefentry><refentrytitle>TIFFReadRGBAImage |
|
236 </refentrytitle><manvolnum>3tiff</manvolnum></citerefentry>, <citerefentry> |
|
237 <refentrytitle>TIFFReadRGBAStrip</refentrytitle><manvolnum>3tiff</manvolnum> |
|
238 </citerefentry>, <citerefentry><refentrytitle>TIFFReadRGBATile</refentrytitle> |
|
239 <manvolnum>3tiff</manvolnum></citerefentry></para> |
|
240 </refsect1> |
|
241 <refsect1 id="TIFFRGBAImage-3tiff-note"><title>¬e-tt;</title> |
|
242 <para>Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel |
|
243 must be either 1, 3, or 4 (that is, <literal>SamplesPerPixel</literal> minus <literal> |
|
244 ExtraSamples</literal>).</para> |
|
245 <para>Palette image colormaps that appear to be incorrectly written as 8-bit |
|
246 values are automatically scaled to 16-bits.</para> |
|
247 <para>Orientations other than bottom-left or top-left are not processed correctly. |
|
248 </para> |
|
249 <para>This man page was originally written by Sam Leffler. Updated by Breda |
|
250 McColgan, Sun Microsystems Inc., 2004.</para> |
|
251 </refsect1> |
|
252 </refentry> |
|
253 <?Pub *0000013365> |
|