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