1 2NOTE: Sept/2004 3 4The following described approach to managing tag extensions has been 5mostly superceeded since libtiff 3.6.0. The described approach requires 6internal knowledge of the libtiff API and tends to be very fragile 7in the face of libtiff upgrades. 8 9Please read over the html/addingtags.html in preference to the below 10described approach. 11 12 13 14================================== 15 16Client module for adding to LIBTIFF tagset 17------------------------------------------- 18 Author: Niles Ritter 19 20 21 22 23In the past, users of the "libtiff" package had to modify the 24source code of the library if they required additional private tags 25or codes not recognized by libtiff. Thus, whenever 26a new revision of libtiff came out the client would have to 27perform modifications to six or seven different files to re-install 28their tags. 29 30The latest versions of libtiff now provide client software new routines, 31giving them the opportunity to install private extensions at runtime, 32rather than compile-time. This means that the client may encapsulate 33all of their private tags into a separate module, which need only 34be recompiled when new versions of libtiff are released; no manual 35editing of files is required. 36 37How it works 38------------ 39 40The mechanism for overriding the tag access has been enabled with 41a single new routine, which has the following calling sequence: 42 43 TIFFExtendProc old_extender; 44 45 old_extender = TIFFSetTagExtender(tag_extender); 46 47which must be called prior to opening or creating TIFF files. 48 49This routine sets a static pointer to the user-specified function 50<tag_extender>, which in turn is called by TIFFDefaultDirectory(), 51just after the usual TIFFSetField() and TIFFGetField() methods 52are defined, and just before the compression tag is set. It also 53returns a pointer to the previously-defined value of the tag-extender, 54so that multiple clients may be installed. 55 56The TIFFExtendProc method that you define should be used to override 57the TIFF file's "vsetfield" and "vgetfield" methods, so that you 58can trap your new, private tags, and install their values into 59a private directory structure. For your convienience, a new pointer 60has also been added to the "TIFF" file structure: 61 62 tidata_t tif_clientdir; /* client TIFF directory */ 63 64into which you may install whatever private directory structures you like. 65You should also override the tag-printing method from within your 66"vsetfield" method, to permit the symbolic printing of your new tags. 67 68 69Example Client Code: 70-------------------- 71 72An example module has been provided as a template for installing 73your own tags into a client tag extender. The module is called 74"xtif_dir.c", and defines all of the interface routines, tag field 75access, tag printing, etc. for most purpose. 76 77To see how the client module operates, there are three "fake" 78tags currently installed. If you use the existing makefile you can 79build them with: 80 81 make all -f Makefile.gcc !or Makefile.mpw 82 maketif 83 listtif 84 85This will build two example programs called "maketif" and "listtif" 86and then run them. These programs do nothing more than create a small 87file called "newtif.tif", install the fake tags, and then list them out 88using TIFFPrintDirectory(). 89 90Installing Private Tags 91----------------------- 92 93To use this module for installing your own tags, edit each of the files 94 95 xtif_dir.c 96 xtiffio.h 97 xtiffiop.h 98 99and search for the string "XXX". At these locations the comments 100will direct you how to install your own tag values, define their 101types, etc. Three examples tags are currently installed, demonstrating 102how to implement multi-valued tags, single-valued tags, and ASCII tags. 103The examples are not valid, registered tags, so you must replace them with 104your own. 105 106To test the routines, also edit the test programs "maketif.c" and 107"listtif.c" and replace the portions of the code that set the 108private tag values and list them. 109 110Once you have edited these files, you may build the client module 111with the Makefile provided, and run the test programs. 112 113To use these files in your own code, the "xtif_dir.c" module defines 114replacement routines for the standard "TIFFOpen()" "TIFFFdOpen", 115and "TIFFClose()" routines, called XTIFFOpen, XTIFFFdOpen and XTIFFClose. 116You must use these routines in order to have the extended tag handlers 117installed. Once installed, the standard TIFFGetField() and TIFFSetField 118routines may be used as before. 119 120Adding Extended Tags to "tools" 121------------------------------- 122To create an extended-tag savvy "tiffinfo" program or other utility, you may 123simply recompile and link the tools to your "libxtiff" library, adding 124 125 -DTIFFOpen=XTIFFOpen -DTIFFClose=XTIFFClose -DTIFFFdOpen=XTIFFFdOpen 126 127to the compile statement. 128 129Bugs, Comments Etc: 130------------------ 131 Send all reports and suggestions to ndr@tazboy.jpl.nasa.gov 132 (Niles Ritter). 133