NOTE: Sept/2004

The following described approach to managing tag extensions has been

mostly superseded since libtiff 3.6.0. The described approach requires

internal knowledge of the libtiff API and tends to be very fragile

in the face of libtiff upgrades.

Please read over the html/addingtags.html in preference to the below

described approach.

==================================

Client module for adding to LIBTIFF tagset

-------------------------------------------

Author: Niles Ritter

In the past, users of the "libtiff" package had to modify the

source code of the library if they required additional private tags

or codes not recognized by libtiff. Thus, whenever

a new revision of libtiff came out the client would have to

perform modifications to six or seven different files to re-install

their tags.

The latest versions of libtiff now provide client software new routines,

giving them the opportunity to install private extensions at runtime,

rather than compile-time. This means that the client may encapsulate

all of their private tags into a separate module, which need only

be recompiled when new versions of libtiff are released; no manual

editing of files is required.

How it works

------------

The mechanism for overriding the tag access has been enabled with

a single new routine, which has the following calling sequence:

TIFFExtendProc old_extender;

old_extender = TIFFSetTagExtender(tag_extender);

which must be called prior to opening or creating TIFF files.

This routine sets a static pointer to the user-specified function

<tag_extender>, which in turn is called by TIFFDefaultDirectory(),

just after the usual TIFFSetField() and TIFFGetField() methods

are defined, and just before the compression tag is set. It also

returns a pointer to the previously-defined value of the tag-extender,

so that multiple clients may be installed.

The TIFFExtendProc method that you define should be used to override

the TIFF file's "vsetfield" and "vgetfield" methods, so that you

can trap your new, private tags, and install their values into

a private directory structure. For your convienience, a new pointer

has also been added to the "TIFF" file structure:

tidata_t tif_clientdir; /* client TIFF directory */

into which you may install whatever private directory structures you like.

You should also override the tag-printing method from within your

"vsetfield" method, to permit the symbolic printing of your new tags.

Example Client Code:

--------------------

An example module has been provided as a template for installing

your own tags into a client tag extender. The module is called

"xtif_dir.c", and defines all of the interface routines, tag field

access, tag printing, etc. for most purpose.

To see how the client module operates, there are three "fake"

tags currently installed. If you use the existing makefile you can

build them with:

make all -f Makefile.gcc !or Makefile.mpw

maketif

listtif

This will build two example programs called "maketif" and "listtif"

and then run them. These programs do nothing more than create a small

file called "newtif.tif", install the fake tags, and then list them out

using TIFFPrintDirectory().

Installing Private Tags

-----------------------

To use this module for installing your own tags, edit each of the files

xtif_dir.c

xtiffio.h

xtiffiop.h

and search for the string "XXX". At these locations the comments

will direct you how to install your own tag values, define their

types, etc. Three examples tags are currently installed, demonstrating

how to implement multi-valued tags, single-valued tags, and ASCII tags.

The examples are not valid, registered tags, so you must replace them with

your own.

To test the routines, also edit the test programs "maketif.c" and

"listtif.c" and replace the portions of the code that set the

private tag values and list them.

Once you have edited these files, you may build the client module

with the Makefile provided, and run the test programs.

To use these files in your own code, the "xtif_dir.c" module defines

replacement routines for the standard "TIFFOpen()" "TIFFFdOpen",

and "TIFFClose()" routines, called XTIFFOpen, XTIFFFdOpen and XTIFFClose.

You must use these routines in order to have the extended tag handlers

installed. Once installed, the standard TIFFGetField() and TIFFSetField

routines may be used as before.

Adding Extended Tags to "tools"

-------------------------------

To create an extended-tag savvy "tiffinfo" program or other utility, you may

simply recompile and link the tools to your "libxtiff" library, adding

-DTIFFOpen=XTIFFOpen -DTIFFClose=XTIFFClose -DTIFFFdOpen=XTIFFFdOpen

to the compile statement.

Bugs, Comments Etc:

------------------

Send all reports and suggestions to ndr@tazboy.jpl.nasa.gov

(Niles Ritter).