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