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

tv.amwa.maj.model

## Interface EssenceAccess

- All Superinterfaces:
    EssenceMultiAccess
  All Known Implementing Classes:
    EssenceAccess

      public interface EssenceAccess
      extends EssenceMultiAccess

  Specifies streaming access over a single channel of essence data. This interface deals with essence data which is in an uncompressed form, and handles compression or decompression of the data if required.

  You should call the `createEssence()` or `openEssence()` methods on material package in order to get an implementation of essence access, as no public constructor or other open method is specified by this interface.

  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:
    `EssenceFormat`, `EssenceData`, `MaterialPackage`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `completeWrite()` Handle any format related writing at the end of the essence and adjust package lengths as required.
    `long` | `countSamples(DataDefinition essenceType)` Returns the number of samples of the given essence type on the essence stream.
    `AUID` | `getCodecID()` Returns the identifier of the codec being used to handle the specified essence.
    `String` | `getCodecName()` Returns the friendly name of the codec expanded for human consumption.
    `EssenceFormat` | `getEmptyFileFormat()` Returns an empty `EssenceFormat` object.
    `EssenceFormat` | `getFileFormat(EssenceFormat opsTemplate)` Given an AAFEssenceFormat, read the essence parameters inside and set the values from the file format.
    `EssenceFormat` | `getFileFormatParametersList()` Returns a list of all file format parameters supported by the current codec.
    `long` | `getIndexedSampleSize(DataDefinition dataDef, long frameNumber)` Returns the size in bytes of the given sample for a given essence type.
    `long` | `getLargestSampleSize(DataDefinition essenceType)` Returns the size in bytes of the largest sample for a given essence type.
    `int` | `getSamplesActuallyRead()` Returns the number of samples actually read by the last call to `readSamples(int)`.
    `void` | `putFileFormat(EssenceFormat ops)` Given an `EssenceFormat`, read the essence parameters inside and change the file format.
    `byte[]` | `readSamples(int nSamples)` Read a given number of samples from an opened essence stream.
    `void` | `seek(long sampleFrameNum)` The seek function for essence.
    `void` | `setEssenceCodecFlavour(AUID flavour)` Sets which flavour of the codec for the essence is to be used.
    `void` | `setTransformParameters(List<? extends EssenceFormat> op)` Sets a series of format objects which will be used to describe the in-memory format.
    `int` | `writeSamples(int nSamples, byte[] buffer)` Writes data to the essence stream.

    - ### Methods inherited from interface tv.amwa.maj.model.EssenceMultiAccess

      `readMultiSamples, writeMultiSamples`

