--------------------------------------------------------------------------------
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 tag ID 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).

Sixteen special keys (PROCESS_PROC, WRITE_PROC, CHECK_PROC, GROUPS, FORMAT,
FIRST_ENTRY, TAG_PREFIX, PRINT_CONV, DID_TAG_ID, WRITABLE, NOTES, IS_OFFSET,
EXTRACT_UNKNOWN, NAMESPACE, PREFERRED and PARENT) are used to provide additional
information about a table.  The special keys have names that are all capitalized
to avoid possible conflicts with tag keys.  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.  If PROCESS_PROC is set to 0, the tags are not added to the lookup.
  The process proc returns 1 on success or 0 on failure, and takes 3 arguments:
  0) reference to the ExifTool object, 1) reference to a directory information
  hash, 2) reference to the tag table hash, with the following members:

    Name        - Tag name for this SubDirectory entry (for verbose messages)
    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
    DirName     - Name of this directory
    OutFile     - Output file or scalar reference
    Parent      - Name of parent directory
    RAF         - Reference to File::RandomAccess object if available
    Multi       - True if we should scan for multiple IFD's
    NewDataPos  - File position of new data (write proc only)
    Fixup       - Reference to hash of offset fixups (used in EXIF writing only)
    FixBase     - Flag set to attempt to fix base offsets
    LastIFD     - Used by WriteExif() to return offset of last IFD written

  WRITE_PROC : Reference to a function to write all new tags for this directory.
  The write proc returns the new directory data or undefined on error.  It takes
  the same arguments as the process proc above except that the second argument
  (reference to directory information hash) is optional, and if specified gives
  information about the source directory for tags to be copied to the output.

  CHECK_PROC : Reference to a function which validates raw values for writing.
  The function takes three arguments: 0) ExifTool object reference, 1) tagInfo
  reference, 2) value reference, and returns undefined (and possibly modifies
  the input value) if successful, or an error message if there was a format
  problem.

  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 corresponding pointer increment
  for entries in a BinaryData table, and defaults to 'int8u' if not specified.
  The possible values of FORMAT are:

    int8s       - Signed 8-bit integer                    (EXIF 'SBYTE')
    int8u       - Unsigned 8-bit integer                  (EXIF 'BYTE')
    int16s      - Signed 16-bit integer                   (EXIF 'SSHORT')
    int16u      - Unsigned 16-bit integer                 (EXIF 'SHORT')
    int32s      - Signed 32-bit integer                   (EXIF 'SLONG')
    int32u      - Unsigned 32-bit integer                 (EXIF 'LONG')
    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  (EXIF 'SRATIONAL')
    rational32u - Rational consisting of 2 int32u values  (EXIF 'RATIONAL')
    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        (EXIF 'FLOAT')
    double      - 64-bit IEEE floating point value        (EXIF 'DOUBLE')
    ifd         - Unsigned 32-bit integer sub-IFD pointer (EXIF 'IFD')
    string      - Series of 8-bit ASCII characters        (EXIF 'ASCII')
    undef       - Undefined-format binary data            (EXIF 'UNDEFINED')
    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.

  TAG_PREFIX : Prefix for names of unknown tags.

  PRINT_CONV : Default print conversion tags where PrintConv isn't specified.

  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.

  WRITABLE : Indicates that all tags in this table are writable.  This is the
  same as setting the Writable flag for each individual tag in the table.

  NOTES : Notes for TagNames documentation.

  IS_OFFSET : Reference to list of TagID's representing offsets for binary
  data tables only.  Not used for EXIF tables.

  EXTRACT_UNKNOWN : Used in PDF tables to specify a directory where all unknown
  tags should be extracted.

  NAMESPACE : Namespace prefix for tags in the XMP table.  May be a reference to
  a list of the namespace prefix and URI if the URI needs specifying.

  PREFERRED : Set to true if the tags in this table should always be added when
  writing information.  Overrides the order specified by SetNewGroups().

  PARENT : Used internally to store the parent table name of a user-defined tag
  table so the appropriate module can be loaded as required.

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 or the new tag has lower Priority.  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.

  Notes         : [optional] Notes for html TagNames documentation.

  Groups        : [optional] Hash lookup for group names for this tag.

  Format        : [optional] Only valid for BinaryData, EXIF and IPTC tables.
                  For a Binary or EXIF table, this gives the format that is used
                  to convert the binary 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).

  Count         : [optional] Used when writing EXIF information to specify the
                  number values to write, or the number of characters in a
                  fixed-length string.  A value of -1 indicates that the count
                  is variable and should be determined by the number of values
                  provided.

  Flags         : [optional] Flags to specify characteristics for this tag.  May
                  be a simple scalar flag name, a reference to a list of flag
                  names, or a reference to a hash of flag/value pairs. If not a
                  hash reference, the flag value is set to 1. Flags are expanded
                  for faster access at run time into members of the tagInfo
                  hash, and may be written directly as members if desired. The
                  available flag names are:

                  'List' - 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).  The value is the list type for XMP lists.

                  'Priority' - gives the priority of this tag while reading.  If
                  set to zero, this tag will not override the value of previous
                  tags with the same name.  If the priority is greater than
                  zero, this tag won't be overridden by subsequent tags unless
                  their priority is equal to or greater than this priority.  A
                  special feature is that Priority 0 tags are automatically
                  incremented to Priority 1 if they exist in the IFD of the full
                  resolution image (as determined by SubFileType).

                  'Protected' - bit mask to protect tags from writing.  Bit 0x01
                  is set to indicate an 'unsafe' tag, which is not written by
                  SetNewValuesFromFile().  Bit 0x02 indicates a 'protected' tag,
                  which should not be set directly by the user.

                  'PrintHex' - specifies that unknown PrintConv values should
                  be printed in hex (ie. "Unknown (0x0)")

                  'SubIFD' - used in writing to determine that the tag specifies
                  an offset to a sub-IFD.  When this flag is set, the Group1
                  name gives the name of the IFD.

                  'IsOffset' - flag set if the tag represents an offset to some
                  data, and causes value will be adjusted to an absolute file
                  offset.

                  'OffsetPair' - set if the tag represents half of an offset/
                  byte count pair.  Data for these tags must be handled
                  separately.  Value is the tagID for the paired tag.

                  'DataTag' - associated tag name containing data for offset or
                  byte count tags.

                  'MakerNotes' - set if this tag is maker note data.

                  'DataMember' - name of exiftool data member associated with
                  this tag if it should be stored as a special data member.

                  'Permanent' - flag indicates that a tag is permanent, and
                  can't be added or deleted from the file.  By default, all
                  MakerNotes tags are permanent unless otherwise specified.
                  
                  'Avoid' - avoid creating this tag if possible.

                  'Unknown' - this is an unknown tag (only extracted when the
                  Unknown option is set.
                  
  ValueConv     : [optional] Used to convert the raw data value to a useable
                  form.  May be a hash reference to act as a lookup table, a
                  scalar which is evaluated as a Perl expression, or a code
                  reference to a subroutine. 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, and $self is
                  a reference to the current ExifTool object.  The subroutine
                  takes 2 arguments: a reference to the  and the value to
                  convert ExifTool object.  When evaluated, the expression or
                  subroutine 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).  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, a scalar Perl
                  expression or a code reference.  In this expression, $val
                  represents the result of the ValueConv from above.  Note that
                  the print conversion is only done if the PrintConv option is
                  enabled (which it is by default), and if the result of the
                  ValueConv is not a scalar reference.

  ValueConvInv  : [optional] The inverse of ValueConv.  Only necessary if
                  ValueConv is specified and this tag is Writable.  Note that
                  DataMember tags may NOT be used in the inverse conversions
                  because these conversions are done before the input file is
                  parsed.  Instead, a Condition must be used.

  PrintConvInv  : [optional] The inverse of PrintConv.  Only necessary if
                  PrintConv is specified and this tag is Writable.

  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.  The first 48 bytes
                  of the raw data value are accessible through the reference
                  $valPt for EXIF and Jpeg2000 tags only.  Note that if the
                  value is writable and $valPt is used, the tag must have a
                  Format (unless 'undef' or 'string'), and a Count (unless 1 or
                  length of the 'undef' or 'string'), so the raw data may be
                  generated for evaluating the Condition.

  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.
                  Require and Desire tag names may be prefixed by an optional
                  group family 0 or 1 name followed by a colon.  Case is
                  significant.

  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.

  Writable      : [optional] Indicates this tag can be written (or not written
                  if value is set to zero), and for EXIF-type tables gives
                  format for writing.  Writable may be set to 1 for MakerNotes
                  information because the existing format is always used,
                  however providing a format is desireable because it is used in
                  validating the value.  For EXIF tables, the Writable flag may
                  be different than the Format flag, in which case Format is
                  used for converting the binary value and Writable specifies
                  the format code written to the EXIF IFD.

  WriteAlso     : [optional] Used for writable tag to specify other tags to
                  write when this tag is written.  The value is a hash
                  reference.  The hash is keys are the names of the tags that
                  must be written, and the values are evaluated to return the
                  ValueConv value of the specified tag (or returns undef to
                  delete the tag).  In the eval, $val may be used to represent
                  the value of the parent tag.

  WriteCheck    : [optional] If given, specifies a scalar which is evaluated as
                  a Perl expression for a one-time validatation the value being
                  written.  The expression has access to two variables: $val
                  is the value to be written, and $self is the ExifTool object.
                  It returns an error string or undef if the value is good.

  WriteCondition: [optional] Only meaningful for writable EXIF tags.  Specifies
                  a condition to be evaluated before the tag can be written to a
                  specific file.  The condition may use $self to reference the
                  ExifTool object, and returns true if it is OK for writing.
                  Unlike WriteCheck which is done only once when the new value
                  is set, this condition is evaluated before the information is
                  written in each file.

  WriteGroup    : [optional] Required for writable EXIF tags to specify the IFD
                  where the information gets written.

  OffsetPair    : [optional] Used in EXIF table to specify the tagID for the
                  corresponding offset or length tag.

  DataTag       : [optional] Used in EXIF table to specify the tag name of the
                  data associated with offset/length tags.

  Struct        : [optional] Used by XMP writer code to specify name of XMP
                  structure so the PropertyPath can be determined.

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

  Table         : [reserved] Reference to parent tag table.

  PropertyPath  : [reserved] Used internally by XMP writer to save property
                  path name.

  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      : [optional] The offset to the start of the subdirectory
                  relative to the current Base.  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.  If not specified,
                  a Start of '$valuePtr' is assumed.

     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.

     DirName    : [optional] Name of this subdirectory.  If not specified, the
                  name is taken from the TagTable default GROUP0 name, or from
                  the tag Group1 name if no TagTable specified.

     FixBase    : [optional] Flag set if base offsets should be fixed.
  }

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