+Modifying The TIFF Library
+
+Modifying The TIFF Library
++This chapter provides information about the internal structure of +the library, how to control the configuration when building it, and +how to add new support to the library. +The following sections are found in this chapter: + +
+Configuration defines are split into three areas: +
+If the define COMPRESSION_SUPPORT is not defined +then a default set of compression schemes is automatically +configured: +
+ +To override the default compression behaviour define +COMPRESSION_SUPPORT and then one or more additional defines +to enable configuration of the appropriate codecs (see the table +below); e.g. + +
+#define COMPRESSION_SUPPORT +#define CCITT_SUPPORT +#define PACKBITS_SUPPORT ++ +Several other compression schemes are configured separately from +the default set because they depend on ancillary software +packages that are not distributed with libtiff. + +
+Support for JPEG compression is controlled by JPEG_SUPPORT. +The JPEG codec that comes with libtiff is designed for +use with release 5 or later of the Independent JPEG Group's freely +available software distribution. +This software can be retrieved from the directory +ftp.uu.net:/graphics/jpeg/. + + +
+
+Enabling JPEG support automatically enables support for
+the TIFF 6.0 colorimetry and YCbCr-related tags.
+
+
+Experimental support for the deflate algorithm is controlled by +DEFLATE_SUPPORT. +The deflate codec that comes with libtiff is designed +for use with version 0.99 or later of the freely available +libz library written by Jean-loup Gailly and Mark Adler. +The data format used by this library is described +in the files +zlib-3.1.doc, +and +deflate-1.1.doc, +available in the directory +ftp.uu.net:/pub/archiving/zip/doc. +The library can be retried from the directory +ftp.uu.net:/pub/archiving/zip/zlib/ +(or try quest.jpl.nasa.gov:/beta/zlib/). + +
+
+The deflate algorithm is experimental. Do not expect
+to exchange files using this compression scheme;
+it is included only because the similar, and more common,
+LZW algorithm is claimed to be governed by licensing restrictions.
+
+
+
+By default tiffconf.h defines +COLORIMETRY_SUPPORT, +YCBCR_SUPPORT, +and +CMYK_SUPPORT. + +
+
| Define | Description |
|---|---|
| CCITT_SUPPORT | +CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, + and 32771) | +
| PACKBITS_SUPPORT | +Macintosh PackBits algorithm (compression 32773) | +
| LZW_SUPPORT | +Lempel-Ziv & Welch (LZW) algorithm (compression 5) | +
| THUNDER_SUPPORT | +4-bit +run-length encoding scheme from ThunderScan (compression 32809) | +
| NEXT_SUPPORT | +2-bit encoding scheme used by NeXT (compression 32766) | +
| OJPEG_SUPPORT | +obsolete JPEG scheme defined in the 6.0 spec (compression 6) | +
| JPEG_SUPPORT | +current JPEG scheme defined in TTN2 (compression 7) | +
| ZIP_SUPPORT | +experimental Deflate scheme (compression 32946) | +
| PIXARLOG_SUPPORT | +Pixar's compression scheme for high-resolution color images (compression 32909) | +
| SGILOG_SUPPORT | +SGI's compression scheme for high-resolution color images (compression 34676 and 34677) | +
| COLORIMETRY_SUPPORT | +support for the TIFF 6.0 colorimetry tags | +
| YCBCR_SUPPORT | +support for the TIFF 6.0 YCbCr-related tags | +
| CMYK_SUPPORT | +support for the TIFF 6.0 CMYK-related tags | +
| ICC_SUPPORT | +support for the ICC Profile tag; see +The ICC Profile Format Specification, +Annex B.3 "Embedding ICC Profiles in TIFF Files"; +available at +http://www.color.org + | +
+In general, the code is guaranteed to work only on SGI machines. +In practice it is highly portable to any 32-bit or 64-bit system and much +work has been done to insure portability to 16-bit systems. +If you encounter portability problems please return fixes so +that future distributions can be improved. + +
+The software is written to assume an ANSI C compilation environment. +If your compiler does not support ANSI function prototypes, const, +and <stdarg.h> then you will have to make modifications to the +software. In the past I have tried to support compilers without const +and systems without <stdarg.h>, but I am +no longer interested in these +antiquated environments. With the general availability of +the freely available GCC compiler, I +see no reason to incorporate modifications to the software for these +purposes. + +
+An effort has been made to isolate as many of the +operating system-dependencies +as possible in two files: tiffcomp.h and +libtiff/tif_<os>.c. The latter file contains +operating system-specific routines to do I/O and I/O-related operations. +The UNIX (tif_unix.c), +Macintosh (tif_apple.c), +and VMS (tif_vms.c) +code has had the most use; +the MS/DOS support (tif_msdos.c) assumes +some level of UNIX system call emulation (i.e. +open, +read, +write, +fstat, +malloc, +free). + +
+Native CPU byte order is determined on the fly by +the library and does not need to be specified. +The HOST_FILLORDER and HOST_BIGENDIAN +definitions are not currently used, but may be employed by +codecs for optimization purposes. + +
+The following defines control general portability: + +
+
| BSDTYPES | +Define this if your system does NOT define the + usual BSD typedefs: u_char, + u_short, u_int, u_long. | +
| HAVE_IEEEFP | +Define this as 0 or 1 according to the floating point + format suported by the machine. If your machine does + not support IEEE floating point then you will need to + add support to tif_machdep.c to convert between the + native format and IEEE format. | +
| HAVE_MMAP | +Define this if there is mmap-style support for +mapping files into memory (used only to read data). | +
| HOST_FILLORDER | +Define the native CPU bit order: one of FILLORDER_MSB2LSB + or FILLORDER_LSB2MSB | +
| HOST_BIGENDIAN | +Define the native CPU byte order: 1 if big-endian (Motorola) + or 0 if little-endian (Intel); this may be used + in codecs to optimize code | +
+On UNIX systems HAVE_MMAP is defined through the running of
+the configure script; otherwise support for memory-mapped
+files is disabled.
+Note that tiffcomp.h defines HAVE_IEEEFP to be
+1 (BSDTYPES is not defined).
+
+
+Types and Portability
+
+The software makes extensive use of C typedefs to promote portability.
+Two sets of typedefs are used, one for communication with clients
+of the library and one for internal data structures and parsing of the
+TIFF format. There are interactions between these two to be careful
+of, but for the most part you should be able to deal with portability
+purely by fiddling with the following machine-dependent typedefs:
+
+
+
+
| uint8 | +8-bit unsigned integer | +tiff.h | +
| int8 | +8-bit signed integer | +tiff.h | +
| uint16 | +16-bit unsigned integer | +tiff.h | +
| int16 | +16-bit signed integer | +tiff.h | +
| uint32 | +32-bit unsigned integer | +tiff.h | +
| int32 | +32-bit signed integer | +tiff.h | +
| dblparam_t | +promoted type for floats | +tiffcomp.h | +
+(to clarify dblparam_t, it is the type that float parameters are +promoted to when passed by value in a function call.) + +
+The following typedefs are used throughout the library and interfaces +to refer to certain objects whose size is dependent on the TIFF image +structure: + + +
+
| typedef unsigned int ttag_t; | directory tag | +
| typedef uint16 tdir_t; | directory index | +
| typedef uint16 tsample_t; | sample number | +
| typedef uint32 tstrip_t; | strip number | +
| typedef uint32 ttile_t; | tile number | +
| typedef int32 tsize_t; | i/o size in bytes | +
| typedef void* tdata_t; | image data ref | +
| typedef void* thandle_t; | client data handle | +
| typedef int32 toff_t; | file offset (should be off_t) | +
| typedef unsigned char* tidata_t; | internal image data | +
+Note that tstrip_t, ttile_t, and tsize_t +are constrained to be +no more than 32-bit quantities by 32-bit fields they are stored +in in the TIFF image. Likewise tsample_t is limited by the 16-bit +field used to store the SamplesPerPixel tag. tdir_t +constrains +the maximum number of IFDs that may appear in an image and may +be an arbitrary size (without penalty). ttag_t must be either +int, unsigned int, pointer, or double +because the library uses a varargs +interface and ANSI C restricts the type of the parameter before an +ellipsis to be a promoted type. toff_t is defined as +int32 because +TIFF file offsets are (unsigned) 32-bit quantities. A signed +value is used because some interfaces return -1 on error (sigh). +Finally, note that tidata_t is used internally to the library to +manipulate internal data. User-specified data references are +passed as opaque handles and only cast at the lowest layers where +their type is presumed. + + +
+A codec, say foo, can have many different entry points: + +
+TIFFInitfoo(tif, scheme)/* initialize scheme and setup entry points in tif */ +fooSetupDecode(tif) /* called once per IFD after tags has been frozen */ +fooPreDecode(tif, sample)/* called once per strip/tile, after data is read, + but before the first row is decoded */ +fooDecode*(tif, bp, cc, sample)/* decode cc bytes of data into the buffer */ + fooDecodeRow(...) /* called to decode a single scanline */ + fooDecodeStrip(...) /* called to decode an entire strip */ + fooDecodeTile(...) /* called to decode an entire tile */ +fooSetupEncode(tif) /* called once per IFD after tags has been frozen */ +fooPreEncode(tif, sample)/* called once per strip/tile, before the first row in + a strip/tile is encoded */ +fooEncode*(tif, bp, cc, sample)/* encode cc bytes of user data (bp) */ + fooEncodeRow(...) /* called to decode a single scanline */ + fooEncodeStrip(...) /* called to decode an entire strip */ + fooEncodeTile(...) /* called to decode an entire tile */ +fooPostEncode(tif) /* called once per strip/tile, just before data is written */ +fooSeek(tif, row) /* seek forwards row scanlines from the beginning + of a strip (row will always be >0 and <rows/strip */ +fooCleanup(tif) /* called when compression scheme is replaced by user */ ++ +
+Note that the encoding and decoding variants are only needed when
+a compression algorithm is dependent on the structure of the data.
+For example, Group 3 2D encoding and decoding maintains a reference
+scanline. The sample parameter identifies which sample is to be
+encoded or decoded if the image is organized with PlanarConfig=2
+(separate planes). This is important for algorithms such as JPEG.
+If PlanarConfig=1 (interleaved), then sample will always be 0.
+
+Other Comments
+
+The library handles most I/O buffering. There are two data buffers
+when decoding data: a raw data buffer that holds all the data in a
+strip, and a user-supplied scanline buffer that compression schemes
+place decoded data into. When encoding data the data in the
+user-supplied scanline buffer is encoded into the raw data buffer (from
+where it is written). Decoding routines should never have to explicitly
+read data -- a full strip/tile's worth of raw data is read and scanlines
+never cross strip boundaries. Encoding routines must be cognizant of
+the raw data buffer size and call TIFFFlushData1() when necessary.
+Note that any pending data is automatically flushed when a new strip/tile is
+started, so there's no need do that in the tif_postencode routine (if
+one exists). Bit order is automatically handled by the library when
+a raw strip or tile is filled. If the decoded samples are interpreted
+by the decoding routine before they are passed back to the user, then
+the decoding logic must handle byte-swapping by overriding the
+tif_postdecode
+routine (set it to TIFFNoPostDecode) and doing the required work
+internally. For an example of doing this look at the horizontal
+differencing code in the routines in tif_predict.c.
+
+
+The variables tif_rawcc, tif_rawdata, and +tif_rawcp in a TIFF structure +are associated with the raw data buffer. tif_rawcc must be non-zero +for the library to automatically flush data. The variable +tif_scanlinesize is the size a user's scanline buffer should be. The +variable tif_tilesize is the size of a tile for tiled images. This +should not normally be used by compression routines, except where it +relates to the compression algorithm. That is, the cc parameter to the +tif_decode* and tif_encode* +routines should be used in terminating +decompression/compression. This ensures these routines can be used, +for example, to decode/encode entire strips of data. + +
+In general, if you have a new compression algorithm to add, work from +the code for an existing routine. In particular, +tif_dumpmode.c +has the trivial code for the "nil" compression scheme, +tif_packbits.c is a +simple byte-oriented scheme that has to watch out for buffer +boundaries, and tif_lzw.c has the LZW scheme that has the most +complexity -- it tracks the buffer boundary at a bit level. +Of course, using a private compression scheme (or private tags) limits +the portability of your TIFF files. + +
+