EssenceSource Class Reference

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

#include <essence.h>

Inheritance diagram for EssenceSource:

RefCount IRefCount EssenceSubParser::ESP_EssenceSource FileParser::SequentialEssenceSource VBISource DV_DIF_EssenceSubParser::ESP_EssenceSource JP2K_EssenceSubParser::ESP_EssenceSource MPEG2_VES_EssenceSubParser::ESP_EssenceSource TEMPLATE_EssenceSubParser::ESP_EssenceSource WAVE_PCM_EssenceSubParser::ESP_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 IndexManagerPtrGetIndexManager (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 DataChunkPtrGetKey (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:

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:
Generated on Mon Apr 2 15:20:58 2007 for MXFLib by  doxygen 1.5.1-p1