src/tiff/contrib/tags/README

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