ALPHALINUX5/util/ALPHALINUX5/man/man3/libtiff.3t

   1 .\" $Header: /d1/sam/tiff/man/RCS/libtiff.3t,v 1.25 1997/08/29 21:48:21 sam Exp $
   2 .\"
   3 .\" Copyright (c) 1988-1997 Sam Leffler
   4 .\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
   5 .\"
   6 .\" Permission to use, copy, modify, distribute, and sell this software and
   7 .\" its documentation for any purpose is hereby granted without fee, provided
   8 .\" that (i) the above copyright notices and this permission notice appear in
   9 .\" all copies of the software and related documentation, and (ii) the names of
  10 .\" Sam Leffler and Silicon Graphics may not be used in any advertising or
  11 .\" publicity relating to the software without the specific, prior written
  12 .\" permission of Sam Leffler and Silicon Graphics.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
  15 .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  16 .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  17 .\"
  18 .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
  19 .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
  20 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  21 .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  22 .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  23 .\" OF THIS SOFTWARE.
  24 .\"
  25 .if n .po 0
  26 .TH INTRO 3T "August 21, 1997"
  27 .SH NAME
  28 libtiff \- introduction to
  29 .IR libtiff ,
  30 a library for reading and writing
  31 .SM TIFF
  32 files
  33 .SH SYNOPSIS
  34 .B "#include <tiffio.h>"
  35 .br
  36 cc file.c
  37 .B -ltiff
  38 .SH DESCRIPTION
  39 .I libtiff
  40 is a library for reading and writing data files encoded with the
  41 .I "Tag Image File"
  42 format, Revision 6.0 (or revision 5.0 or revision 4.0).
  43 This file format is suitable for archiving multi-color and
  44 monochromatic image data.
  45 .PP
  46 The library supports several compression algorithms, as indicated
  47 by the
  48 .I Compression
  49 field, including:
  50 no compression (1),
  51 .SM CCITT
  52 1D Huffman compression (2),
  53 .SM CCITT
  54 Group 3 Facsimile compression (3),
  55 .SM CCITT
  56 Group 4 Facsimile compression (4),
  57 Lempel-Ziv & Welch compression (5),
  58 baseline JPEG compression (7),
  59 word-aligned 1D Huffman compression (32771),
  60 and
  61 PackBits compression (32773).
  62 In addition, several nonstandard compression algorithms are supported:
  63 the 4-bit compression algorithm used
  64 by the
  65 .I ThunderScan
  66 program (32809) (decompression only),
  67 NeXT's 2-bit compression algorithm (32766) (decompression only),
  68 an experimental LZ-style algorithm known as Deflate (32946), and
  69 an experimental CIE LogLuv compression scheme designed for images
  70 with high dynamic range (32845 for LogL and 32845 for LogLuv).
  71 Directory information may be in either little- or big-endian byte
  72 order\-byte swapping is automatically done by the library.
  73 Data bit ordering may be either Most Significant Bit (\c
  74 .SM MSB\c
  75 ) to Least Significant Bit (\c
  76 .SM LSB\c
  77 ) or
  78 .SM LSB
  79 to
  80 .SM MSB.
  81 Finally, the library does not support files in which the
  82 .IR BitsPerSample ,
  83 .IR Compression ,
  84 .IR MinSampleValue ,
  85 or
  86 .IR MaxSampleValue
  87 fields are defined differently on a per-sample basis
  88 (in Rev. 6.0 the
  89 .I Compression
  90 tag is not defined on a per-sample basis, so this is immaterial).
  91 .SH "DATA TYPES"
  92 The library makes extensive use of C typedefs to promote portability.
  93 Two sets of typedefs are used, one for communication with clients
  94 of the library and one for internal data structures and parsing of the
  95 .SM TIFF
  96 format.
  97 The following typedefs are exposed to users either through
  98 function definitions or through parameters passed through the
  99 varargs interfaces.
 100 .in +.5i
 101 .sp 5p
 102 .ta +\w'typedef unsigned <\fIthing\fP> uint32;    'u
 103 .nf
 104 typedef unsigned short uint16;  16-bit unsigned integer
 105 typedef unsigned <\fIthing\fP> uint32;  32-bit unsigned integer
 106 .sp 5p
 107 typedef unsigned int ttag_t;    directory tag
 108 typedef uint16 tdir_t;  directory index
 109 typedef uint16 tsample_t;       sample number
 110 typedef uint32 tstrip_t;        strip number
 111 typedef uint32 ttile_t; tile number
 112 typedef int32 tsize_t;  i/o size in bytes
 113 typedef void* tdata_t;  image data ref
 114 typedef void* thandle_t;        client data handle
 115 typedef int32 toff_t;   file offset
 116 .fi
 117 .sp 5p
 118 .in -.5i
 119 Note that
 120 .IR tstrip_t ,
 121 .IR ttile_t ,
 122 and
 123 .I tsize_t
 124 are constrained to be no more than 32-bit quantities by
 125 32-bit fields they are stored in in the
 126 .SM TIFF
 127 image.
 128 Likewise
 129 .I tsample_t
 130 is limited by the 16-bit field used to store the
 131 .I SamplesPerPixel
 132 tag.
 133 .I tdir_t
 134 constrains the maximum number of
 135 .SM IFDs
 136 that may appear in an image and may be an arbitrary size (w/o penalty).
 137 .I ttag_t
 138 must be either int, unsigned int, pointer, or double because
 139 the library uses a varargs interface and
 140 .SM "ANSI C"
 141 restricts the type of the parameter before an ellipsis to be a
 142 promoted type.
 143 .I toff_t
 144 is defined as int32 because TIFF file offsets are (unsigned) 32-bit
 145 quantities.
 146 A signed value is used because some interfaces return \-1 on error.
 147 Finally, note that user-specified data references are
 148 passed as opaque handles and only cast at the lowest layers where
 149 their type is presumed.
 150 .SH "LIST OF ROUTINES"
 151 The following routines are part of the library.
 152 Consult specific manual pages for details on their operation.
 153 The manual page names listed below are for systems
 154 where the full function names can not be encoded in the filesystem;
 155 on most systems doing ``man function-name'' will work.
 156 .sp 5p
 157 .nf
 158 .ta \w'TIFFWriteEncodedStrip'u+2n +\w'Appears on Page'u+2n
 159 \fIName\fP      \fIAppears on Page\fP   \fIDescription\fP
 160 .sp 5p
 161 TIFFCheckTile   tile.3t very x,y,z,sample is within image
 162 TIFFClientOpen  open.3t open a file for reading or writing
 163 TIFFClose       close.3t        close an open file
 164 TIFFComputeStrip        strip.3t        return strip containing y,sample
 165 TIFFComputeTile tile.3t return tile containing x,y,z,sample
 166 TIFFCurrentDirectory    query.3t        return index of current directory
 167 TIFFCurrentRow  query.3t        return index of current scanline
 168 TIFFCurrentStrip        query.3t        return index of current strip
 169 TIFFCurrentTile query.3t        return index of current tile
 170 TIFFError       error.3t        library error handler
 171 TIFFFdOpen      open.3t open a file for reading or writing
 172 TIFFFileName    query.3t        return name of open file
 173 TIFFFileno      query.3t        return open file descriptor
 174 TIFFFlush       flush.3t        flush all pending writes
 175 TIFFFlushData   flush.3t        flush pending data writes
 176 TIFFGetBitRevTable      swab.3t return bit reversal table
 177 TIFFGetField    getfield.3t     return tag value in current directory
 178 TIFFGetFieldDefaulted   getfield.3t     return tag value in current directory
 179 TIFFGetMode     query.3t        return open file mode
 180 TIFFGetVersion  query.3t        return library version string
 181 TIFFIsTiled     query.3t        return true if image data is tiled
 182 TIFFIsByteSwapped       query.3t        return true if image data is byte-swapped
 183 TIFFNumberOfStrips      strip.3t        return number of strips in an image
 184 TIFFNumberOfTiles       tile.3t return number of tiles in an image
 185 TIFFOpen        open.3t open a file for reading or writing
 186 TIFFPrintDirectory      print.3t        print description of the current directory
 187 TIFFReadBufferSetup     rdbuf.3t        specify i/o buffer for reading
 188 TIFFReadDirectory       readdir.3t      read the next directory
 189 TIFFReadEncodedStrip    rdestrip.3t     read and decode a strip of data
 190 TIFFReadEncodedTile     rdetile.3t      read and decode a tile of data
 191 TIFFReadRawStrip        rdrstrip.3t     read a raw strip of data
 192 TIFFReadRawTile rdrtile.3t      read a raw tile of data
 193 TIFFReadRGBAImage       rdimage.3t      read an image into a fixed format raster
 194 TIFFReadScanline        readline.3t     read and decode a row of data
 195 TIFFReadTile    readtile.3t     read and decode a tile of data
 196 TIFFReverseBits swab.3t reverse bits in an array of bytes
 197 TIFFRGBAImageBegin      rgbaimage.3t    setup decoder state for TIFFRGBAImageGet
 198 TIFFRGBAImageEnd        rgbaimage.3t    release TIFFRGBAImage decoder state
 199 TIFFRGBAImageGet        rgbaimage.3t    read and decode an image
 200 TIFFRGBAImageOK rgbaimage.3t    is image readable by TIFFRGBAImageGet
 201 TIFFScanlineSize        size.3t return size of a scanline
 202 TIFFSetDirectory        setdir.3t       set the current directory
 203 TIFFSetSubDirectory     setdir.3t       set the current directory
 204 TIFFSetErrorHandler     error.3t        set error handler function
 205 TIFFSetField    setfield.3t     set a tag's value in the current directory
 206 TIFFSetWarningHandler   error.3t        set warning handler function
 207 TIFFStripSize   size.3t return size of a strip
 208 TIFFSwabShort   swab.3t swap bytes of short
 209 TIFFSwabLong    swab.3t swap bytes of long
 210 TIFFSwabArrayOfShort    swab.3t swap bytes of an array of shorts
 211 TIFFSwabArrayOfLong     swab.3t swap bytes of an array of longs
 212 TIFFTileRowSize size.3t return size of a row in a tile
 213 TIFFTileSize    size.3t return size of a tile
 214 TIFFVGetField   getfield.3t     return tag value in current directory
 215 TIFFVGetFieldDefaulted  getfield.3t     return tag value in current directory
 216 TIFFVSetField   setfield.3t     set a tag's value in the current directory
 217 TIFFWarning     warning.3t      library warning handler
 218 TIFFWriteDirectory      writedir.3t     write the current directory
 219 TIFFWriteEncodedStrip   wrestrip.3t     compress and write a strip of data
 220 TIFFWriteEncodedTile    wretile.3t      compress and write a tile of data
 221 TIFFWriteRawStrip       wrrstrip.3t     write a raw strip of data
 222 TIFFWriteRawTile        wrrtile.3t      write a raw tile of data
 223 TIFFWriteScanline       writeline.3t    write a scanline of data
 224 TIFFWriteTile   wrrtile.3t      compress and write a tile of data
 225 .fi
 226 .SH "TAG USAGE"
 227 The table below lists the
 228 .SM TIFF
 229 tags that are recognized and handled by the library.
 230 If no use is indicated in the table, then the library
 231 reads and writes the tag, but does not use it internally.
 232 Note that some tags are meaningful only when a particular
 233 compression scheme is being used; e.g.
 234 .I Group3Options
 235 is only useful if
 236 .I Compression
 237 is set to
 238 .SM CCITT
 239 Group 3 encoding.
 240 Tags of this sort are considered
 241 .I codec-specific
 242 tags and the library does not recognize them except when the
 243 .I Compression
 244 tag has been previously set to the relevant compression scheme.
 245 .sp 5p
 246 .nf
 247 .ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Value'u+2n +\w'R/W'u+2n
 248 \fITag Name\fP  \fIValue\fP     \fIR/W\fP       \fILibrary Use/Notes\fP
 249 .sp 5p
 250 .nf
 251 Artist  315     R/W
 252 BadFaxLines     326     R/W
 253 BitsPerSample   258     R/W     lots
 254 CellLength      265             parsed but ignored
 255 CellWidth       264             parsed but ignored
 256 CleanFaxData    327     R/W
 257 ColorMap        320     R/W
 258 ColorResponseUnit       300             parsed but ignored
 259 Compression     259     R/W     choosing codec
 260 ConsecutiveBadFaxLines  328     R/W
 261 DataType        32996   R       obsoleted by SampleFormat tag
 262 DateTime        306     R/W
 263 DocumentName    269     R/W
 264 DotRange        336     R/W
 265 ExtraSamples    338     R/W     lots
 266 FaxRecvParams   34908   R/W
 267 FaxSubAddress   34909   R/W
 268 FaxRecvTime     34910   R/W
 269 FillOrder       266     R/W     control bit order
 270 FreeByteCounts  289             parsed but ignored
 271 FreeOffsets     288             parsed but ignored
 272 GrayResponseCurve       291             parsed but ignored
 273 GrayResponseUnit        290             parsed but ignored
 274 Group3Options   292     R/W     used by Group 3 codec
 275 Group4Options   293     R/W
 276 HostComputer    316     R/W
 277 ImageDepth      32997   R/W     tile/strip calculations
 278 ImageDescription        270     R/W
 279 ImageLength     257     R/W     lots
 280 ImageWidth      256     R/W     lots
 281 InkNames        333     R/W
 282 InkSet  332     R/W
 283 JPEGTables      347     R/W     used by JPEG codec
 284 Make    271     R/W
 285 Matteing        32995   R       obsoleted by ExtraSamples tag
 286 MaxSampleValue  281     R/W
 287 MinSampleValue  280     R/W
 288 Model   272     R/W
 289 NewSubFileType  254     R/W     called SubFileType in spec
 290 NumberOfInks    334     R/W
 291 Orientation     274     R/W
 292 PageName        285     R/W
 293 PageNumber      297     R/W
 294 PhotometricInterpretation       262     R/W     used by Group 3 and JPEG codecs
 295 PlanarConfiguration     284     R/W     data i/o
 296 Predictor       317     R/W     used by LZW and Deflate codecs
 297 PrimaryChromacities     319     R/W
 298 ReferenceBlackWhite     532     R/W
 299 ResolutionUnit  296     R/W     used by Group 3 codec
 300 RowsPerStrip    278     R/W     data i/o
 301 SampleFormat    339     R/W
 302 SamplesPerPixel 277     R/W     lots
 303 SMinSampleValue 340     R/W
 304 SMaxSampleValue 341     R/W
 305 Software        305     R/W
 306 StoNits 37439   R/W
 307 StripByteCounts 279     R/W     data i/o
 308 StripOffsets    273     R/W     data i/o
 309 SubFileType     255     R/W     called OSubFileType in spec
 310 TargetPrinter   337     R/W
 311 Thresholding    263     R/W
 312 TileByteCounts  324     R/W     data i/o
 313 TileDepth       32998   R/W     tile/strip calculations
 314 TileLength      323     R/W     data i/o
 315 TileOffsets     324     R/W     data i/o
 316 TileWidth       322     R/W     data i/o
 317 TransferFunction        301     R/W
 318 WhitePoint      318     R/W
 319 XPosition       286     R/W
 320 XResolution     282     R/W
 321 YCbCrCoefficients       529     R/W     used by TIFFRGBAImage support
 322 YCbCrPositioning        531     R/W     tile/strip size calulcations
 323 YCbCrSubsampling        530     R/W
 324 YPosition       286     R/W
 325 YResolution     283     R/W     used by Group 3 codec
 326 .SH "PSEUDO TAGS"
 327 In addition to the normal
 328 .SM TIFF
 329 tags the library supports a collection of
 330 tags whose values lie in a range outside the valid range of
 331 .SM TIFF
 332 tags.
 333 These tags are termed
 334 .I pseud-tags
 335 and are used to control various codec-specific functions within the library.
 336 The table below summarizes the defined pseudo-tags.
 337 .sp 5p
 338 .nf
 339 .ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Codec'u+2n +\w'R/W'u+2n
 340 \fITag Name\fP  \fICodec\fP     \fIR/W\fP       \fILibrary Use/Notes\fP
 341 .sp 5p
 342 .nf
 343 TIFFTAG_FAXMODE G3      R/W     general codec operation
 344 TIFFTAG_FAXFILLFUNC     G3/G4   R/W     bitmap fill function
 345 TIFFTAG_JPEGQUALITY     JPEG    R/W     compression quality control
 346 TIFFTAG_JPEGCOLORMODE   JPEG    R/W     control colorspace conversions
 347 TIFFTAG_JPEGTABLESMODE  JPEG    R/W     control contents of \fIJPEGTables\fP tag
 348 TIFFTAG_ZIPQUALITY      Deflate R/W     compression quality level
 349 TIFFTAG_PIXARLOGDATAFMT PixarLog        R/W     user data format
 350 TIFFTAG_PIXARLOGQUALITY PixarLog        R/W     compression quality level
 351 TIFFTAG_SGILOGDATAFMT   SGILog  R/W     user data format
 352 .fi
 353 .TP
 354 .B TIFFTAG_FAXMODE
 355 Control the operation of the Group 3 codec.
 356 Possible values (independent bits that can be combined by
 357 or'ing them together) are:
 358 FAXMODE_CLASSIC
 359 (enable old-style format in which the
 360 .SM RTC
 361 is written at the end of the last strip),
 362 FAXMODE_NORTC
 363 (opposite of
 364 FAXMODE_CLASSIC;
 365 also called
 366 FAXMODE_CLASSF),
 367 FAXMODE_NOEOL
 368 (do not write
 369 .SM EOL
 370 codes at the start of each row of data),
 371 FAXMODE_BYTEALIGN
 372 (align each encoded row to an 8-bit boundary),
 373 FAXMODE_WORDALIGN
 374 (align each encoded row to an 16-bit boundary),
 375 The default value is dependent on the compression scheme; this
 376 pseudo-tag is used by the various G3 and G4 codecs to share code.
 377 .TP
 378 .B TIFFTAG_FAXFILLFUNC
 379 Control the function used to convert arrays of black and white
 380 runs to packed bit arrays.
 381 This hook can be used to image decoded scanlines in multi-bit
 382 depth rasters (e.g. for display in colormap mode)
 383 or for other purposes.
 384 The default value is a pointer to a builtin function that images
 385 packed bilevel data.
 386 .TP
 387 .B TIFFTAG_JPEGQUALITY
 388 Control the compression quality level used in the baseline algorithm.
 389 Note that quality levels are in the range 0-100 with a default value of 75.
 390 .TP
 391 .B TIFFTAG_JPEGCOLORMODE
 392 Control whether or not conversion is done between
 393 RGB and YCbCr colorspaces.
 394 Possible values are:
 395 JPEGCOLORMODE_RAW
 396 (do not convert), and
 397 JPEGCOLORMODE_RGB
 398 (convert to/from RGB)
 399 The default value is JPEGCOLORMODE_RAW.
 400 .TP
 401 .B TIFFTAG_JPEGTABLESMODE
 402 Control the information written in the
 403 .I JPEGTables
 404 tag.
 405 Possible values (independent bits that can be combined by
 406 or'ing them together) are:
 407 JPEGTABLESMODE_QUANT
 408 (include quantization tables),
 409 and
 410 JPEGTABLESMODE_HUFF
 411 (include Huffman encoding tables).
 412 The default value is JPEGTABLESMODE_QUANT|JPEGTABLESMODE_HUFF.
 413 .TP
 414 .B TIFFTAG_ZIPQUALITY
 415 Control the compression technique used by the Deflate codec.
 416 Quality levels are in the range 1-9 with larger numbers yielding better
 417 compression at the cost of more computation.
 418 The default quality level is 6 which yields a good time-space tradeoff.
 419 .TP
 420 .B TIFFTAG_PIXARLOGDATAFMT
 421 Control the format of user data passed
 422 .I in
 423 to the PixarLog codec when encoding and passed
 424 .I out
 425 from when decoding.
 426 Possible values are:
 427 PIXARLOGDATAFMT_8BIT
 428 for 8-bit unsigned pixels,
 429 PIXARLOGDATAFMT_8BITABGR
 430 for 8-bit unsigned ABGR-ordered pixels,
 431 PIXARLOGDATAFMT_11BITLOG
 432 for 11-bit log-encoded raw data,
 433 PIXARLOGDATAFMT_12BITPICIO
 434 for 12-bit PICIO-compatible data,
 435 PIXARLOGDATAFMT_16BIT
 436 for 16-bit signed samples,
 437 and
 438 PIXARLOGDATAFMT_FLOAT
 439 for 32-bit IEEE floating point samples.
 440 .TP
 441 .B TIFFTAG_PIXARLOGQUALITY
 442 Control the compression technique used by the PixarLog codec.
 443 This value is treated identically to TIFFTAG_ZIPQUALITY; see the
 444 above description.
 445 .TP
 446 .B TIFFTAG_SGILOGDATAFMT
 447 Control the format of client data passed
 448 .I in
 449 to the SGILog codec when encoding and passed
 450 .I out
 451 from when decoding.
 452 Possible values are:
 453 SGILOGDATAFMT_FLTXYZ
 454 for converting between LogLuv and 32-bit IEEE floating valued XYZ pixels,
 455 SGILOGDATAFMT_16BITLUV
 456 for 16-bit encoded Luv pixels,
 457 SGILOGDATAFMT_32BITRAW and SGILOGDATAFMT_24BITRAW
 458 for no conversion of data,
 459 SGILOGDATAFMT_8BITRGB
 460 for returning 8-bit RGB data (valid only when decoding LogLuv-encoded data),
 461 SGILOGDATAFMT_FLTY
 462 for converting between LogL and 32-bit IEEE floating valued Y pixels,
 463 SGILOGDATAFMT_16BITL
 464 for 16-bit encoded L pixels,
 465 and
 466 SGILOGDATAFMT_8BITGRY
 467 for returning 8-bit greyscale data
 468 (valid only when decoding LogL-encoded data).
 469 .SH DIAGNOSTICS
 470 All error messages are directed through the
 471 .IR TIFFError
 472 routine.
 473 By default messages are directed to
 474 .B stderr
 475 in the form:
 476 .IR "module: message\en."
 477 Warning messages are likewise directed through the
 478 .IR TIFFWarning
 479 routine.
 480 .SH "SEE ALSO"
 481 .IR fax2tiff (1),
 482 .IR gif2tiff (1),
 483 .IR pal2rgb (1),
 484 .IR ppm2tiff (1),
 485 .IR rgb2ycbcr (1),
 486 .IR ras2tiff (1),
 487 .IR sgi2tiff (1),
 488 .IR tiff2bw (1),
 489 .IR tiffdither (1),
 490 .IR tiffdump (1),
 491 .IR tiffcp (1),
 492 .IR tiffcmp (1),
 493 .IR tiffgt (1),
 494 .IR tiffinfo (1),
 495 .IR tiffmedian (1),
 496 .IR tiffsplit (1),
 497 .IR tiffsv (1),
 498 .PP
 499 .IR "Tag Image File Format Specification \(em Revision 6.0" ,
 500 an Aldus Technical Memorandum.
 501 .PP
 502 .IR "The Spirit of TIFF Class F" ,
 503 an appendix to the TIFF 5.0 specification prepared by Cygnet Technologies.
 504 .SH BUGS
 505 The library does not support multi-sample images
 506 where some samples have different bits/sample.
 507 .PP
 508 The library does not support random access to compressed data
 509 that is organized with more than one row per tile or strip.
 510 The library discards unknown tags.
 511 The library should do more validity checking of a directory's contents.