EssenceFormat (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.model

## Interface EssenceFormat

- All Known Implementing Classes:
    EssenceFormat

      public interface EssenceFormat

  Specifies a collection of parameters (such as image height/width, audio sample width) which describes a piece of essence. Each parameter is specified by an AUID, and contains a variable length piece of data.

  When creating a piece of essence, you should call `addFormatSpecifier(AUID, byte[])` for each required or known parameter, and the codec will supply defaults for other optional parameters.

  Note that the current version of the MAJ API has no built-in codec support, large essence is not supported and the methods of this interface do nothing.

  See Also:
    `EssenceAccess`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addFormatSpecifier(AUID essenceFormatCode, byte[] value)` Appends a format specifier to the essence format.
    `byte[]` | `getFormatSpecifier(AUID essenceFormatCode)` Data value representing the essence format of the given essence format code.
    `AUID` | `getIndexedEssenceFormatCode(int index)` Returns the essence format code associated with the format specifier at the given index.
    `byte[]` | `getIndexedFormatSpecifier(int index)` Returns the data value at the given index.
    `int` | `numSpecifiers()` Returns the number of specifiers present in this essence format.

- - ### Method Detail

    - #### addFormatSpecifier

          void addFormatSpecifier(AUID essenceFormatCode,
                                  @DataBuffer
                                  byte[] value)
                           throws NullPointerException

      Appends a format specifier to the essence format. If a particular essence format code has already been added, then this call replaces the value, otherwise the value is added.

      Parameters:
        `essenceFormatCode` - Essence format code (as defined in "`aafdefuids.h`").
        `value` - Data value for format specifier.
      Throws:
        `NullPointerException` - One or more of the arguments is null.

    - #### getFormatSpecifier

          @DataBuffer
          byte[] getFormatSpecifier(AUID essenceFormatCode)
                                         throws NullPointerException

      Data value representing the essence format of the given essence format code.

      Parameters:
        `essenceFormatCode` - Essence format code (as defined in "`aafdefuids.h`").
      Returns:
        Corresponding data value.
      Throws:
        `NullPointerException` - Argument is null.

    - #### numSpecifiers

          @UInt32
          int numSpecifiers()

      Returns the number of specifiers present in this essence format.

      Returns:
        Number of specifiers in this essence format.

    - #### getIndexedFormatSpecifier

          @DataBuffer
          byte[] getIndexedFormatSpecifier(@Int32
                                                       int index)
                                                throws IndexOutOfBoundsException

      Returns the data value at the given index.

      Parameters:
        `index` - 0-based index for the format specifier to retrieve.
      Returns:
        Data value of the format specifier.
      Throws:
        `IndexOutOfBoundsException` - The specified index is outside the acceptable range for the current number of specifiers.

    - #### getIndexedEssenceFormatCode

          AUID getIndexedEssenceFormatCode(@Int32
                                           int index)
                                    throws IndexOutOfBoundsException

      Returns the essence format code associated with the format specifier at the given index.

      Parameters:
        `index` - 0-based index for the format specifier to retrieve.
      Returns:
        Corresponding essence format code.
      Throws:
        `IndexOutOfBoundsException` - The specified index is outside the acceptable range for the current number of specifiers.

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.