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

tv.amwa.maj.io.mxf

## Interface IndexEntry

- All Superinterfaces:
    Cloneable
  All Known Implementing Classes:
    IndexEntryImpl

      public interface IndexEntry
      extends Cloneable

  Element of an array that provides stream offsets and other description of an edit unit along an incrementing timeline.

  See Also:
    `IndexTableSegment.getIndexEntryArray()`, `TypeDefinitions.IndexEntry`, `TypeDefinitions.IndexEntryArray`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte` | `EDITFLAG_BACKWARD_PREDICTION` Set this bit on an edit unit flag to indicate backward prediction from a future frame is in use.
    `static byte` | `EDITFLAG_FORWARD_PREDICTION` Set this bit on an edit unit flag to indicate forward prediction from the previous frame is in use.
    `static byte` | `EDITFLAG_RANDOM_ACCESS` Set this bit on an edit unit flag to indicate that it is a bona fide random access point in the stream.
    `static byte` | `EDITFLAG_SEQUENCE_HEADER` Set this bit on an edit unit flag to indicate that the edit unit contains an MPEG sequence header.
    `static byte` | `FLAGS_DEFAULT` Default value for the flags stating what kind of frame this is.
    `static byte` | `KEYFRAMEOFFSET_DEFAULT` Default value for the offset from the indexed frame to the previous key frame.
    `static byte` | `TEMPORALOFFSET_DEFAULT` Default value for the offset from the display order to the coded order.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `IndexEntry` | `clone()` Create a cloned copy of this index entry.
    `byte` | `getFlags()` Returns the edit flags that indicate the coding of the edit unit associated with the index entry.
    `byte` | `getKeyFrameOffset()` Returns the offset measured in edit units to the previous key frame for this index entry, which may be the preceding I-frame for an MPEG stream.
    `Rational[]` | `getPosTable()` Returns the array of fractional position offsets from the start of the content package to the synchronized sample in the content package.
    `int[]` | `getSliceOffset()` Returns the array of byte offsets from the stream offset of the edit unit to each slice.
    `long` | `getStreamOffset()` Returns the offset of the edit unit within the container stream relative to the start of that container stream, measured in bytes.
    `byte` | `getTemporalOffset()` Returns the offset measured in edit units from the display order to the coded order for this index entry.
    `void` | `resolveBytes(IndexTableSegment parentSegment)` Resolves any bytes that could not be parsed initially without the context of an index table segment in the context of the given index table segment.
    `void` | `setFlags(byte flags)` Sets the edit flags that indicate the coding of the edit unit associated with the index entry.
    `void` | `setKeyFrameOffset(byte keyFrameOffset)` Sets the offset measured in edit units to the previous key frame for this index entry, which may be the preceding I-frame for an MPEG stream.
    `void` | `setPosTable(Rational[] posTable)` Sets the array of fractional position offsets from the start of the content package to the synchronized sample in the content package.
    `void` | `setSliceOffset(int[] sliceOffset)` Sets the array of byte offsets from the stream offset of the edit unit to each slice.
    `void` | `setStreamOffset(long streamOffset)` Sets the offset of the edit unit within the container stream relative to the start of that container stream, measured in bytes.
    `void` | `setTemporalOffset(byte temporalOffset)` Sets the offset measured in edit units from the display order to the coded order for this index entry.

- - ### Field Detail

    - #### TEMPORALOFFSET_DEFAULT

          @Int8
          static final byte TEMPORALOFFSET_DEFAULT

      Default value for the offset from the display order to the coded order.

      See Also:
        `getTemporalOffset()`, `setTemporalOffset(byte)`, Constant Field Values

    - #### KEYFRAMEOFFSET_DEFAULT

          @Int8
          static final byte KEYFRAMEOFFSET_DEFAULT

      Default value for the offset from the indexed frame to the previous key frame.

      See Also:
        `getKeyFrameOffset()`, `setKeyFrameOffset(byte)`, Constant Field Values

    - #### FLAGS_DEFAULT

          @UInt8
          static final byte FLAGS_DEFAULT

      Default value for the flags stating what kind of frame this is. The value represents a bona fide random access frame with no forward or backward predicition, e.g. for MPEG-2 the frame is an I-frame.

      See Also:
        `getFlags()`, `setFlags(byte)`, `EDITFLAG_RANDOM_ACCESS`, Constant Field Values

    - #### EDITFLAG_RANDOM_ACCESS

          static final byte EDITFLAG_RANDOM_ACCESS

      Set this bit on an edit unit flag to indicate that it is a bona fide random access point in the stream.

      See Also:
        `getFlags()`, `setFlags(byte)`, `FLAGS_DEFAULT`, Constant Field Values

    - #### EDITFLAG_SEQUENCE_HEADER

          static final byte EDITFLAG_SEQUENCE_HEADER

      Set this bit on an edit unit flag to indicate that the edit unit contains an MPEG sequence header.

      See Also:
        `getFlags()`, `setFlags(byte)`, Constant Field Values

    - #### EDITFLAG_FORWARD_PREDICTION

          static final byte EDITFLAG_FORWARD_PREDICTION

      Set this bit on an edit unit flag to indicate forward prediction from the previous frame is in use.

      See Also:
        `getFlags()`, `setFlags(byte)`, Constant Field Values

    - #### EDITFLAG_BACKWARD_PREDICTION

          static final byte EDITFLAG_BACKWARD_PREDICTION

      Set this bit on an edit unit flag to indicate backward prediction from a future frame is in use.

      See Also:
        `getFlags()`, `setFlags(byte)`, Constant Field Values

  - ### Method Detail

    - #### getTemporalOffset

          @Int8
          byte getTemporalOffset()

      Returns the offset measured in edit units from the display order to the coded order for this index entry.

      Returns:
        Offset measured in edit units from the display order to the coded order.
      See Also:
        `TEMPORALOFFSET_DEFAULT`, `DeltaEntry.getPosTableIndex()`

    - #### setTemporalOffset

          void setTemporalOffset(@Int8
                                 byte temporalOffset)

      Sets the offset measured in edit units from the display order to the coded order for this index entry.

      Parameters:
        `temporalOffset` - Offset measured in edit units from the display order to the coded order.
      See Also:
        `TEMPORALOFFSET_DEFAULT`, `DeltaEntry.setPosTableIndex(byte)`

    - #### getKeyFrameOffset

          @Int8
          byte getKeyFrameOffset()

      Returns the offset measured in edit units to the previous key frame for this index entry, which may be the preceding I-frame for an MPEG stream. The value is zero if this is a key frame.

      Returns:
        Offset measured in edit units to the previous key frame.
      See Also:
        `KEYFRAMEOFFSET_DEFAULT`

    - #### setKeyFrameOffset

          void setKeyFrameOffset(@Int8
                                 byte keyFrameOffset)

      Sets the offset measured in edit units to the previous key frame for this index entry, which may be the preceding I-frame for an MPEG stream. The value is zero if this is a key frame.

      Parameters:
        `keyFrameOffset` - Offset measured in edit units to the previous key frame.
      See Also:
        `KEYFRAMEOFFSET_DEFAULT`

    - #### getFlags

          @EditUnitFlag
          byte getFlags()

      Returns the edit flags that indicate the coding of the edit unit associated with the index entry.

      Note the following about prediction flags:

      - If no forward or backward prediction is set, either this is not an MPEG stream or if it is an MPEG stream, the edit unit is an I-frame.
      - If only the forward prediction flag is set, the edit unit is a P-frame.
      - If the backward prediction is set, the edit unit is a B-frame and this may include forward prediction, depending on the state of the forward prediction flag.
      Returns:
        Edit flags that indicate the coding of the edit unit.
      See Also:
        `FLAGS_DEFAULT`, `EDITFLAG_RANDOM_ACCESS`, `EDITFLAG_SEQUENCE_HEADER`, `EDITFLAG_FORWARD_PREDICTION`, `EDITFLAG_BACKWARD_PREDICTION`

    - #### setFlags

          void setFlags(@EditUnitFlag
                        byte flags)

      Sets the edit flags that indicate the coding of the edit unit associated with the index entry.

      Note the following about prediction flags:

      - If no forward or backward prediction is set, either this is not an MPEG stream or if it is an MPEG stream, the edit unit is an I-frame.
      - If only the forward prediction flag is set, the edit unit is a P-frame.
      - If the backward prediction is set, the edit unit is a B-frame and this may include forward prediction, depending on the state of the forward prediction flag.
      Parameters:
        `flags` - Edit flags that indicate the coding of the edit unit.
      See Also:
        `FLAGS_DEFAULT`, `EDITFLAG_RANDOM_ACCESS`, `EDITFLAG_SEQUENCE_HEADER`, `EDITFLAG_FORWARD_PREDICTION`, `EDITFLAG_BACKWARD_PREDICTION`

    - #### getStreamOffset

          @UInt64
          long getStreamOffset()

      Returns the offset of the edit unit within the container stream relative to the start of that container stream, measured in bytes.

      Returns:
        Offset of the edit unit within the container stream relative to the start of that container stream, measured in bytes.

    - #### setStreamOffset

          void setStreamOffset(@UInt64
                               long streamOffset)
                        throws IllegalArgumentException

      Sets the offset of the edit unit within the container stream relative to the start of that container stream, measured in bytes.

      Parameters:
        `streamOffset` - offset of the edit unit within the container stream relative to the start of that container stream, measured in bytes.
      Throws:
        `IllegalArgumentException` - Stream offset values cannot be negative.

    - #### getSliceOffset

          @UInt32Array
          int[] getSliceOffset()

      Returns the array of byte offsets from the stream offset of the edit unit to each slice. Other than the first slice always starts at the beginning of the edit unit, a slice offset indicates the start of a group of sections following a variable bitrate encoded item.

      Returns:
        Array of byte offsets from the stream offset of the edit unit to each slice.
      See Also:
        `DeltaEntry.getSlice()`

    - #### setSliceOffset

          void setSliceOffset(@UInt32Array
                              int[] sliceOffset)
                       throws IllegalArgumentException

      Sets the array of byte offsets from the stream offset of the edit unit to each slice. Other than the first slice always starts at the beginning of the edit unit, a slice offset indicates the start of a group of sections following a variable bitrate encoded item.

      Parameters:
        `sliceOffset` - Array of byte offsets from the stream offset of the edit unit to each slice.
      Throws:
        `IllegalArgumentException` - Slice offset values cannot be negative.
      See Also:
        `DeltaEntry.setSlice(byte)`

    - #### getPosTable

          Rational[] getPosTable()

      Returns the array of fractional position offsets from the start of the content package to the synchronized sample in the content package. Fractional offsets are required when a difference exists between the frame size of content, such as between audio and video.

      For example, the audio may only be synchronized with the video every few frames. In this case the fraction indicates how much of a fraction differece exists between the start of the audio frame and the start of the video frame.

      Returns:
        Array of fractional position offsets from the start of the content package to the synchronized sample in the content package.
      See Also:
        `DeltaEntry.getPosTableIndex()`

    - #### setPosTable

          void setPosTable(Rational[] posTable)
                    throws NullPointerException

      Sets the array of fractional position offsets from the start of the content package to the synchronized sample in the content package. Fractional offsets are required when a difference exists between the frame size of content, such as between audio and video.

      For example, the audio may only be synchronized with the video every few frames. In this case the fraction indicates how much of a fraction differece exists between the start of the audio frame and the start of the video frame.

      Parameters:
        `posTable` - Array of fractional position offsets from the start of the content package to the synchronized sample in the content package.
      Throws:
        `NullPointerException` - Cannot create a position table with `null` elements.
      See Also:
        `DeltaEntry.setPosTableIndex(byte)`

    - #### clone

          IndexEntry clone()

      Create a cloned copy of this index entry.

      Returns:
        Cloned copy of this index entry.

    - #### resolveBytes

          void resolveBytes(IndexTableSegment parentSegment)
                     throws NullPointerException,
                            EndOfDataException

      Resolves any bytes that could not be parsed initially without the context of an index table segment in the context of the given index table segment. The result of calling this method is to set the slice offset and position table properties using the slice count and position table count of the index table segment.

      Parameters:
        `parentSegment` - Segment that owns the index entry and provides the slice count and position table count values.
      Throws:
        `NullPointerException` - The given parent segment is `null`.
        `EndOfDataException` - Insufficient data in the unresolved bytes of each index entry to be resolved to arrays of the required size.
      See Also:
        `IndexTableSegment.getSliceCount()`, `IndexTableSegment.getPosTableCount()`

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