From d479dd1aab1c1cb907932c6595b0ef33523fc797 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Fri, 6 Nov 2015 07:14:47 +0100 Subject: Imported Upstream version 1.8.3 --- tiff/html/internals.html | 572 ----------------------------------------------- 1 file changed, 572 deletions(-) delete mode 100755 tiff/html/internals.html (limited to 'tiff/html/internals.html') diff --git a/tiff/html/internals.html b/tiff/html/internals.html deleted file mode 100755 index 83d53b0..0000000 --- a/tiff/html/internals.html +++ /dev/null @@ -1,572 +0,0 @@ - - - -Modifying The TIFF Library - - - - -

- -Modifying The TIFF Library -

- - -

-This chapter provides information about the internal structure of -the library, how to control the configuration when building it, and -how to add new support to the library. -The following sections are found in this chapter: - -

- - -

Library Configuration

 - -Information on compiling the library is given -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 port.h -(as generated by the configure script for UNIX systems) -or tiffconf.h. - -

-Configuration defines are split into three areas: -

- -

-If the define COMPRESSION_SUPPORT is not defined -then a default set of compression schemes is automatically -configured: -

- -

- -To override the default compression behaviour define -COMPRESSION_SUPPORT and then one or more additional defines -to enable configuration of the appropriate codecs (see the table -below); e.g. - -

- -Several other compression schemes are configured separately from -the default set because they depend on ancillary software -packages that are not distributed with libtiff. - -

-Support for JPEG compression is controlled by JPEG_SUPPORT. -The JPEG codec that comes with libtiff is designed for -use with release 5 or later of the Independent JPEG Group's freely -available software distribution. -This software can be retrieved from the directory -ftp.uu.net:/graphics/jpeg/. - - -

-NOTE: -Enabling JPEG support automatically enables support for -the TIFF 6.0 colorimetry and YCbCr-related tags. - -

-Experimental support for the deflate algorithm is controlled by -DEFLATE_SUPPORT. -The deflate codec that comes with libtiff is designed -for use with version 0.99 or later of the freely available -libz library written by Jean-loup Gailly and Mark Adler. -The data format used by this library is described -in the files -zlib-3.1.doc, -and -deflate-1.1.doc, -available in the directory -ftp.uu.net:/pub/archiving/zip/doc. -The library can be retried from the directory -ftp.uu.net:/pub/archiving/zip/zlib/ -(or try quest.jpl.nasa.gov:/beta/zlib/). - -

-NOTE: -The deflate algorithm is experimental. Do not expect -to exchange files using this compression scheme; -it is included only because the similar, and more common, -LZW algorithm is claimed to be governed by licensing restrictions. - - -

-By default tiffconf.h defines -COLORIMETRY_SUPPORT, -YCBCR_SUPPORT, -and -CMYK_SUPPORT. - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DefineDescription
CCITT_SUPPORTCCITT Group 3 and 4 algorithms (compression codes 2, 3, 4, - and 32771)
PACKBITS_SUPPORTMacintosh PackBits algorithm (compression 32773)
LZW_SUPPORTLempel-Ziv & Welch (LZW) algorithm (compression 5)
THUNDER_SUPPORT4-bit -run-length encoding scheme from ThunderScan (compression 32809)
NEXT_SUPPORT2-bit encoding scheme used by NeXT (compression 32766)
OJPEG_SUPPORTobsolete JPEG scheme defined in the 6.0 spec (compression 6)
JPEG_SUPPORTcurrent JPEG scheme defined in TTN2 (compression 7)
ZIP_SUPPORTexperimental Deflate scheme (compression 32946)
PIXARLOG_SUPPORTPixar's compression scheme for high-resolution color images (compression 32909)
SGILOG_SUPPORTSGI's compression scheme for high-resolution color images (compression 34676 and 34677)
COLORIMETRY_SUPPORTsupport for the TIFF 6.0 colorimetry tags
YCBCR_SUPPORTsupport for the TIFF 6.0 YCbCr-related tags
CMYK_SUPPORTsupport for the TIFF 6.0 CMYK-related tags
ICC_SUPPORTsupport for the ICC Profile tag; see -The ICC Profile Format Specification, -Annex B.3 "Embedding ICC Profiles in TIFF Files"; -available at -http://www.color.org -
- - -

General Portability Comments

- -This software is developed on Silicon Graphics UNIX -systems (big-endian, MIPS CPU, 32-bit ints, -IEEE floating point). -The configure 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. - -

-In general, the code is guaranteed to work only on SGI machines. -In practice it is highly portable to any 32-bit or 64-bit system and much -work has been done to insure portability to 16-bit systems. -If you encounter portability problems please return fixes so -that future distributions can be improved. - -

