1<HTML> 2<HEAD> 3<TITLE> 4Modifying 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> 11Modifying The TIFF Library 12</H1> 13 14 15<P> 16This chapter provides information about the internal structure of 17the library, how to control the configuration when building it, and 18how to add new support to the library. 19The 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 34Information on compiling the library is given 35<A HREF=build.html>elsewhere in this documentation</A>. 36This section describes the low-level mechanisms used to control 37the optional parts of the library that are configured at build 38time. Control is based on 39a collection of C defines that are specified either on the compiler 40command line or in a configuration file such as <TT>port.h</TT> 41(as generated by the <TT>configure</TT> script for UNIX systems) 42or <B>tiffconf.h</B>. 43 44<P> 45Configuration 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> 55If the define <TT>COMPRESSION_SUPPORT</TT> is <STRONG>not defined</STRONG> 56then a default set of compression schemes is automatically 57configured: 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 69To override the default compression behaviour define 70<TT>COMPRESSION_SUPPORT</TT> and then one or more additional defines 71to enable configuration of the appropriate codecs (see the table 72below); e.g. 73 74<UL><PRE> 75#define COMPRESSION_SUPPORT 76#define CCITT_SUPPORT 77#define PACKBITS_SUPPORT 78</PRE></UL> 79 80Several other compression schemes are configured separately from 81the default set because they depend on ancillary software 82packages that are not distributed with <TT>libtiff</TT>. 83 84<P> 85Support for JPEG compression is controlled by <TT>JPEG_SUPPORT</TT>. 86The JPEG codec that comes with <TT>libtiff</TT> is designed for 87use with release 5 or later of the Independent JPEG Group's freely 88available software distribution. 89This 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 96the TIFF 6.0 colorimetry and YCbCr-related tags.</EM> 97 98<P> 99Experimental support for the deflate algorithm is controlled by 100<TT>DEFLATE_SUPPORT</TT>. 101The deflate codec that comes with <TT>libtiff</TT> is designed 102for use with version 0.99 or later of the freely available 103<TT>libz</TT> library written by Jean-loup Gailly and Mark Adler. 104The data format used by this library is described 105in the files 106<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/zlib-3.1.doc>zlib-3.1.doc</A>, 107and 108<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/deflate-1.1.doc>deflate-1.1.doc</A>, 109available in the directory 110<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc>ftp.uu.net:/pub/archiving/zip/doc</A>.</EM> 111The 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 118to exchange files using this compression scheme; 119it is included only because the similar, and more common, 120LZW algorithm is claimed to be governed by licensing restrictions.</EM> 121 122 123<P> 124By default <B>tiffconf.h</B> defines 125<TT>COLORIMETRY_SUPPORT</TT>, 126<TT>YCBCR_SUPPORT</TT>, 127and 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 154run-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>, 206Annex B.3 "Embedding ICC Profiles in TIFF Files"; 207available 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 217This software is developed on Silicon Graphics UNIX 218systems (big-endian, MIPS CPU, 32-bit ints, 219IEEE floating point). 220The <TT>configure</TT> shell script generates the appropriate 221include files and make files for UNIX systems. 222Makefiles exist for non-UNIX platforms that the 223code runs on -- this work has mostly been done by other people. 224 225<P> 226In general, the code is guaranteed to work only on SGI machines. 227In practice it is highly portable to any 32-bit or 64-bit system and much 228work has been done to insure portability to 16-bit systems. 229If you encounter portability problems please return fixes so 230that future distributions can be improved. 231 232<P> 233The software is written to assume an ANSI C compilation environment. 234If your compiler does not support ANSI function prototypes, <TT>const</TT>, 235and <TT><stdarg.h></TT> then you will have to make modifications to the 236software. In the past I have tried to support compilers without <TT>const</TT> 237and systems without <TT><stdarg.h></TT>, but I am 238<EM>no longer interested in these 239antiquated environments</EM>. With the general availability of 240the freely available GCC compiler, I 241see no reason to incorporate modifications to the software for these 242purposes. 243 244<P> 245An effort has been made to isolate as many of the 246operating system-dependencies 247as possible in two files: <B>tiffcomp.h</B> and 248<B>libtiff/tif_<os>.c</B>. The latter file contains 249operating system-specific routines to do I/O and I/O-related operations. 250The UNIX (<B>tif_unix.c</B>), 251Macintosh (<B>tif_apple.c</B>), 252and VMS (<B>tif_vms.c</B>) 253code has had the most use; 254the MS/DOS support (<B>tif_msdos.c</B>) assumes 255some 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> 264Native CPU byte order is determined on the fly by 265the library and does not need to be specified. 266The <TT>HOST_FILLORDER</TT> and <TT>HOST_BIGENDIAN</TT> 267definitions are not currently used, but may be employed by 268codecs for optimization purposes. 269 270<P> 271The 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 295mapping 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> 313On UNIX systems <TT>HAVE_MMAP</TT> is defined through the running of 314the <TT>configure</TT> script; otherwise support for memory-mapped 315files is disabled. 316Note that <B>tiffcomp.h</B> defines <TT>HAVE_IEEEFP</TT> to be 3171 (<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 322The software makes extensive use of C typedefs to promote portability. 323Two sets of typedefs are used, one for communication with clients 324of the library and one for internal data structures and parsing of the 325TIFF format. There are interactions between these two to be careful 326of, but for the most part you should be able to deal with portability 327purely 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 379promoted to when passed by value in a function call.) 380 381<P> 382The following typedefs are used throughout the library and interfaces 383to refer to certain objects whose size is dependent on the TIFF image 384structure: 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> 433Note that <TT>tstrip_t</TT>, <TT>ttile_t</TT>, and <TT>tsize_t</TT> 434are constrained to be 435no more than 32-bit quantities by 32-bit fields they are stored 436in in the TIFF image. Likewise <TT>tsample_t</TT> is limited by the 16-bit 437field used to store the <TT>SamplesPerPixel</TT> tag. <TT>tdir_t</TT> 438constrains 439the maximum number of IFDs that may appear in an image and may 440be 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> 442because the library uses a varargs 443interface and ANSI C restricts the type of the parameter before an 444ellipsis to be a promoted type. <TT>toff_t</TT> is defined as 445<TT>int32</TT> because 446TIFF file offsets are (unsigned) 32-bit quantities. A signed 447value is used because some interfaces return -1 on error (sigh). 448Finally, note that <TT>tidata_t</TT> is used internally to the library to 449manipulate internal data. User-specified data references are 450passed as opaque handles and only cast at the lowest layers where 451their type is presumed. 452 453 454<P><HR WIDTH=65% ALIGN=right><H3>General Comments</H3></A> 455 456The library is designed to hide as much of the details of TIFF from 457applications as 458possible. In particular, TIFF directories are read in their entirety 459into an internal format. Only the tags known by the library are 460available to a user and certain tag data may be maintained that a user 461does 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 465To add builtin support for a new compression algorithm, you can either 466use the "tag-extension" trick to override the handling of the 467TIFF Compression tag (see <A HREF=addingtags.html>Adding New Tags</A>), 468or 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> 484A codec, say <TT>foo</TT>, can have many different entry points: 485 486<PRE> 487TIFFInitfoo(tif, scheme)/* initialize scheme and setup entry points in tif */ 488fooSetupDecode(tif) /* called once per IFD after tags has been frozen */ 489fooPreDecode(tif, sample)/* called once per strip/tile, after data is read, 490 but before the first row is decoded */ 491fooDecode*(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 */ 495fooSetupEncode(tif) /* called once per IFD after tags has been frozen */ 496fooPreEncode(tif, sample)/* called once per strip/tile, before the first row in 497 a strip/tile is encoded */ 498fooEncode*(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 */ 502fooPostEncode(tif) /* called once per strip/tile, just before data is written */ 503fooSeek(tif, row) /* seek forwards row scanlines from the beginning 504 of a strip (row will always be >0 and <rows/strip */ 505fooCleanup(tif) /* called when compression scheme is replaced by user */ 506</PRE> 507 508<P> 509Note that the encoding and decoding variants are only needed when 510a compression algorithm is dependent on the structure of the data. 511For example, Group 3 2D encoding and decoding maintains a reference 512scanline. The sample parameter identifies which sample is to be 513encoded or decoded if the image is organized with <TT>PlanarConfig</TT>=2 514(separate planes). This is important for algorithms such as JPEG. 515If <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 519The library handles most I/O buffering. There are two data buffers 520when decoding data: a raw data buffer that holds all the data in a 521strip, and a user-supplied scanline buffer that compression schemes 522place decoded data into. When encoding data the data in the 523user-supplied scanline buffer is encoded into the raw data buffer (from 524where it is written). Decoding routines should never have to explicitly 525read data -- a full strip/tile's worth of raw data is read and scanlines 526never cross strip boundaries. Encoding routines must be cognizant of 527the raw data buffer size and call <TT>TIFFFlushData1()</TT> when necessary. 528Note that any pending data is automatically flushed when a new strip/tile is 529started, so there's no need do that in the tif_postencode routine (if 530one exists). Bit order is automatically handled by the library when 531a raw strip or tile is filled. If the decoded samples are interpreted 532by the decoding routine before they are passed back to the user, then 533the decoding logic must handle byte-swapping by overriding the 534<TT>tif_postdecode</TT> 535routine (set it to <TT>TIFFNoPostDecode</TT>) and doing the required work 536internally. For an example of doing this look at the horizontal 537differencing code in the routines in <B>tif_predict.c</B>. 538 539<P> 540The variables <TT>tif_rawcc</TT>, <TT>tif_rawdata</TT>, and 541<TT>tif_rawcp</TT> in a <TT>TIFF</TT> structure 542are associated with the raw data buffer. <TT>tif_rawcc</TT> must be non-zero 543for the library to automatically flush data. The variable 544<TT>tif_scanlinesize</TT> is the size a user's scanline buffer should be. The 545variable <TT>tif_tilesize</TT> is the size of a tile for tiled images. This 546should not normally be used by compression routines, except where it 547relates to the compression algorithm. That is, the <TT>cc</TT> parameter to the 548<TT>tif_decode*</TT> and <TT>tif_encode*</TT> 549routines should be used in terminating 550decompression/compression. This ensures these routines can be used, 551for example, to decode/encode entire strips of data. 552 553<P> 554In general, if you have a new compression algorithm to add, work from 555the code for an existing routine. In particular, 556<B>tif_dumpmode.c</B> 557has the trivial code for the "nil" compression scheme, 558<B>tif_packbits.c</B> is a 559simple byte-oriented scheme that has to watch out for buffer 560boundaries, and <B>tif_lzw.c</B> has the LZW scheme that has the most 561complexity -- it tracks the buffer boundary at a bit level. 562Of course, using a private compression scheme (or private tags) limits 563the portability of your TIFF files. 564 565<P> 566<HR> 567 568Last updated: $Date: 2016-09-25 20:05:44 $ 569 570</BODY> 571 572</HTML> 573