EssenceSource Class Reference

Abstract super-class for objects that supply large quantities of essence data. More...

#include <essence.h>

Inheritance diagram for EssenceSource:

List of all members.

Public Member Functions
	EssenceSource ()
virtual	~EssenceSource ()
	Virtual destructor to allow polymorphism.
virtual size_t	GetEssenceDataSize (void)=0
	Get the size of the essence data in bytes.
virtual DataChunkPtr	GetEssenceData (size_t Size=0, size_t MaxSize=0)=0
	Get the next "installment" of essence data.
virtual bool	EndOfItem (void)=0
	Did the last call to GetEssenceData() return the end of a wrapping item.
virtual bool	EndOfData (void)=0
	Is all data exhasted?
virtual UInt8	GetGCEssenceType (void)=0
	Get the GCEssenceType to use when wrapping this essence in a Generic Container.
virtual UInt8	GetGCElementType (void)=0
	Get the GCEssenceType to use when wrapping this essence in a Generic Container.
void	SetStreamID (GCStreamID NewID)
	Set the stream ID for this stream or sub-stream.
GCStreamID	GetStreamID (void)
	Get the stream ID for this stream or sub-stream.
virtual bool	IsEditPoint (void)
	Is the last data read the start of an edit point?
virtual Rational	GetEditRate (void)=0
	Get the edit rate of this wrapping of the essence.
virtual Position	GetCurrentPosition (void)=0
	Get the current position in GetEditRate() sized edit units.
virtual int	GetBERSize (void)
	Get the preferred BER length size for essence KLVs written from this source, 0 for auto.
virtual bool	SetOption (std::string Option, Int64 Param=0)
	Set a source type or parser specific option.
virtual UInt32	GetBytesPerEditUnit (UInt32 KAGSize=1)
	Get BytesPerEditUnit if Constant, else 0.
virtual bool	CanIndex ()
	Can this stream provide indexing.
virtual void	SetIndexManager (IndexManagerPtr &Manager, int StreamID)
	Set the index manager to use for building index tables for this essence.
virtual IndexManagerPtr &	GetIndexManager (void)
	Get the index manager.
virtual int	GetIndexStreamID (void)
	Get the index manager sub-stream ID.
virtual void	SetKey (DataChunkPtr &Key, bool NonGC=false)
	Override the default essence key.
virtual DataChunkPtr &	GetKey (void)
	Get the current overridden essence key.
virtual bool	GetNonGC (void)
	Get true if the default essence key has been overriden with a key that does not use GC track number mechanism.
virtual bool	IsPictureEssence (void)
	Is this picture essence?
virtual bool	IsSoundEssence (void)
	Is this sound essence?
virtual bool	IsDataEssence (void)
	Is this data essence?
virtual bool	IsCompoundEssence (void)
	Is this compound essence?
virtual Int32	RelativeWriteOrder (void)
	An indication of the relative write order to use for this stream.
virtual int	RelativeWriteOrderType (void)
	The type for relative write-order positioning if RelativeWriteOrder() != 0.
virtual Length	GetPrechargeSize (void)
	Get the origin value to use for this essence specifically to take account of pre-charge.
virtual Position	GetRangeStart (void)
	Get the range start position.
virtual Position	GetRangeEnd (void)
	Get the range end position.
virtual Length	GetRangeDuration (void)
	Get the range duration.
Protected Attributes
GCStreamID	StreamID
	Holds the stream ID for this essence stream when added to a GCWriter.
IndexManagerPtr	IndexMan
	Index manager to use if we can index the essence.
int	IndexStreamID
	Sub-stream ID to use for our index data if we can index the essence.
DataChunkPtr	SpecifiedKey
	If the default essence key has been overridden for this source it is stored here.
bool	NonGC
	True if the default essence key has been overridden with a key that does not use GC track number mechanism.

---

Detailed Description

Abstract super-class for objects that supply large quantities of essence data.

This is used when clip-wrapping to prevent large quantities of data being loaded into memory !

Note:

Classes derived from this class must not include their own RefCount<> derivation

---

Constructor & Destructor Documentation

EssenceSource

(

)

[inline]

virtual ~EssenceSource

(

)

[inline, virtual]

Virtual destructor to allow polymorphism.

---

Member Function Documentation

virtual size_t GetEssenceDataSize

(

void

)

[pure virtual]

Get the size of the essence data in bytes.

Note:

There is intentionally no support for an "unknown" response

Implemented in DV_DIF_EssenceSubParser::ESP_EssenceSource, JP2K_EssenceSubParser::ESP_EssenceSource, MPEG2_VES_EssenceSubParser::ESP_EssenceSource, TEMPLATE_EssenceSubParser::ESP_EssenceSource, WAVE_PCM_EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual DataChunkPtr GetEssenceData	(	size_t	Size = 0,
		size_t	MaxSize = 0
	)			[pure virtual]

