NAME

       TIFFCustomDirectory - routines to create a custom directory

SYNOPSIS

          #include <tiffio.h>

       int TIFFCreateCustomDirectory(TIFF *tif, const TIFFFieldArray *infoarray)

       int TIFFCreateEXIFDirectory(TIFF *tif)

       int TIFFCreateGPSDirectory(TIFF *tif)

       int TIFFWriteCustomDirectory(TIFF *tif, uint64 *pdiroff)

       int TIFFReadCustomDirectory(TIFF *tif, toff_t diroff, const TIFFFieldArray *infoarray)

       int TIFFReadEXIFDirectory(TIFF *tif, toff_t diroff)

       int TIFFReadGPSDirectory(TIFF *tif, toff_t diroff)

       const TIFFFieldArray *_TIFFGetExifFields(void)

       const TIFFFieldArray *_TIFFGetGpsFields(void)

DESCRIPTION

       The  following  routines  create a custom directory and retrieve information about directories in an open
       TIFF file.

       TIFFCreateCustomDirectory(), TIFFCreateEXIFDirectory(),  TIFFCreateGPSDirectory()  will  setup  a  custom
       directory  or one of the predefined EXIF or GPS directories and set the context of the TIFF-handle tif to
       that custom directory for functions like TIFFSetField().

       TIFFWriteCustomDirectory() will write the contents of the current custom directory to the file and return
       the offset to that directory in pdiroff. That offset has to be written to the main-IFD:

           /* Go back to the first directory, and add the EXIFIFD pointer. */
          TIFFSetDirectory(tif, 0);
          TIFFSetField(tif, TIFFTAG_EXIFIFD, pdiroff);

       TIFFReadCustomDirectory() will read the custom directory from the arbitrary offset into the infoarray and
       sets the context of the TIFF-handle tif to that custom directory for functions like TIFFReadField().  The
       TIFFFieldArray  infoarray has to be according the layout of the custom directory. For the predefined EXIF
       and  GPS  directories,  the  relevant  TIFFFieldArray  definitions  are  hidden  within   the   functions
       TIFFReadEXIFDirectory()  and TIFFReadGPSDirectory() The code is very similar to TIFFReadDirectory().  The
       offset to the custom directory diroff has to be read from the relative TIFF tag first.

       _TIFFGetExifFields() and _TIFFGetGpsFields()  will return a pointer to the  libtiff  internal  definition
       list of the EXIF and GPS tags, respectively.

NOTES

       Be aware

       • that  until  a  directory  is not written to file AND read back, the query functions won't retrieve the
         correct information!

       • that  the  newly  created  directory  will  not  exist   on   the   file   till   TIFFWriteDirectory(),
         TIFFCheckpointDirectory(), TIFFFlush() or TIFFClose() has been called.

       • that TIFFCreateDirectory() and TIFFWriteDirectory() create a new directory, free the *tif structure and
         set up a new one.

       • that  unlike  TIFFWriteDirectory(),  TIFFCheckpointDirectory()  does  not  free  up  the directory data
         structures in memory.

       • that LibTiff does not support custom directory chains (NextIFD pointing to another  IFD).   NextIFD  of
         custom directories is always set to zero and should be zero when reading.

       Unfortunately  to create or read custom directories with predefined fields it is necessary to include the
       private tif_dir.h. However, for EXIF and GPS directories, which have a predefined schema within  libtiff,
       this  is  not necessary. There are some test programmes that briefly demonstrate the creation and reading
       of EXIF, GPS and custom directories.  See test/custom_dir.c and test/custom_dir_EXIF_231.c

       After    libtiff    version    4.6.0    TIFFCreateCustomDirectory(),    TIFFCreateEXIFDirectory()     and
       TIFFCreateGPSDirectory()   also   releases   the   directory   part  of  the  tif  structure  by  calling
       TIFFFreeDirectory(), which should have been  called  by  the  user  application  before  creating  a  new
       directory.

HINTS AND DETAILED INSTRUCTIONS

       Writing  TIFF  files  with more than one directory (IFD) is not easy because some side effects need to be
       known.

       The main point here is that there can only be one tif structure in the main memory for a file, which  can
       only  hold  the  tags  of  one  directory  at  a time. It is useless to work with two different tiffOut1,
       tiffOut2 pointers, because there is only ONE TIFF object (TIFF directory) within the libtiff. If you want
       to address a second directory in the file, the tags of the current directory must first be saved  in  the
       file,  otherwise they will be lost (overwritten or mixed). Then the tif structure in the main memory must
       be tidied up, otherwise the old tags will beincluded in the new directory.  This can be  done  either  by
       creating a new, empty tif structure or by reading in an directory previously saved in the file.

       A sequence to handle a second (or third) TIFF directory - in this case the GPS IFD - is as follows:

       1. Create TIFF file

       2. Complete the "normal" metadata

       3. Set  the tag for the custom directory with a “dummy” value in order to get the tag reserved. The final
          value will be inserted lateron. This prevents the main directory from being written to the file  again
          at an additional area, leaving the first memory area unused:

          TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);

       4. Save  current  TIFF-directory  to  file.  Otherwise, it will be lost.  Remember also the number of the
          current directory:

          TIFFWriteDirectory(tiffOut);
          dirNum = TIFFCurrentDirectory(tiffOut);

       5. Create the second TIFF-directory (e.g. custom  directory)  and  set  its  fields.  The  TIFFFieldArray
          infoarray has to be specified beforehand somewhere in your private include files.  An example is given
          for the EXIF directory in tif_dirinfo.c

          TIFFCreateCustomDirectory(tiffOut, infoarray);        /* for a real custom directory */
          /* or alternatively, use GPS or EXIF with pre-defined TIFFFieldArray IFD field structure */
          TIFFCreateGPSDirectory(tiffOut);
          TIFFSetField(tiffOut, GPSTAG_VERSIONID, gpsVersion);  /* set fields of the custom directory */

       Be aware that every TIFFCreateDirectory() or TIFFWriteDirectory() apparently frees the *tif structure and
       sets up a new one!

       6. Write custom directory to file. The offset to that directory in the file is returned in dir_offset.

          TIFFWriteCustomDirectory(tiffOut, &dir_offset);

       7. Reload  the  first directory (i.e. the original TIFF directory).  Apparently, this reads the data back
          from file.

          TIFFSetDirectory(tiffOut, dirNum);

       8. Set the correct offset value of the custom directory IFD tag and save that changes to file.

          TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);
          TIFFWriteDirectory(tiffOut);

RETURN VALUES

       1 is returned when the contents are successfully written to the file.  Otherwise, 0  is  returned  if  an
       error was encountered when writing the directory contents.

DIAGNOSTICS

       All  error messages are directed to the TIFFErrorExtR() routine.  Likewise, warning messages are directed
       to the TIFFWarningExtR() routine.

SEE ALSO

       libtiff   (3tiff),   TIFFCreateDirectory   (3tiff),   TIFFquery   (3tiff),   TIFFSetDirectory    (3tiff),
       TIFFWriteDirectory (3tiff)

AUTHOR

       LibTIFF contributors

COPYRIGHT

       1988-2022, LibTIFF contributors

4.7                                               Apr 30, 2025                        TIFFCUSTOMDIRECTORY(3tiff)