--------------------------------------------------------------------------------
File:         Image/ExifTool/README

Description:  ExifTool support modules documentation

The ExifTool support modules are loaded by ExifTool to interpret various formats
of meta information.

The tables in these files are used as lookups based on the EXIF tag values.  The
hash keys are the tag IDs (in decimal or hexadecimal if the ID is numerical as
with EXIF tables, or the tag name if the ID is ASCII as with XMP tables).  In
the case of a BinaryData table, the IDs are numerical and specify offsets into
the binary data block.  The corresponding hash value provides information about
the tag (explained later).  Each package my define a special table named
'Composite' which contains tags whose values are calculated after all other tag
values have been extracted from the file.

Seven special keys (PROCESS_PROC, GROUPS, FORMAT, FIRST_ENTRY, TAG_PREFIX,
PRINT_CONV and DID_TAG_ID) are used to provide additional information about a
table.  The special keys have names that are all capitalized to avoid possible
conflicts with tag names.  Below is an explanation of the meaning of each
special key:

  PROCESS_PROC : Reference to a function used to process the directory for this
  table.  If PROCESS_PROC is not given, \&Image::ExifTool::Exif::ProcessExif is
  assumed.  The process proc returns 1 on success or 0 on failure, and takes
  3 arguments: 0) reference to the ExifTool object, 1) reference to the tag
  table hash, 2) reference to a directory information hash, with the following
  members:
  
    Base        - Base offset for pointers from start of file.
    DataPt      - Reference to data block containing directory (may be undef).
    DataPos     - Position of data block within file (relative to Base).
    DataLen     - Length of data block in bytes.
    DirStart    - Offset to start of directory from start of data block.
    DirLen      - Length of directory data within block.
    Nesting     - Nesting depth in directory tree.
    IfdName     - Name of IFD if this is an EXIF directory.
    RAF         - Reference to File::RandomAccess object if available.

  GROUPS : A hash lookup for the default group names for all entries in this
  table. If not specified, the Group 0 and 1 names will be set automatically
  according to the name of the module.
  
  FORMAT : Specifies the default tag Format and the pointer increment for
  entries in a BinaryData table, and defaults to 'int8u' if not specified.  Can
  also be used to override EXIF format in an EXIF table.  The possible  values
  of FORMAT and Format are:

    int8s          - Signed 8-bit integer
    int8u          - Unsigned 8-bit integer
    int16s         - Signed 16-bit integer
    int16u         - Unsigned 16-bit integer
    int32s         - Signed 32-bit integer
    int32u         - Unsigned 32-bit integer
    int64s         - Signed 64-bit integer
    int64u         - Unsigned 64-bit integer
    rational16s    - Rational consisting of 2 int16s values
    rational16u    - Rational consisting of 2 int16u values
    rational32s    - Rational consisting of 2 int32s values
    rational32u    - Rational consisting of 2 int32u values
    fixed16s       - Signed 16-bit fixed point value
    fixed16u       - Unsigned 16-bit fixed point value
    fixed32s       - Signed 32-bit fixed point value
    fixed32u       - Unsigned 32-bit fixed point value
    float          - 32-bit IEEE floating point value
    double         - 64-bit IEEE floating point value
    string         - Series of 8-bit ASCII characters
    binary         - Binary data
  
  FIRST_ENTRY : Specifies the index for the first tag entry in a binary table.
  This value is only used if the Unknown option is set to 2 or higher, and
  allows the binary data to be scanned for unknown tag entries.
  
  INCREMENT : If specified, overrides the default increment for a BinaryData
  table.  The default increment is the number of bytes in the default format.
  
  TAG_PREFIX : Prefix for names of unknown tags.
  
  PRINT_CONV : Print conversion for unknown tags. 
  
  DID_TAG_ID : Used by GetTagID() as a flag to indicate that TagID's have been
               defined for all tags in this table.  This may be set in the table
               definition to prevent GetTagID() from assigning TagID's.
  
