Imported Upstream version 1.8.3

author: Jörg Frings-Fürst <debian@jff-webhosting.net> 2015-11-06 05:38:49 +0100
committer: Jörg Frings-Fürst <debian@jff-webhosting.net> 2015-11-06 05:38:49 +0100
commit: 9491825ddff7a294d1f49061bae7044e426aeb2e (patch)
tree: 06e651099f87140ec534ae47fb8ce1ac6ec7976d /tiff/html/internals.html
parent: fa756339d4204bff7f2820067f58214d32780d17 (diff)
1 files changed, 572 insertions, 0 deletions
diff --git a/tiff/html/internals.html b/tiff/html/internals.html
new file mode 100755
index 0000000..83d53b0
--- /dev/null
+++ b/tiff/html/internals.html
@@ -0,0 +1,572 @@
+<HTML>
+<HEAD>
+<TITLE>
+Modifying The TIFF Library
+</TITLE>
+</HEAD>
+<BODY BGCOLOR=white> 
+<FONT FACE="Arial, Helvetica, Sans">
+<H1>
+<IMG SRC=images/dave.gif WIDTH=107 HEIGHT=148 BORDER=2 ALIGN=left HSPACE=6>
+Modifying The TIFF Library
+</H1>
+
+
+<P>
+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:
+
+<UL>
+<LI><A HREF=#Config>Library Configuration</A>
+<LI><A HREF=#Portability>General Portability Comments</A>
+<LI><A HREF="#Types">Types and Portability</A>
+<LI><A HREF="addingtags.html">Adding New Tags</A>
+<LI><A HREF=#AddingCODECS>Adding New Builtin Codecs</A>
+<LI><A HREF="addingtags.html#AddingCODECTags">Adding New Codec-private Tags</A>
+<LI><A HREF=#Other>Other Comments</A>
+</UL>
+
+
+<A NAME="Config"><P><HR WIDTH=65% ALIGN=right><H3>Library Configuration</H3></A>
+
+Information on compiling the library is given
+<A HREF=build.html>elsewhere in this documentation</A>.
+This section describes the low-level mechanisms used to control
+the optional parts of the library that are configured at build
+time.   Control is based on
+a collection of C defines that are specified either on the compiler
+command line or in a configuration file such as <TT>port.h</TT>
+(as generated by the <TT>configure</TT> script for UNIX systems)
+or <B>tiffconf.h</B>.
+
+<P>
+Configuration defines are split into three areas:
+<UL>
+<LI>those that control which compression schemes are
+    configured as part of the builtin codecs,
+<LI>those that control support for groups of tags that
+    are considered optional, and
+<LI>those that control operating system or machine-specific support.
+</UL>
+
+<P>
+If the define <TT>COMPRESSION_SUPPORT</TT> is <STRONG>not defined</STRONG>
+then a default set of compression schemes is automatically
+configured:
+<UL>
+<LI>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, and 32771),
+<LI>the Macintosh PackBits algorithm (compression 32773),
+<LI>a 4-bit run-length encoding scheme from ThunderScan (compression 32809),
+<LI>a 2-bit encoding scheme used by NeXT (compression 32766), and
+<LI>two experimental schemes intended for images with high dynamic range
+(compression 34676 and 34677).
+</UL>
+
+<P>
+
+To override the default compression behaviour define
+<TT>COMPRESSION_SUPPORT</TT> and then one or more additional defines
+to enable configuration of the appropriate codecs (see the table
+below); e.g.
+
+<UL><PRE>
+#define	COMPRESSION_SUPPORT
+#define	CCITT_SUPPORT
+#define	PACKBITS_SUPPORT
+</PRE></UL>
+
+Several other compression schemes are configured separately from
+the default set because they depend on ancillary software
+packages that are not distributed with <TT>libtiff</TT>.
+
+<P>
+Support for JPEG compression is controlled by <TT>JPEG_SUPPORT</TT>.
+The JPEG codec that comes with <TT>libtiff</TT> 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
+<A HREF=ftp://ftp.uu.net/graphics/jpeg>ftp.uu.net:/graphics/jpeg/</A>.
+
+
+<P>
+<IMG SRC="images/info.gif" ALT="NOTE: " ALIGN=left HSPACE=8>
+<EM>Enabling JPEG support automatically enables support for
+the TIFF 6.0 colorimetry and YCbCr-related tags.</EM>
+
+<P>
+Experimental support for the deflate algorithm is controlled by
+<TT>DEFLATE_SUPPORT</TT>.
+The deflate codec that comes with <TT>libtiff</TT> is designed
+for use with version 0.99 or later of the freely available
+<TT>libz</TT> library written by Jean-loup Gailly and Mark Adler.
+The data format used by this library is described
+in the files
+<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/zlib-3.1.doc>zlib-3.1.doc</A>,
+and
+<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc/deflate-1.1.doc>deflate-1.1.doc</A>,
+available in the directory
+<A HREF=ftp://ftp.uu.net/pub/archiving/zip/doc>ftp.uu.net:/pub/archiving/zip/doc</A>.</EM>
+The library can be retried from the directory
+<A HREF=ftp://ftp.uu.net/pub/archiving/zip/zlib/>ftp.uu.net:/pub/archiving/zip/zlib/</A>
+(or try <A HREF=ftp://quest.jpl.nasa.gov/beta/zlib/>quest.jpl.nasa.gov:/beta/zlib/</A>).
+
+<P>
+<IMG SRC="images/warning.gif" ALT="NOTE: " ALIGN=left HSPACE=8 VSPACE=6>
+<EM>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.</EM>
+
+
+<P>
+By default <B>tiffconf.h</B> defines
+<TT>COLORIMETRY_SUPPORT</TT>, 
+<TT>YCBCR_SUPPORT</TT>,
+and 
+<TT>CMYK_SUPPORT</TT>.
+
+<P>
+<TABLE BORDER CELLPADDING=3>
+
+<TR><TH ALIGN=left>Define</TH><TH ALIGN=left>Description</TH></TR>
+
+<TR>
+<TD VALIGN=top><TT>CCITT_SUPPORT</TT></TD>
+<TD>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4,
+    and 32771)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>PACKBITS_SUPPORT</TT></TD>
+<TD>Macintosh PackBits algorithm (compression 32773)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>LZW_SUPPORT</TT></TD>
+<TD>Lempel-Ziv & Welch (LZW) algorithm (compression 5)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>THUNDER_SUPPORT</TT></TD>
+<TD>4-bit
+run-length encoding scheme from ThunderScan (compression 32809)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>NEXT_SUPPORT</TT></TD>
+<TD>2-bit encoding scheme used by NeXT (compression 32766)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>OJPEG_SUPPORT</TT></TD>
+<TD>obsolete JPEG scheme defined in the 6.0 spec (compression 6)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>JPEG_SUPPORT</TT></TD>
+<TD>current JPEG scheme defined in TTN2 (compression 7)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>ZIP_SUPPORT</TT></TD>
+<TD>experimental Deflate scheme (compression 32946)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>PIXARLOG_SUPPORT</TT></TD>
+<TD>Pixar's compression scheme for high-resolution color images (compression 32909)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>SGILOG_SUPPORT</TT></TD>
+<TD>SGI's compression scheme for high-resolution color images (compression 34676 and 34677)</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>COLORIMETRY_SUPPORT</TT></TD>
+<TD>support for the TIFF 6.0 colorimetry tags</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>YCBCR_SUPPORT</TT></TD>
+<TD>support for the TIFF 6.0 YCbCr-related tags</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>CMYK_SUPPORT</TT></TD>
+<TD>support for the TIFF 6.0 CMYK-related tags</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>ICC_SUPPORT</TT></TD>
+<TD>support for the ICC Profile tag; see
+<I>The ICC Profile Format Specification</I>,
+Annex B.3 "Embedding ICC Profiles in TIFF Files";
+available at
+<A HREF=http://www.color.org>http://www.color.org</A>
+</TD>
+</TR>
+
+</TABLE>
+
+
+<A NAME="Portability"><P><HR WIDTH=65% ALIGN=right><H3>General Portability Comments</H3></A>
+
+This software is developed on Silicon Graphics UNIX
+systems (big-endian, MIPS CPU, 32-bit ints,
+IEEE floating point). 
+The <TT>configure</TT> shell script generates the appropriate
+include files and make files for UNIX systems.
+Makefiles exist for non-UNIX platforms that the
+code runs on -- this work has mostly been done by other people.
+
+<P>
+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.
+
+<P>
+The software is written to assume an ANSI C compilation environment.
+If your compiler does not support ANSI function prototypes, <TT>const</TT>,
+and <TT>&lt;stdarg.h&gt;</TT> then you will have to make modifications to the
+software.  In the past I have tried to support compilers without <TT>const</TT>
+and systems without <TT>&lt;stdarg.h&gt;</TT>, but I am
+<EM>no longer interested in these
+antiquated environments</EM>.  With the general availability of
+the freely available GCC compiler, I
+see no reason to incorporate modifications to the software for these
+purposes.
+
+<P>
+An effort has been made to isolate as many of the
+operating system-dependencies
+as possible in two files: <B>tiffcomp.h</B> and
+<B>libtiff/tif_&lt;os&gt;.c</B>.  The latter file contains
+operating system-specific routines to do I/O and I/O-related operations.
+The UNIX (<B>tif_unix.c</B>),
+Macintosh (<B>tif_apple.c</B>),
+and VMS (<B>tif_vms.c</B>)
+code has had the most use;
+the MS/DOS support (<B>tif_msdos.c</B>) assumes
+some level of UNIX system call emulation (i.e.
+<TT>open</TT>,
+<TT>read</TT>,
+<TT>write</TT>,
+<TT>fstat</TT>,
+<TT>malloc</TT>,
+<TT>free</TT>).
+
+<P>
+Native CPU byte order is determined on the fly by
+the library and does not need to be specified.
+The <TT>HOST_FILLORDER</TT> and <TT>HOST_BIGENDIAN</TT>
+definitions are not currently used, but may be employed by
+codecs for optimization purposes.
+
+<P>
+The following defines control general portability:
+
+<P>
+<TABLE BORDER CELLPADDING=3 WIDTH=100%>
+
+<TR>
+<TD VALIGN=top><TT>BSDTYPES</TT></TD>
+<TD>Define this if your system does NOT define the
+		usual BSD typedefs: <TT>u_char</TT>,
+		<TT>u_short</TT>, <TT>u_int</TT>, <TT>u_long</TT>.</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>HAVE_IEEEFP</TT></TD>
+<TD>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.</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>HAVE_MMAP</TT></TD>
+<TD>Define this if there is <I>mmap-style</I> support for
+mapping files into memory (used only to read data).</TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>HOST_FILLORDER</TT></TD>
+<TD>Define the native CPU bit order: one of <TT>FILLORDER_MSB2LSB</TT>
+ or <TT>FILLORDER_LSB2MSB</TT></TD>
+</TR>
+
+<TR>
+<TD VALIGN=top><TT>HOST_BIGENDIAN</TT></TD>
+<TD>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</TD>
+</TR>
+</TABLE>
+
+<P>
+On UNIX systems <TT>HAVE_MMAP</TT> is defined through the running of
+the <TT>configure</TT> script; otherwise support for memory-mapped
+files is disabled.
+Note that <B>tiffcomp.h</B> defines <TT>HAVE_IEEEFP</TT> to be
+1 (<TT>BSDTYPES</TT> is not defined).
+
+
+<A NAME="Types"><P><HR WIDTH=65% ALIGN=right><H3>Types and Portability</H3></A>
+
+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:
+
+
+<P>
+<TABLE BORDER CELLPADDING=3 WIDTH=100%>
+
+<TR>
+<TD>uint8</TD>
+<TD>8-bit unsigned integer</TD>
+<TD>tiff.h</TD>
+</TR>
+
+<TR>
+<TD>int8</TD>
+<TD>8-bit signed integer</TD>
+<TD>tiff.h</TD>
+</TR>
+
+<TR>
+<TD>uint16</TD>
+<TD>16-bit unsigned integer</TD>
+<TD>tiff.h</TD>
+</TR>
+
+<TR>
+<TD>int16</TD>
+<TD>16-bit signed integer</TD>
+<TD>tiff.h</TD>
+</TR>
+
+<TR>
+<TD>uint32</TD>
+<TD>32-bit unsigned integer</TD>
+<TD>tiff.h</TD>
+</TR>
+
+<TR>
+<TD>int32</TD>
+<TD>32-bit signed integer</TD>
+<TD>tiff.h</TD>
+</TR>
+
+<TR>
+<TD>dblparam_t</TD>
+<TD>promoted type for floats</TD>
+<TD>tiffcomp.h</TD>
+</TR>
+
+</TABLE>
+
+<P>
+(to clarify <TT>dblparam_t</TT>, it is the type that float parameters are
+promoted to when passed by value in a function call.)
+
+<P>
+The following typedefs are used throughout the library and interfaces
+to refer to certain objects whose size is dependent on the TIFF image
+structure:
+
+
+<P>
+<TABLE BORDER CELLPADDING=3 WIDTH=100%>
+
+<TR>
+<TD WIDTH=25%>typedef unsigned int ttag_t;</TD>	<TD>directory tag</TD>
+</TR>
+
+<TR>
+<TD>typedef uint16 tdir_t;</TD>		<TD>directory index</TD>
+</TR>
+
+<TR>
+<TD>typedef uint16 tsample_t;</TD>	<TD>sample number</TD>
+</TR>
+
+<TR>
+<TD>typedef uint32 tstrip_t;</TD>	<TD>strip number</TD>
+</TR>
+
+<TR>
+<TD>typedef uint32 ttile_t;</TD>		<TD>tile number</TD>
+</TR>
+
+<TR>
+<TD>typedef int32 tsize_t;</TD>		<TD>i/o size in bytes</TD>
+</TR>
+
+<TR>
+<TD>typedef void* tdata_t;</TD>		<TD>image data ref</TD>
+</TR>
+
+<TR>
+<TD>typedef void* thandle_t;</TD>	<TD>client data handle</TD>
+</TR>
+
+<TR>
+<TD>typedef int32 toff_t;</TD>		<TD>file offset (should be off_t)</TD>
+</TR>
+
+<TR>
+<TD>typedef unsigned char* tidata_t;</TD> <TD>internal image data</TD>
+</TR>
+
+</TABLE>
+
+<P>
+Note that <TT>tstrip_t</TT>, <TT>ttile_t</TT>, and <TT>tsize_t</TT>
+are constrained to be
+no more than 32-bit quantities by 32-bit fields they are stored
+in in the TIFF image.  Likewise <TT>tsample_t</TT> is limited by the 16-bit
+field used to store the <TT>SamplesPerPixel</TT> tag.  <TT>tdir_t</TT>
+constrains
+the maximum number of IFDs that may appear in an image and may
+be an arbitrary size (without penalty).  <TT>ttag_t</TT> must be either
+<TT>int</TT>, <TT>unsigned int</TT>, pointer, or <TT>double</TT>
+because the library uses a varargs
+interface and ANSI C restricts the type of the parameter before an
+ellipsis to be a promoted type.  <TT>toff_t</TT> is defined as
+<TT>int32</TT> 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 <TT>tidata_t</TT> 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.
+
+
+<P><HR WIDTH=65% ALIGN=right><H3>General Comments</H3></A>
+
+The library is designed to hide as much of the details of TIFF from
+applications as
+possible.  In particular, TIFF directories are read in their entirety
+into an internal format.  Only the tags known by the library are
+available to a user and certain tag data may be maintained that a user
+does not care about (e.g. transfer function tables).
+
+<A NAME=AddingCODECS><P><HR WIDTH=65% ALIGN=right><H3>Adding New Builtin Codecs</H3></A>
+
+To add builtin support for a new compression algorithm, you can either
+use the "tag-extension" trick to override the handling of the
+TIFF Compression tag (see <A HREF=addingtags.html>Adding New Tags</A>), 
+or do the following to add support directly to the core library:
+
+<OL>
+<LI>Define the tag value in <B>tiff.h</B>.
+<LI>Edit the file <B>tif_codec.c</B> to add an entry to the
+   _TIFFBuiltinCODECS array (see how other algorithms are handled).
+<LI>Add the appropriate function prototype declaration to
+   <B>tiffiop.h</B> (close to the bottom).
+<LI>Create a file with the compression scheme code, by convention files
+   are named <B>tif_*.c</B> (except perhaps on some systems where the
+   tif_ prefix pushes some filenames over 14 chars.
+<LI>Edit <B>Makefile.in</B> (and any other Makefiles)
+   to include the new source file.
+</OL>
+
+<P>
+A codec, say <TT>foo</TT>, can have many different entry points:
+
+<PRE>
+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 &gt;0 and &lt;rows/strip */
+fooCleanup(tif)		/* called when compression scheme is replaced by user */
+</PRE>
+
+<P>
+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 <TT>PlanarConfig</TT>=2
+(separate planes).  This is important for algorithms such as JPEG.
+If <TT>PlanarConfig</TT>=1 (interleaved), then sample will always be 0.
+
+<A NAME=Other><P><HR WIDTH=65% ALIGN=right><H3>Other Comments</H3></A>
+
+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 <TT>TIFFFlushData1()</TT> 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
+<TT>tif_postdecode</TT>
+routine (set it to <TT>TIFFNoPostDecode</TT>) and doing the required work
+internally.  For an example of doing this look at the horizontal
+differencing code in the routines in <B>tif_predict.c</B>.
+
+<P>
+The variables <TT>tif_rawcc</TT>, <TT>tif_rawdata</TT>, and
+<TT>tif_rawcp</TT> in a <TT>TIFF</TT> structure
+are associated with the raw data buffer.  <TT>tif_rawcc</TT> must be non-zero
+for the library to automatically flush data.  The variable
+<TT>tif_scanlinesize</TT> is the size a user's scanline buffer should be.  The
+variable <TT>tif_tilesize</TT> 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 <TT>cc</TT> parameter to the
+<TT>tif_decode*</TT> and <TT>tif_encode*</TT>
+routines should be used in terminating
+decompression/compression.  This ensures these routines can be used,
+for example, to decode/encode entire strips of data.
+
+<P>
+In general, if you have a new compression algorithm to add, work from
+the code for an existing routine.  In particular,
+<B>tif_dumpmode.c</B>
+has the trivial code for the "nil" compression scheme,
+<B>tif_packbits.c</B> is a
+simple byte-oriented scheme that has to watch out for buffer
+boundaries, and <B>tif_lzw.c</B> 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.
+
+<P>
+<HR>
+
+Last updated: $Date: 2004-09-10 14:47:31 $
+
+</BODY>
+
+</HTML>
author	Jörg Frings-Fürst <debian@jff-webhosting.net>	2015-11-06 05:38:49 +0100
committer	Jörg Frings-Fürst <debian@jff-webhosting.net>	2015-11-06 05:38:49 +0100
commit	9491825ddff7a294d1f49061bae7044e426aeb2e (patch)
tree	06e651099f87140ec534ae47fb8ce1ac6ec7976d /tiff/html/internals.html
parent	fa756339d4204bff7f2820067f58214d32780d17 (diff)