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