The remaining entries in a tag table are the EXIF tags with their associated
information.  The information may exist in one of three forms:  1) A simple
scalar which is the name of the tag, 2) A reference to a hash of information
describing this tag, or 3) a reference to a list of hashes which contain
Condition expressions allowing the appropriate hash to be selected to suit the
conditions.  The following is a description of possible hash entries:

  Name          : [required if tag is numerical] The tag name.  Tag names need
                  not be unique.  If they aren't unique, duplicate tags
                  overwrite values of previous tags unless the Duplicates option
                  is set.  With Duplicates set, the name of the previous tag is
                  changed to the form "TagName (N)" where N starts at 1 and
                  increments for subsequent duplicate tags.

  Description   : [optional] A more readable description of tag name.  If a tag
                  doesn't specify a Description, then the tag Name is used
                  instead, with spaces inserted between the words.

  Format        : [optional] Only valid for BinaryData, EXIF and IPTC tables.
                  For a Binary or EXIF table, this gives the format of the data,
                  and is one of the FORMAT types specified above.  For
                  BinaryData tables, the format may have a size in trailing
                  brackets which is a perl expression to be evaluated.  The
                  expression may access any of the previous table entries
                  through a %val hash, or the data size via $size. For example,
                  'string[$val{3}]' defines a string with length given by the
                  table entry with tag index '3'. If not specified, the format
                  of an EXIF entry is taken from the EXIF information, and the
                  format of a BinaryData entry is taken from the FORMAT
                  specified for the table (or int8u if FORMAT is not specified).
                  For IPTC tables, the only valid Format type is binary,
                  otherwise the data is assumed to be string.

  Flags         : [optional] Flag or list of flags to specify characteristics of
                  this tag value.  Currently the only flag is 'List', which
                  indicates that duplicate entries of this tag should be
                  accumulated in a list (a comma separated string of PrintConv
                  values and a reference to an array of ValueConv values).

  ValueConv     : [optional] Used to convert the raw data value to a useable
                  form.  May be either a hash reference to act as a lookup table
                  or a scalar which is evaluated as a Perl expression. If a hash
                  reference is used and the raw value doesn't appear as one of
                  the keys, then the converted value is set to "Unknown (X)",
                  where X is the raw value.  In an expression, $val is the raw
                  value, $dataPt may be used to access the original EXIF data
                  block, and $self is a reference to the current ExifTool
                  object.  Composite tags which Require or Desire other tags may
                  access the ValueConv and PrintConv values of these tags
                  through the elements of the @val and @valPrint lists. The
                  result of the ValueConv evaluation may be undefined to
                  indicate the tag should be ignored.  If ValueConv is not
                  specified, the raw value is not converted.

  PrintConv     : [optional] This entry is similar to ValueConv above, except
                  that it is used to further convert the tag value to a human
                  readable form.  It can be either a hash lookup or a scalar
                  Perl expression.  In this expression, $val represents the
                  result of the ValueConv from above.  When evaluated, the
                  expression may return either a scalar representing the a
                  printable value, or a scalar reference to the value if it is
                  not printable (as with a binary data block).  Note that the
                  print conversion is only done if the PrintConv option is
                  enabled (which it is by default).

  Condition     : [optional] If given, specifies scalar which is evaluated as a
                  Perl expression to decide whether the tag is valid.  If used
                  in a list, the first list entry with a true condition is
                  taken.  If no condition exists, then a 'true' condition is
                  assumed.  The previous value for this tag is available as
                  $oldVal for use in the logic expression.

  Require       : [Composite tables only] Specifies a list of tag names for
                  values which are required in order to calculate the composite
                  value.  The values are stored in a @val list in the positions
                  specified by the Require keys, and can be used in a ValueConv
                  or PrintConv expression.  The composite value is only
                  calculated if the values for all Require'd tags are defined.

  Desire        : [Composite tables only] This is the same as Require except
                  that the value is still calculated even if the specified tags
                  don't exist.  Beware that the elements of @val and @valPrint
                  may be undefined for Desire'd tags.  Both Require and Desire
                  may exist together, however be sure to specify unique keys for
                  each tag since they are used as indices into the @val and
                  @valPrint lists.

  TagID         : [reserved] This entry is used internally by GetTagID() to
                  cache tag ID numbers for speed.

  SubDirectory {  [optional] If it exists, this specifies the start of a new 
                  subdirectory.  It contains a collection of variables which
                  specify the type and location of the subdirectory.  These
                  variables are described below:

      TagTable  : [optional] Specifies the name of the tag table lookup for the
                  new subdirectory.  If not specified, the current tag table is
                  used.
                  
      Start     : [required] The offset to the start of the subdirectory.  This
                  is a Perl expression which may use $valuePtr to represent the
                  location of the tag value in the file, or $val for the value
                  itself.

      OffsetPt  : [optional] If specified, this is a Perl expression that gives
                  the position of a 32-bit word in the current directory that is
                  added to the Start position to get the position of the new
                  subdirectory.  The expression should use the position of the
                  current tag ($valuePtr).

      Base      : [optional] This specifies the base offset for all pointers in
                  the subdirectory.  This need not be specified if the offset
                  is the same as the current directory, which is normally the
                  case.  May use $start to represent the subdirectory start
                  location relative to the current base.

      MaxSubdirs: [optional] Maximum number of subdirectories specified by the
                  current tag (if the tag specifies multiple values).  If not
                  specified, the tag value ($val) is used as-is.  If MaxSubdirs
                  is specified, then one subdirectory is parsed for each value
                  found up to the maximum number specified.

      ByteOrder : [optional] Specifies byte ordering if different than than the
                  rest of the file.  Must be either BigEndian, LittleEndian or
                  Unknown.  If Unknown is specified, the byte order will be
                  determined from the directory count (however, this can not be
                  done if OffsetPt is specified).
                  
      Validate  : [optional] If given, specifies Perl expression which is used
                  to validate the subdirectory data.  The following variables
                  may be used in the expression: $val (value of the tag),
                  $dirData (reference to directory data), $subdirStart (offset
                  to subdirectory start) and $size (size of subdirectory).
                  
      ProcessProc : [optional] If given, specifies processing procedure used
                  to decode this subdirectory data.  This overrides the default
                  procedure specified by PROCESS_PROC in the tag table.
  }

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