4
Modifying The TIFF Library
8
<FONT FACE="Arial, Helvetica, Sans">
11
Defining New TIFF Tags
14
Libtiff has built-in knowledge of all the standard TIFF tags, as
15
well as extentions. The following describes how to add knowledge of
16
new tags as builtins to libtiff, or how to application specific tags can
17
be used by applications without modifying libtiff.
20
<h2>TIFFFieldInfo</h2>
22
How libtiff manages specific tags is primarily controlled by the
23
definition for that tag value stored internally as a TIFFFieldInfo structure.
24
This structure looks like this:
29
ttag_t field_tag; /* field's tag */
30
short field_readcount; /* read count/TIFF_VARIABLE/TIFF_SPP */
31
short field_writecount; /* write count/TIFF_VARIABLE */
32
TIFFDataType field_type; /* type of associated data */
33
unsigned short field_bit; /* bit in fieldsset bit vector */
34
unsigned char field_oktochange;/* if true, can change while writing */
35
unsigned char field_passcount;/* if true, pass dir count on set */
36
char *field_name; /* ASCII name */
41
<li> <b>field_tag</b>: the tag number. For instance 277 for the
42
SamplesPerPixel tag. Builtin tags will generally have a #define in
43
tiff.h for each known tag. <p>
45
<li> <b>field_readcount</b>: The number of values which should be read.
46
The special value TIFF_VARIABLE (-1) indicates that a variable number of
47
values may be read. The special value TIFFTAG_SPP (-2) indicates that there
48
should be one value for each sample as defined by TIFFTAG_SAMPLESPERPIXEL.
49
The special value TIFF_VARIABLE2 (-3) is presumably similar to TIFF_VARIABLE
50
though I am not sure what the distinction in behaviour is. This field
51
is TIFF_VARIABLE for variable length ascii fields.<p>
53
<li> <b>field_writecount</b>: The number of values which should be written.
54
Generally the same as field_readcount. A few built-in exceptions exist, but
55
I haven't analysed why they differ. <p>
57
<li> <b>field_type</b>: Type of the field. One of TIFF_BYTE, TIFF_ASCII,
58
TIFF_SHORT, TIFF_LONG, TIFF_RATIONAL, TIFF_SBYTE, TIFF_UNDEFINED,
59
TIFF_SSHORT, TIFF_SLONG, TIFF_SRATIONAL, TIFF_FLOAT, TIFF_DOUBLE or
60
TIFF_IFD. Note that some fields can support more than one type (for
61
instance short and long). These fields should have multiple TIFFFieldInfos.
64
<li> <b>field_bit</b>: Built-in tags stored in special fields in the
65
TIFF structure have assigned field numbers to distinguish them (ie.
66
FIELD_SAMPLESPERPIXEL). New tags should generally just use
67
FIELD_CUSTOM indicating they are stored in the generic tag list.<p>
69
<li> <b>field_oktochange</b>: TRUE if it is OK to change this tag value
70
while an image is being written. FALSE for stuff that must be set once
71
and then left unchanged (like ImageWidth, or PhotometricInterpretation for
74
<li> <b>field_passcount</b>: If TRUE, then the count value must be passed
75
in TIFFSetField(), and TIFFGetField(), otherwise the count is not required.
76
This should generally be TRUE for non-ascii variable count tags unless
77
the count is implicit (such as with the colormap).<p>
79
<li> <b>field_name</b>: A name for the tag. Normally mixed case (studly caps)
80
like "StripByteCounts" and relatively short. <p>
84
A TIFFFieldInfo definition exists for each built-in tag in the tif_dirinfo.c
85
file. Some tags which support multiple data types have more than one
86
definition, one per data type supported. <p>
88
Various functions exist for getting the internal TIFFFieldInfo definitions,
89
including _TIFFFindFieldInfo(), and _TIFFFindFieldInfoByName(). See
90
tif_dirinfo.c for details. There must be some mechanism to get the whole
91
list, though I don't see it off hand.<p>
93
<h2>Default Tag Auto-registration</h2>
95
In libtiff 3.6.0 a new mechanism was introduced allowing libtiff to
96
read unrecognised tags automatically. When an unknown tags is encountered,
97
it is automatically internally defined with a default name and a type
98
derived from the tag value in the file. Applications only need to predefine
99
application specific tags if they need to be able to set them in a file, or
100
if particular calling conventions are desired for TIFFSetField() and
103
When tags are autodefined like this the <b>field_readcount</b> and
104
<b>field_writecount</b> values are always TIFF_VARIABLE. The
105
<b>field_passcount</b> is always TRUE, and the <b>field_bit</b> is
106
FIELD_CUSTOM. The field name will be "Tag %d" where the %d is the tag
109
<h2>Defining Application Tags</h2>
111
For various reasons, it is common for applications to want to define
112
their own tags to store information outside the core TIFF specification.
113
This is done by calling TIFFMergeFieldInfo() with one or more TIFFFieldInfos.
116
The libgeotiff library provides geospatial information extentions within
117
a TIFF file. First, a set of TIFFFieldInfo's is prepared with information
121
static const TIFFFieldInfo xtiffFieldInfo[] = {
123
/* XXX Insert Your tags here */
124
{ TIFFTAG_GEOPIXELSCALE, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
125
TRUE, TRUE, "GeoPixelScale" },
126
{ TIFFTAG_GEOTRANSMATRIX, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
127
TRUE, TRUE, "GeoTransformationMatrix" },
128
{ TIFFTAG_GEOTIEPOINTS, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
129
TRUE, TRUE, "GeoTiePoints" },
130
{ TIFFTAG_GEOKEYDIRECTORY, -1,-1, TIFF_SHORT, FIELD_CUSTOM,
131
TRUE, TRUE, "GeoKeyDirectory" },
132
{ TIFFTAG_GEODOUBLEPARAMS, -1,-1, TIFF_DOUBLE, FIELD_CUSTOM,
133
TRUE, TRUE, "GeoDoubleParams" },
134
{ TIFFTAG_GEOASCIIPARAMS, -1,-1, TIFF_ASCII, FIELD_CUSTOM,
135
TRUE, FALSE, "GeoASCIIParams" }
139
In order to define the tags, we call TIFFMergeFieldInfo() on the
140
desired TIFF handle with the list of TIFFFieldInfos.<p>
143
#define N(a) (sizeof (a) / sizeof (a[0]))
145
/* Install the extended Tag field info */
146
TIFFMergeFieldInfo(tif, xtiffFieldInfo, N(xtiffFieldInfo));
149
The tags need to be defined for each TIFF file opened - and when reading
150
they should be defined before the tags of the file are read, yet a valid
151
TIFF * is needed to merge the tags against. In order to get them
152
registered at the appropriate part of the setup process, it is necessary
153
to register our merge function as an extender callback with libtiff.
154
This is done with TIFFSetTagExtender(). We also keep track of the
155
previous tag extender (if any) so that we can call it from our extender
156
allowing a chain of customizations to take effect. <P>
159
static TIFFExtendProc _ParentExtender = NULL;
162
void _XTIFFInitialize(void)
164
static int first_time=1;
166
if (! first_time) return; /* Been there. Done that. */
169
/* Grab the inherited method and install */
170
_ParentExtender = TIFFSetTagExtender(_XTIFFDefaultDirectory);
174
The extender callback is looks like this. It merges in our new fields
175
and then calls the next extender if there is one in effect.<p>
179
_XTIFFDefaultDirectory(TIFF *tif)
181
/* Install the extended Tag field info */
182
TIFFMergeFieldInfo(tif, xtiffFieldInfo, N(xtiffFieldInfo));
184
/* Since an XTIFF client module may have overridden
185
* the default directory method, we call it now to
186
* allow it to set up the rest of its own methods.
190
(*_ParentExtender)(tif);
194
The above approach ensures that our new definitions are used when reading
195
or writing any TIFF file. However, since on reading we already have
196
default definitions for tags, it is usually not critical to pre-define them.
197
If tag definitions are only required for writing custom tags, you can just
198
call TIFFMergeFieldInfo() before setting new tags. The whole extender
199
architecture can then be avoided.<p>
201
<A NAME=AddingTags><P><H2>Adding New Builtin Tags</H2></A>
203
A similar approach is taken to the above. However, the TIFFFieldInfo
204
should be added to the tiffFieldInfo[] list in tif_dirinfo.c. Ensure that
205
new tags are added in sorted order by the tag number.<p>
207
Normally new built-in tags should be defined with FIELD_CUSTOM; however, if
208
it is desirable for the tag value to have it's own field in the TIFFDirectory
209
structure, then you will need to #define a new FIELD_ value for it, and
210
add appropriate handling as follows:
214
<LI>Define the tag in <B>tiff.h</B>.
215
<LI>Add a field to the directory structure in <B>tif_dir.h</B>
216
and define a <TT>FIELD_*</TT> bit (also update the definition of
217
<TT>FIELD_CODEC</TT> to reflect your addition).
218
<LI>Add an entry in the <TT>TIFFFieldInfo</TT> array defined at the top of
219
<B>tif_dirinfo.c</B>.
220
Note that you must keep this array sorted by tag
221
number and that the widest variant entry for a tag should come
222
first (e.g. <TT>LONG</TT> before <TT>SHORT</TT>).
223
<LI>Add entries in <TT>_TIFFVSetField()</TT> and <TT>_TIFFVGetField()</TT>
225
<LI>(<I>optional</I>) If the value associated with the tag is not a scalar value
226
(e.g. the array for <TT>TransferFunction</TT>) and requires
228
then add the appropriate code to <TT>TIFFReadDirectory()</TT> and
229
<TT>TIFFWriteDirectory()</TT>. You're best off finding a similar tag and
231
<LI>Add support to <TT>TIFFPrintDirectory()</TT> in <B>tif_print.c</B>
232
to print the tag's value.
236
If you want to maintain portability, beware of making assumptions
237
about data types. Use the typedefs (<TT>uint16</TT>, etc. when dealing with
238
data on disk and <TT>t*_t</TT> when stuff is in memory) and be careful about
239
passing items through printf or similar vararg interfaces.
241
<A NAME=AddingCODECTags><P><H2>Adding New Codec-private Tags</H2></A>
243
To add tags that are meaningful <EM>only when a particular compression
244
algorithm is used</EM> follow these steps:
247
<LI>Define the tag in <B>tiff.h</B>.
248
<LI>Allocate storage for the tag values in the private state block of
250
<LI>Insure the state block is created when the codec is initialized.
251
<LI>At <TT>TIFFInitfoo</TT> time override the method pointers in the
253
for getting, setting and printing tag values. For example,
255
sp->vgetparent = tif->tif_vgetfield;
256
tif->tif_vgetfield = fooVGetField; /* hook for codec tags */
257
sp->vsetparent = tif->tif_vsetfield;
258
tif->tif_vsetfield = fooVSetField; /* hook for codec tags */
259
tif->tif_printdir = fooPrintDir; /* hook for codec tags */
261
(Actually you may decide not to override the
262
<TT>tif_printdir</TT> method, but rather just specify it).
263
<LI>Create a private <TT>TIFFFieldInfo</TT> array for your tags and
264
merge them into the core tags at initialization time using
265
<TT>_TIFFMergeFieldInfo</TT>; e.g.
267
_TIFFMergeFieldInfo(tif, fooFieldInfo, N(fooFieldInfo));
269
(where <TT>N</TT> is a macro used liberaly throughout the distributed code).
270
<LI>Fill in the get and set routines. Be sure to call the parent method
271
for tags that you are not handled directly. Also be sure to set the
272
<TT>FIELD_*</TT> bits for tags that are to be written to the file. Note that
273
you can create ``pseudo-tags'' by defining tags that are processed
274
exclusively in the get/set routines and never written to file (see
275
the handling of <TT>TIFFTAG_FAXMODE</TT> in <B>tif_fax3.c</B>
276
for an example of this).
277
<LI>Fill in the print routine, if appropriate.
280
Note that space has been allocated in the <TT>FIELD_*</TT> bit space for
281
codec-private tags. Define your bits as <TT>FIELD_CODEC+<offset></TT> to
282
keep them away from the core tags. If you need more tags than there
283
is room for, just increase <TT>FIELD_SETLONGS</TT> at the top of
288
Last updated: $Date: 2004/09/10 14:43:18 $
added
removed
html/addingtags.html