Get the next "installment" of essence data.

This will attempt to return an entire wrapping unit (e.g. a full frame for frame-wrapping) but will return it in smaller chunks if this would break the MaxSize limit. If a Size is specified then the chunk returned will end at the first wrapping unit end encountered before Size. On no account will portions of two or more different wrapping units be returned together. The mechanism for selecting a type of wrapping (e.g. frame, line or clip) is not (currently) part of the common EssenceSource interface.

Returns:

Pointer to a data chunk holding the next data or a NULL pointer when no more remains

Note:

If there is more data to come but it is not currently available the return value will be a pointer to an empty data chunk

If Size = 0 the object will decide the size of the chunk to return

On no account will the returned chunk be larger than MaxSize (if MaxSize > 0)

Implemented in DV_DIF_EssenceSubParser::ESP_EssenceSource, JP2K_EssenceSubParser::ESP_EssenceSource, MPEG2_VES_EssenceSubParser::ESP_EssenceSource, TEMPLATE_EssenceSubParser::ESP_EssenceSource, WAVE_PCM_EssenceSubParser::ESP_EssenceSource, EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual bool EndOfItem

(

void

)

[pure virtual]

Did the last call to GetEssenceData() return the end of a wrapping item.

Returns:

true if the last call to GetEssenceData() returned an entire wrapping unit.

true if the last call to GetEssenceData() returned the last chunk of a wrapping unit.

true if the last call to GetEssenceData() returned the end of a clip-wrapped clip.

false if there is more data pending for the current wrapping unit.

false if the source is to be clip-wrapped and there is more data pending for the clip

Implemented in MPEG2_VES_EssenceSubParser::ESP_EssenceSource, WAVE_PCM_EssenceSubParser::ESP_EssenceSource, EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual bool EndOfData

(

void

)

[pure virtual]

Is all data exhasted?

Returns:

true if a call to GetEssenceData() will return some valid essence data

Implemented in EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual UInt8 GetGCEssenceType

(

void

)

[pure virtual]

Get the GCEssenceType to use when wrapping this essence in a Generic Container.

Implemented in EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual UInt8 GetGCElementType

(

void

)

[pure virtual]

Get the GCEssenceType to use when wrapping this essence in a Generic Container.

Implemented in EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

void SetStreamID

(

GCStreamID

NewID

)

[inline]

Set the stream ID for this stream or sub-stream.

GCStreamID GetStreamID

(

void

)

[inline]

Get the stream ID for this stream or sub-stream.

virtual bool IsEditPoint

(

void

)

[inline, virtual]

Is the last data read the start of an edit point?

Reimplemented in MPEG2_VES_EssenceSubParser::ESP_EssenceSource, EssenceSubParser::ESP_EssenceSource, and FileParser::SequentialEssenceSource.

virtual Rational GetEditRate

(

void

)

[pure virtual]

Get the edit rate of this wrapping of the essence.

Note:

This may not be the same as the original "native" edit rate of the essence if this EssenceSource is wrapping to a different edit rate

Implemented in EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual Position GetCurrentPosition

(

void

)

[pure virtual]

Get the current position in GetEditRate() sized edit units.

This is relative to the start of the stream, so the first edit unit is always 0. This is the same as the number of edit units read so far, so when the essence is exhausted the value returned shall be the size of the essence

Implemented in EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual int GetBERSize

(

void

)

[inline, virtual]

Get the preferred BER length size for essence KLVs written from this source, 0 for auto.

Reimplemented in DV_DIF_EssenceSubParser::ESP_EssenceSource, JP2K_EssenceSubParser::ESP_EssenceSource, MPEG2_VES_EssenceSubParser::ESP_EssenceSource, WAVE_PCM_EssenceSubParser::ESP_EssenceSource, FileParser::SequentialEssenceSource, and VBISource.

virtual bool SetOption	(	std::string	Option,
		Int64	Param = 0
	)			[inline, virtual]

Set a source type or parser specific option.

Returns:

true if the option was successfully set

Reimplemented in EssenceSubParser::ESP_EssenceSource, and FileParser::SequentialEssenceSource.

virtual UInt32 GetBytesPerEditUnit

(

UInt32

KAGSize = 1

)

[inline, virtual]

Get BytesPerEditUnit if Constant, else 0.

Note:

This value may be useful even if CanIndex() returns false

Reimplemented in EssenceSubParser::ESP_EssenceSource, and FileParser::SequentialEssenceSource.

virtual bool CanIndex

(

)

[inline, virtual]

Can this stream provide indexing.

If true then SetIndex Manager can be used to set the index manager that will receive indexing data

Reimplemented in EssenceSubParser::ESP_EssenceSource, and FileParser::SequentialEssenceSource.

virtual void SetIndexManager	(	IndexManagerPtr &	Manager,
		int	StreamID
	)			[inline, virtual]