- - ### Method Detail

    - #### setEssenceCodecFlavour

          void setEssenceCodecFlavour(AUID flavour)
                               throws NullPointerException

      Sets which flavour of the codec for the essence is to be used.

      Parameters:
        `flavour` - The codec flavour to be used.
      Throws:
        `NullPointerException` - The given codec flavour is `null`.
      See Also:
        `CodecFlavour`

    - #### writeSamples

          @UInt32
          int writeSamples(@UInt32
                                   int nSamples,
                                   @DataBuffer
                                   byte[] buffer)
                            throws NullPointerException,
                                   SingleChannelOpException

      Writes data to the essence stream.

      A single video frame is one sample.

      Parameters:
        `nSamples` - Write this many samples.
        `buffer` - Buffer to write data from.
      Returns:
        The number of samples actually written.
      Throws:
        `NullPointerException` - The given buffer is `null`.
        `SingleChannelOpException` - Tried to write to an interleaved stream.

    - #### getLargestSampleSize

          @LengthType
          long getLargestSampleSize(DataDefinition essenceType)
                                         throws NullPointerException

      Returns the size in bytes of the largest sample for a given essence type.

      For uncompressed data, or the output of the software codec, the sample size is likely to be a constant value.

      The essence type parameter exists to support codecs with multiple interleaved essence types.

      Parameters:
        `essenceType` - The essence type.
      Returns:
        The largest sample size for the given essence type.
      Throws:
        `NullPointerException` - The given essence type is `null`

    - #### getIndexedSampleSize

          @LengthType
          long getIndexedSampleSize(DataDefinition dataDef,
                                                @PositionType
                                                long frameNumber)
                                         throws NullPointerException,
                                                BadSampleOffsetException

      Returns the size in bytes of the given sample for a given essence type. For uncompressed data, or the output of the software codec, the sample size is likely be a constant value.

      The essence type parameter exists to support codecs with multiple interleaved essence types.

      Parameters:
        `dataDef` - The essence type.
        `frameNumber` - The 0-based index of a sample frame number.
      Returns:
        Size of the sample frame at the given index for the given type of data.
      Throws:
        `NullPointerException` - The given essence type is `null`.
        `BadSampleOffsetException` - The supplied sample offset is outside the acceptable range for the essence.

    - #### setTransformParameters

          void setTransformParameters(List<? extends EssenceFormat> op)
                               throws NullPointerException

      Sets a series of format objects which will be used to describe the in-memory format. This is the format expected on writes and produced on reads. On writes, the data will be written in this format, except where a software codec may be used. On reads, the data will be translated to this format.

      The order of the parameters does matter, as transformations will be applied in that order to get from the on-disk format to the in-memory format.

      Parameters:
        `op` - An ordered list iterator over transforms to apply to the essence if required.
      Throws:
        `NullPointerException` - Argument is null.

    - #### countSamples

          @LengthType
          long countSamples(DataDefinition essenceType)
                                 throws NullPointerException

      Returns the number of samples of the given essence type on the essence stream. A video sample is one frame.

      Parameters:
        `essenceType` - Type of essence to count.
      Returns:
        Number of samples that are present for the given essence type.
      Throws:
        `NullPointerException` - The given essence type is `null`.

    - #### readSamples

          @DataBuffer
          byte[] readSamples(@UInt32
                                         int nSamples)
                                  throws EndOfDataException

      Read a given number of samples from an opened essence stream. This call will only return a single channel of essence from an interleaved stream. A signle video sample is a frame.

      Parameters:
        `nSamples` - Read this many samples.
      Returns:
        Buffer containing samples.
      Throws:
        `EndOfDataException` - Hit the end of the essence (like EOF) while reading.

    - #### getSamplesActuallyRead

          @UInt32
          int getSamplesActuallyRead()

      Returns the number of samples actually read by the last call to `readSamples(int)`.

      Returns:
        Number of samples actually read. Will return 0 if `readSamples(int)` has not previously been called or 0 samples were read.

    - #### seek

          void seek(@PositionType
                    long sampleFrameNum)
             throws BadSampleOffsetException

      The seek function for essence. Useful only on reading as you cannot seek around while writing essence.

      An audio frame is one sample across all channels.

      Parameters:
        `sampleFrameNum` - A 0-based offset in units of the sample rate to seek to.
      Throws:
        `BadSampleOffsetException` - Hit the end of the essence (like EOF) while reading.

    - #### getFileFormat

          EssenceFormat getFileFormat(EssenceFormat opsTemplate)
                               throws NullPointerException,
                                      InvalidParameterException

      Given an AAFEssenceFormat, read the essence parameters inside and set the values from the file format.

      Parameters:
        `opsTemplate` - An `EssenceFormat` with parameter codes set but no values.
      Returns:
        Another `EssenceFormat` with values set.
      Throws:
        `NullPointerException` - Argument is null.
        `InvalidParameterException` - Matching parameter not found.

    - #### getFileFormatParametersList

          EssenceFormat getFileFormatParametersList()

      Returns a list of all file format parameters supported by the current codec.

      Returns:
        List of file format parameters.

    - #### getEmptyFileFormat

          EssenceFormat getEmptyFileFormat()

      Returns an empty `EssenceFormat` object. This is the factory method for EssenceFormat.

      Returns:
        An empty essence format object.

    - #### putFileFormat

          void putFileFormat(EssenceFormat ops)
                      throws NullPointerException

      Given an `EssenceFormat`, read the essence parameters inside and change the file format.

      Parameters:
        `ops` - An `EssenceFormat` with one or more parameter/value pairs.
      Throws:
        `NullPointerException` - Argument is null.

    - #### getCodecName

          @AAFString
          String getCodecName()

      Returns the friendly name of the codec expanded for human consumption. No other call uses this name, so it may be fully descriptive, especially of limitations.

      Returns:
        Human-readable name and optional description of codec.

    - #### getCodecID

          @CodecID
          AUID getCodecID()

      Returns the identifier of the codec being used to handle the specified essence. This will be required in order to be able to send private data to the codec.

      Returns:
        The current codec used for accessing the essence.
      See Also:
        `CodecDefinition`, `CodecConstant`

    - #### completeWrite

          void completeWrite()
                      throws StreamFullException

      Handle any format related writing at the end of the essence and adjust package lengths as required. Must be called before releasing a write essence access.

      Throws:
        `StreamFullException` - The stream has insufficient capacity to complete the write operation.

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