AAFEssenceAccess is an interace which provides streaming access over multiple channels of essence data. More...

Public Member Functions
HRESULT	SetEssenceCodecFlavour ([in, ref] aafUID_constref flavour)
	Sets which flavour of the codec ID is to be used.
HRESULT	WriteSamples ([in] aafUInt32 nSamples,[in] aafUInt32 buflen,[in, size_is(buflen)] aafDataBuffer_t buffer,[out, ref] aafUInt32 samplesWritten,[out, ref] aafUInt32 bytesWritten)
	Writes data to the given essence stream.
HRESULT	GetLargestSampleSize ([in] IAAFDataDef pDataDef,[out] aafLength_t maxSize)
	Returns the size in bytes of the largest sample for a given essence type.
HRESULT	GetIndexedSampleSize ([in] IAAFDataDef pDataDef,[in] aafPosition_t frameNum,[out] aafLength_t frameSize)
	Returns the size in bytes of the given sample for a given essence type.
HRESULT	SetTransformParameters ([in] IAAFEssenceFormat *op)
	Sets a series of format objects which will be used to describe the in-memory format.
HRESULT	CountSamples ([in] IAAFDataDef pDataDef,[out] aafLength_t result)
	Returns the number of samples of the given essence type on the given essence stream.
HRESULT	ReadSamples ([in] aafUInt32 nSamples,[in] aafUInt32 buflen,[out, size_is(buflen), length_is(bytesRead)] aafDataBuffer_t buffer,[out, ref] aafUInt32 samplesRead,[out, ref] aafUInt32 *bytesRead)
	Read a given number of samples from an opened essence stream.
HRESULT	Seek ([in] aafPosition_t sampleFrameNum)
	The seek function for essence.
HRESULT	GetFileFormat ([in] IAAFEssenceFormat opsTemplate,[out] IAAFEssenceFormat *opsResult)
	Given an AAFEssenceFormat, read the essence parameters inside and set the values from the file format.
HRESULT	GetFileFormatParameterList ([out] IAAFEssenceFormat **ops)
	Returns an AAFEssenceFormat containing a list of all parameters supported by the current codec.
HRESULT	GetEmptyFileFormat ([out] IAAFEssenceFormat **ops)
	Returns an empty AAFEssenceFormat object.
HRESULT	PutFileFormat ([in] IAAFEssenceFormat *ops)
	Given an AAFEssenceFormat, read the essence parameters inside and change the file format.
HRESULT	GetCodecName ([in] aafUInt32 namelen,[out, size_is(namelen)] aafCharacter *name)
	Returns the full name of the given codec expanded for human consumption.
HRESULT	GetCodecID ([out] aafCodecID_t *codecID)
	Returns the codec ID being used to handle the specified essence.
HRESULT	CompleteWrite ()
	Handle any format related writing at the end and adjust mob lengths.

Detailed Description

AAFEssenceAccess is an interace which provides streaming access 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 may need to QueryInterface for an AAFEssenceAccess interface in order to do non-read write operations such as seek.

You should call the CreateMultiEssence or OpenMultiEssence calls on AAFMasterMob in order to get an interface pointer to AAFEssenceAccess, as there is no public create or open method in the interface.

A number of errors can be returned from most method calls, These are: AAFRESULT_NOMEMORY -- The system ran out of memory processing the method. AAFRESULT_NULL_PARAM -- A NULL parameter was passed in which was required.

Objects that implement IAAFEssenceAccess also implement the following interfaces:

IAAFEssenceMultiAccess

Definition at line 7952 of file AAF.idl.

Member Function Documentation

HRESULT IAAFEssenceAccess::CompleteWrite ( )

Handle any format related writing at the end and adjust mob lengths.

Must be called before releasing a write essence access.

Possible Errors: AAFRESULT_STREAM_FULL

The essence can not be written because of a fault such as a disk full error in the underlying operating system.

HRESULT IAAFEssenceAccess::CountSamples	(	[in] IAAFDataDef *	pDataDef,
		[out] aafLength_t *	result
	)

Returns the number of samples of the given essence type on the given essence stream.

A video sample is one frame.

Parameters:

pDataDef	[in] For this essence dataDef
result	[out] find out how many samples are present

HRESULT IAAFEssenceAccess::GetCodecID ( [out] aafCodecID_t * codecID )

Returns the codec ID being used to handle the specified essence.

This will be required in order to send private data to the codec.

The name will be truncated to fit within "buflen" bytes.

Parameters:

codecID [out] Returns the current codec ID

HRESULT IAAFEssenceAccess::GetCodecName	(	[in] aafUInt32	namelen,
		[out, size_is(namelen)] aafCharacter *	name
	)

Returns the full name of the given codec expanded for human consumption.

No other call uses this name, so it may be fully descriptive, esp. of limitations.

The name will be truncated to fit within "buflen" bytes.

Possible Errors: AAFRESULT_CODEC_INVALID - The given codec ID is not loaded. AAFRESULT_SMALLBUF - The buffer is not large enough to hold the data.

