tv.amwa.maj.iface
Interface EssenceAccess

All Superinterfaces:

EssenceMultiAccess

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 master mob 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.

Author:

Richard Cartwright

See Also:

EssenceFormat, EssenceData, MasterMob

Method Summary

void	completeWrite() Handle any format related writing at the end of the essence and adjust mob 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.iface.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, CodecDefinition.getCodecFlavours()

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, CodecDefinition.forIdentification(AUID)

completeWrite

void completeWrite()
                   throws StreamFullException

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

Throws:

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