diff options
Diffstat (limited to 'man/libtiff.3t')
| -rw-r--r-- | man/libtiff.3t | 511 |
1 files changed, 511 insertions, 0 deletions
diff --git a/man/libtiff.3t b/man/libtiff.3t new file mode 100644 index 00000000..00b0ff12 --- /dev/null +++ b/man/libtiff.3t @@ -0,0 +1,511 @@ +.\" $Header: /cvs/maptools/cvsroot/libtiff/man/Attic/libtiff.3t,v 1.1 1999-07-27 21:50:27 mike Exp $ +.\" +.\" Copyright (c) 1988-1997 Sam Leffler +.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. +.\" +.\" Permission to use, copy, modify, distribute, and sell this software and +.\" its documentation for any purpose is hereby granted without fee, provided +.\" that (i) the above copyright notices and this permission notice appear in +.\" all copies of the software and related documentation, and (ii) the names of +.\" Sam Leffler and Silicon Graphics may not be used in any advertising or +.\" publicity relating to the software without the specific, prior written +.\" permission of Sam Leffler and Silicon Graphics. +.\" +.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY +.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. +.\" +.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR +.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, +.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF +.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE +.\" OF THIS SOFTWARE. +.\" +.if n .po 0 +.TH INTRO 3T "August 21, 1997" +.SH NAME +libtiff \- introduction to +.IR libtiff , +a library for reading and writing +.SM TIFF +files +.SH SYNOPSIS +.B "#include <tiffio.h>" +.br +cc file.c +.B -ltiff +.SH DESCRIPTION +.I libtiff +is a library for reading and writing data files encoded with the +.I "Tag Image File" +format, Revision 6.0 (or revision 5.0 or revision 4.0). +This file format is suitable for archiving multi-color and +monochromatic image data. +.PP +The library supports several compression algorithms, as indicated +by the +.I Compression +field, including: +no compression (1), +.SM CCITT +1D Huffman compression (2), +.SM CCITT +Group 3 Facsimile compression (3), +.SM CCITT +Group 4 Facsimile compression (4), +Lempel-Ziv & Welch compression (5), +baseline JPEG compression (7), +word-aligned 1D Huffman compression (32771), +and +PackBits compression (32773). +In addition, several nonstandard compression algorithms are supported: +the 4-bit compression algorithm used +by the +.I ThunderScan +program (32809) (decompression only), +NeXT's 2-bit compression algorithm (32766) (decompression only), +an experimental LZ-style algorithm known as Deflate (32946), and +an experimental CIE LogLuv compression scheme designed for images +with high dynamic range (32845 for LogL and 32845 for LogLuv). +Directory information may be in either little- or big-endian byte +order\-byte swapping is automatically done by the library. +Data bit ordering may be either Most Significant Bit (\c +.SM MSB\c +) to Least Significant Bit (\c +.SM LSB\c +) or +.SM LSB +to +.SM MSB. +Finally, the library does not support files in which the +.IR BitsPerSample , +.IR Compression , +.IR MinSampleValue , +or +.IR MaxSampleValue +fields are defined differently on a per-sample basis +(in Rev. 6.0 the +.I Compression +tag is not defined on a per-sample basis, so this is immaterial). +.SH "DATA TYPES" +The library 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 +.SM TIFF +format. +The following typedefs are exposed to users either through +function definitions or through parameters passed through the +varargs interfaces. +.in +.5i +.sp 5p +.ta +\w'typedef unsigned <\fIthing\fP> uint32; 'u +.nf +typedef unsigned short uint16; 16-bit unsigned integer +typedef unsigned <\fIthing\fP> uint32; 32-bit unsigned integer +.sp 5p +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 +.fi +.sp 5p +.in -.5i +Note that +.IR tstrip_t , +.IR ttile_t , +and +.I tsize_t +are constrained to be no more than 32-bit quantities by +32-bit fields they are stored in in the +.SM TIFF +image. +Likewise +.I tsample_t +is limited by the 16-bit field used to store the +.I SamplesPerPixel +tag. +.I tdir_t +constrains the maximum number of +.SM IFDs +that may appear in an image and may be an arbitrary size (w/o penalty). +.I ttag_t +must be either int, unsigned int, pointer, or double because +the library uses a varargs interface and +.SM "ANSI C" +restricts the type of the parameter before an ellipsis to be a +promoted type. +.I 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. +Finally, note that user-specified data references are +passed as opaque handles and only cast at the lowest layers where +their type is presumed. +.SH "LIST OF ROUTINES" +The following routines are part of the library. +Consult specific manual pages for details on their operation. +The manual page names listed below are for systems +where the full function names can not be encoded in the filesystem; +on most systems doing ``man function-name'' will work. +.sp 5p +.nf +.ta \w'TIFFWriteEncodedStrip'u+2n +\w'Appears on Page'u+2n +\fIName\fP \fIAppears on Page\fP \fIDescription\fP +.sp 5p +TIFFCheckTile tile.3t very x,y,z,sample is within image +TIFFClientOpen open.3t open a file for reading or writing +TIFFClose close.3t close an open file +TIFFComputeStrip strip.3t return strip containing y,sample +TIFFComputeTile tile.3t return tile containing x,y,z,sample +TIFFCurrentDirectory query.3t return index of current directory +TIFFCurrentRow query.3t return index of current scanline +TIFFCurrentStrip query.3t return index of current strip +TIFFCurrentTile query.3t return index of current tile +TIFFError error.3t library error handler +TIFFFdOpen open.3t open a file for reading or writing +TIFFFileName query.3t return name of open file +TIFFFileno query.3t return open file descriptor +TIFFFlush flush.3t flush all pending writes +TIFFFlushData flush.3t flush pending data writes +TIFFGetBitRevTable swab.3t return bit reversal table +TIFFGetField getfield.3t return tag value in current directory +TIFFGetFieldDefaulted getfield.3t return tag value in current directory +TIFFGetMode query.3t return open file mode +TIFFGetVersion query.3t return library version string +TIFFIsTiled query.3t return true if image data is tiled +TIFFIsByteSwapped query.3t return true if image data is byte-swapped +TIFFNumberOfStrips strip.3t return number of strips in an image +TIFFNumberOfTiles tile.3t return number of tiles in an image +TIFFOpen open.3t open a file for reading or writing +TIFFPrintDirectory print.3t print description of the current directory +TIFFReadBufferSetup rdbuf.3t specify i/o buffer for reading +TIFFReadDirectory readdir.3t read the next directory +TIFFReadEncodedStrip rdestrip.3t read and decode a strip of data +TIFFReadEncodedTile rdetile.3t read and decode a tile of data +TIFFReadRawStrip rdrstrip.3t read a raw strip of data +TIFFReadRawTile rdrtile.3t read a raw tile of data +TIFFReadRGBAImage rdimage.3t read an image into a fixed format raster +TIFFReadScanline readline.3t read and decode a row of data +TIFFReadTile readtile.3t read and decode a tile of data +TIFFReverseBits swab.3t reverse bits in an array of bytes +TIFFRGBAImageBegin rgbaimage.3t setup decoder state for TIFFRGBAImageGet +TIFFRGBAImageEnd rgbaimage.3t release TIFFRGBAImage decoder state +TIFFRGBAImageGet rgbaimage.3t read and decode an image +TIFFRGBAImageOK rgbaimage.3t is image readable by TIFFRGBAImageGet +TIFFScanlineSize size.3t return size of a scanline +TIFFSetDirectory setdir.3t set the current directory +TIFFSetSubDirectory setdir.3t set the current directory +TIFFSetErrorHandler error.3t set error handler function +TIFFSetField setfield.3t set a tag's value in the current directory +TIFFSetWarningHandler error.3t set warning handler function +TIFFStripSize size.3t return size of a strip +TIFFSwabShort swab.3t swap bytes of short +TIFFSwabLong swab.3t swap bytes of long +TIFFSwabArrayOfShort swab.3t swap bytes of an array of shorts +TIFFSwabArrayOfLong swab.3t swap bytes of an array of longs +TIFFTileRowSize size.3t return size of a row in a tile +TIFFTileSize size.3t return size of a tile +TIFFVGetField getfield.3t return tag value in current directory +TIFFVGetFieldDefaulted getfield.3t return tag value in current directory +TIFFVSetField setfield.3t set a tag's value in the current directory +TIFFWarning warning.3t library warning handler +TIFFWriteDirectory writedir.3t write the current directory +TIFFWriteEncodedStrip wrestrip.3t compress and write a strip of data +TIFFWriteEncodedTile wretile.3t compress and write a tile of data +TIFFWriteRawStrip wrrstrip.3t write a raw strip of data +TIFFWriteRawTile wrrtile.3t write a raw tile of data +TIFFWriteScanline writeline.3t write a scanline of data +TIFFWriteTile wrrtile.3t compress and write a tile of data +.fi +.SH "TAG USAGE" +The table below lists the +.SM TIFF +tags that are recognized and handled by the library. +If no use is indicated in the table, then the library +reads and writes the tag, but does not use it internally. +Note that some tags are meaningful only when a particular +compression scheme is being used; e.g. +.I Group3Options +is only useful if +.I Compression +is set to +.SM CCITT +Group 3 encoding. +Tags of this sort are considered +.I codec-specific +tags and the library does not recognize them except when the +.I Compression +tag has been previously set to the relevant compression scheme. +.sp 5p +.nf +.ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Value'u+2n +\w'R/W'u+2n +\fITag Name\fP \fIValue\fP \fIR/W\fP \fILibrary Use/Notes\fP +.sp 5p +.nf +Artist 315 R/W +BadFaxLines 326 R/W +BitsPerSample 258 R/W lots +CellLength 265 parsed but ignored +CellWidth 264 parsed but ignored +CleanFaxData 327 R/W +ColorMap 320 R/W +ColorResponseUnit 300 parsed but ignored +Compression 259 R/W choosing codec +ConsecutiveBadFaxLines 328 R/W +DataType 32996 R obsoleted by SampleFormat tag +DateTime 306 R/W +DocumentName 269 R/W +DotRange 336 R/W +ExtraSamples 338 R/W lots +FaxRecvParams 34908 R/W +FaxSubAddress 34909 R/W +FaxRecvTime 34910 R/W +FillOrder 266 R/W control bit order +FreeByteCounts 289 parsed but ignored +FreeOffsets 288 parsed but ignored +GrayResponseCurve 291 parsed but ignored +GrayResponseUnit 290 parsed but ignored +Group3Options 292 R/W used by Group 3 codec +Group4Options 293 R/W +HostComputer 316 R/W +ImageDepth 32997 R/W tile/strip calculations +ImageDescription 270 R/W +ImageLength 257 R/W lots +ImageWidth 256 R/W lots +InkNames 333 R/W +InkSet 332 R/W +JPEGTables 347 R/W used by JPEG codec +Make 271 R/W +Matteing 32995 R obsoleted by ExtraSamples tag +MaxSampleValue 281 R/W +MinSampleValue 280 R/W +Model 272 R/W +NewSubFileType 254 R/W called SubFileType in spec +NumberOfInks 334 R/W +Orientation 274 R/W +PageName 285 R/W +PageNumber 297 R/W +PhotometricInterpretation 262 R/W used by Group 3 and JPEG codecs +PlanarConfiguration 284 R/W data i/o +Predictor 317 R/W used by LZW and Deflate codecs +PrimaryChromacities 319 R/W +ReferenceBlackWhite 532 R/W +ResolutionUnit 296 R/W used by Group 3 codec +RowsPerStrip 278 R/W data i/o +SampleFormat 339 R/W +SamplesPerPixel 277 R/W lots +SMinSampleValue 340 R/W +SMaxSampleValue 341 R/W +Software 305 R/W +StoNits 37439 R/W +StripByteCounts 279 R/W data i/o +StripOffsets 273 R/W data i/o +SubFileType 255 R/W called OSubFileType in spec +TargetPrinter 337 R/W +Thresholding 263 R/W +TileByteCounts 324 R/W data i/o +TileDepth 32998 R/W tile/strip calculations +TileLength 323 R/W data i/o +TileOffsets 324 R/W data i/o +TileWidth 322 R/W data i/o +TransferFunction 301 R/W +WhitePoint 318 R/W +XPosition 286 R/W +XResolution 282 R/W +YCbCrCoefficients 529 R/W used by TIFFRGBAImage support +YCbCrPositioning 531 R/W tile/strip size calulcations +YCbCrSubsampling 530 R/W +YPosition 286 R/W +YResolution 283 R/W used by Group 3 codec +.SH "PSEUDO TAGS" +In addition to the normal +.SM TIFF +tags the library supports a collection of +tags whose values lie in a range outside the valid range of +.SM TIFF +tags. +These tags are termed +.I pseud-tags +and are used to control various codec-specific functions within the library. +The table below summarizes the defined pseudo-tags. +.sp 5p +.nf +.ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Codec'u+2n +\w'R/W'u+2n +\fITag Name\fP \fICodec\fP \fIR/W\fP \fILibrary Use/Notes\fP +.sp 5p +.nf +TIFFTAG_FAXMODE G3 R/W general codec operation +TIFFTAG_FAXFILLFUNC G3/G4 R/W bitmap fill function +TIFFTAG_JPEGQUALITY JPEG R/W compression quality control +TIFFTAG_JPEGCOLORMODE JPEG R/W control colorspace conversions +TIFFTAG_JPEGTABLESMODE JPEG R/W control contents of \fIJPEGTables\fP tag +TIFFTAG_ZIPQUALITY Deflate R/W compression quality level +TIFFTAG_PIXARLOGDATAFMT PixarLog R/W user data format +TIFFTAG_PIXARLOGQUALITY PixarLog R/W compression quality level +TIFFTAG_SGILOGDATAFMT SGILog R/W user data format +.fi +.TP +.B TIFFTAG_FAXMODE +Control the operation of the Group 3 codec. +Possible values (independent bits that can be combined by +or'ing them together) are: +FAXMODE_CLASSIC +(enable old-style format in which the +.SM RTC +is written at the end of the last strip), +FAXMODE_NORTC +(opposite of +FAXMODE_CLASSIC; +also called +FAXMODE_CLASSF), +FAXMODE_NOEOL +(do not write +.SM EOL +codes at the start of each row of data), +FAXMODE_BYTEALIGN +(align each encoded row to an 8-bit boundary), +FAXMODE_WORDALIGN +(align each encoded row to an 16-bit boundary), +The default value is dependent on the compression scheme; this +pseudo-tag is used by the various G3 and G4 codecs to share code. +.TP +.B TIFFTAG_FAXFILLFUNC +Control the function used to convert arrays of black and white +runs to packed bit arrays. +This hook can be used to image decoded scanlines in multi-bit +depth rasters (e.g. for display in colormap mode) +or for other purposes. +The default value is a pointer to a builtin function that images +packed bilevel data. +.TP +.B TIFFTAG_JPEGQUALITY +Control the compression quality level used in the baseline algorithm. +Note that quality levels are in the range 0-100 with a default value of 75. +.TP +.B TIFFTAG_JPEGCOLORMODE +Control whether or not conversion is done between +RGB and YCbCr colorspaces. +Possible values are: +JPEGCOLORMODE_RAW +(do not convert), and +JPEGCOLORMODE_RGB +(convert to/from RGB) +The default value is JPEGCOLORMODE_RAW. +.TP +.B TIFFTAG_JPEGTABLESMODE +Control the information written in the +.I JPEGTables +tag. +Possible values (independent bits that can be combined by +or'ing them together) are: +JPEGTABLESMODE_QUANT +(include quantization tables), +and +JPEGTABLESMODE_HUFF +(include Huffman encoding tables). +The default value is JPEGTABLESMODE_QUANT|JPEGTABLESMODE_HUFF. +.TP +.B TIFFTAG_ZIPQUALITY +Control the compression technique used by the Deflate codec. +Quality levels are in the range 1-9 with larger numbers yielding better +compression at the cost of more computation. +The default quality level is 6 which yields a good time-space tradeoff. +.TP +.B TIFFTAG_PIXARLOGDATAFMT +Control the format of user data passed +.I in +to the PixarLog codec when encoding and passed +.I out +from when decoding. +Possible values are: +PIXARLOGDATAFMT_8BIT +for 8-bit unsigned pixels, +PIXARLOGDATAFMT_8BITABGR +for 8-bit unsigned ABGR-ordered pixels, +PIXARLOGDATAFMT_11BITLOG +for 11-bit log-encoded raw data, +PIXARLOGDATAFMT_12BITPICIO +for 12-bit PICIO-compatible data, +PIXARLOGDATAFMT_16BIT +for 16-bit signed samples, +and +PIXARLOGDATAFMT_FLOAT +for 32-bit IEEE floating point samples. +.TP +.B TIFFTAG_PIXARLOGQUALITY +Control the compression technique used by the PixarLog codec. +This value is treated identically to TIFFTAG_ZIPQUALITY; see the +above description. +.TP +.B TIFFTAG_SGILOGDATAFMT +Control the format of client data passed +.I in +to the SGILog codec when encoding and passed +.I out +from when decoding. +Possible values are: +SGILOGDATAFMT_FLTXYZ +for converting between LogLuv and 32-bit IEEE floating valued XYZ pixels, +SGILOGDATAFMT_16BITLUV +for 16-bit encoded Luv pixels, +SGILOGDATAFMT_32BITRAW and SGILOGDATAFMT_24BITRAW +for no conversion of data, +SGILOGDATAFMT_8BITRGB +for returning 8-bit RGB data (valid only when decoding LogLuv-encoded data), +SGILOGDATAFMT_FLTY +for converting between LogL and 32-bit IEEE floating valued Y pixels, +SGILOGDATAFMT_16BITL +for 16-bit encoded L pixels, +and +SGILOGDATAFMT_8BITGRY +for returning 8-bit greyscale data +(valid only when decoding LogL-encoded data). +.SH DIAGNOSTICS +All error messages are directed through the +.IR TIFFError +routine. +By default messages are directed to +.B stderr +in the form: +.IR "module: message\en." +Warning messages are likewise directed through the +.IR TIFFWarning +routine. +.SH "SEE ALSO" +.IR fax2tiff (1), +.IR gif2tiff (1), +.IR pal2rgb (1), +.IR ppm2tiff (1), +.IR rgb2ycbcr (1), +.IR ras2tiff (1), +.IR sgi2tiff (1), +.IR tiff2bw (1), +.IR tiffdither (1), +.IR tiffdump (1), +.IR tiffcp (1), +.IR tiffcmp (1), +.IR tiffgt (1), +.IR tiffinfo (1), +.IR tiffmedian (1), +.IR tiffsplit (1), +.IR tiffsv (1), +.PP +.IR "Tag Image File Format Specification \(em Revision 6.0" , +an Aldus Technical Memorandum. +.PP +.IR "The Spirit of TIFF Class F" , +an appendix to the TIFF 5.0 specification prepared by Cygnet Technologies. +.SH BUGS +The library does not support multi-sample images +where some samples have different bits/sample. +.PP +The library does not support random access to compressed data +that is organized with more than one row per tile or strip. +The library discards unknown tags. +The library should do more validity checking of a directory's contents. |