Set the index manager to use for building index tables for this essence.

Note:

The values are stored even if this stream does not support indexing as a derived stream may do

Reimplemented in EssenceSubParser::ESP_EssenceSource, and FileParser::SequentialEssenceSource.

virtual IndexManagerPtr& GetIndexManager

(

void

)

[inline, virtual]

Get the index manager.

Reimplemented in FileParser::SequentialEssenceSource.

virtual int GetIndexStreamID

(

void

)

[inline, virtual]

Get the index manager sub-stream ID.

Reimplemented in FileParser::SequentialEssenceSource.

virtual void SetKey	(	DataChunkPtr &	Key,
		bool	NonGC = false
	)			[inline, virtual]

Override the default essence key.

virtual DataChunkPtr& GetKey

(

void

)

[inline, virtual]

Get the current overridden essence key.

DRAGONS: If the key has not been overridden NULL will be returned - not the default key

Note:

Defined EssenceSource sub-classes may always use a non-standard key, in which case they will always return a non-NULL value from this function

virtual bool GetNonGC

(

void

)

[inline, virtual]

Get true if the default essence key has been overriden with a key that does not use GC track number mechanism.

virtual bool IsPictureEssence

(

void

)

[inline, virtual]

Is this picture essence?

Reimplemented in VBISource.

virtual bool IsSoundEssence

(

void

)

[inline, virtual]

Is this sound essence?

Reimplemented in VBISource.

virtual bool IsDataEssence

(

void

)

[inline, virtual]

Is this data essence?

Reimplemented in VBISource.

virtual bool IsCompoundEssence

(

void

)

[inline, virtual]

Is this compound essence?

Reimplemented in VBISource.

virtual Int32 RelativeWriteOrder

(

void

)

[inline, virtual]

An indication of the relative write order to use for this stream.

Normally streams in a GC are ordered as follows:

• All the CP system items (in Scheme ID then Element ID order)
• All the GC system items (in Scheme ID then Element ID order)
• All the CP picture items (in Element ID then Element Number order)
• All the GC picture items (in Element ID then Element Number order)
• All the CP sound items (in Element ID then Element Number order)
• All the GC sound items (in Element ID then Element Number order)
• All the CP data items (in Element ID then Element Number order)
• All the GC data items (in Element ID then Element Number order)
• All the GC compound items (in Element ID then Element Number order) (no GC compound)

However, sometimes this order needs to be overridden - such as for VBI data preceding picture items.

The normal case for ordering of an essence stream is for RelativeWriteOrder to return 0, indicating that the default ordering is to be used. Any other value indicates that relative ordering is required, and this is used as the Position value for a SetRelativeWriteOrder() call. The value of Type for that call is acquired from RelativeWriteOrderType()

For example: to force a source to be written between the last GC sound item and the first CP data item, RelativeWriteOrder() can return any -ve number, with RelativeWriteOrderType() returning 0x07 (meaning before CP data). Alternatively RelativeWriteOrder() could return a +ve number and RelativeWriteOrderType() return 0x16 (meaning after GC sound)

Reimplemented in VBISource.

virtual int RelativeWriteOrderType

(

void

)

[inline, virtual]

The type for relative write-order positioning if RelativeWriteOrder() != 0.

This method indicates the essence type to order this data before or after if reletive write-ordering is used

Reimplemented in VBISource.

virtual Length GetPrechargeSize

(

void

)

[inline, virtual]

Get the origin value to use for this essence specifically to take account of pre-charge.

Returns:

Zero if not applicable for this source

Reimplemented in FileParser::SequentialEssenceSource.

virtual Position GetRangeStart

(

void

)

[inline, virtual]

Get the range start position.

Returns:

Zero if not applicable for this source

Reimplemented in FileParser::SequentialEssenceSource.

virtual Position GetRangeEnd

(

void

)

[inline, virtual]

Get the range end position.

Returns:

-1 if not applicable for this source

Reimplemented in FileParser::SequentialEssenceSource.

virtual Length GetRangeDuration

(

void

)

[inline, virtual]

Get the range duration.

Returns:

-1 if not applicable for this source

Reimplemented in FileParser::SequentialEssenceSource.

---

Member Data Documentation

GCStreamID StreamID [protected]

Holds the stream ID for this essence stream when added to a GCWriter.

This value is persisted here between calls to a GCWriter via BodyWriter or similar. Set to -1 if no stream ID yet set.

IndexManagerPtr IndexMan [protected]

Index manager to use if we can index the essence.

int IndexStreamID [protected]

Sub-stream ID to use for our index data if we can index the essence.

DataChunkPtr SpecifiedKey [protected]

If the default essence key has been overridden for this source it is stored here.

bool NonGC [protected]

True if the default essence key has been overridden with a key that does not use GC track number mechanism.

---

The documentation for this class was generated from the following file:

• essence.h

---