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

tv.amwa.maj.model

## Interface EssenceMultiAccess

- All Known Subinterfaces:
    EssenceAccess
  All Known Implementing Classes:
    EssenceAccess, EssenceMultiAccess

      public interface EssenceMultiAccess

  Specifies streaming access over over multiple channels 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 `createMultiEssence()` or `openMultiEssence()` methods of material package in order to get an implementation of an essence multi-channel access, as no public create or open method in is specified in 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:
    `EssenceAccess`, `EssenceData`, `MaterialPackage`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `MultiResultItem[]` | `readMultiSamples(MultiXferItem[] xferArray)` Reads multiple channels of data from an interleaved data stream.
    `MultiResultItem[]` | `writeMultiSamples(MultiXferItem[] xferArray)` Writes multiple channels worth of sample data into the essence from an array of items representing interleaved data streams in the natural order for the codec.

- - ### Method Detail

    - #### writeMultiSamples

          MultiResultItem[] writeMultiSamples(MultiXferItem[] xferArray)
                                       throws NullPointerException,
                                              InvalidParameterException

      Writes multiple channels worth of sample data into the essence from an array of items representing interleaved data streams in the natural order for the codec. See `MultiXferItem` for details of the fields of each item.

      The array returned contains details of how many bytes and samples were transferred by the operation corresponding to each input item of the array given as a parameter. See `MultiResultItem` for more details.

      Parameters:
        `xferArray` - An array of transfer parameters. All fields of items in this array must be set up before performing the transfer.
      Returns:
        An array containing the details of how many bytes and samples were transferred for each item of the given array.
      Throws:
        `NullPointerException` - The given transfer array is `null` or one or more of its elements is `null`.
        `InvalidParameterException` - One or more of the parameters defined by an item of the given array is invalid.

    - #### readMultiSamples

          MultiResultItem[] readMultiSamples(MultiXferItem[] xferArray)
                                      throws NullPointerException,
                                             InvalidParameterException

      Reads multiple channels of data from an interleaved data stream. The given input array contains items that define which channel of data should be read. These items are modified by the operation by their data buffers being filled with data from the essence according to the parameters they specify. See `MultiXferItem` for more details.

      The array returned contains details of how many bytes and samples were transferred by the operation corresponding to each input item of the array given as a parameter. See `MultiResultItem` for more details.

      Parameters:
        `xferArray` - Array of transfer items to read data into.
      Returns:
        An array containing the details of how many bytes and samples were transferred array by the operation for each item of the given array.
      Throws:
        `NullPointerException` - The given transfer array is `null` or one or more of its elements is `null`.
        `InvalidParameterException` - One or more of the parameters defined by an item of the given array is invalid.

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