|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
NOTE: Sept/2004
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
The following described approach to managing tag extensions has been
|
|
Packit |
7838c8 |
mostly superceeded since libtiff 3.6.0. The described approach requires
|
|
Packit |
7838c8 |
internal knowledge of the libtiff API and tends to be very fragile
|
|
Packit |
7838c8 |
in the face of libtiff upgrades.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
Please read over the html/addingtags.html in preference to the below
|
|
Packit |
7838c8 |
described approach.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
==================================
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
Client module for adding to LIBTIFF tagset
|
|
Packit |
7838c8 |
-------------------------------------------
|
|
Packit |
7838c8 |
Author: Niles Ritter
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
In the past, users of the "libtiff" package had to modify the
|
|
Packit |
7838c8 |
source code of the library if they required additional private tags
|
|
Packit |
7838c8 |
or codes not recognized by libtiff. Thus, whenever
|
|
Packit |
7838c8 |
a new revision of libtiff came out the client would have to
|
|
Packit |
7838c8 |
perform modifications to six or seven different files to re-install
|
|
Packit |
7838c8 |
their tags.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
The latest versions of libtiff now provide client software new routines,
|
|
Packit |
7838c8 |
giving them the opportunity to install private extensions at runtime,
|
|
Packit |
7838c8 |
rather than compile-time. This means that the client may encapsulate
|
|
Packit |
7838c8 |
all of their private tags into a separate module, which need only
|
|
Packit |
7838c8 |
be recompiled when new versions of libtiff are released; no manual
|
|
Packit |
7838c8 |
editing of files is required.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
How it works
|
|
Packit |
7838c8 |
------------
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
The mechanism for overriding the tag access has been enabled with
|
|
Packit |
7838c8 |
a single new routine, which has the following calling sequence:
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
TIFFExtendProc old_extender;
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
old_extender = TIFFSetTagExtender(tag_extender);
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
which must be called prior to opening or creating TIFF files.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
This routine sets a static pointer to the user-specified function
|
|
Packit |
7838c8 |
<tag_extender>, which in turn is called by TIFFDefaultDirectory(),
|
|
Packit |
7838c8 |
just after the usual TIFFSetField() and TIFFGetField() methods
|
|
Packit |
7838c8 |
are defined, and just before the compression tag is set. It also
|
|
Packit |
7838c8 |
returns a pointer to the previously-defined value of the tag-extender,
|
|
Packit |
7838c8 |
so that multiple clients may be installed.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
The TIFFExtendProc method that you define should be used to override
|
|
Packit |
7838c8 |
the TIFF file's "vsetfield" and "vgetfield" methods, so that you
|
|
Packit |
7838c8 |
can trap your new, private tags, and install their values into
|
|
Packit |
7838c8 |
a private directory structure. For your convienience, a new pointer
|
|
Packit |
7838c8 |
has also been added to the "TIFF" file structure:
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
tidata_t tif_clientdir; /* client TIFF directory */
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
into which you may install whatever private directory structures you like.
|
|
Packit |
7838c8 |
You should also override the tag-printing method from within your
|
|
Packit |
7838c8 |
"vsetfield" method, to permit the symbolic printing of your new tags.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
Example Client Code:
|
|
Packit |
7838c8 |
--------------------
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
An example module has been provided as a template for installing
|
|
Packit |
7838c8 |
your own tags into a client tag extender. The module is called
|
|
Packit |
7838c8 |
"xtif_dir.c", and defines all of the interface routines, tag field
|
|
Packit |
7838c8 |
access, tag printing, etc. for most purpose.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
To see how the client module operates, there are three "fake"
|
|
Packit |
7838c8 |
tags currently installed. If you use the existing makefile you can
|
|
Packit |
7838c8 |
build them with:
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
make all -f Makefile.gcc !or Makefile.mpw
|
|
Packit |
7838c8 |
maketif
|
|
Packit |
7838c8 |
listtif
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
This will build two example programs called "maketif" and "listtif"
|
|
Packit |
7838c8 |
and then run them. These programs do nothing more than create a small
|
|
Packit |
7838c8 |
file called "newtif.tif", install the fake tags, and then list them out
|
|
Packit |
7838c8 |
using TIFFPrintDirectory().
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
Installing Private Tags
|
|
Packit |
7838c8 |
-----------------------
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
To use this module for installing your own tags, edit each of the files
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
xtif_dir.c
|
|
Packit |
7838c8 |
xtiffio.h
|
|
Packit |
7838c8 |
xtiffiop.h
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
and search for the string "XXX". At these locations the comments
|
|
Packit |
7838c8 |
will direct you how to install your own tag values, define their
|
|
Packit |
7838c8 |
types, etc. Three examples tags are currently installed, demonstrating
|
|
Packit |
7838c8 |
how to implement multi-valued tags, single-valued tags, and ASCII tags.
|
|
Packit |
7838c8 |
The examples are not valid, registered tags, so you must replace them with
|
|
Packit |
7838c8 |
your own.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
To test the routines, also edit the test programs "maketif.c" and
|
|
Packit |
7838c8 |
"listtif.c" and replace the portions of the code that set the
|
|
Packit |
7838c8 |
private tag values and list them.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
Once you have edited these files, you may build the client module
|
|
Packit |
7838c8 |
with the Makefile provided, and run the test programs.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
To use these files in your own code, the "xtif_dir.c" module defines
|
|
Packit |
7838c8 |
replacement routines for the standard "TIFFOpen()" "TIFFFdOpen",
|
|
Packit |
7838c8 |
and "TIFFClose()" routines, called XTIFFOpen, XTIFFFdOpen and XTIFFClose.
|
|
Packit |
7838c8 |
You must use these routines in order to have the extended tag handlers
|
|
Packit |
7838c8 |
installed. Once installed, the standard TIFFGetField() and TIFFSetField
|
|
Packit |
7838c8 |
routines may be used as before.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
Adding Extended Tags to "tools"
|
|
Packit |
7838c8 |
-------------------------------
|
|
Packit |
7838c8 |
To create an extended-tag savvy "tiffinfo" program or other utility, you may
|
|
Packit |
7838c8 |
simply recompile and link the tools to your "libxtiff" library, adding
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
-DTIFFOpen=XTIFFOpen -DTIFFClose=XTIFFClose -DTIFFFdOpen=XTIFFFdOpen
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
to the compile statement.
|
|
Packit |
7838c8 |
|
|
Packit |
7838c8 |
Bugs, Comments Etc:
|
|
Packit |
7838c8 |
------------------
|
|
Packit |
7838c8 |
Send all reports and suggestions to ndr@tazboy.jpl.nasa.gov
|
|
Packit |
7838c8 |
(Niles Ritter).
|