diff options
Diffstat (limited to 'man/intro.3t')
| -rw-r--r-- | man/intro.3t | 359 |
1 files changed, 359 insertions, 0 deletions
diff --git a/man/intro.3t b/man/intro.3t new file mode 100644 index 00000000..85b2c1a2 --- /dev/null +++ b/man/intro.3t @@ -0,0 +1,359 @@ +.\" $Header: /usr/people/sam/tiff/man/RCS/intro.3t,v 1.17 1995/07/07 23:29:04 sam Exp $ +.\" +.\" Copyright (c) 1988, 1989, 1990, 1991, 1992, 1993, 1994 Sam Leffler +.\" Copyright (c) 1991, 1992, 1993, 1994 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 "February 14, 1992" +.SH NAME +intro \- 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), +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), +and NeXT's 2-bit compression algorithm (32766) (decompression only). +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 <thing> uint32; 'u +.nf +typedef unsigned short uint16; 16-bit unsigned integer +typedef unsigned <thing> 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 available. +Consult specific manual pages for details on their operation. +(The manual page names give here 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 +TIFFScanlineSize size.3t return size of a scanline +TIFFSetDirectory 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. +.sp 5p +.nf +.ta \w'PhotometricInterpretation'u+2n +\w'Value'u+2n +\w'R/W'u+2n +\fITag Name\fP \fIValue\fP \fIR/W\fP \fILibrary's Use\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 compression routines +ConsecutiveBadFaxLines 328 R/W +DataType 32996 R +DateTime 306 R/W +DocumentName 269 R/W +DotRange 336 R/W +ExtraSamples 338 R/W lots +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 code +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 +JPEGACTables 521 R/W JPEG code +JPEGDCTables 520 R/W JPEG code +JPEGProc 512 R/W JPEG code +JPEGQRestartInterval 515 R/W JPEG code +JPEGQTables 519 R/W JPEG code +Make 271 R/W +Matteing 32995 R +MaxSampleValue 281 R/W +MinSampleValue 280 R/W +Model 272 R/W +NewSubFileType 254 R/W (called SubFileType) +Orientation 274 R/W +PageName 285 R/W +PageNumber 297 R/W +PhotometricInterpretation 262 R/W Group 3 and JPEG code +PlanarConfiguration 284 R/W data i/o +Predictor 317 R/W used by LZW code +PrimaryChromacities 319 R/W +ReferenceBlackWhite 532 R/W +ResolutionUnit 296 R/W +RowsPerStrip 278 R/W data i/o +SampleFormat 339 R/W +SamplesPerPixel 277 R/W lots +Software 305 R/W +StripByteCounts 279 R/W data i/o +StripOffsets 273 R/W data i/o +SubFileType 255 R/W (called OSubFileType) +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 TIFFReadRGBAImage +YCbCrPositioning 531 R/W tile/strip size calulcations +YCbCrSubsampling 530 R/W +YPosition 286 R/W +YResolution 283 R/W used by Group 3 2d encoding +.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, +to be released. +.PP +.IR "The Spirit of TIFF Class F" , +an appendix to the TIFF 5.0 specification prepared by Cygnet Technologies. +.PP +.IR "Appendix ALPHA: Associated Alpha Information" , +a proposed appendix to the TIFF 6.0 specification. +.SH BUGS +The library does not support multi-sample images +where some samples have different bits/sample. +.PP +It is not possible to overwrite the contents of a strip with +.IR TIFFWriteEncodedStrip +or +.IR TIFFWriteRawStrip +since they +.I append +to a strip. +Likewise, +.IR TIFFWriteEncodedTile +and +.IR TIFFWriteRawTile +append to a tile. +.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. |