|
0
|
1 |
<HTML>
|
|
|
2 |
<HEAD>
|
|
|
3 |
<TITLE>
|
|
|
4 |
Modifying The TIFF Library
|
|
|
5 |
</TITLE>
|
|
|
6 |
</HEAD>
|
|
|
7 |
<BODY BGCOLOR=white>
|
|
|
8 |
<FONT FACE="Arial, Helvetica, Sans">
|
|
|
9 |
<H1>
|
|
|
10 |
<IMG SRC=images/dave.gif WIDTH=107 HEIGHT=148 BORDER=2 ALIGN=left HSPACE=6>
|
|
|
11 |
Modifying The TIFF Library
|
|
|
12 |
</H1>
|
|
|
13 |
|
|
|
14 |
|
|
|
15 |
<P>
|
|
|
16 |
This chapter provides information about the internal structure of
|
|
|
17 |
the library, how to control the configuration when building it, and
|
|
|
18 |
how to add new support to the library.
|
|
|
19 |
The following sections are found in this chapter:
|
|
|
20 |
|
|
|
21 |
<UL>
|
|
|
22 |
<LI><A HREF=#Config>Library Configuration</A>
|
|
|
23 |
<LI><A HREF=#Portability>General Portability Comments</A>
|
|
|
24 |
<LI><A HREF="#Types">Types and Portability</A>
|
|
|
25 |
<LI><A HREF="addingtags.html">Adding New Tags</A>
|
|
|
26 |
<LI><A HREF=#AddingCODECS>Adding New Builtin Codecs</A>
|
|
|
27 |
<LI><A HREF="addingtags.html#AddingCODECTags">Adding New Codec-private Tags</A>
|
|
|
28 |
<LI><A HREF=#Other>Other Comments</A>
|
|
|
29 |
</UL>
|
|
|
30 |
|
|
|
31 |
|
|
|
32 |
<A NAME="Config"><P><HR WIDTH=65% ALIGN=right><H3>Library Configuration</H3></A>
|
|
|
33 |
|
|
|
34 |
Information on compiling the library is given
|
|
|
35 |
<A HREF=build.html>elsewhere in this documentation</A>.
|
|
|
36 |
This section describes the low-level mechanisms used to control
|
|
|
37 |
the optional parts of the library that are configured at build
|
|
|
38 |
time. Control is based on
|
|
|
39 |
a collection of C defines that are specified either on the compiler
|
|
|
40 |
command line or in a configuration file such as <TT>port.h</TT>
|
|
|
41 |
(as generated by the <TT>configure</TT> script for UNIX systems)
|
|
|
42 |
or <B>tiffconf.h</B>.
|
|
|
43 |
|
|
|
44 |
<P>
|
|
|
45 |
Configuration defines are split into three areas:
|
|
|
46 |
<UL>
|
|
|
47 |
<LI>those that control which compression schemes are
|
|
|
48 |
configured as part of the builtin codecs,
|
|
|
49 |
<LI>those that control support for groups of tags that
|
|
|
50 |
are considered optional, and
|
|
|
51 |
<LI>those that control operating system or machine-specific support.
|
|
|
52 |
</UL>
|
|
|
53 |
|
|
|
54 |
<P>
|
|
|
55 |
If the define <TT>COMPRESSION_SUPPORT</TT> is <STRONG>not defined</STRONG>
|
|
|
56 |
then a default set of compression schemes is automatically
|
|
|
57 |
configured:
|
|
|
58 |
<UL>
|
|
|
59 |
<LI>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, and 32771),
|
|
|
60 |
<LI>the Macintosh PackBits algorithm (compression 32773),
|
|
|
61 |
<LI>a 4-bit run-length encoding scheme from ThunderScan (compression 32809),
|
|
|
62 |
<LI>a 2-bit encoding scheme used by NeXT (compression 32766), and
|
|
|
63 |
<LI>two experimental schemes intended for images with high dynamic range
|
|
|
64 |
(compression 34676 and 34677).
|
|
|
65 |
</UL>
|
|
|
66 |
|
|
|
67 |
<P>
|
|
|
68 |
|
|
|
69 |
To override the default compression behaviour define
|
|
|
70 |
<TT>COMPRESSION_SUPPORT</TT> and then one or more additional defines
|
|
|
71 |
to enable configuration of the appropriate codecs (see the table
|
|
|
72 |
below); e.g.
|
|
|
73 |
|
|
|
74 |
<UL><PRE>
|
|
|
75 |
#define COMPRESSION_SUPPORT
|
|
|
76 |
#define CCITT_SUPPORT
|
|
|
77 |
#define PACKBITS_SUPPORT
|
|
|
78 |
</PRE></UL>
|
|
|
79 |
|
|
|
80 |
Several other compression schemes are configured separately from
|
|
|
81 |
the default set because they depend on ancillary software
|
|
|
82 |
packages that are not distributed with <TT>libtiff</TT>.
|
|
|
83 |
|
|
|
84 |
<P>
|
|
|
85 |
Support for JPEG compression is controlled by <TT>JPEG_SUPPORT</TT>.
|
|
|
86 |
The JPEG codec that comes with <TT>libtiff</TT> is designed for
|
|
|
87 |
use with release 5 or later of the Independent JPEG Group's freely
|
|
|
88 |
available software distribution.
|
|
|
89 |
This software can be retrieved from the directory
|
|
|
90 |
<A HREF=ftp://ftp.uu.net/graphics/jpeg>ftp.uu.net:/graphics/jpeg/</A>.
|
|
|
91 |
|
|
|
92 |
|
|
|
93 |
<P>
|
|
|
94 |
<IMG SRC="images/info.gif" ALT="NOTE: " ALIGN=left HSPACE=8>
|
|
|
95 |
<EM>Enabling JPEG support automatically enables support for
|
|
|
96 |
the TIFF 6.0 colorimetry and YCbCr-related tags.</EM>
|
|
|
97 |
|
|
|
98 |
<P>
|
|
|
99 |
Experimental support for the deflate algorithm is controlled by
|
|
|
100 |
<TT>DEFLATE_SUPPORT</TT>.
|
|
|
101 |
The deflate codec that comes with <TT>libtiff</TT> is designed
|
|
|
102 |
for use with version 0.99 or later of the freely available
|
|
|
103 |
<TT>libz</TT> library written by Jean-loup Gailly and Mark Adler.
|
|
|
104 |
The data format used by this library is described
|
|
|
105 |
in the files
|
|
|
106 |
<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/zlib-3.1.doc>zlib-3.1.doc</A>,
|
|
|
107 |
and
|
|
|
108 |
<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/deflate-1.1.doc>deflate-1.1.doc</A>,
|
|
|
109 |
available in the directory
|
|
|
110 |
<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc>ftp.uu.net:/pub/archiving/zip/doc</A>.</EM>
|
|
|
111 |
The library can be retried from the directory
|
|
|
112 |
<A HREF=ftp://ftp.uu.net/pub/archiving/zip/zlib/>ftp.uu.net:/pub/archiving/zip/zlib/</A>
|
|
|
113 |
(or try <A HREF=ftp://quest.jpl.nasa.gov/beta/zlib/>quest.jpl.nasa.gov:/beta/zlib/</A>).
|
|
|
114 |
|
|
|
115 |
<P>
|
|
|
116 |
<IMG SRC="images/warning.gif" ALT="NOTE: " ALIGN=left HSPACE=8 VSPACE=6>
|
|
|
117 |
<EM>The deflate algorithm is experimental. Do not expect
|
|
|
118 |
to exchange files using this compression scheme;
|
|
|
119 |
it is included only because the similar, and more common,
|
|
|
120 |
LZW algorithm is claimed to be governed by licensing restrictions.</EM>
|
|
|
121 |
|
|
|
122 |
|
|
|
123 |
<P>
|
|
|
124 |
By default <B>tiffconf.h</B> defines
|
|
|
125 |
<TT>COLORIMETRY_SUPPORT</TT>,
|
|
|
126 |
<TT>YCBCR_SUPPORT</TT>,
|
|
|
127 |
and
|
|
|
128 |
<TT>CMYK_SUPPORT</TT>.
|
|
|
129 |
|
|
|
130 |
<P>
|
|
|
131 |
<TABLE BORDER CELLPADDING=3>
|
|
|
132 |
|
|
|
133 |
<TR><TH ALIGN=left>Define</TH><TH ALIGN=left>Description</TH></TR>
|
|
|
134 |
|
|
|
135 |
<TR>
|
|
|
136 |
<TD VALIGN=top><TT>CCITT_SUPPORT</TT></TD>
|
|
|
137 |
<TD>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4,
|
|
|
138 |
and 32771)</TD>
|
|
|
139 |
</TR>
|
|
|
140 |
|
|
|
141 |
<TR>
|
|
|
142 |
<TD VALIGN=top><TT>PACKBITS_SUPPORT</TT></TD>
|
|
|
143 |
<TD>Macintosh PackBits algorithm (compression 32773)</TD>
|
|
|
144 |
</TR>
|
|
|
145 |
|
|
|
146 |
<TR>
|
|
|
147 |
<TD VALIGN=top><TT>LZW_SUPPORT</TT></TD>
|
|
|
148 |
<TD>Lempel-Ziv & Welch (LZW) algorithm (compression 5)</TD>
|
|
|
149 |
</TR>
|
|
|
150 |
|
|
|
151 |
<TR>
|
|
|
152 |
<TD VALIGN=top><TT>THUNDER_SUPPORT</TT></TD>
|
|
|
153 |
<TD>4-bit
|
|
|
154 |
run-length encoding scheme from ThunderScan (compression 32809)</TD>
|
|
|
155 |
</TR>
|
|
|
156 |
|
|
|
157 |
<TR>
|
|
|
158 |
<TD VALIGN=top><TT>NEXT_SUPPORT</TT></TD>
|
|
|
159 |
<TD>2-bit encoding scheme used by NeXT (compression 32766)</TD>
|
|
|
160 |
</TR>
|
|
|
161 |
|
|
|
162 |
<TR>
|
|
|
163 |
<TD VALIGN=top><TT>OJPEG_SUPPORT</TT></TD>
|
|
|
164 |
<TD>obsolete JPEG scheme defined in the 6.0 spec (compression 6)</TD>
|
|
|
165 |
</TR>
|
|
|
166 |
|
|
|
167 |
<TR>
|
|
|
168 |
<TD VALIGN=top><TT>JPEG_SUPPORT</TT></TD>
|
|
|
169 |
<TD>current JPEG scheme defined in TTN2 (compression 7)</TD>
|
|
|
170 |
</TR>
|
|
|
171 |
|
|
|
172 |
<TR>
|
|
|
173 |
<TD VALIGN=top><TT>ZIP_SUPPORT</TT></TD>
|
|
|
174 |
<TD>experimental Deflate scheme (compression 32946)</TD>
|
|
|
175 |
</TR>
|
|
|
176 |
|
|
|
177 |
<TR>
|
|
|
178 |
<TD VALIGN=top><TT>PIXARLOG_SUPPORT</TT></TD>
|
|
|
179 |
<TD>Pixar's compression scheme for high-resolution color images (compression 32909)</TD>
|
|
|
180 |
</TR>
|
|
|
181 |
|
|
|
182 |
<TR>
|
|
|
183 |
<TD VALIGN=top><TT>SGILOG_SUPPORT</TT></TD>
|
|
|
184 |
<TD>SGI's compression scheme for high-resolution color images (compression 34676 and 34677)</TD>
|
|
|
185 |
</TR>
|
|
|
186 |
|
|
|
187 |
<TR>
|
|
|
188 |
<TD VALIGN=top><TT>COLORIMETRY_SUPPORT</TT></TD>
|
|
|
189 |
<TD>support for the TIFF 6.0 colorimetry tags</TD>
|
|
|
190 |
</TR>
|
|
|
191 |
|
|
|
192 |
<TR>
|
|
|
193 |
<TD VALIGN=top><TT>YCBCR_SUPPORT</TT></TD>
|
|
|
194 |
<TD>support for the TIFF 6.0 YCbCr-related tags</TD>
|
|
|
195 |
</TR>
|
|
|
196 |
|
|
|
197 |
<TR>
|
|
|
198 |
<TD VALIGN=top><TT>CMYK_SUPPORT</TT></TD>
|
|
|
199 |
<TD>support for the TIFF 6.0 CMYK-related tags</TD>
|
|
|
200 |
</TR>
|
|
|
201 |
|
|
|
202 |
<TR>
|
|
|
203 |
<TD VALIGN=top><TT>ICC_SUPPORT</TT></TD>
|
|
|
204 |
<TD>support for the ICC Profile tag; see
|
|
|
205 |
<I>The ICC Profile Format Specification</I>,
|
|
|
206 |
Annex B.3 "Embedding ICC Profiles in TIFF Files";
|
|
|
207 |
available at
|
|
|
208 |
<A HREF=http://www.color.org>http://www.color.org</A>
|
|
|
209 |
</TD>
|
|
|
210 |
</TR>
|
|
|
211 |
|
|
|
212 |
</TABLE>
|
|
|
213 |
|
|
|
214 |
|
|
|
215 |
<A NAME="Portability"><P><HR WIDTH=65% ALIGN=right><H3>General Portability Comments</H3></A>
|
|
|
216 |
|
|
|
217 |
This software is developed on Silicon Graphics UNIX
|
|
|
218 |
systems (big-endian, MIPS CPU, 32-bit ints,
|
|
|
219 |
IEEE floating point).
|
|
|
220 |
The <TT>configure</TT> shell script generates the appropriate
|
|
|
221 |
include files and make files for UNIX systems.
|
|
|
222 |
Makefiles exist for non-UNIX platforms that the
|
|
|
223 |
code runs on -- this work has mostly been done by other people.
|
|
|
224 |
|
|
|
225 |
<P>
|
|
|
226 |
In general, the code is guaranteed to work only on SGI machines.
|
|
|
227 |
In practice it is highly portable to any 32-bit or 64-bit system and much
|
|
|
228 |
work has been done to insure portability to 16-bit systems.
|
|
|
229 |
If you encounter portability problems please return fixes so
|
|
|
230 |
that future distributions can be improved.
|
|
|
231 |
|
|
|
232 |
<P>
|
|
|
233 |
The software is written to assume an ANSI C compilation environment.
|
|
|
234 |
If your compiler does not support ANSI function prototypes, <TT>const</TT>,
|
|
|
235 |
and <TT><stdarg.h></TT> then you will have to make modifications to the
|
|
|
236 |
software. In the past I have tried to support compilers without <TT>const</TT>
|
|
|
237 |
and systems without <TT><stdarg.h></TT>, but I am
|
|
|
238 |
<EM>no longer interested in these
|
|
|
239 |
antiquated environments</EM>. With the general availability of
|
|
|
240 |
the freely available GCC compiler, I
|
|
|
241 |
see no reason to incorporate modifications to the software for these
|
|
|
242 |
purposes.
|
|
|
243 |
|
|
|
244 |
<P>
|
|
|
245 |
An effort has been made to isolate as many of the
|
|
|
246 |
operating system-dependencies
|
|
|
247 |
as possible in two files: <B>tiffcomp.h</B> and
|
|
|
248 |
<B>libtiff/tif_<os>.c</B>. The latter file contains
|
|
|
249 |
operating system-specific routines to do I/O and I/O-related operations.
|
|
|
250 |
The UNIX (<B>tif_unix.c</B>),
|
|
|
251 |
Macintosh (<B>tif_apple.c</B>),
|
|
|
252 |
and VMS (<B>tif_vms.c</B>)
|
|
|
253 |
code has had the most use;
|
|
|
254 |
the MS/DOS support (<B>tif_msdos.c</B>) assumes
|
|
|
255 |
some level of UNIX system call emulation (i.e.
|
|
|
256 |
<TT>open</TT>,
|
|
|
257 |
<TT>read</TT>,
|
|
|
258 |
<TT>write</TT>,
|
|
|
259 |
<TT>fstat</TT>,
|
|
|
260 |
<TT>malloc</TT>,
|
|
|
261 |
<TT>free</TT>).
|
|
|
262 |
|
|
|
263 |
<P>
|
|
|
264 |
Native CPU byte order is determined on the fly by
|
|
|
265 |
the library and does not need to be specified.
|
|
|
266 |
The <TT>HOST_FILLORDER</TT> and <TT>HOST_BIGENDIAN</TT>
|
|
|
267 |
definitions are not currently used, but may be employed by
|
|
|
268 |
codecs for optimization purposes.
|
|
|
269 |
|
|
|
270 |
<P>
|
|
|
271 |
The following defines control general portability:
|
|
|
272 |
|
|
|
273 |
<P>
|
|
|
274 |
<TABLE BORDER CELLPADDING=3 WIDTH=100%>
|
|
|
275 |
|
|
|
276 |
<TR>
|
|
|
277 |
<TD VALIGN=top><TT>BSDTYPES</TT></TD>
|
|
|
278 |
<TD>Define this if your system does NOT define the
|
|
|
279 |
usual BSD typedefs: <TT>u_char</TT>,
|
|
|
280 |
<TT>u_short</TT>, <TT>u_int</TT>, <TT>u_long</TT>.</TD>
|
|
|
281 |
</TR>
|
|
|
282 |
|
|
|
283 |
<TR>
|
|
|
284 |
<TD VALIGN=top><TT>HAVE_IEEEFP</TT></TD>
|
|
|
285 |
<TD>Define this as 0 or 1 according to the floating point
|
|
|
286 |
format suported by the machine. If your machine does
|
|
|
287 |
not support IEEE floating point then you will need to
|
|
|
288 |
add support to tif_machdep.c to convert between the
|
|
|
289 |
native format and IEEE format.</TD>
|
|
|
290 |
</TR>
|
|
|
291 |
|
|
|
292 |
<TR>
|
|
|
293 |
<TD VALIGN=top><TT>HAVE_MMAP</TT></TD>
|
|
|
294 |
<TD>Define this if there is <I>mmap-style</I> support for
|
|
|
295 |
mapping files into memory (used only to read data).</TD>
|
|
|
296 |
</TR>
|
|
|
297 |
|
|
|
298 |
<TR>
|
|
|
299 |
<TD VALIGN=top><TT>HOST_FILLORDER</TT></TD>
|
|
|
300 |
<TD>Define the native CPU bit order: one of <TT>FILLORDER_MSB2LSB</TT>
|
|
|
301 |
or <TT>FILLORDER_LSB2MSB</TT></TD>
|
|
|
302 |
</TR>
|
|
|
303 |
|
|
|
304 |
<TR>
|
|
|
305 |
<TD VALIGN=top><TT>HOST_BIGENDIAN</TT></TD>
|
|
|
306 |
<TD>Define the native CPU byte order: 1 if big-endian (Motorola)
|
|
|
307 |
or 0 if little-endian (Intel); this may be used
|
|
|
308 |
in codecs to optimize code</TD>
|
|
|
309 |
</TR>
|
|
|
310 |
</TABLE>
|
|
|
311 |
|
|
|
312 |
<P>
|
|
|
313 |
On UNIX systems <TT>HAVE_MMAP</TT> is defined through the running of
|
|
|
314 |
the <TT>configure</TT> script; otherwise support for memory-mapped
|
|
|
315 |
files is disabled.
|
|
|
316 |
Note that <B>tiffcomp.h</B> defines <TT>HAVE_IEEEFP</TT> to be
|
|
|
317 |
1 (<TT>BSDTYPES</TT> is not defined).
|
|
|
318 |
|
|
|
319 |
|
|
|
320 |
<A NAME="Types"><P><HR WIDTH=65% ALIGN=right><H3>Types and Portability</H3></A>
|
|
|
321 |
|
|
|
322 |
The software makes extensive use of C typedefs to promote portability.
|
|
|
323 |
Two sets of typedefs are used, one for communication with clients
|
|
|
324 |
of the library and one for internal data structures and parsing of the
|
|
|
325 |
TIFF format. There are interactions between these two to be careful
|
|
|
326 |
of, but for the most part you should be able to deal with portability
|
|
|
327 |
purely by fiddling with the following machine-dependent typedefs:
|
|
|
328 |
|
|
|
329 |
|
|
|
330 |
<P>
|
|
|
331 |
<TABLE BORDER CELLPADDING=3 WIDTH=100%>
|
|
|
332 |
|
|
|
333 |
<TR>
|
|
|
334 |
<TD>uint8</TD>
|
|
|
335 |
<TD>8-bit unsigned integer</TD>
|
|
|
336 |
<TD>tiff.h</TD>
|
|
|
337 |
</TR>
|
|
|
338 |
|
|
|
339 |
<TR>
|
|
|
340 |
<TD>int8</TD>
|
|
|
341 |
<TD>8-bit signed integer</TD>
|
|
|
342 |
<TD>tiff.h</TD>
|
|
|
343 |
</TR>
|
|
|
344 |
|
|
|
345 |
<TR>
|
|
|
346 |
<TD>uint16</TD>
|
|
|
347 |
<TD>16-bit unsigned integer</TD>
|
|
|
348 |
<TD>tiff.h</TD>
|
|
|
349 |
</TR>
|
|
|
350 |
|
|
|
351 |
<TR>
|
|
|
352 |
<TD>int16</TD>
|
|
|
353 |
<TD>16-bit signed integer</TD>
|
|
|
354 |
<TD>tiff.h</TD>
|
|
|
355 |
</TR>
|
|
|
356 |
|
|
|
357 |
<TR>
|
|
|
358 |
<TD>uint32</TD>
|
|
|
359 |
<TD>32-bit unsigned integer</TD>
|
|
|
360 |
<TD>tiff.h</TD>
|
|
|
361 |
</TR>
|
|
|
362 |
|
|
|
363 |
<TR>
|
|
|
364 |
<TD>int32</TD>
|
|
|
365 |
<TD>32-bit signed integer</TD>
|
|
|
366 |
<TD>tiff.h</TD>
|
|
|
367 |
</TR>
|
|
|
368 |
|
|
|
369 |
<TR>
|
|
|
370 |
<TD>dblparam_t</TD>
|
|
|
371 |
<TD>promoted type for floats</TD>
|
|
|
372 |
<TD>tiffcomp.h</TD>
|
|
|
373 |
</TR>
|
|
|
374 |
|
|
|
375 |
</TABLE>
|
|
|
376 |
|
|
|
377 |
<P>
|
|
|
378 |
(to clarify <TT>dblparam_t</TT>, it is the type that float parameters are
|
|
|
379 |
promoted to when passed by value in a function call.)
|
|
|
380 |
|
|
|
381 |
<P>
|
|
|
382 |
The following typedefs are used throughout the library and interfaces
|
|
|
383 |
to refer to certain objects whose size is dependent on the TIFF image
|
|
|
384 |
structure:
|
|
|
385 |
|
|
|
386 |
|
|
|
387 |
<P>
|
|
|
388 |
<TABLE BORDER CELLPADDING=3 WIDTH=100%>
|
|
|
389 |
|
|
|
390 |
<TR>
|
|
|
391 |
<TD WIDTH=25%>typedef unsigned int ttag_t;</TD> <TD>directory tag</TD>
|
|
|
392 |
</TR>
|
|
|
393 |
|
|
|
394 |
<TR>
|
|
|
395 |
<TD>typedef uint16 tdir_t;</TD> <TD>directory index</TD>
|
|
|
396 |
</TR>
|
|
|
397 |
|
|
|
398 |
<TR>
|
|
|
399 |
<TD>typedef uint16 tsample_t;</TD> <TD>sample number</TD>
|
|
|
400 |
</TR>
|
|
|
401 |
|
|
|
402 |
<TR>
|
|
|
403 |
<TD>typedef uint32 tstrip_t;</TD> <TD>strip number</TD>
|
|
|
404 |
</TR>
|
|
|
405 |
|
|
|
406 |
<TR>
|
|
|
407 |
<TD>typedef uint32 ttile_t;</TD> <TD>tile number</TD>
|
|
|
408 |
</TR>
|
|
|
409 |
|
|
|
410 |
<TR>
|
|
|
411 |
<TD>typedef int32 tsize_t;</TD> <TD>i/o size in bytes</TD>
|
|
|
412 |
</TR>
|
|
|
413 |
|
|
|
414 |
<TR>
|
|
|
415 |
<TD>typedef void* tdata_t;</TD> <TD>image data ref</TD>
|
|
|
416 |
</TR>
|
|
|
417 |
|
|
|
418 |
<TR>
|
|
|
419 |
<TD>typedef void* thandle_t;</TD> <TD>client data handle</TD>
|
|
|
420 |
</TR>
|
|
|
421 |
|
|
|
422 |
<TR>
|
|
|
423 |
<TD>typedef int32 toff_t;</TD> <TD>file offset (should be off_t)</TD>
|
|
|
424 |
</TR>
|
|
|
425 |
|
|
|
426 |
<TR>
|
|
|
427 |
<TD>typedef unsigned char* tidata_t;</TD> <TD>internal image data</TD>
|
|
|
428 |
</TR>
|
|
|
429 |
|
|
|
430 |
</TABLE>
|
|
|
431 |
|
|
|
432 |
<P>
|
|
|
433 |
Note that <TT>tstrip_t</TT>, <TT>ttile_t</TT>, and <TT>tsize_t</TT>
|
|
|
434 |
are constrained to be
|
|
|
435 |
no more than 32-bit quantities by 32-bit fields they are stored
|
|
|
436 |
in in the TIFF image. Likewise <TT>tsample_t</TT> is limited by the 16-bit
|
|
|
437 |
field used to store the <TT>SamplesPerPixel</TT> tag. <TT>tdir_t</TT>
|
|
|
438 |
constrains
|
|
|
439 |
the maximum number of IFDs that may appear in an image and may
|
|
|
440 |
be an arbitrary size (without penalty). <TT>ttag_t</TT> must be either
|
|
|
441 |
<TT>int</TT>, <TT>unsigned int</TT>, pointer, or <TT>double</TT>
|
|
|
442 |
because the library uses a varargs
|
|
|
443 |
interface and ANSI C restricts the type of the parameter before an
|
|
|
444 |
ellipsis to be a promoted type. <TT>toff_t</TT> is defined as
|
|
|
445 |
<TT>int32</TT> because
|
|
|
446 |
TIFF file offsets are (unsigned) 32-bit quantities. A signed
|
|
|
447 |
value is used because some interfaces return -1 on error (sigh).
|
|
|
448 |
Finally, note that <TT>tidata_t</TT> is used internally to the library to
|
|
|
449 |
manipulate internal data. User-specified data references are
|
|
|
450 |
passed as opaque handles and only cast at the lowest layers where
|
|
|
451 |
their type is presumed.
|
|
|
452 |
|
|
|
453 |
|
|
|
454 |
<P><HR WIDTH=65% ALIGN=right><H3>General Comments</H3></A>
|
|
|
455 |
|
|
|
456 |
The library is designed to hide as much of the details of TIFF from
|
|
|
457 |
applications as
|
|
|
458 |
possible. In particular, TIFF directories are read in their entirety
|
|
|
459 |
into an internal format. Only the tags known by the library are
|
|
|
460 |
available to a user and certain tag data may be maintained that a user
|
|
|
461 |
does not care about (e.g. transfer function tables).
|
|
|
462 |
|
|
|
463 |
<A NAME=AddingCODECS><P><HR WIDTH=65% ALIGN=right><H3>Adding New Builtin Codecs</H3></A>
|
|
|
464 |
|
|
|
465 |
To add builtin support for a new compression algorithm, you can either
|
|
|
466 |
use the "tag-extension" trick to override the handling of the
|
|
|
467 |
TIFF Compression tag (see <A HREF=addingtags.html>Adding New Tags</A>),
|
|
|
468 |
or do the following to add support directly to the core library:
|
|
|
469 |
|
|
|
470 |
<OL>
|
|
|
471 |
<LI>Define the tag value in <B>tiff.h</B>.
|
|
|
472 |
<LI>Edit the file <B>tif_codec.c</B> to add an entry to the
|
|
|
473 |
_TIFFBuiltinCODECS array (see how other algorithms are handled).
|
|
|
474 |
<LI>Add the appropriate function prototype declaration to
|
|
|
475 |
<B>tiffiop.h</B> (close to the bottom).
|
|
|
476 |
<LI>Create a file with the compression scheme code, by convention files
|
|
|
477 |
are named <B>tif_*.c</B> (except perhaps on some systems where the
|
|
|
478 |
tif_ prefix pushes some filenames over 14 chars.
|
|
|
479 |
<LI>Edit <B>Makefile.in</B> (and any other Makefiles)
|
|
|
480 |
to include the new source file.
|
|
|
481 |
</OL>
|
|
|
482 |
|
|
|
483 |
<P>
|
|
|
484 |
A codec, say <TT>foo</TT>, can have many different entry points:
|
|
|
485 |
|
|
|
486 |
<PRE>
|
|
|
487 |
TIFFInitfoo(tif, scheme)/* initialize scheme and setup entry points in tif */
|
|
|
488 |
fooSetupDecode(tif) /* called once per IFD after tags has been frozen */
|
|
|
489 |
fooPreDecode(tif, sample)/* called once per strip/tile, after data is read,
|
|
|
490 |
but before the first row is decoded */
|
|
|
491 |
fooDecode*(tif, bp, cc, sample)/* decode cc bytes of data into the buffer */
|
|
|
492 |
fooDecodeRow(...) /* called to decode a single scanline */
|
|
|
493 |
fooDecodeStrip(...) /* called to decode an entire strip */
|
|
|
494 |
fooDecodeTile(...) /* called to decode an entire tile */
|
|
|
495 |
fooSetupEncode(tif) /* called once per IFD after tags has been frozen */
|
|
|
496 |
fooPreEncode(tif, sample)/* called once per strip/tile, before the first row in
|
|
|
497 |
a strip/tile is encoded */
|
|
|
498 |
fooEncode*(tif, bp, cc, sample)/* encode cc bytes of user data (bp) */
|
|
|
499 |
fooEncodeRow(...) /* called to decode a single scanline */
|
|
|
500 |
fooEncodeStrip(...) /* called to decode an entire strip */
|
|
|
501 |
fooEncodeTile(...) /* called to decode an entire tile */
|
|
|
502 |
fooPostEncode(tif) /* called once per strip/tile, just before data is written */
|
|
|
503 |
fooSeek(tif, row) /* seek forwards row scanlines from the beginning
|
|
|
504 |
of a strip (row will always be >0 and <rows/strip */
|
|
|
505 |
fooCleanup(tif) /* called when compression scheme is replaced by user */
|
|
|
506 |
</PRE>
|
|
|
507 |
|
|
|
508 |
<P>
|
|
|
509 |
Note that the encoding and decoding variants are only needed when
|
|
|
510 |
a compression algorithm is dependent on the structure of the data.
|
|
|
511 |
For example, Group 3 2D encoding and decoding maintains a reference
|
|
|
512 |
scanline. The sample parameter identifies which sample is to be
|
|
|
513 |
encoded or decoded if the image is organized with <TT>PlanarConfig</TT>=2
|
|
|
514 |
(separate planes). This is important for algorithms such as JPEG.
|
|
|
515 |
If <TT>PlanarConfig</TT>=1 (interleaved), then sample will always be 0.
|
|
|
516 |
|
|
|
517 |
<A NAME=Other><P><HR WIDTH=65% ALIGN=right><H3>Other Comments</H3></A>
|
|
|
518 |
|
|
|
519 |
The library handles most I/O buffering. There are two data buffers
|
|
|
520 |
when decoding data: a raw data buffer that holds all the data in a
|
|
|
521 |
strip, and a user-supplied scanline buffer that compression schemes
|
|
|
522 |
place decoded data into. When encoding data the data in the
|
|
|
523 |
user-supplied scanline buffer is encoded into the raw data buffer (from
|
|
|
524 |
where it is written). Decoding routines should never have to explicitly
|
|
|
525 |
read data -- a full strip/tile's worth of raw data is read and scanlines
|
|
|
526 |
never cross strip boundaries. Encoding routines must be cognizant of
|
|
|
527 |
the raw data buffer size and call <TT>TIFFFlushData1()</TT> when necessary.
|
|
|
528 |
Note that any pending data is automatically flushed when a new strip/tile is
|
|
|
529 |
started, so there's no need do that in the tif_postencode routine (if
|
|
|
530 |
one exists). Bit order is automatically handled by the library when
|
|
|
531 |
a raw strip or tile is filled. If the decoded samples are interpreted
|
|
|
532 |
by the decoding routine before they are passed back to the user, then
|
|
|
533 |
the decoding logic must handle byte-swapping by overriding the
|
|
|
534 |
<TT>tif_postdecode</TT>
|
|
|
535 |
routine (set it to <TT>TIFFNoPostDecode</TT>) and doing the required work
|
|
|
536 |
internally. For an example of doing this look at the horizontal
|
|
|
537 |
differencing code in the routines in <B>tif_predict.c</B>.
|
|
|
538 |
|
|
|
539 |
<P>
|
|
|
540 |
The variables <TT>tif_rawcc</TT>, <TT>tif_rawdata</TT>, and
|
|
|
541 |
<TT>tif_rawcp</TT> in a <TT>TIFF</TT> structure
|
|
|
542 |
are associated with the raw data buffer. <TT>tif_rawcc</TT> must be non-zero
|
|
|
543 |
for the library to automatically flush data. The variable
|
|
|
544 |
<TT>tif_scanlinesize</TT> is the size a user's scanline buffer should be. The
|
|
|
545 |
variable <TT>tif_tilesize</TT> is the size of a tile for tiled images. This
|
|
|
546 |
should not normally be used by compression routines, except where it
|
|
|
547 |
relates to the compression algorithm. That is, the <TT>cc</TT> parameter to the
|
|
|
548 |
<TT>tif_decode*</TT> and <TT>tif_encode*</TT>
|
|
|
549 |
routines should be used in terminating
|
|
|
550 |
decompression/compression. This ensures these routines can be used,
|
|
|
551 |
for example, to decode/encode entire strips of data.
|
|
|
552 |
|
|
|
553 |
<P>
|
|
|
554 |
In general, if you have a new compression algorithm to add, work from
|
|
|
555 |
the code for an existing routine. In particular,
|
|
|
556 |
<B>tif_dumpmode.c</B>
|
|
|
557 |
has the trivial code for the "nil" compression scheme,
|
|
|
558 |
<B>tif_packbits.c</B> is a
|
|
|
559 |
simple byte-oriented scheme that has to watch out for buffer
|
|
|
560 |
boundaries, and <B>tif_lzw.c</B> has the LZW scheme that has the most
|
|
|
561 |
complexity -- it tracks the buffer boundary at a bit level.
|
|
|
562 |
Of course, using a private compression scheme (or private tags) limits
|
|
|
563 |
the portability of your TIFF files.
|
|
|
564 |
|
|
|
565 |
<P>
|
|
|
566 |
<HR>
|
|
|
567 |
|
|
|
568 |
Last updated: $Date: 2004/09/10 14:47:31 $
|
|
|
569 |
|
|
|
570 |
</BODY>
|
|
|
571 |
|
|
|
572 |
</HTML>
|