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