|
Server : Apache/2.4.62 System : FreeBSD fbsdweb2.web.rcn.net 14.1-RELEASE FreeBSD 14.1-RELEASE releng/14.1-n267679-10e31f0946d8 GENERIC amd64 User : www ( 80) PHP Version : 8.3.8 Disable Function : NONE Directory : /usr/local/share/doc/tiff-4.6.0/manual/ |
Upload File : |
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Modifying The TIFF Library — LibTIFF 4.6.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Defining New TIFF Tags" href="addingtags.html" />
<link rel="prev" title="_TIFFRewriteField" href="functions/_TIFFRewriteField.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="addingtags.html" title="Defining New TIFF Tags"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="functions/_TIFFRewriteField.html" title="_TIFFRewriteField"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">LibTIFF 4.6.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Modifying The TIFF Library</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="modifying-the-tiff-library">
<h1>Modifying The TIFF Library<a class="headerlink" href="#modifying-the-tiff-library" title="Permalink to this heading">¶</a></h1>
<a class="reference internal image-reference" href="_images/dave.gif"><img alt="dave" src="_images/dave.gif" style="width: 107px;" /></a>
<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:</p>
<section id="library-configuration">
<h2>Library Configuration<a class="headerlink" href="#library-configuration" title="Permalink to this heading">¶</a></h2>
<p>Information on compiling the library is given <a class="reference internal" href="build.html"><span class="doc">Building the TIFF Software Distribution</span></a>
elsewhere in this documentation.
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 <code class="file docutils literal notranslate"><span class="pre">port.h</span></code>
(as generated by the <strong class="program">configure</strong> script for UNIX systems)
or <code class="file docutils literal notranslate"><span class="pre">tiffconf.h</span></code>.</p>
<p>Configuration defines are split into three areas:</p>
<ul class="simple">
<li><p>those that control which compression schemes are
configured as part of the builtin codecs,</p></li>
<li><p>those that control support for groups of tags that
are considered optional, and</p></li>
<li><p>those that control operating system or machine-specific support.</p></li>
</ul>
<p>If the define <code class="xref c c-macro docutils literal notranslate"><span class="pre">COMPRESSION_SUPPORT</span></code> is <strong>not defined</strong>
then a default set of compression schemes is automatically
configured:</p>
<ul class="simple">
<li><p>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, and 32771),</p></li>
<li><p>the Macintosh PackBits algorithm (compression 32773),</p></li>
<li><p>a 4-bit run-length encoding scheme from ThunderScan (compression 32809),</p></li>
<li><p>a 2-bit encoding scheme used by NeXT (compression 32766), and</p></li>
<li><p>two experimental schemes intended for images with high dynamic range
(compression 34676 and 34677).</p></li>
</ul>
<p>To override the default compression behaviour define
<code class="xref c c-macro docutils literal notranslate"><span class="pre">COMPRESSION_SUPPORT</span></code> and then one or more additional defines
to enable configuration of the appropriate codecs (see the table
below); e.g.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#define COMPRESSION_SUPPORT</span>
<span class="cp">#define CCITT_SUPPORT</span>
<span class="cp">#define PACKBITS_SUPPORT</span>
</pre></div>
</div>
<p>Several other compression schemes are configured separately from
the default set because they depend on ancillary software
packages that are not distributed with LibTIFF.</p>
<p>Support for JPEG compression is controlled by <code class="xref c c-macro docutils literal notranslate"><span class="pre">JPEG_SUPPORT</span></code>.
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
<a class="reference external" href="ftp://ftp.uu.net/graphics/jpeg">ftp://ftp.uu.net/graphics/jpeg</a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Enabling JPEG support automatically enables support for
the TIFF 6.0 colorimetry and YCbCr-related tags.</p>
</div>
<p>Experimental support for the deflate algorithm is controlled by
<code class="xref c c-macro docutils literal notranslate"><span class="pre">DEFLATE_SUPPORT</span></code>.
The deflate codec that comes with LibTIFF is designed
for use with version 0.99 or later of the freely available
<code class="docutils literal notranslate"><span class="pre">libz</span></code> library written by Jean-loup Gailly and Mark Adler.
The data format used by this library is described
in the files
<a class="reference external" href="ftp://ftp.uu.net/pub/archiving/zip/doc/zlib-3.1.doc">ftp://ftp.uu.net/pub/archiving/zip/doc/zlib-3.1.doc</a>,
and
<a class="reference external" href="ftp://ftp.uu.net/pub/archiving/zip/doc/deflate-1.1.doc">ftp://ftp.uu.net/pub/archiving/zip/doc/deflate-1.1.doc</a>,
available in the directory
<a class="reference external" href="ftp://ftp.uu.net/pub/archiving/zip/doc">ftp://ftp.uu.net/pub/archiving/zip/doc</a>..
The library can be retried from the directory
<a class="reference external" href="ftp://ftp.uu.net/pub/archiving/zip/zlib">ftp://ftp.uu.net/pub/archiving/zip/zlib</a>
(or try <a class="reference external" href="ftp://quest.jpl.nasa.gov/beta/zlib/">ftp://quest.jpl.nasa.gov/beta/zlib/</a>).</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p><strong>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.</strong></p>
</div>
<p>By default <code class="file docutils literal notranslate"><span class="pre">tiffconf.h</span></code> defines
<code class="xref c c-macro docutils literal notranslate"><span class="pre">COLORIMETRY_SUPPORT</span></code>,
<code class="xref c c-macro docutils literal notranslate"><span class="pre">YCBCR_SUPPORT</span></code>,
and
<code class="xref c c-macro docutils literal notranslate"><span class="pre">CMYK_SUPPORT</span></code>.</p>
<table class="docutils align-default" id="id1">
<caption><span class="caption-text"><code class="file docutils literal notranslate"><span class="pre">tiffconf.h</span></code> defines</span><a class="headerlink" href="#id1" title="Permalink to this table">¶</a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 80.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Define</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">CCITT_SUPPORT</span></code></p></td>
<td><p>CCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, and 32771)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PACKBITS_SUPPORT</span></code></p></td>
<td><p>Macintosh PackBits algorithm (compression 32773)</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">LZW_SUPPORT</span></code></p></td>
<td><p>Lempel-Ziv & Welch (LZW) algorithm (compression 5)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">THUNDER_SUPPORT</span></code></p></td>
<td><p>4-bit run-length encoding scheme from ThunderScan (compression 32809)</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">NEXT_SUPPORT</span></code></p></td>
<td><p>2-bit encoding scheme used by NeXT (compression 32766)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">OJPEG_SUPPORT</span></code></p></td>
<td><p>obsolete JPEG scheme defined in the 6.0 spec (compression 6)</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">JPEG_SUPPORT</span></code></p></td>
<td><p>current JPEG scheme defined in TTN2 (compression 7)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">ZIP_SUPPORT</span></code></p></td>
<td><p>experimental Deflate scheme (compression 32946)</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">PIXARLOG_SUPPORT</span></code></p></td>
<td><p>Pixar’s compression scheme for high-resolution color images (compression 32909)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">SGILOG_SUPPORT</span></code></p></td>
<td><p>SGI’s compression scheme for high-resolution color images (compression 34676 and 34677)</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">COLORIMETRY_SUPPORT</span></code></p></td>
<td><p>support for the TIFF 6.0 colorimetry tags</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">YCBCR_SUPPORT</span></code></p></td>
<td><p>support for the TIFF 6.0 YCbCr-related tags</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">CMYK_SUPPORT</span></code></p></td>
<td><p>support for the TIFF 6.0 CMYK-related tags</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">ICC_SUPPORT</span></code></p></td>
<td><p>support for the ICC Profile tag; see
<em>The ICC Profile Format Specification</em>,
Annex B.3 “Embedding ICC Profiles in TIFF Files”;
available at
<a class="reference external" href="http://www.color.org/">http://www.color.org/</a></p></td>
</tr>
</tbody>
</table>
</section>
<section id="general-portability-comments">
<h2>General Portability Comments<a class="headerlink" href="#general-portability-comments" title="Permalink to this heading">¶</a></h2>
<p>This software is developed on Silicon Graphics UNIX
systems (big-endian, MIPS CPU, 32-bit ints,
IEEE floating point).
The <strong class="program">configure</strong> 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>
<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>
<p>The software is written to assume an ANSI C compilation environment.
If your compiler does not support ANSI function prototypes, <code class="docutils literal notranslate"><span class="pre">const</span></code>,
and <code class="file docutils literal notranslate"><span class="pre"><stdarg.h></span></code> then you will have to make modifications to the
software. In the past I have tried to support compilers without <code class="docutils literal notranslate"><span class="pre">const</span></code>
and systems without <code class="file docutils literal notranslate"><span class="pre"><stdarg.h></span></code>, but I am
<strong>no longer interested in these
antiquated environments</strong>. With the general availability of
the freely available GCC compiler, I
see no reason to incorporate modifications to the software for these
purposes.</p>
<p>An effort has been made to isolate as many of the
operating system-dependencies
as possible in two files: <code class="file docutils literal notranslate"><span class="pre">tiffcomp.h</span></code> and
<code class="file docutils literal notranslate"><span class="pre">libtiff/tif_<os>.c</span></code>. The latter file contains
operating system-specific routines to do I/O and I/O-related operations.
The UNIX (<code class="file docutils literal notranslate"><span class="pre">tif_unix.c</span></code>) code has had the most use.</p>
<p>Native CPU byte order is determined through the <code class="xref c c-macro docutils literal notranslate"><span class="pre">WORDS_BIGENDIAN</span></code>
definition, which must be set to the appropriate value in <code class="file docutils literal notranslate"><span class="pre">tif_config.h</span></code>
by the build system.</p>
<p>The following defines control general portability:</p>
<table class="docutils align-default" id="id2">
<caption><span class="caption-text">Portability defines</span><a class="headerlink" href="#id2" title="Permalink to this table">¶</a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 80.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Define</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">BSDTYPES</span></code></p></td>
<td><p>Define this if your system does <strong>not</strong> define the
usual BSD typedefs: <code class="xref c c-type docutils literal notranslate"><span class="pre">u_char</span></code>,
<code class="xref c c-type docutils literal notranslate"><span class="pre">u_short</span></code>, <code class="xref c c-type docutils literal notranslate"><span class="pre">u_int</span></code>, <code class="xref c c-type docutils literal notranslate"><span class="pre">u_long</span></code>.</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">HAVE_IEEEFP</span></code></p></td>
<td><p>Define this as 0 or 1 according to the floating point
format supported 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.</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">HAVE_MMAP</span></code></p></td>
<td><p>Define this if there is <em>mmap-style</em> support for
mapping files into memory (used only to read data).</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">HOST_FILLORDER</span></code></p></td>
<td><p>Define the native CPU bit order: one of <code class="xref c c-macro docutils literal notranslate"><span class="pre">FILLORDER_MSB2LSB</span></code>
or <code class="xref c c-macro docutils literal notranslate"><span class="pre">FILLORDER_LSB2MSB</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-macro docutils literal notranslate"><span class="pre">HOST_BIGENDIAN</span></code></p></td>
<td><p>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</p></td>
</tr>
</tbody>
</table>
<p>On UNIX systems <code class="xref c c-macro docutils literal notranslate"><span class="pre">HAVE_MMAP</span></code> is defined through the running of
the <strong class="program">configure</strong> script; otherwise support for memory-mapped
files is disabled.
Note that <code class="file docutils literal notranslate"><span class="pre">tiffcomp.h</span></code> defines <code class="xref c c-macro docutils literal notranslate"><span class="pre">HAVE_IEEEFP</span></code> to be
1 (<code class="xref c c-macro docutils literal notranslate"><span class="pre">BSDTYPES</span></code> is not defined).</p>
</section>
<section id="types-and-portability">
<h2>Types and Portability<a class="headerlink" href="#types-and-portability" title="Permalink to this heading">¶</a></h2>
<p>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 class="docutils align-default" id="id3">
<caption><span class="caption-text">Portability typedefs</span><a class="headerlink" href="#id3" title="Permalink to this table">¶</a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 60.0%" />
<col style="width: 20.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Typedef</p></th>
<th class="head"><p>Description</p></th>
<th class="head"><p>Header</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">uint8_t</span></code></p></td>
<td><p>8-bit unsigned integer</p></td>
<td><p><code class="file docutils literal notranslate"><span class="pre">tiff.h</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">int8_t</span></code></p></td>
<td><p>8-bit signed integer</p></td>
<td><p><code class="file docutils literal notranslate"><span class="pre">tiff.h</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">uint16_t</span></code></p></td>
<td><p>16-bit unsigned integer</p></td>
<td><p><code class="file docutils literal notranslate"><span class="pre">tiff.h</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">int16_t</span></code></p></td>
<td><p>16-bit signed integer</p></td>
<td><p><code class="file docutils literal notranslate"><span class="pre">tiff.h</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">uint32_t</span></code></p></td>
<td><p>32-bit unsigned integer</p></td>
<td><p><code class="file docutils literal notranslate"><span class="pre">tiff.h</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">int32_t</span></code></p></td>
<td><p>32-bit signed integer</p></td>
<td><p><code class="file docutils literal notranslate"><span class="pre">tiff.h</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">dblparam_t</span></code></p></td>
<td><p>promoted type for floats</p></td>
<td><p><code class="file docutils literal notranslate"><span class="pre">tiffcomp.h</span></code></p></td>
</tr>
</tbody>
</table>
<p>(to clarify <code class="xref c c-type docutils literal notranslate"><span class="pre">dblparam_t</span></code>, it is the type that float parameters are
promoted to when passed by value in a function call.)</p>
<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 class="docutils align-default" id="id4">
<caption><span class="caption-text">TIFF image typedefs</span><a class="headerlink" href="#id4" title="Permalink to this table">¶</a></caption>
<colgroup>
<col style="width: 33.3%" />
<col style="width: 33.3%" />
<col style="width: 33.3%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Typedef</p></th>
<th class="head"><p>Type</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">ttag_t</span></code></p></td>
<td><p><span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span></span></p></td>
<td><p>directory tag</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">tdir_t</span></code></p></td>
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">uint16_t</span></code></p></td>
<td><p>directory index</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">tsample_t</span></code></p></td>
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">uint16_t</span></code></p></td>
<td><p>sample number</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">tstrip_t</span></code></p></td>
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">uint32_t</span></code></p></td>
<td><p>strip number</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">ttile_t</span></code></p></td>
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">uint32_t</span></code></p></td>
<td><p>tile number</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">tsize_t</span></code></p></td>
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">int32_t</span></code></p></td>
<td><p>i/o size in bytes</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">tdata_t</span></code></p></td>
<td><p><span class="c-expr sig sig-inline c"><span class="kt">void</span><span class="p">*</span></span></p></td>
<td><p>image data ref</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">thandle_t</span></code></p></td>
<td><p><span class="c-expr sig sig-inline c"><span class="kt">void</span><span class="p">*</span></span></p></td>
<td><p>client data handle</p></td>
</tr>
<tr class="row-even"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">toff_t</span></code></p></td>
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">int32_t</span></code></p></td>
<td><p>file offset (should be off_t)</p></td>
</tr>
<tr class="row-odd"><td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">tidata_t</span></code></p></td>
<td><p><span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span></p></td>
<td><p>internal image data</p></td>
</tr>
</tbody>
</table>
<p>Note that <code class="xref c c-type docutils literal notranslate"><span class="pre">tstrip_t</span></code>, <code class="xref c c-type docutils literal notranslate"><span class="pre">ttile_t</span></code>, and <code class="xref c c-type docutils literal notranslate"><span class="pre">tsize_t</span></code>
are constrained to be
no more than 32-bit quantities by 32-bit fields they are stored
in in the TIFF image. Likewise <code class="xref c c-type docutils literal notranslate"><span class="pre">tsample_t</span></code> is limited by the 16-bit
field used to store the <code class="docutils literal notranslate"><span class="pre">SamplesPerPixel</span></code> tag. <code class="xref c c-type docutils literal notranslate"><span class="pre">tdir_t</span></code>
constrains
the maximum number of IFDs that may appear in an image and may
be an arbitrary size (without penalty). <code class="xref c c-type docutils literal notranslate"><span class="pre">ttag_t</span></code> must be either
<span class="c-expr sig sig-inline c"><span class="kt">int</span></span>, <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">int</span></span>, pointer, or <span class="c-expr sig sig-inline c"><span class="kt">double</span></span>
because the library uses a varargs
interface and ANSI C restricts the type of the parameter before an
ellipsis to be a promoted type. <code class="xref c c-type docutils literal notranslate"><span class="pre">toff_t</span></code> is defined as
<code class="xref c c-type docutils literal notranslate"><span class="pre">int32_t</span></code> 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 <code class="xref c c-type docutils literal notranslate"><span class="pre">tidata_t</span></code> 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>
</section>
<section id="general-comments">
<h2>General Comments<a class="headerlink" href="#general-comments" title="Permalink to this heading">¶</a></h2>
<p>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).</p>
</section>
<section id="adding-new-builtin-codecs">
<h2>Adding New Builtin Codecs<a class="headerlink" href="#adding-new-builtin-codecs" title="Permalink to this heading">¶</a></h2>
<p>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 class="reference internal" href="addingtags.html"><span class="doc">Defining New TIFF Tags</span></a>),
or do the following to add support directly to the core library:</p>
<ul class="simple">
<li><p>Define the tag value in <code class="file docutils literal notranslate"><span class="pre">tiff.h</span></code>.</p></li>
<li><p>Edit the file <code class="file docutils literal notranslate"><span class="pre">tif_codec.c</span></code> to add an entry to the
<code class="xref c c-var docutils literal notranslate"><span class="pre">_TIFFBuiltinCODECS</span></code> array (see how other algorithms are handled).</p></li>
<li><p>Add the appropriate function prototype declaration to
<code class="file docutils literal notranslate"><span class="pre">tiffiop.h</span></code> (close to the bottom).</p></li>
<li><p>Create a file with the compression scheme code, by convention files
are named <code class="file docutils literal notranslate"><span class="pre">tif_*.c</span></code> (except perhaps on some systems where the
<code class="docutils literal notranslate"><span class="pre">tif_</span></code> prefix pushes some filenames over 14 chars.</p></li>
<li><p>Update build configuration to include new source file.</p></li>
</ul>
<p>A codec, say <code class="docutils literal notranslate"><span class="pre">foo</span></code>, can have many different entry points:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">TIFFInitfoo</span><span class="p">(</span><span class="n">tif</span><span class="p">,</span><span class="w"> </span><span class="n">scheme</span><span class="p">)</span><span class="w"> </span><span class="cm">/* initialize scheme and setup entry points in tif */</span>
<span class="n">fooSetupDecode</span><span class="p">(</span><span class="n">tif</span><span class="p">)</span><span class="w"> </span><span class="cm">/* called once per IFD after tags has been frozen */</span>
<span class="n">fooPreDecode</span><span class="p">(</span><span class="n">tif</span><span class="p">,</span><span class="w"> </span><span class="n">sample</span><span class="p">)</span><span class="w"> </span><span class="cm">/* called once per strip/tile, after data is read,</span>
<span class="cm"> but before the first row is decoded */</span>
<span class="n">fooDecode</span><span class="o">*</span><span class="p">(</span><span class="n">tif</span><span class="p">,</span><span class="w"> </span><span class="n">bp</span><span class="p">,</span><span class="w"> </span><span class="n">cc</span><span class="p">,</span><span class="w"> </span><span class="n">sample</span><span class="p">)</span><span class="w"> </span><span class="cm">/* decode cc bytes of data into the buffer */</span>
<span class="w"> </span><span class="n">fooDecodeRow</span><span class="p">(...)</span><span class="w"> </span><span class="cm">/* called to decode a single scanline */</span>
<span class="w"> </span><span class="n">fooDecodeStrip</span><span class="p">(...)</span><span class="w"> </span><span class="cm">/* called to decode an entire strip */</span>
<span class="w"> </span><span class="n">fooDecodeTile</span><span class="p">(...)</span><span class="w"> </span><span class="cm">/* called to decode an entire tile */</span>
<span class="w"> </span><span class="n">fooSetupEncode</span><span class="p">(</span><span class="n">tif</span><span class="p">)</span><span class="w"> </span><span class="cm">/* called once per IFD after tags has been frozen */</span>
<span class="w"> </span><span class="n">fooPreEncode</span><span class="p">(</span><span class="n">tif</span><span class="p">,</span><span class="w"> </span><span class="n">sample</span><span class="p">)</span><span class="w"> </span><span class="cm">/* called once per strip/tile, before the first row in</span>
<span class="cm"> a strip/tile is encoded */</span>
<span class="n">fooEncode</span><span class="o">*</span><span class="p">(</span><span class="n">tif</span><span class="p">,</span><span class="w"> </span><span class="n">bp</span><span class="p">,</span><span class="w"> </span><span class="n">cc</span><span class="p">,</span><span class="w"> </span><span class="n">sample</span><span class="p">)</span><span class="cm">/* encode cc bytes of user data (bp) */</span>
<span class="w"> </span><span class="n">fooEncodeRow</span><span class="p">(...)</span><span class="w"> </span><span class="cm">/* called to decode a single scanline */</span>
<span class="w"> </span><span class="n">fooEncodeStrip</span><span class="p">(...)</span><span class="w"> </span><span class="cm">/* called to decode an entire strip */</span>
<span class="w"> </span><span class="n">fooEncodeTile</span><span class="p">(...)</span><span class="w"> </span><span class="cm">/* called to decode an entire tile */</span>
<span class="n">fooPostEncode</span><span class="p">(</span><span class="n">tif</span><span class="p">)</span><span class="w"> </span><span class="cm">/* called once per strip/tile, just before data is written */</span>
<span class="n">fooSeek</span><span class="p">(</span><span class="n">tif</span><span class="p">,</span><span class="w"> </span><span class="n">row</span><span class="p">)</span><span class="w"> </span><span class="cm">/* seek forwards row scanlines from the beginning</span>
<span class="cm"> of a strip (row will always be <0 and >rows/strip */</span>
<span class="n">fooCleanup</span><span class="p">(</span><span class="n">tif</span><span class="p">)</span><span class="w"> </span><span class="cm">/* called when compression scheme is replaced by user */</span>
</pre></div>
</div>
<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 <code class="docutils literal notranslate"><span class="pre">PlanarConfig=2</span></code>
(separate planes). This is important for algorithms such as JPEG.
If <code class="docutils literal notranslate"><span class="pre">PlanarConfig=1</span></code> (interleaved), then sample will always be 0.</p>
</section>
<section id="other-comments">
<h2>Other Comments<a class="headerlink" href="#other-comments" title="Permalink to this heading">¶</a></h2>
<p>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 <code class="xref c c-func docutils literal notranslate"><span class="pre">TIFFFlushData1()</span></code> 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
<code class="xref c c-member docutils literal notranslate"><span class="pre">tif_postdecode</span></code>
routine (set it to <code class="xref c c-func docutils literal notranslate"><span class="pre">TIFFNoPostDecode()</span></code>) and doing the required work
internally. For an example of doing this look at the horizontal
differencing code in the routines in <code class="file docutils literal notranslate"><span class="pre">tif_predict.c</span></code>.</p>
<p>The variables <code class="xref c c-member docutils literal notranslate"><span class="pre">tif_rawcc</span></code>, <code class="xref c c-member docutils literal notranslate"><span class="pre">tif_rawdata</span></code>, and
<code class="xref c c-member docutils literal notranslate"><span class="pre">tif_rawcp</span></code> in a <code class="xref c c-struct docutils literal notranslate"><span class="pre">TIFF</span></code> structure
are associated with the raw data buffer. <code class="xref c c-member docutils literal notranslate"><span class="pre">tif_rawcc</span></code> must be non-zero
for the library to automatically flush data. The variable
<code class="xref c c-member docutils literal notranslate"><span class="pre">tif_scanlinesize</span></code> is the size a user’s scanline buffer should be. The
variable <code class="xref c c-member docutils literal notranslate"><span class="pre">tif_tilesize</span></code> 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 <code class="docutils literal notranslate"><span class="pre">cc</span></code> parameter to the
<span class="c-expr sig sig-inline c"><span class="n">tif_decode</span><span class="p">*</span></span> and <span class="c-expr sig sig-inline c"><span class="n">tif_encode</span><span class="p">*</span></span>
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>
<p>In general, if you have a new compression algorithm to add, work from
the code for an existing routine. In particular,
<code class="file docutils literal notranslate"><span class="pre">tif_dumpmode.c</span></code>
has the trivial code for the “nil” compression scheme,
<code class="file docutils literal notranslate"><span class="pre">tif_packbits.c</span></code> is a
simple byte-oriented scheme that has to watch out for buffer
boundaries, and <code class="file docutils literal notranslate"><span class="pre">tif_lzw.c</span></code> 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>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Modifying The TIFF Library</a><ul>
<li><a class="reference internal" href="#library-configuration">Library Configuration</a></li>
<li><a class="reference internal" href="#general-portability-comments">General Portability Comments</a></li>
<li><a class="reference internal" href="#types-and-portability">Types and Portability</a></li>
<li><a class="reference internal" href="#general-comments">General Comments</a></li>
<li><a class="reference internal" href="#adding-new-builtin-codecs">Adding New Builtin Codecs</a></li>
<li><a class="reference internal" href="#other-comments">Other Comments</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="functions/_TIFFRewriteField.html"
title="previous chapter">_TIFFRewriteField</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="addingtags.html"
title="next chapter">Defining New TIFF Tags</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/internals.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="addingtags.html" title="Defining New TIFF Tags"
>next</a> |</li>
<li class="right" >
<a href="functions/_TIFFRewriteField.html" title="_TIFFRewriteField"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">LibTIFF 4.6.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Modifying The TIFF Library</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 1988-2022, LibTIFF contributors.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.0.1.
</div>
</body>
</html>