10ef31e1fSMike Welles<HTML> 20ef31e1fSMike Welles<HEAD> 30ef31e1fSMike Welles<TITLE> 40ef31e1fSMike WellesModifying The TIFF Library 50ef31e1fSMike Welles</TITLE> 60ef31e1fSMike Welles</HEAD> 7a446e861SMike Welles<BODY BGCOLOR=white> 8dcb05556SMike Welles<FONT FACE="Arial, Helvetica, Sans"> 90ef31e1fSMike Welles<H1> 100ef31e1fSMike Welles<IMG SRC=images/dave.gif WIDTH=107 HEIGHT=148 BORDER=2 ALIGN=left HSPACE=6> 110ef31e1fSMike WellesModifying The TIFF Library 120ef31e1fSMike Welles</H1> 130ef31e1fSMike Welles 140ef31e1fSMike Welles 150ef31e1fSMike Welles<P> 160ef31e1fSMike WellesThis chapter provides information about the internal structure of 170ef31e1fSMike Wellesthe library, how to control the configuration when building it, and 180ef31e1fSMike Welleshow to add new support to the library. 190ef31e1fSMike WellesThe following sections are found in this chapter: 200ef31e1fSMike Welles 210ef31e1fSMike Welles<UL> 220ef31e1fSMike Welles<LI><A HREF=#Config>Library Configuration</A> 230ef31e1fSMike Welles<LI><A HREF=#Portability>General Portability Comments</A> 240ef31e1fSMike Welles<LI><A HREF="#Types">Types and Portability</A> 250ef31e1fSMike Welles<LI><A HREF=#AddingTags>Adding New Tags</A> 260ef31e1fSMike Welles<LI><A HREF=#AddingCODECS>Adding New Builtin Codecs</A> 270ef31e1fSMike Welles<LI><A HREF=#AddingCODECTags>Adding New Codec-private Tags</A> 280ef31e1fSMike Welles<LI><A HREF=#Other>Other Comments</A> 290ef31e1fSMike Welles</UL> 300ef31e1fSMike Welles 310ef31e1fSMike Welles 320ef31e1fSMike Welles<A NAME="Config"><P><HR WIDTH=65% ALIGN=right><H3>Library Configuration</H3></A> 330ef31e1fSMike Welles 340ef31e1fSMike WellesInformation on compiling the library is given 350ef31e1fSMike Welles<A HREF=build.html>elsewhere in this documentation</A>. 360ef31e1fSMike WellesThis section describes the low-level mechanisms used to control 370ef31e1fSMike Wellesthe optional parts of the library that are configured at build 380ef31e1fSMike Wellestime. Control is based on 390ef31e1fSMike Wellesa collection of C defines that are specified either on the compiler 400ef31e1fSMike Wellescommand line or in a configuration file such as <TT>port.h</TT> 410ef31e1fSMike Welles(as generated by the <TT>configure</TT> script for UNIX systems) 420ef31e1fSMike Wellesor <B>tiffconf.h</B>. 430ef31e1fSMike Welles 440ef31e1fSMike Welles<P> 450ef31e1fSMike WellesConfiguration defines are split into three areas: 460ef31e1fSMike Welles<UL> 470ef31e1fSMike Welles<LI>those that control which compression schemes are 480ef31e1fSMike Welles configured as part of the builtin codecs, 490ef31e1fSMike Welles<LI>those that control support for groups of tags that 500ef31e1fSMike Welles are considered optional, and 510ef31e1fSMike Welles<LI>those that control operating system or machine-specific support. 520ef31e1fSMike Welles</UL> 530ef31e1fSMike Welles 540ef31e1fSMike Welles<P> 550ef31e1fSMike WellesIf the define <TT>COMPRESSION_SUPPORT</TT> is <STRONG>not defined</STRONG> 560ef31e1fSMike Wellesthen a default set of compression schemes is automatically 570ef31e1fSMike Wellesconfigured: 580ef31e1fSMike Welles<UL> 590ef31e1fSMike Welles<LI>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, and 32771), 600ef31e1fSMike Welles<LI>the Macintosh PackBits algorithm (compression 32773), 610ef31e1fSMike Welles<LI>a 4-bit run-length encoding scheme from ThunderScan (compression 32809), 620ef31e1fSMike Welles<LI>a 2-bit encoding scheme used by NeXT (compression 32766), and 630ef31e1fSMike Welles<LI>two experimental schemes intended for images with high dynamic range 640ef31e1fSMike Welles(compression 34676 and 34677). 650ef31e1fSMike Welles</UL> 660ef31e1fSMike Welles 6786f76420SMike Welles<P> 6886f76420SMike Welles 6986f76420SMike WellesTo override the default compression behaviour define 7086f76420SMike Welles<TT>COMPRESSION_SUPPORT</TT> and then one or more additional defines 7186f76420SMike Wellesto enable configuration of the appropriate codecs (see the table 7286f76420SMike Wellesbelow); e.g. 730ef31e1fSMike Welles 740ef31e1fSMike Welles<UL><PRE> 750ef31e1fSMike Welles#define COMPRESSION_SUPPORT 760ef31e1fSMike Welles#define CCITT_SUPPORT 770ef31e1fSMike Welles#define PACKBITS_SUPPORT 780ef31e1fSMike Welles</PRE></UL> 790ef31e1fSMike Welles 800ef31e1fSMike WellesSeveral other compression schemes are configured separately from 810ef31e1fSMike Wellesthe default set because they depend on ancillary software 820ef31e1fSMike Wellespackages that are not distributed with <TT>libtiff</TT>. 830ef31e1fSMike Welles 840ef31e1fSMike Welles<P> 850ef31e1fSMike WellesSupport for JPEG compression is controlled by <TT>JPEG_SUPPORT</TT>. 860ef31e1fSMike WellesThe JPEG codec that comes with <TT>libtiff</TT> is designed for 870ef31e1fSMike Wellesuse with release 5 or later of the Independent JPEG Group's freely 880ef31e1fSMike Wellesavailable software distribution. 890ef31e1fSMike WellesThis software can be retrieved from the directory 900ef31e1fSMike Welles<A HREF=ftp://ftp.uu.net/graphics/jpeg>ftp.uu.net:/graphics/jpeg/</A>. 910ef31e1fSMike Welles 920ef31e1fSMike Welles 930ef31e1fSMike Welles<P> 940ef31e1fSMike Welles<IMG SRC="images/info.gif" ALT="NOTE: " ALIGN=left HSPACE=8> 950ef31e1fSMike Welles<EM>Enabling JPEG support automatically enables support for 960ef31e1fSMike Wellesthe TIFF 6.0 colorimetry and YCbCr-related tags.</EM> 970ef31e1fSMike Welles 980ef31e1fSMike Welles<P> 990ef31e1fSMike WellesExperimental support for the deflate algorithm is controlled by 1000ef31e1fSMike Welles<TT>DEFLATE_SUPPORT</TT>. 1010ef31e1fSMike WellesThe deflate codec that comes with <TT>libtiff</TT> is designed 1020ef31e1fSMike Wellesfor use with version 0.99 or later of the freely available 1030ef31e1fSMike Welles<TT>libz</TT> library written by Jean-loup Gailly and Mark Adler. 1040ef31e1fSMike WellesThe data format used by this library is described 1050ef31e1fSMike Wellesin the files 1060ef31e1fSMike Welles<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/zlib-3.1.doc>zlib-3.1.doc</A>, 1070ef31e1fSMike Wellesand 1080ef31e1fSMike Welles<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/deflate-1.1.doc>deflate-1.1.doc</A>, 1090ef31e1fSMike Wellesavailable in the directory 1100ef31e1fSMike Welles<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc>ftp.uu.net:/pub/archiving/zip/doc</A>.</EM> 1110ef31e1fSMike WellesThe library can be retried from the directory 1120ef31e1fSMike Welles<A HREF=ftp://ftp.uu.net/pub/archiving/zip/zlib/>ftp.uu.net:/pub/archiving/zip/zlib/</A> 1130ef31e1fSMike Welles(or try <A HREF=ftp://quest.jpl.nasa.gov/beta/zlib/>quest.jpl.nasa.gov:/beta/zlib/</A>). 1140ef31e1fSMike Welles 1150ef31e1fSMike Welles<P> 1160ef31e1fSMike Welles<IMG SRC="images/warning.gif" ALT="NOTE: " ALIGN=left HSPACE=8 VSPACE=6> 1170ef31e1fSMike Welles<EM>The deflate algorithm is experimental. Do not expect 1180ef31e1fSMike Wellesto exchange files using this compression scheme; 1190ef31e1fSMike Wellesit is included only because the similar, and more common, 1200ef31e1fSMike WellesLZW algorithm is claimed to be governed by licensing restrictions.</EM> 1210ef31e1fSMike Welles 1220ef31e1fSMike Welles 1230ef31e1fSMike Welles<P> 1240ef31e1fSMike WellesBy default <B>tiffconf.h</B> defines 1250ef31e1fSMike Welles<TT>COLORIMETRY_SUPPORT</TT>, 1260ef31e1fSMike Welles<TT>YCBCR_SUPPORT</TT>, 1270ef31e1fSMike Wellesand 1280ef31e1fSMike Welles<TT>CMYK_SUPPORT</TT>. 1290ef31e1fSMike Welles 1300ef31e1fSMike Welles<P> 1310ef31e1fSMike Welles<TABLE BORDER CELLPADDING=3> 1320ef31e1fSMike Welles 1330ef31e1fSMike Welles<TR><TH ALIGN=left>Define</TH><TH ALIGN=left>Description</TH></TR> 1340ef31e1fSMike Welles 1350ef31e1fSMike Welles<TR> 1360ef31e1fSMike Welles<TD VALIGN=top><TT>CCITT_SUPPORT</TT></TD> 1370ef31e1fSMike Welles<TD>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, 1380ef31e1fSMike Welles and 32771)</TD> 1390ef31e1fSMike Welles</TR> 1400ef31e1fSMike Welles 1410ef31e1fSMike Welles<TR> 1420ef31e1fSMike Welles<TD VALIGN=top><TT>PACKBITS_SUPPORT</TT></TD> 1430ef31e1fSMike Welles<TD>Macintosh PackBits algorithm (compression 32773)</TD> 1440ef31e1fSMike Welles</TR> 1450ef31e1fSMike Welles 1460ef31e1fSMike Welles<TR> 1470ef31e1fSMike Welles<TD VALIGN=top><TT>LZW_SUPPORT</TT></TD> 1480ef31e1fSMike Welles<TD>Lempel-Ziv & Welch (LZW) algorithm (compression 5)</TD> 1490ef31e1fSMike Welles</TR> 1500ef31e1fSMike Welles 1510ef31e1fSMike Welles<TR> 1520ef31e1fSMike Welles<TD VALIGN=top><TT>THUNDER_SUPPORT</TT></TD> 1530ef31e1fSMike Welles<TD>4-bit 1540ef31e1fSMike Wellesrun-length encoding scheme from ThunderScan (compression 32809)</TD> 1550ef31e1fSMike Welles</TR> 1560ef31e1fSMike Welles 1570ef31e1fSMike Welles<TR> 1580ef31e1fSMike Welles<TD VALIGN=top><TT>NEXT_SUPPORT</TT></TD> 1590ef31e1fSMike Welles<TD>2-bit encoding scheme used by NeXT (compression 32766)</TD> 1600ef31e1fSMike Welles</TR> 1610ef31e1fSMike Welles 1620ef31e1fSMike Welles<TR> 1630ef31e1fSMike Welles<TD VALIGN=top><TT>OJPEG_SUPPORT</TT></TD> 1640ef31e1fSMike Welles<TD>obsolete JPEG scheme defined in the 6.0 spec (compression 6)</TD> 1650ef31e1fSMike Welles</TR> 1660ef31e1fSMike Welles 1670ef31e1fSMike Welles<TR> 1680ef31e1fSMike Welles<TD VALIGN=top><TT>JPEG_SUPPORT</TT></TD> 1690ef31e1fSMike Welles<TD>current JPEG scheme defined in TTN2 (compression 7)</TD> 1700ef31e1fSMike Welles</TR> 1710ef31e1fSMike Welles 1720ef31e1fSMike Welles<TR> 1730ef31e1fSMike Welles<TD VALIGN=top><TT>ZIP_SUPPORT</TT></TD> 1740ef31e1fSMike Welles<TD>experimental Deflate scheme (compression 32946)</TD> 1750ef31e1fSMike Welles</TR> 1760ef31e1fSMike Welles 1770ef31e1fSMike Welles<TR> 1780ef31e1fSMike Welles<TD VALIGN=top><TT>PIXARLOG_SUPPORT</TT></TD> 1790ef31e1fSMike Welles<TD>Pixar's compression scheme for high-resolution color images (compression 32909)</TD> 1800ef31e1fSMike Welles</TR> 1810ef31e1fSMike Welles 1820ef31e1fSMike Welles<TR> 1830ef31e1fSMike Welles<TD VALIGN=top><TT>SGILOG_SUPPORT</TT></TD> 1840ef31e1fSMike Welles<TD>SGI's compression scheme for high-resolution color images (compression 34676 and 34677)</TD> 1850ef31e1fSMike Welles</TR> 1860ef31e1fSMike Welles 1870ef31e1fSMike Welles<TR> 1880ef31e1fSMike Welles<TD VALIGN=top><TT>COLORIMETRY_SUPPORT</TT></TD> 1890ef31e1fSMike Welles<TD>support for the TIFF 6.0 colorimetry tags</TD> 1900ef31e1fSMike Welles</TR> 1910ef31e1fSMike Welles 1920ef31e1fSMike Welles<TR> 1930ef31e1fSMike Welles<TD VALIGN=top><TT>YCBCR_SUPPORT</TT></TD> 1940ef31e1fSMike Welles<TD>support for the TIFF 6.0 YCbCr-related tags</TD> 1950ef31e1fSMike Welles</TR> 1960ef31e1fSMike Welles 1970ef31e1fSMike Welles<TR> 1980ef31e1fSMike Welles<TD VALIGN=top><TT>CMYK_SUPPORT</TT></TD> 1990ef31e1fSMike Welles<TD>support for the TIFF 6.0 CMYK-related tags</TD> 2000ef31e1fSMike Welles</TR> 2010ef31e1fSMike Welles 2020ef31e1fSMike Welles<TR> 2030ef31e1fSMike Welles<TD VALIGN=top><TT>ICC_SUPPORT</TT></TD> 2040ef31e1fSMike Welles<TD>support for the ICC Profile tag; see 2050ef31e1fSMike Welles<I>The ICC Profile Format Specification</I>, 2060ef31e1fSMike WellesAnnex B.3 "Embedding ICC Profiles in TIFF Files"; 2070ef31e1fSMike Wellesavailable at 2080ef31e1fSMike Welles<A HREF=http://www.color.org>http://www.color.org</A> 2090ef31e1fSMike Welles</TD> 2100ef31e1fSMike Welles</TR> 2110ef31e1fSMike Welles 2120ef31e1fSMike Welles</TABLE> 2130ef31e1fSMike Welles 2140ef31e1fSMike Welles 2150ef31e1fSMike Welles<A NAME="Portability"><P><HR WIDTH=65% ALIGN=right><H3>General Portability Comments</H3></A> 2160ef31e1fSMike Welles 2170ef31e1fSMike WellesThis software is developed on Silicon Graphics UNIX 2180ef31e1fSMike Wellessystems (big-endian, MIPS CPU, 32-bit ints, 2190ef31e1fSMike WellesIEEE floating point). 2200ef31e1fSMike WellesThe <TT>configure</TT> shell script generates the appropriate 2210ef31e1fSMike Wellesinclude files and make files for UNIX systems. 2220ef31e1fSMike WellesMakefiles exist for non-UNIX platforms that the 2230ef31e1fSMike Wellescode runs on -- this work has mostly been done by other people. 2240ef31e1fSMike Welles 2250ef31e1fSMike Welles<P> 2260ef31e1fSMike WellesIn general, the code is guaranteed to work only on SGI machines. 2270ef31e1fSMike WellesIn practice it is highly portable to any 32-bit or 64-bit system and much 2280ef31e1fSMike Welleswork has been done to insure portability to 16-bit systems. 2290ef31e1fSMike WellesIf you encounter portability problems please return fixes so 2300ef31e1fSMike Wellesthat future distributions can be improved. 2310ef31e1fSMike Welles 2320ef31e1fSMike Welles<P> 2330ef31e1fSMike WellesThe software is written to assume an ANSI C compilation environment. 2340ef31e1fSMike WellesIf your compiler does not support ANSI function prototypes, <TT>const</TT>, 2350ef31e1fSMike Wellesand <TT><stdarg.h></TT> then you will have to make modifications to the 2360ef31e1fSMike Wellessoftware. In the past I have tried to support compilers without <TT>const</TT> 2370ef31e1fSMike Wellesand systems without <TT><stdarg.h></TT>, but I am 2380ef31e1fSMike Welles<EM>no longer interested in these 2390ef31e1fSMike Wellesantiquated environments</EM>. With the general availability of 2400ef31e1fSMike Wellesthe freely available GCC compiler, I 2410ef31e1fSMike Wellessee no reason to incorporate modifications to the software for these 2420ef31e1fSMike Wellespurposes. 2430ef31e1fSMike Welles 2440ef31e1fSMike Welles<P> 2450ef31e1fSMike WellesAn effort has been made to isolate as many of the 2460ef31e1fSMike Wellesoperating system-dependencies 2470ef31e1fSMike Wellesas possible in two files: <B>tiffcomp.h</B> and 2480ef31e1fSMike Welles<B>libtiff/tif_<os>.c</B>. The latter file contains 2490ef31e1fSMike Wellesoperating system-specific routines to do I/O and I/O-related operations. 2500ef31e1fSMike WellesThe UNIX (<B>tif_unix.c</B>), 2510ef31e1fSMike WellesMacintosh (<B>tif_apple.c</B>), 2520ef31e1fSMike Wellesand VMS (<B>tif_vms.c</B>) 2530ef31e1fSMike Wellescode has had the most use; 2540ef31e1fSMike Wellesthe MS/DOS support (<B>tif_msdos.c</B>) assumes 2550ef31e1fSMike Wellessome level of UNIX system call emulation (i.e. 2560ef31e1fSMike Welles<TT>open</TT>, 2570ef31e1fSMike Welles<TT>read</TT>, 2580ef31e1fSMike Welles<TT>write</TT>, 2590ef31e1fSMike Welles<TT>fstat</TT>, 2600ef31e1fSMike Welles<TT>malloc</TT>, 2610ef31e1fSMike Welles<TT>free</TT>). 2620ef31e1fSMike Welles 2630ef31e1fSMike Welles<P> 2640ef31e1fSMike WellesNative CPU byte order is determined on the fly by 2650ef31e1fSMike Wellesthe library and does not need to be specified. 2660ef31e1fSMike WellesThe <TT>HOST_FILLORDER</TT> and <TT>HOST_BIGENDIAN</TT> 2670ef31e1fSMike Wellesdefinitions are not currently used, but may be employed by 2680ef31e1fSMike Wellescodecs for optimization purposes. 2690ef31e1fSMike Welles 2700ef31e1fSMike Welles<P> 2710ef31e1fSMike WellesThe following defines control general portability: 2720ef31e1fSMike Welles 2730ef31e1fSMike Welles<P> 2740ef31e1fSMike Welles<TABLE BORDER CELLPADDING=3 WIDTH=100%> 2750ef31e1fSMike Welles 2760ef31e1fSMike Welles<TR> 2770ef31e1fSMike Welles<TD VALIGN=top><TT>BSDTYPES</TT></TD> 2780ef31e1fSMike Welles<TD>Define this if your system does NOT define the 2790ef31e1fSMike Welles usual BSD typedefs: <TT>u_char</TT>, 2800ef31e1fSMike Welles <TT>u_short</TT>, <TT>u_int</TT>, <TT>u_long</TT>.</TD> 2810ef31e1fSMike Welles</TR> 2820ef31e1fSMike Welles 2830ef31e1fSMike Welles<TR> 2840ef31e1fSMike Welles<TD VALIGN=top><TT>HAVE_IEEEFP</TT></TD> 2850ef31e1fSMike Welles<TD>Define this as 0 or 1 according to the floating point 2860ef31e1fSMike Welles format suported by the machine. If your machine does 2870ef31e1fSMike Welles not support IEEE floating point then you will need to 2880ef31e1fSMike Welles add support to tif_machdep.c to convert between the 2890ef31e1fSMike Welles native format and IEEE format.</TD> 2900ef31e1fSMike Welles</TR> 2910ef31e1fSMike Welles 2920ef31e1fSMike Welles<TR> 2930ef31e1fSMike Welles<TD VALIGN=top><TT>HAVE_MMAP</TT></TD> 2940ef31e1fSMike Welles<TD>Define this if there is <I>mmap-style</I> support for 2950ef31e1fSMike Wellesmapping files into memory (used only to read data).</TD> 2960ef31e1fSMike Welles</TR> 2970ef31e1fSMike Welles 2980ef31e1fSMike Welles<TR> 2990ef31e1fSMike Welles<TD VALIGN=top><TT>HOST_FILLORDER</TT></TD> 3000ef31e1fSMike Welles<TD>Define the native CPU bit order: one of <TT>FILLORDER_MSB2LSB</TT> 3010ef31e1fSMike Welles or <TT>FILLORDER_LSB2MSB</TT></TD> 3020ef31e1fSMike Welles</TR> 3030ef31e1fSMike Welles 3040ef31e1fSMike Welles<TR> 3050ef31e1fSMike Welles<TD VALIGN=top><TT>HOST_BIGENDIAN</TT></TD> 3060ef31e1fSMike Welles<TD>Define the native CPU byte order: 1 if big-endian (Motorola) 3070ef31e1fSMike Welles or 0 if little-endian (Intel); this may be used 3080ef31e1fSMike Welles in codecs to optimize code</TD> 3090ef31e1fSMike Welles</TR> 3100ef31e1fSMike Welles</TABLE> 3110ef31e1fSMike Welles 3120ef31e1fSMike Welles<P> 3130ef31e1fSMike WellesOn UNIX systems <TT>HAVE_MMAP</TT> is defined through the running of 3140ef31e1fSMike Wellesthe <TT>configure</TT> script; otherwise support for memory-mapped 3150ef31e1fSMike Wellesfiles is disabled. 3160ef31e1fSMike WellesNote that <B>tiffcomp.h</B> defines <TT>HAVE_IEEEFP</TT> to be 3170ef31e1fSMike Welles1 (<TT>BSDTYPES</TT> is not defined). 3180ef31e1fSMike Welles 3190ef31e1fSMike Welles 3200ef31e1fSMike Welles<A NAME="Types"><P><HR WIDTH=65% ALIGN=right><H3>Types and Portability</H3></A> 3210ef31e1fSMike Welles 3220ef31e1fSMike WellesThe software makes extensive use of C typedefs to promote portability. 3230ef31e1fSMike WellesTwo sets of typedefs are used, one for communication with clients 3240ef31e1fSMike Wellesof the library and one for internal data structures and parsing of the 3250ef31e1fSMike WellesTIFF format. There are interactions between these two to be careful 3260ef31e1fSMike Wellesof, but for the most part you should be able to deal with portability 3270ef31e1fSMike Wellespurely by fiddling with the following machine-dependent typedefs: 3280ef31e1fSMike Welles 3290ef31e1fSMike Welles 3300ef31e1fSMike Welles<P> 3310ef31e1fSMike Welles<TABLE BORDER CELLPADDING=3 WIDTH=100%> 3320ef31e1fSMike Welles 3330ef31e1fSMike Welles<TR> 3340ef31e1fSMike Welles<TD>uint8</TD> 3350ef31e1fSMike Welles<TD>8-bit unsigned integer</TD> 3360ef31e1fSMike Welles<TD>tiff.h</TD> 3370ef31e1fSMike Welles</TR> 3380ef31e1fSMike Welles 3390ef31e1fSMike Welles<TR> 3400ef31e1fSMike Welles<TD>int8</TD> 3410ef31e1fSMike Welles<TD>8-bit signed integer</TD> 3420ef31e1fSMike Welles<TD>tiff.h</TD> 3430ef31e1fSMike Welles</TR> 3440ef31e1fSMike Welles 3450ef31e1fSMike Welles<TR> 3460ef31e1fSMike Welles<TD>uint16</TD> 3470ef31e1fSMike Welles<TD>16-bit unsigned integer</TD> 3480ef31e1fSMike Welles<TD>tiff.h</TD> 3490ef31e1fSMike Welles</TR> 3500ef31e1fSMike Welles 3510ef31e1fSMike Welles<TR> 3520ef31e1fSMike Welles<TD>int16</TD> 3530ef31e1fSMike Welles<TD>16-bit signed integer</TD> 3540ef31e1fSMike Welles<TD>tiff.h</TD> 3550ef31e1fSMike Welles</TR> 3560ef31e1fSMike Welles 3570ef31e1fSMike Welles<TR> 3580ef31e1fSMike Welles<TD>uint32</TD> 3590ef31e1fSMike Welles<TD>32-bit unsigned integer</TD> 3600ef31e1fSMike Welles<TD>tiff.h</TD> 3610ef31e1fSMike Welles</TR> 3620ef31e1fSMike Welles 3630ef31e1fSMike Welles<TR> 3640ef31e1fSMike Welles<TD>int32</TD> 3650ef31e1fSMike Welles<TD>32-bit signed integer</TD> 3660ef31e1fSMike Welles<TD>tiff.h</TD> 3670ef31e1fSMike Welles</TR> 3680ef31e1fSMike Welles 3690ef31e1fSMike Welles<TR> 3700ef31e1fSMike Welles<TD>dblparam_t</TD> 3710ef31e1fSMike Welles<TD>promoted type for floats</TD> 3720ef31e1fSMike Welles<TD>tiffcomp.h</TD> 3730ef31e1fSMike Welles</TR> 3740ef31e1fSMike Welles 3750ef31e1fSMike Welles</TABLE> 3760ef31e1fSMike Welles 3770ef31e1fSMike Welles<P> 3780ef31e1fSMike Welles(to clarify <TT>dblparam_t</TT>, it is the type that float parameters are 3790ef31e1fSMike Wellespromoted to when passed by value in a function call.) 3800ef31e1fSMike Welles 3810ef31e1fSMike Welles<P> 3820ef31e1fSMike WellesThe following typedefs are used throughout the library and interfaces 3830ef31e1fSMike Wellesto refer to certain objects whose size is dependent on the TIFF image 3840ef31e1fSMike Wellesstructure: 3850ef31e1fSMike Welles 3860ef31e1fSMike Welles 3870ef31e1fSMike Welles<P> 3880ef31e1fSMike Welles<TABLE BORDER CELLPADDING=3 WIDTH=100%> 3890ef31e1fSMike Welles 3900ef31e1fSMike Welles<TR> 3910ef31e1fSMike Welles<TD WIDTH=25%>typedef unsigned int ttag_t;</TD> <TD>directory tag</TD> 3920ef31e1fSMike Welles</TR> 3930ef31e1fSMike Welles 3940ef31e1fSMike Welles<TR> 3950ef31e1fSMike Welles<TD>typedef uint16 tdir_t;</TD> <TD>directory index</TD> 3960ef31e1fSMike Welles</TR> 3970ef31e1fSMike Welles 3980ef31e1fSMike Welles<TR> 3990ef31e1fSMike Welles<TD>typedef uint16 tsample_t;</TD> <TD>sample number</TD> 4000ef31e1fSMike Welles</TR> 4010ef31e1fSMike Welles 4020ef31e1fSMike Welles<TR> 4030ef31e1fSMike Welles<TD>typedef uint32 tstrip_t;</TD> <TD>strip number</TD> 4040ef31e1fSMike Welles</TR> 4050ef31e1fSMike Welles 4060ef31e1fSMike Welles<TR> 4070ef31e1fSMike Welles<TD>typedef uint32 ttile_t;</TD> <TD>tile number</TD> 4080ef31e1fSMike Welles</TR> 4090ef31e1fSMike Welles 4100ef31e1fSMike Welles<TR> 4110ef31e1fSMike Welles<TD>typedef int32 tsize_t;</TD> <TD>i/o size in bytes</TD> 4120ef31e1fSMike Welles</TR> 4130ef31e1fSMike Welles 4140ef31e1fSMike Welles<TR> 4150ef31e1fSMike Welles<TD>typedef void* tdata_t;</TD> <TD>image data ref</TD> 4160ef31e1fSMike Welles</TR> 4170ef31e1fSMike Welles 4180ef31e1fSMike Welles<TR> 4190ef31e1fSMike Welles<TD>typedef void* thandle_t;</TD> <TD>client data handle</TD> 4200ef31e1fSMike Welles</TR> 4210ef31e1fSMike Welles 4220ef31e1fSMike Welles<TR> 4230ef31e1fSMike Welles<TD>typedef int32 toff_t;</TD> <TD>file offset (should be off_t)</TD> 4240ef31e1fSMike Welles</TR> 4250ef31e1fSMike Welles 4260ef31e1fSMike Welles<TR> 4270ef31e1fSMike Welles<TD>typedef unsigned char* tidata_t;</TD> <TD>internal image data</TD> 4280ef31e1fSMike Welles</TR> 4290ef31e1fSMike Welles 4300ef31e1fSMike Welles</TABLE> 4310ef31e1fSMike Welles 4320ef31e1fSMike Welles<P> 4330ef31e1fSMike WellesNote that <TT>tstrip_t</TT>, <TT>ttile_t</TT>, and <TT>tsize_t</TT> 4340ef31e1fSMike Wellesare constrained to be 4350ef31e1fSMike Wellesno more than 32-bit quantities by 32-bit fields they are stored 4360ef31e1fSMike Wellesin in the TIFF image. Likewise <TT>tsample_t</TT> is limited by the 16-bit 4370ef31e1fSMike Wellesfield used to store the <TT>SamplesPerPixel</TT> tag. <TT>tdir_t</TT> 4380ef31e1fSMike Wellesconstrains 4390ef31e1fSMike Wellesthe maximum number of IFDs that may appear in an image and may 4400ef31e1fSMike Wellesbe an arbitrary size (without penalty). <TT>ttag_t</TT> must be either 4410ef31e1fSMike Welles<TT>int</TT>, <TT>unsigned int</TT>, pointer, or <TT>double</TT> 4420ef31e1fSMike Wellesbecause the library uses a varargs 4430ef31e1fSMike Wellesinterface and ANSI C restricts the type of the parameter before an 4440ef31e1fSMike Wellesellipsis to be a promoted type. <TT>toff_t</TT> is defined as 4450ef31e1fSMike Welles<TT>int32</TT> because 4460ef31e1fSMike WellesTIFF file offsets are (unsigned) 32-bit quantities. A signed 4470ef31e1fSMike Wellesvalue is used because some interfaces return -1 on error (sigh). 4480ef31e1fSMike WellesFinally, note that <TT>tidata_t</TT> is used internally to the library to 4490ef31e1fSMike Wellesmanipulate internal data. User-specified data references are 4500ef31e1fSMike Wellespassed as opaque handles and only cast at the lowest layers where 4510ef31e1fSMike Wellestheir type is presumed. 4520ef31e1fSMike Welles 4530ef31e1fSMike Welles 4540ef31e1fSMike Welles<P><HR WIDTH=65% ALIGN=right><H3>General Comments</H3></A> 4550ef31e1fSMike Welles 4560ef31e1fSMike WellesThe library is designed to hide as much of the details of TIFF from 4570ef31e1fSMike Wellesapplications as 4580ef31e1fSMike Wellespossible. In particular, TIFF directories are read in their entirety 4590ef31e1fSMike Wellesinto an internal format. Only the tags known by the library are 4600ef31e1fSMike Wellesavailable to a user and certain tag data may be maintained that a user 4610ef31e1fSMike Wellesdoes not care about (e.g. transfer function tables). 4620ef31e1fSMike Welles 4630ef31e1fSMike Welles<A NAME=AddingTags><P><HR WIDTH=65% ALIGN=right><H3>Adding New Tags</H3></A> 4640ef31e1fSMike Welles 4650ef31e1fSMike WellesTo add support for a new directory tag you have three options. If your 4660ef31e1fSMike Wellestag is specific to a compression algorithm, see below. If you have a lot 4670ef31e1fSMike Wellesof tags you may want to try using Niles Ritter's runtime tag-extension 4680ef31e1fSMike Wellesscheme in the "contrib/tags" directory, which makes the changes 4690ef31e1fSMike Wellesorthogonal to the main libtiff code. Otherwise use 4700ef31e1fSMike Wellesthe following guidelines to add support to the ``core library''. 4710ef31e1fSMike Welles 4720ef31e1fSMike Welles<OL> 4730ef31e1fSMike Welles<LI>Define the tag in <B>tiff.h</B>. 4740ef31e1fSMike Welles<LI>Add a field to the directory structure in <B>tif_dir.h</B> 4750ef31e1fSMike Welles and define a <TT>FIELD_*</TT> bit (also update the definition of 4760ef31e1fSMike Welles <TT>FIELD_CODEC</TT> to reflect your addition). 4770ef31e1fSMike Welles<LI>Add an entry in the <TT>TIFFFieldInfo</TT> array defined at the top of 4780ef31e1fSMike Welles <B>tif_dirinfo.c</B>. 4790ef31e1fSMike Welles Note that you must keep this array sorted by tag 4800ef31e1fSMike Welles number and that the widest variant entry for a tag should come 4810ef31e1fSMike Welles first (e.g. <TT>LONG</TT> before <TT>SHORT</TT>). 4820ef31e1fSMike Welles<LI>Add entries in <TT>_TIFFVSetField()</TT> and <TT>_TIFFVGetField()</TT> 4830ef31e1fSMike Welles for the new tag. 4840ef31e1fSMike Welles<LI>(<I>optional</I>) If the value associated with the tag is not a scalar value 4850ef31e1fSMike Welles (e.g. the array for <TT>TransferFunction</TT>) and requires 4860ef31e1fSMike Welles special processing, 4870ef31e1fSMike Welles then add the appropriate code to <TT>TIFFReadDirectory()</TT> and 4880ef31e1fSMike Welles <TT>TIFFWriteDirectory()</TT>. You're best off finding a similar tag and 4890ef31e1fSMike Welles cribbing code. 4900ef31e1fSMike Welles<LI>Add support to <TT>TIFFPrintDirectory()</TT> in <B>tif_print.c</B> 4910ef31e1fSMike Welles to print the tag's value. 4920ef31e1fSMike Welles</OL> 4930ef31e1fSMike Welles 4940ef31e1fSMike Welles<P> 4950ef31e1fSMike WellesIf you want to maintain portability, beware of making assumptions 4960ef31e1fSMike Wellesabout data types. Use the typedefs (<TT>uint16</TT>, etc. when dealing with 4970ef31e1fSMike Wellesdata on disk and <TT>t*_t</TT> when stuff is in memory) and be careful about 4980ef31e1fSMike Wellespassing items through printf or similar vararg interfaces. 4990ef31e1fSMike Welles 5000ef31e1fSMike Welles<A NAME=AddingCODECS><P><HR WIDTH=65% ALIGN=right><H3>Adding New Builtin Codecs</H3></A> 5010ef31e1fSMike Welles 5020ef31e1fSMike WellesTo add builtin support for a new compression algorithm, you can either 5030ef31e1fSMike Wellesuse the "tag-extension" trick to override the handling of the 5040ef31e1fSMike WellesTIFF Compression tag (see <A HREF=#AddingTags>Adding New Tags</A>, above), 5050ef31e1fSMike Wellesor do the following to add support directly to the core library: 5060ef31e1fSMike Welles 5070ef31e1fSMike Welles<OL> 5080ef31e1fSMike Welles<LI>Define the tag value in <B>tiff.h</B>. 5090ef31e1fSMike Welles<LI>Edit the file <B>tif_codec.c</B> to add an entry to the 5100ef31e1fSMike Welles _TIFFBuiltinCODECS array (see how other algorithms are handled). 5110ef31e1fSMike Welles<LI>Add the appropriate function prototype declaration to 5120ef31e1fSMike Welles <B>tiffiop.h</B> (close to the bottom). 5130ef31e1fSMike Welles<LI>Create a file with the compression scheme code, by convention files 5140ef31e1fSMike Welles are named <B>tif_*.c</B> (except perhaps on some systems where the 5150ef31e1fSMike Welles tif_ prefix pushes some filenames over 14 chars. 5160ef31e1fSMike Welles<LI>Edit <B>Makefile.in</B> (and any other Makefiles) 5170ef31e1fSMike Welles to include the new source file. 5180ef31e1fSMike Welles</OL> 5190ef31e1fSMike Welles 5200ef31e1fSMike Welles<P> 5210ef31e1fSMike WellesA codec, say <TT>foo</TT>, can have many different entry points: 5220ef31e1fSMike Welles 5230ef31e1fSMike Welles<PRE> 5240ef31e1fSMike WellesTIFFInitfoo(tif, scheme)/* initialize scheme and setup entry points in tif */ 5250ef31e1fSMike WellesfooSetupDecode(tif) /* called once per IFD after tags has been frozen */ 5260ef31e1fSMike WellesfooPreDecode(tif, sample)/* called once per strip/tile, after data is read, 5270ef31e1fSMike Welles but before the first row is decoded */ 5280ef31e1fSMike WellesfooDecode*(tif, bp, cc, sample)/* decode cc bytes of data into the buffer */ 5290ef31e1fSMike Welles fooDecodeRow(...) /* called to decode a single scanline */ 5300ef31e1fSMike Welles fooDecodeStrip(...) /* called to decode an entire strip */ 5310ef31e1fSMike Welles fooDecodeTile(...) /* called to decode an entire tile */ 5320ef31e1fSMike WellesfooSetupEncode(tif) /* called once per IFD after tags has been frozen */ 5330ef31e1fSMike WellesfooPreEncode(tif, sample)/* called once per strip/tile, before the first row in 5340ef31e1fSMike Welles a strip/tile is encoded */ 5350ef31e1fSMike WellesfooEncode*(tif, bp, cc, sample)/* encode cc bytes of user data (bp) */ 5360ef31e1fSMike Welles fooEncodeRow(...) /* called to decode a single scanline */ 5370ef31e1fSMike Welles fooEncodeStrip(...) /* called to decode an entire strip */ 5380ef31e1fSMike Welles fooEncodeTile(...) /* called to decode an entire tile */ 5390ef31e1fSMike WellesfooPostEncode(tif) /* called once per strip/tile, just before data is written */ 5400ef31e1fSMike WellesfooSeek(tif, row) /* seek forwards row scanlines from the beginning 5410ef31e1fSMike Welles of a strip (row will always be >0 and <rows/strip */ 5420ef31e1fSMike WellesfooCleanup(tif) /* called when compression scheme is replaced by user */ 5430ef31e1fSMike Welles</PRE> 5440ef31e1fSMike Welles 5450ef31e1fSMike Welles<P> 5460ef31e1fSMike WellesNote that the encoding and decoding variants are only needed when 5470ef31e1fSMike Wellesa compression algorithm is dependent on the structure of the data. 5480ef31e1fSMike WellesFor example, Group 3 2D encoding and decoding maintains a reference 5490ef31e1fSMike Wellesscanline. The sample parameter identifies which sample is to be 5500ef31e1fSMike Wellesencoded or decoded if the image is organized with <TT>PlanarConfig</TT>=2 5510ef31e1fSMike Welles(separate planes). This is important for algorithms such as JPEG. 5520ef31e1fSMike WellesIf <TT>PlanarConfig</TT>=1 (interleaved), then sample will always be 0. 5530ef31e1fSMike Welles 5540ef31e1fSMike Welles 5550ef31e1fSMike Welles<A NAME=AddingCODECTags><P><HR WIDTH=65% ALIGN=right><H3>Adding New Codec-private Tags</H3></A> 5560ef31e1fSMike Welles 5570ef31e1fSMike WellesTo add tags that are meaningful <EM>only when a particular compression 5580ef31e1fSMike Wellesalgorithm is used</EM> follow these steps: 5590ef31e1fSMike Welles 5600ef31e1fSMike Welles<OL> 5610ef31e1fSMike Welles<LI>Define the tag in <B>tiff.h</B>. 5620ef31e1fSMike Welles<LI>Allocate storage for the tag values in the private state block of 5630ef31e1fSMike Welles the codec. 5640ef31e1fSMike Welles<LI>Insure the state block is created when the codec is initialized. 5650ef31e1fSMike Welles<LI>At <TT>TIFFInitfoo</TT> time override the method pointers in the 5660ef31e1fSMike Welles TIFF structure 5670ef31e1fSMike Welles for getting, setting and printing tag values. For example, 5680ef31e1fSMike Welles<PRE> 5690ef31e1fSMike Welles sp->vgetparent = tif->tif_vgetfield; 5700ef31e1fSMike Welles tif->tif_vgetfield = fooVGetField; /* hook for codec tags */ 5710ef31e1fSMike Welles sp->vsetparent = tif->tif_vsetfield; 5720ef31e1fSMike Welles tif->tif_vsetfield = fooVSetField; /* hook for codec tags */ 5730ef31e1fSMike Welles tif->tif_printdir = fooPrintDir; /* hook for codec tags */ 5740ef31e1fSMike Welles</PRE> 5750ef31e1fSMike Welles (Actually you may decide not to override the 5760ef31e1fSMike Welles <TT>tif_printdir</TT> method, but rather just specify it). 5770ef31e1fSMike Welles<LI>Create a private <TT>TIFFFieldInfo</TT> array for your tags and 5780ef31e1fSMike Welles merge them into the core tags at initialization time using 5790ef31e1fSMike Welles <TT>_TIFFMergeFieldInfo</TT>; e.g. 5800ef31e1fSMike Welles<PRE> 5810ef31e1fSMike Welles _TIFFMergeFieldInfo(tif, fooFieldInfo, N(fooFieldInfo)); 5820ef31e1fSMike Welles</PRE> 5830ef31e1fSMike Welles (where <TT>N</TT> is a macro used liberaly throughout the distributed code). 5840ef31e1fSMike Welles<LI>Fill in the get and set routines. Be sure to call the parent method 5850ef31e1fSMike Welles for tags that you are not handled directly. Also be sure to set the 5860ef31e1fSMike Welles <TT>FIELD_*</TT> bits for tags that are to be written to the file. Note that 5870ef31e1fSMike Welles you can create ``pseudo-tags'' by defining tags that are processed 5880ef31e1fSMike Welles exclusively in the get/set routines and never written to file (see 5890ef31e1fSMike Welles the handling of <TT>TIFFTAG_FAXMODE</TT> in <B>tif_fax3.c</B> 5900ef31e1fSMike Welles for an example of this). 5910ef31e1fSMike Welles<LI>Fill in the print routine, if appropriate. 5920ef31e1fSMike Welles</OL> 5930ef31e1fSMike Welles 5940ef31e1fSMike WellesNote that space has been allocated in the <TT>FIELD_*</TT> bit space for 5950ef31e1fSMike Wellescodec-private tags. Define your bits as <TT>FIELD_CODEC+<offset></TT> to 5960ef31e1fSMike Welleskeep them away from the core tags. If you need more tags than there 5970ef31e1fSMike Wellesis room for, just increase <TT>FIELD_SETLONGS</TT> at the top of 5980ef31e1fSMike Welles<B>tiffiop.h</B>. 5990ef31e1fSMike Welles 6000ef31e1fSMike Welles 6010ef31e1fSMike Welles<A NAME=Other><P><HR WIDTH=65% ALIGN=right><H3>Other Comments</H3></A> 6020ef31e1fSMike Welles 6030ef31e1fSMike WellesThe library handles most I/O buffering. There are two data buffers 6040ef31e1fSMike Welleswhen decoding data: a raw data buffer that holds all the data in a 6050ef31e1fSMike Wellesstrip, and a user-supplied scanline buffer that compression schemes 6060ef31e1fSMike Wellesplace decoded data into. When encoding data the data in the 6070ef31e1fSMike Wellesuser-supplied scanline buffer is encoded into the raw data buffer (from 6080ef31e1fSMike Welleswhere it is written). Decoding routines should never have to explicitly 6090ef31e1fSMike Wellesread data -- a full strip/tile's worth of raw data is read and scanlines 6100ef31e1fSMike Wellesnever cross strip boundaries. Encoding routines must be cognizant of 6110ef31e1fSMike Wellesthe raw data buffer size and call <TT>TIFFFlushData1()</TT> when necessary. 6120ef31e1fSMike WellesNote that any pending data is automatically flushed when a new strip/tile is 6130ef31e1fSMike Wellesstarted, so there's no need do that in the tif_postencode routine (if 6140ef31e1fSMike Wellesone exists). Bit order is automatically handled by the library when 6150ef31e1fSMike Wellesa raw strip or tile is filled. If the decoded samples are interpreted 6160ef31e1fSMike Wellesby the decoding routine before they are passed back to the user, then 6170ef31e1fSMike Wellesthe decoding logic must handle byte-swapping by overriding the 6180ef31e1fSMike Welles<TT>tif_postdecode</TT> 6190ef31e1fSMike Wellesroutine (set it to <TT>TIFFNoPostDecode</TT>) and doing the required work 6200ef31e1fSMike Wellesinternally. For an example of doing this look at the horizontal 621*f5b59ca7SFrank Warmerdamdifferencing code in the routines in <B>tif_predict.c</B>. 6220ef31e1fSMike Welles 6230ef31e1fSMike Welles<P> 6240ef31e1fSMike WellesThe variables <TT>tif_rawcc</TT>, <TT>tif_rawdata</TT>, and 6250ef31e1fSMike Welles<TT>tif_rawcp</TT> in a <TT>TIFF</TT> structure 6260ef31e1fSMike Wellesare associated with the raw data buffer. <TT>tif_rawcc</TT> must be non-zero 6270ef31e1fSMike Wellesfor the library to automatically flush data. The variable 6280ef31e1fSMike Welles<TT>tif_scanlinesize</TT> is the size a user's scanline buffer should be. The 6290ef31e1fSMike Wellesvariable <TT>tif_tilesize</TT> is the size of a tile for tiled images. This 6300ef31e1fSMike Wellesshould not normally be used by compression routines, except where it 6310ef31e1fSMike Wellesrelates to the compression algorithm. That is, the <TT>cc</TT> parameter to the 6320ef31e1fSMike Welles<TT>tif_decode*</TT> and <TT>tif_encode*</TT> 6330ef31e1fSMike Wellesroutines should be used in terminating 6340ef31e1fSMike Wellesdecompression/compression. This ensures these routines can be used, 6350ef31e1fSMike Wellesfor example, to decode/encode entire strips of data. 6360ef31e1fSMike Welles 6370ef31e1fSMike Welles<P> 6380ef31e1fSMike WellesIn general, if you have a new compression algorithm to add, work from 6390ef31e1fSMike Wellesthe code for an existing routine. In particular, 6400ef31e1fSMike Welles<B>tif_dumpmode.c</B> 6410ef31e1fSMike Welleshas the trivial code for the "nil" compression scheme, 6420ef31e1fSMike Welles<B>tif_packbits.c</B> is a 6430ef31e1fSMike Wellessimple byte-oriented scheme that has to watch out for buffer 6440ef31e1fSMike Wellesboundaries, and <B>tif_lzw.c</B> has the LZW scheme that has the most 6450ef31e1fSMike Wellescomplexity -- it tracks the buffer boundary at a bit level. 6460ef31e1fSMike WellesOf course, using a private compression scheme (or private tags) limits 6470ef31e1fSMike Wellesthe portability of your TIFF files. 6480ef31e1fSMike Welles 6490ef31e1fSMike Welles<P> 6500ef31e1fSMike Welles<HR> 6510ef31e1fSMike Welles 652*f5b59ca7SFrank WarmerdamLast updated: $Date: 2004-09-10 13:36:22 $ 6530ef31e1fSMike Welles 6540ef31e1fSMike Welles</BODY> 655a446e861SMike Welles 6560ef31e1fSMike Welles</HTML> 657
