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

Twenty-one 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, PARENT, PRIORITY, WRITE_GROUP, LANG_INFO,
VARS and DATAMEMBER) 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 (with the following entries:), 2) reference to the tag table hash.

    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
    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
    ImageData   - Used by WriteExif() to avoid buffering large image data blocks

  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
    rational32s - Rational consisting of 2 int16s values
    rational32u - Rational consisting of 2 int16u values
    rational64s - Rational consisting of 2 int32s values  (EXIF 'SRATIONAL')
    rational64u - 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')
    extended    - 80-bit extended floating float
    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, except
  for SubDirectory tags which are not made Writable.

  NOTES : Notes to introduce the table in the 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.  If this isn't a
  standard (pre-defined) namespace, then the URI must be defined as well.  To do
  this, the NAMESPACE value is a reference to either a list or a hash, where the
  first element (or hash key) is the namespace prefix and and the second element
  (or hash value) is the URI.

  PREFERRED : Set to true if the tags in this table should always be added when
  writing information.  Overrides the order specified by SetNewGroups().  When
  this feature is used, it may also be desireable to specify a preferred group
  when calling InitWriteDirs() to write these tags; this avoids creating other
  directories for tags which are already being creating in the preferred group.

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

  PRIORITY : Default Priority for all tags in this table.

  WRITE_GROUP : Default WriteGroup for all tags in the table.

  LANG_INFO : Code reference to a routine which returns a reference to a
  language-specific tag information hash.  The routine takes two arguments: a
  reference to the non-specific tagInfo hash, and the language code. Used only
  in tables which support tag name language extensions.

  VARS : Used to store additional module-specific variables for the table.

  DATAMEMBER : BinaryData tables only.  A reference to a list of tag ID's which
  must be extracted as data members when writing.

