src/tiff/html/addingtags.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>
   4 Modifying The TIFF Library
   5 </TITLE>
   6 </HEAD>
   7 <BODY BGCOLOR=white>
   8 <FONT FACE="Arial, Helvetica, Sans">
   9
  10 <H1>
  11 Defining New TIFF Tags
  12 </H1>
  13
  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.
  18 <p>
  19
  20 <h2>TIFFFieldInfo</h2>
  21
  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:
  25 <p>
  26
  27 <pre>
  28 typedef struct {
  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 */
  37 } TIFFFieldInfo;
  38 </pre>
  39
  40 <ul>
  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>
  44
  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>
  52
  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>
  56
  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.
  62 <p>
  63
  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>
  68
  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
  72 instance).<p>
  73
  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>
  78
  79 <li> <b>field_name</b>: A name for the tag.  Normally mixed case (studly caps)
  80 like "StripByteCounts" and relatively short. <p>
  81
  82 </ul>
  83
  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>
  87
  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>
  92
  93 <h2>Default Tag Auto-registration</h2>
  94
  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
 101 TIFFGetField().<p>
 102
 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
 107 number.<p>
 108
 109 <h2>Defining Application Tags</h2>
 110
 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.
 114 <p>
 115
 116 The libgeotiff library provides geospatial information extentions within
 117 a TIFF file.  First, a set of TIFFFieldInfo's is prepared with information
 118 on the new tags:<p>
 119
 120 <pre>
 121 static const TIFFFieldInfo xtiffFieldInfo[] = {
 122
 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" }
 136 };
 137 </pre>
 138
 139 In order to define the tags, we call TIFFMergeFieldInfo() on the
 140 desired TIFF handle with the list of TIFFFieldInfos.<p>
 141
 142 <pre>
 143 #define N(a)    (sizeof (a) / sizeof (a[0]))
 144
 145     /* Install the extended Tag field info */
 146     TIFFMergeFieldInfo(tif, xtiffFieldInfo, N(xtiffFieldInfo));
 147 </pre>
 148
 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>
 157
 158 <pre>
 159 static TIFFExtendProc _ParentExtender = NULL;
 160
 161 static
 162 void _XTIFFInitialize(void)
 163 {
 164     static int first_time=1;
 165
 166     if (! first_time) return; /* Been there. Done that. */
 167     first_time = 0;
 168
 169     /* Grab the inherited method and install */
 170     _ParentExtender = TIFFSetTagExtender(_XTIFFDefaultDirectory);
 171 }
 172 </pre>
 173
 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>
 176
 177 <pre>
 178 static void
 179 _XTIFFDefaultDirectory(TIFF *tif)
 180 {
 181     /* Install the extended Tag field info */
 182     TIFFMergeFieldInfo(tif, xtiffFieldInfo, N(xtiffFieldInfo));
 183
 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.
 187      */
 188
 189     if (_ParentExtender)
 190         (*_ParentExtender)(tif);
 191 }
 192 </pre>
 193
 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>
 200
 201 <A NAME=AddingTags><P><H2>Adding New Builtin Tags</H2></A>
 202
 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>
 206
 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:
 211
 212
 213 <OL>
 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>
 224    for the new tag.
 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
 227    special processing,
 228    then add the appropriate code to <TT>TIFFReadDirectory()</TT> and
 229    <TT>TIFFWriteDirectory()</TT>.  You're best off finding a similar tag and
 230    cribbing code.
 231 <LI>Add support to <TT>TIFFPrintDirectory()</TT> in <B>tif_print.c</B>
 232     to print the tag's value.
 233 </OL>
 234
 235 <P>
 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.
 240
 241 <A NAME=AddingCODECTags><P><H2>Adding New Codec-private Tags</H2></A>
 242
 243 To add tags that are meaningful <EM>only when a particular compression
 244 algorithm is used</EM> follow these steps:
 245
 246 <OL>
 247 <LI>Define the tag in <B>tiff.h</B>.
 248 <LI>Allocate storage for the tag values in the private state block of
 249    the codec.
 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
 252     TIFF structure
 253    for getting, setting and printing tag values.  For example,
 254 <PRE>
 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 */
 260 </PRE>
 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.
 266 <PRE>
 267     _TIFFMergeFieldInfo(tif, fooFieldInfo, N(fooFieldInfo));
 268 </PRE>
 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.
 278 </OL>
 279
 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+&lt;offset&gt;</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
 284 <B>tiffiop.h</B>.
 285
 286 <HR>
 287
 288 Last updated: $Date: 2004/09/10 14:43:18 $
 289
 290 </BODY>
 291
 292 </HTML>