Parameters:

namelen	[in] The size of the name buffer to be filled
name	[out,size_is(namelen)] The buffer to fill

HRESULT IAAFEssenceAccess::GetEmptyFileFormat ( [out] IAAFEssenceFormat ** ops )

Returns an empty AAFEssenceFormat object.

This is the factory method for AAFEssenceFormat.

Parameters:

ops	[out] An ampty AAFEssenceFormat object

HRESULT IAAFEssenceAccess::GetFileFormat	(	[in] IAAFEssenceFormat *	opsTemplate,
		[out] IAAFEssenceFormat **	opsResult
	)

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

Parameters:

opsTemplate	[in] An AAFEssenceFormat with parameter codes set but no values
opsResult	[out] Another AAFEssenceFormat with values set

HRESULT IAAFEssenceAccess::GetFileFormatParameterList ( [out] IAAFEssenceFormat ** ops )

Returns an AAFEssenceFormat containing a list of all parameters supported by the current codec.

Parameters:

ops	[out] An ampty AAFEssenceFormat object

HRESULT IAAFEssenceAccess::GetIndexedSampleSize	(	[in] IAAFDataDef *	pDataDef,
		[in] aafPosition_t	frameNum,
		[out] aafLength_t *	frameSize
	)

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 will propably be a constant.

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

Possible Errors: AAFRESULT_NULL_PARAM -- A return parameter was NULL. AAFRESULT_BADSAMPLEOFFSET -- The supplied sample offset is out of range.

Parameters:

pDataDef	[in] and this essence type
frameNum	[in] for this [0-based] sample frame number
frameSize	[out] How big is the sample frame?

HRESULT IAAFEssenceAccess::GetLargestSampleSize	(	[in] IAAFDataDef *	pDataDef,
		[out] aafLength_t *	maxSize
	)

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 will propably be a constant.

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

Parameters:

pDataDef	[in] for this essence type
maxSize	[out] the largest sample size

HRESULT IAAFEssenceAccess::PutFileFormat ( [in] IAAFEssenceFormat * ops )

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

Parameters:

ops	[in] An AAFEssenceFormat with one or more parameter/value pairs

HRESULT IAAFEssenceAccess::ReadSamples	(	[in] aafUInt32	nSamples,
		[in] aafUInt32	buflen,
		[out, size_is(buflen), length_is(*bytesRead)] aafDataBuffer_t	buffer,
		[out, ref] aafUInt32 *	samplesRead,
		[out, ref] aafUInt32 *	bytesRead
	)

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 video sample is a frame.

Buflen is in bytes, and should be large enough to hold the samples after the requested transforms have been applied.

Possible Errors: AAFRESULT_END_OF_DATA -- Hit the end of the essence (like EOF) while reading. AAFRESULT_SMALLBUF -- Buffer too small for samples.

Parameters:

nSamples	[in] Read this many samples
buflen	[in] into a buffer of this size
buffer	[out, size_is(buflen),length_is(*bytesRead)] The transfer buffer
samplesRead	[out, ref] The number of samples actually read
bytesRead	[out, ref] The number of bytes actually read

HRESULT IAAFEssenceAccess::Seek ( [in] aafPosition_t sampleFrameNum )

The seek function for essence.

Useful only on reading, you can't seek aound while writing essence.

An audio frame is one sample across all channels.

Possible Errors: AAFRESULT_BADSAMPLEOFFSET -- Hit the end of the essence (like EOF) while reading.

Parameters:

sampleFrameNum [in] A 0-based offset in units of the sample rate to seek to.

HRESULT IAAFEssenceAccess::SetEssenceCodecFlavour ( [in, ref] aafUID_constref flavour )

Sets which flavour of the codec ID is to be used.

An example of a flavour would be a number of standard starting JPEG tables.

Parameters:

flavour [in, ref] The particular flavour

HRESULT IAAFEssenceAccess::SetTransformParameters ( [in] IAAFEssenceFormat * op )

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	[in] A set of transforms to apply to the essence if required

HRESULT IAAFEssenceAccess::WriteSamples	(	[in] aafUInt32	nSamples,
		[in] aafUInt32	buflen,
		[in, size_is(buflen)] aafDataBuffer_t	buffer,
		[out, ref] aafUInt32 *	samplesWritten,
		[out, ref] aafUInt32 *	bytesWritten
	)

Writes data to the given essence stream.

A single video frame is ONE sample.

Buflen must be large enough to hold the total sample size.

Possible Errors: AAFRESULT_SINGLE_CHANNEL_OP -- Tried to write to an interleaved stream. AAFRESULT_BADDATAADDRESS -- The buffer must not be a NULL pointer.

Parameters:

nSamples	[in] write this many samples
buflen	[in] from a buffer of this size
buffer	[in,size_is(buflen)] from a buffer
samplesWritten	[out, ref] The number of samples actually written
bytesWritten	[out, ref] The number of bytes actually written

Public Member Functions

Detailed Description

Member Function Documentation