]> git.saurik.com Git - wxWidgets.git/blob - src/tiff/man/TIFFGetField.3tiff
Remove all lines containing cvs/svn "$Id$" keyword.
[wxWidgets.git] / src / tiff / man / TIFFGetField.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 TIFFGetField 3TIFF "March 18, 2005" "libtiff"
26 .SH NAME
27 TIFFGetField, TIFFVGetField \- get the value(s) of a tag in an open
28 .SM TIFF
29 file
30 .SH SYNOPSIS
31 .B "#include <tiffio.h>"
32 .sp
33 .BI "int TIFFGetField(TIFF *" tif ", ttag_t " tag ", " ... ")"
34 .sp
35 .B "#include <stdarg.h>"
36 .sp
37 .BI "int TIFFVGetField(TIFF *" tif ", ttag_t " tag ", va_list " ap ")"
38 .br
39 .BI "int TIFFGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", " ... ")"
40 .br
41 .BI "int TIFFVGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", va_list " ap ")"
42 .SH DESCRIPTION
43 .IR TIFFGetField
44 returns the value of a tag or pseudo-tag associated with the the current
45 directory of the opened
46 .SM TIFF
47 file
48 .IR tif .
49 (A
50 .I pseudo-tag
51 is a parameter that is used to control the operation of the
52 .SM TIFF
53 library but whose value is not read or written to the underlying file.) The
54 file must have been previously opened with
55 .IR TIFFOpen (3TIFF).
56 The tag is identified by
57 .IR tag ,
58 one of the values defined in the include file
59 .B tiff.h
60 (see also the table below). The type and number of values returned is
61 dependent on the tag being requested. The programming interface uses a
62 variable argument list as prescribed by the
63 .IR stdarg (3)
64 interface. The returned values should only be interpreted if
65 .IR TIFFGetField
66 returns 1.
67 .PP
68 .IR TIFFVGetField
69 is functionally equivalent to
70 .IR TIFFGetField
71 except that it takes a pointer to a variable argument list.
72 .I TIFFVGetField
73 is useful for layering interfaces on top of the functionality provided by
74 .IR TIFFGetField .
75 .PP
76 .IR TIFFGetFieldDefaulted
77 and
78 .IR TIFFVGetFieldDefaulted
79 are identical to
80 .IR TIFFGetField
81 and
82 .IR TIFFVGetField ,
83 except that if a tag is not defined in the current directory and it has a
84 default value, then the default value is returned.
85 .PP
86 The tags understood by
87 .IR libtiff(3TIFF),
88 the number of parameter values, and the types for the returned values are
89 shown below. The data types are specified as in C and correspond to the types
90 used to specify tag values to
91 .IR TIFFSetField (3TIFF).
92 Remember that
93 .IR TIFFGetField
94 returns parameter values, so all the listed data types are pointers to storage
95 where values should be returned.
96 Consult the
97 .SM TIFF
98 specification (or relevant industry specification) for information on the
99 meaning of each tag and their possible values.
100 .PP
101 .nf
102 .ta \w'TIFFTAG_CONSECUTIVEBADFAXLINES'u+2n +\w'Count'u+2n +\w'TIFFFaxFillFunc*'u+2n
103 \fITag Name\fP \fICount\fP \fITypes\fP \fINotes\fP
104 .sp 5p
105 TIFFTAG_ARTIST 1 char**
106 TIFFTAG_BADFAXLINES 1 uint32*
107 TIFFTAG_BITSPERSAMPLE 1 uint16*
108 TIFFTAG_CLEANFAXDATA 1 uint16*
109 TIFFTAG_COLORMAP 3 uint16** 1<<BitsPerSample arrays
110 TIFFTAG_COMPRESSION 1 uint16*
111 TIFFTAG_CONSECUTIVEBADFAXLINES 1 uint32*
112 TIFFTAG_COPYRIGHT 1 char**
113 TIFFTAG_DATATYPE 1 uint16*
114 TIFFTAG_DATETIME 1 char**
115 TIFFTAG_DOCUMENTNAME 1 char**
116 TIFFTAG_DOTRANGE 2 uint16*
117 TIFFTAG_EXTRASAMPLES 2 uint16*,uint16** count & types array
118 TIFFTAG_FAXFILLFUNC 1 TIFFFaxFillFunc* G3/G4 compression pseudo-tag
119 TIFFTAG_FAXMODE 1 int* G3/G4 compression pseudo-tag
120 TIFFTAG_FILLORDER 1 uint16*
121 TIFFTAG_GROUP3OPTIONS 1 uint32*
122 TIFFTAG_GROUP4OPTIONS 1 uint32*
123 TIFFTAG_HALFTONEHINTS 2 uint16*
124 TIFFTAG_HOSTCOMPUTER 1 char**
125 TIFFTAG_ICCPROFILE 2 uint32*,void** count, profile data
126 TIFFTAG_IMAGEDEPTH 1 uint32*
127 TIFFTAG_IMAGEDESCRIPTION 1 char**
128 TIFFTAG_IMAGELENGTH 1 uint32*
129 TIFFTAG_IMAGEWIDTH 1 uint32*
130 TIFFTAG_INKNAMES 1 char**
131 TIFFTAG_INKSET 1 uint16*
132 TIFFTAG_JPEGCOLORMODE 1 int* JPEG pseudo-tag
133 TIFFTAG_JPEGQUALITY 1 int* JPEG pseudo-tag
134 TIFFTAG_JPEGTABLES 2 uint32*,void** count & tables
135 TIFFTAG_JPEGTABLESMODE 1 int* JPEG pseudo-tag
136 TIFFTAG_MAKE 1 char**
137 TIFFTAG_MATTEING 1 uint16*
138 TIFFTAG_MAXSAMPLEVALUE 1 uint16*
139 TIFFTAG_MINSAMPLEVALUE 1 uint16*
140 TIFFTAG_MODEL 1 char**
141 TIFFTAG_ORIENTATION 1 uint16*
142 TIFFTAG_PAGENAME 1 char**
143 TIFFTAG_PAGENUMBER 2 uint16*
144 TIFFTAG_PHOTOMETRIC 1 uint16*
145 TIFFTAG_PHOTOSHOP 2 uint32*,void** count, data
146 TIFFTAG_PLANARCONFIG 1 uint16*
147 TIFFTAG_PREDICTOR 1 uint16*
148 TIFFTAG_PRIMARYCHROMATICITIES 1 float** 6-entry array
149 TIFFTAG_REFERENCEBLACKWHITE 1 float** 6-entry array
150 TIFFTAG_RESOLUTIONUNIT 1 uint16*
151 TIFFTAG_RICHTIFFIPTC 2 uint32*,void** count, data
152 TIFFTAG_ROWSPERSTRIP 1 uint32*
153 TIFFTAG_SAMPLEFORMAT 1 uint16*
154 TIFFTAG_SAMPLESPERPIXEL 1 uint16*
155 TIFFTAG_SMAXSAMPLEVALUE 1 double*
156 TIFFTAG_SMINSAMPLEVALUE 1 double*
157 TIFFTAG_SOFTWARE 1 char**
158 TIFFTAG_STONITS 1 double**
159 TIFFTAG_STRIPBYTECOUNTS 1 uint32**
160 TIFFTAG_STRIPOFFSETS 1 uint32**
161 TIFFTAG_SUBFILETYPE 1 uint32*
162 TIFFTAG_SUBIFD 2 uint16*,uint32** count & offsets array
163 TIFFTAG_TARGETPRINTER 1 char**
164 TIFFTAG_THRESHHOLDING 1 uint16*
165 TIFFTAG_TILEBYTECOUNTS 1 uint32**
166 TIFFTAG_TILEDEPTH 1 uint32*
167 TIFFTAG_TILELENGTH 1 uint32*
168 TIFFTAG_TILEOFFSETS 1 uint32**
169 TIFFTAG_TILEWIDTH 1 uint32*
170 TIFFTAG_TRANSFERFUNCTION 1 or 3\(dg uint16**1<<BitsPerSample entry arrays
171 TIFFTAG_WHITEPOINT 1 float** 2-entry array
172 TIFFTAG_XMLPACKET 2 uint32*,void** count, data
173 TIFFTAG_XPOSITION 1 float*
174 TIFFTAG_XRESOLUTION 1 float*
175 TIFFTAG_YCBCRCOEFFICIENTS 1 float** 3-entry array
176 TIFFTAG_YCBCRPOSITIONING 1 uint16*
177 TIFFTAG_YCBCRSUBSAMPLING 2 uint16*
178 TIFFTAG_YPOSITION 1 float*
179 TIFFTAG_YRESOLUTION 1 float*\(dd
180 .fi
181 \(dg If
182 .I SamplesPerPixel
183 is one, then a single array is returned; otherwise three arrays are returned.
184 .fi
185 \(dd The contents of this field are quite complex. See
186 .IR "The ICC Profile Format Specification" ,
187 Annex B.3 "Embedding ICC Profiles in TIFF Files" (available at
188 http://www.color.org) for an explanation.
189 .SH AUTOREGISTERED TAGS
190 If you can't find the tag in the table above that means this is an unsupported
191 tag and is not directly supported by
192 .BR libtiff(3TIFF)
193 library. You will still be able to read it's value if you know the data type of
194 that tag. For example, if you want to read the LONG value from the tag 33424
195 and ASCII string from the tag 36867 you can use the following code:
196 .PP
197 .RS
198 .nf
199 uint32 count;
200 void *data;
201
202 TIFFGetField(tiff, 33424, &count, &data);
203 printf("Tag %d: %d, count %d\n", 33424, *(uint32 *)data, count);
204 TIFFGetField(tiff, 36867, &count, &data);
205 printf("Tag %d: %s, count %d\n", 36867, (char *)data, count);
206 .fi
207 .RE
208 .PP
209 .SH RETURN VALUES
210 1 is returned if the tag is defined in the current directory; otherwise a 0 is
211 returned.
212 .SH DIAGNOSTICS
213 All error messages are directed to the
214 .BR TIFFError (3TIFF)
215 routine.
216 .PP
217 .BR "Unknown field, tag 0x%x" .
218 An unknown tag was supplied.
219 .SH "SEE ALSO"
220 .BR TIFFOpen (3TIFF),
221 .BR TIFFSetField (3TIFF),
222 .BR TIFFSetDirectory (3TIFF),
223 .BR TIFFReadDirectory (3TIFF),
224 .BR TIFFWriteDirectory (3TIFF)
225 .BR libtiff (3TIFF),
226 .PP
227 Libtiff library home page:
228 .BR http://www.remotesensing.org/libtiff/