|
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> |