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