-The software is written to assume an ANSI C compilation environment. -If your compiler does not support ANSI function prototypes, const, -and <stdarg.h> then you will have to make modifications to the -software. In the past I have tried to support compilers without const -and systems without <stdarg.h>, but I am -no longer interested in these -antiquated environments. With the general availability of -the freely available GCC compiler, I -see no reason to incorporate modifications to the software for these -purposes. - -

-An effort has been made to isolate as many of the -operating system-dependencies -as possible in two files: tiffcomp.h and -libtiff/tif_<os>.c. The latter file contains -operating system-specific routines to do I/O and I/O-related operations. -The UNIX (tif_unix.c), -Macintosh (tif_apple.c), -and VMS (tif_vms.c) -code has had the most use; -the MS/DOS support (tif_msdos.c) assumes -some level of UNIX system call emulation (i.e. -open, -read, -write, -fstat, -malloc, -free). - -

-Native CPU byte order is determined on the fly by -the library and does not need to be specified. -The HOST_FILLORDER and HOST_BIGENDIAN -definitions are not currently used, but may be employed by -codecs for optimization purposes. - -

-The following defines control general portability: - -

- - - - - - - - - - - - - - - - - - - - - - - - - - -
BSDTYPESDefine this if your system does NOT define the - usual BSD typedefs: u_char, - u_short, u_int, u_long.
HAVE_IEEEFPDefine this as 0 or 1 according to the floating point - format suported by the machine. If your machine does - not support IEEE floating point then you will need to - add support to tif_machdep.c to convert between the - native format and IEEE format.
HAVE_MMAPDefine this if there is mmap-style support for -mapping files into memory (used only to read data).
HOST_FILLORDERDefine the native CPU bit order: one of FILLORDER_MSB2LSB - or FILLORDER_LSB2MSB
HOST_BIGENDIANDefine the native CPU byte order: 1 if big-endian (Motorola) - or 0 if little-endian (Intel); this may be used - in codecs to optimize code
- -

-On UNIX systems HAVE_MMAP is defined through the running of -the configure script; otherwise support for memory-mapped -files is disabled. -Note that tiffcomp.h defines HAVE_IEEEFP to be -1 (BSDTYPES is not defined). - - -

Types and Portability

- -The software makes extensive use of C typedefs to promote portability. -Two sets of typedefs are used, one for communication with clients -of the library and one for internal data structures and parsing of the -TIFF format. There are interactions between these two to be careful -of, but for the most part you should be able to deal with portability -purely by fiddling with the following machine-dependent typedefs: - - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
uint88-bit unsigned integertiff.h
int88-bit signed integertiff.h
uint1616-bit unsigned integertiff.h
int1616-bit signed integertiff.h
uint3232-bit unsigned integertiff.h
int3232-bit signed integertiff.h
dblparam_tpromoted type for floatstiffcomp.h
- -

-(to clarify dblparam_t, it is the type that float parameters are -promoted to when passed by value in a function call.) - -

-The following typedefs are used throughout the library and interfaces -to refer to certain objects whose size is dependent on the TIFF image -structure: - - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
typedef unsigned int ttag_t; directory tag
typedef uint16 tdir_t; directory index
typedef uint16 tsample_t; sample number
typedef uint32 tstrip_t; strip number
typedef uint32 ttile_t; tile number
typedef int32 tsize_t; i/o size in bytes
typedef void* tdata_t; image data ref
typedef void* thandle_t; client data handle
typedef int32 toff_t; file offset (should be off_t)
typedef unsigned char* tidata_t; internal image data
- -

-Note that tstrip_t, ttile_t, and tsize_t -are constrained to be -no more than 32-bit quantities by 32-bit fields they are stored -in in the TIFF image. Likewise tsample_t is limited by the 16-bit -field used to store the SamplesPerPixel tag. tdir_t -constrains -the maximum number of IFDs that may appear in an image and may -be an arbitrary size (without penalty). ttag_t must be either -int, unsigned int, pointer, or double -because the library uses a varargs -interface and ANSI C restricts the type of the parameter before an -ellipsis to be a promoted type. toff_t is defined as -int32 because -TIFF file offsets are (unsigned) 32-bit quantities. A signed -value is used because some interfaces return -1 on error (sigh). -Finally, note that tidata_t is used internally to the library to -manipulate internal data. User-specified data references are -passed as opaque handles and only cast at the lowest layers where -their type is presumed. - - -

General Comments

- -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). - -