The remaining entries in a tag table are the tag IDs 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.  All
entries are optional, except for the tag Name which is required if the tag ID is
numerical.

  Name          : 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, to allow multiple tags with
                  the same name to exist in the tag information hash, the key of
                  the previous tag is changed to the form "TagName (N)", where N
                  starts at 1 and increments for subsequent duplicate tags.  A
                  tag name should start with an uppercase letter, and contain
                  only the charcters in the set [A-Za-z0-9_-].

  Description   : 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         : Notes for this tag in the HTML TagNames documentation.

  Groups        : Hash lookup for group names for this tag.

  Format        : 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         : 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.
                  Note that this count that corresponds to the specified Format,
                  so if a different-sized Writable format is defined, the actual
                  count written to the file will be different.

  Flags         : 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:

                  'Avoid' - avoid creating this tag if possible.

                  'Binary' - set to 1 for binary data.  This has the same effect
                  as setting ValueConv to '\$val', but it it a bit cleaner and
                  avoids dummy ValueConvInv entries for writable tags.  Has no
                  effect if ValueConv is defined for the tag.

                  'DataMember' - name of exiftool data member associated with
                  this tag if it should be stored as a special data member when
                  writing information.  Necessary only if the value of the tag
                  affects other written information.  Currently only used for
                  tags in EXIF tables.

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

                  'Drop' - set to 1 for tags that should be excluded when
                  rebuilding maker notes when copying all tags.

                  'EntryBased' - set to 1 if the offset for this value is based
                  on the IFD entry position.  This allows individual values to
                  be entry-based even though some others aren't (as with the
                  Casio PrintIM information).

                  'IsOffset' - flag set if the tag represents an offset to some
                  data, and causes value will be adjusted to an absolute file
                  offset.  If set to 2, the offset base of the parent directory
                  is used even if the base changes for the current directory
                  (only some maker notes are this messed up).

                  'List' - indicates that duplicate entries of this tag are
                  allowed, and will be accumulated in a list.  Note that for XMP
                  information, 3 different types of lists are supported and the
                  List value specifies the type: 'Bag', 'Seq' or 'Alt'.

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

                  '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.

                  '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.

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

                  '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 indicates an 'unsafe' tag, which is not set via
                  SetNewValuesFromFile() unless specified explicitly.
                  Bit 0x02 indicates a 'protected' tag, which should not be set
                  directly by the user.

                  'SeparateTable' - set to list PrintConv values in a separate
                  table in the HTML documentation.  Value is 1 or the name of
                  the module where the table should be located.

                  'SetResourceName' - [Photoshop tags only] set to 1 to append
                  resource name to the extracted value (ie. 'VALUE/#NAME#/').
                  Also allows resource name to be appended when writing new
                  values.  May be set to any value other than 1 for a default
                  resource name to use when writing if an appended name is not
                  provided.

                  '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.

                  'Unknown' - this is an unknown tag (only extracted when the
                  Unknown option is set).

  RawConv       : Used to convert the Raw value at extraction time (while the
                  image file is still open, unlike ValueConv and PrintConv below
                  which are done later only if the value is requested).  May be
                  a scalar expression using $val (the Raw tag value) and $self
                  (the current ExifTool object), or a code reference with $val
                  and $self as arguments.  For Composite tags, $val is a
                  reference to a hash of component tag names, and @val may be
                  used to access the Raw values of these tags. The returned
                  value may be a scalar which is used as the new Raw value, a
                  scalar reference to a binary data value, or undefined to
                  indicate that the tag should be ignored.  Note: RawConv should
                  only be used if necessary (in general, only if the tag may
                  be ignored).  It is preferable to use ValueConv instead of
                  RawConv because ValueConv is only executed if the tag value is
                  requested, while RawConv is executed for all extracted tags.

  ValueConv     : Used to convert the Raw 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 (unless a
                  special 'BITMASK' key exists, in which case the hash
                  referenced by 'BITMASK' is used to decode individual value
                  bits).  In an expression, $self is a reference to the current
                  ExifTool object, $val is the Raw value, and $tag is the tag
                  name.  The subroutine takes 2 arguments: the Raw value and a
                  reference to the current ExifTool object.  The expression or
                  subroutine is evaluated when and if the tag value is requested
                  (ie. only after all extraction is complete), so if necessary
                  at this time the values of all other tags are available via
                  calls to $self->GetValue("Tag","Raw"). (Note: In theory, types
                  other than "Raw" may be accessed, but they are slower and may
                  lead to cyclical dependencies so they should be avoided).
                  When evaluated, the expression or subroutine returns a scalar
                  for the converted value, or a scalar reference to a binary
                  data value (see the 'Binary' flag).  The return value should
                  always be defined -- use RawConv instead to return undef if it
                  is necessary to test the value for validity, otherwise an
                  undef tag may hide a previously defined value when the
                  Duplicates option is not enabled.  Composite tags which
                  Require or Desire other tags may access the ValueConv,
                  PrintConv and Raw values of these tags through the elements of
                  the @val, @prt and @raw lists respectively.  If ValueConv is
                  not specified, the Raw value is not converted.

  PrintConv     : 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, $self,
                  $val and $tag may be used as with ValueConv, but the returned
                  value should always be defined.  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.

  RawConvInv    : The inverse of RawConv.  This should only be used in very rare
                  situations when the raw value can not be predetermined.
                  Unlike the other inverse conversions which are applied in
                  SetNewValue(), this conversion is applied in WriteInfo() as
                  the file is being written.  This is important because it means
                  that FILE_TYPE and any DataMember tags ocurring before this
                  tag in the file are available.  Beware that if the return
                  value is not defined, the tag will be deleted unless there is
                  specific code to avoid this (currently, only EXIF and Binary
                  data directories handle this case).

  ValueConvInv  : 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 or RawConvInv must be used.

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

  Condition     : If given, specifies scalar which is evaluated as a Perl
                  expression at extraction time to decide whether the tag is
                  valid.  If used in a list of alternate tag definitions, the
                  first list entry with a true condition is taken.  If no
                  condition exists, then a 'true' condition is assumed.  The
                  expression may use $self to access the ExifTool object, and
                  $oldVal to access the previous Raw value of the tag (if it
                  exists).  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 tags 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 tags 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, @prt and @raw 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, @prt
                  and @raw lists.

  Shift         : [Writable tags only] Specifies type of shift to apply if this
                  value may be shifted.  Set to 'Time' for shifting date/time
                  tags.

  Writable      : 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     : 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    : 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 3 variables: $val is
                  the value to be written, $self is the ExifTool object, and
                  $tagInfo is the tag information hash reference. It returns an
                  error string or undef if the value is good.

  WriteCondition: [Writable EXIF tags only] 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    : [Required for writable EXIF tags] Specifies the IFD where the
                  information gets written by default.

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

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

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

  Units         : [MIE tags only] Reference to a list of valid units strings.
                  The default units are the first item in the list.

  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 {  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   : Specifies the name of the tag table lookup for the new
                  subdirectory.  If not specified, the parent tag table is used.

     Start      : 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   : 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       : 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.

     EntryBased : Flag indicating that the offsets are based on the indidual
                  directory entry position, so offsets are incremented by 12
                  times the corresponding entry index.

     MaxSubdirs : 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  : 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   : 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: 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    : Name of this subdirectory.  If not specified, the name is
                  taken from the tag name.  DirName is important because it is
                  used when writing to compare against names in the directory
                  map to determine which directories need to be edited.

     FixBase    : Flag set if base offsets should be fixed.  Used to add a
                  constant to maker notes offsets to fix damage done by some
                  image editing utilities.
  }

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