From 9491825ddff7a294d1f49061bae7044e426aeb2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Fri, 6 Nov 2015 05:38:49 +0100 Subject: Imported Upstream version 1.8.3 --- tiff/contrib/tags/README | 132 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100755 tiff/contrib/tags/README (limited to 'tiff/contrib/tags/README') diff --git a/tiff/contrib/tags/README b/tiff/contrib/tags/README new file mode 100755 index 0000000..73c6c21 --- /dev/null +++ b/tiff/contrib/tags/README @@ -0,0 +1,132 @@ + +NOTE: Sept/2004 + +The following described approach to managing tag extensions has been +mostly superceeded 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 +, 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). -- cgit v1.2.3