Adding New Builtin Codecs

 - -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 Adding New Tags), -or do the following to add support directly to the core library: - -
    -
  1. Define the tag value in tiff.h. -
  2. Edit the file tif_codec.c to add an entry to the - _TIFFBuiltinCODECS array (see how other algorithms are handled). -
  3. Add the appropriate function prototype declaration to - tiffiop.h (close to the bottom). -
  4. Create a file with the compression scheme code, by convention files - are named tif_*.c (except perhaps on some systems where the - tif_ prefix pushes some filenames over 14 chars. -
  5. Edit Makefile.in (and any other Makefiles) - to include the new source file. -
- -

-A codec, say foo, can have many different entry points: - -

-TIFFInitfoo(tif, scheme)/* initialize scheme and setup entry points in tif */
-fooSetupDecode(tif)	/* called once per IFD after tags has been frozen */
-fooPreDecode(tif, sample)/* called once per strip/tile, after data is read,
-			    but before the first row is decoded */
-fooDecode*(tif, bp, cc, sample)/* decode cc bytes of data into the buffer */
-    fooDecodeRow(...)	/* called to decode a single scanline */
-    fooDecodeStrip(...)	/* called to decode an entire strip */
-    fooDecodeTile(...)	/* called to decode an entire tile */
-fooSetupEncode(tif)	/* called once per IFD after tags has been frozen */
-fooPreEncode(tif, sample)/* called once per strip/tile, before the first row in
-			    a strip/tile is encoded */
-fooEncode*(tif, bp, cc, sample)/* encode cc bytes of user data (bp) */
-    fooEncodeRow(...)	/* called to decode a single scanline */
-    fooEncodeStrip(...)	/* called to decode an entire strip */
-    fooEncodeTile(...)	/* called to decode an entire tile */
-fooPostEncode(tif)	/* called once per strip/tile, just before data is written */
-fooSeek(tif, row)	/* seek forwards row scanlines from the beginning
-			   of a strip (row will always be >0 and <rows/strip */
-fooCleanup(tif)		/* called when compression scheme is replaced by user */
-
- -

-Note that the encoding and decoding variants are only needed when -a compression algorithm is dependent on the structure of the data. -For example, Group 3 2D encoding and decoding maintains a reference -scanline. The sample parameter identifies which sample is to be -encoded or decoded if the image is organized with PlanarConfig=2 -(separate planes). This is important for algorithms such as JPEG. -If PlanarConfig=1 (interleaved), then sample will always be 0. - -

Other Comments

- -The library handles most I/O buffering. There are two data buffers -when decoding data: a raw data buffer that holds all the data in a -strip, and a user-supplied scanline buffer that compression schemes -place decoded data into. When encoding data the data in the -user-supplied scanline buffer is encoded into the raw data buffer (from -where it is written). Decoding routines should never have to explicitly -read data -- a full strip/tile's worth of raw data is read and scanlines -never cross strip boundaries. Encoding routines must be cognizant of -the raw data buffer size and call TIFFFlushData1() when necessary. -Note that any pending data is automatically flushed when a new strip/tile is -started, so there's no need do that in the tif_postencode routine (if -one exists). Bit order is automatically handled by the library when -a raw strip or tile is filled. If the decoded samples are interpreted -by the decoding routine before they are passed back to the user, then -the decoding logic must handle byte-swapping by overriding the -tif_postdecode -routine (set it to TIFFNoPostDecode) and doing the required work -internally. For an example of doing this look at the horizontal -differencing code in the routines in tif_predict.c. - -

-The variables tif_rawcc, tif_rawdata, and -tif_rawcp in a TIFF structure -are associated with the raw data buffer. tif_rawcc must be non-zero -for the library to automatically flush data. The variable -tif_scanlinesize is the size a user's scanline buffer should be. The -variable tif_tilesize is the size of a tile for tiled images. This -should not normally be used by compression routines, except where it -relates to the compression algorithm. That is, the cc parameter to the -tif_decode* and tif_encode* -routines should be used in terminating -decompression/compression. This ensures these routines can be used, -for example, to decode/encode entire strips of data. - -

-In general, if you have a new compression algorithm to add, work from -the code for an existing routine. In particular, -tif_dumpmode.c -has the trivial code for the "nil" compression scheme, -tif_packbits.c is a -simple byte-oriented scheme that has to watch out for buffer -boundaries, and tif_lzw.c has the LZW scheme that has the most -complexity -- it tracks the buffer boundary at a bit level. -Of course, using a private compression scheme (or private tags) limits -the portability of your TIFF files. - -

-

- -Last updated: $Date: 2004-09-10 14:47:31 $ - - - - -- cgit v1.2.3