GCWriter Class Reference

Class that manages writing of generic container essence. More...

#include <essence.h>

Inheritance diagram for GCWriter:

List of all members.

Public Types
typedef std::map< UInt32, WriteBlock >	WriteQueueMap
	Type for holding the write queue in write order.
Public Member Functions
	GCWriter (MXFFilePtr File, UInt32 BodySID=0, int Base=0)
	Constructor.
	~GCWriter ()
	Destructor.
void	SetKAG (UInt32 KAG, bool ForceBER4=false)
	Set the KAG for this Essence Container.
UInt32	GetKAG (void)
	Get the current KAGSize.
GCStreamID	AddSystemElement (unsigned int RegistryDesignator, unsigned int SchemeID, unsigned int ElementID, unsigned int SubID=0)
	Define a new non-CP system element for this container.
GCStreamID	AddCPSystemElement (unsigned int RegistryDesignator, unsigned int SchemeID, unsigned int ElementID, unsigned int SubID=0)
	Define a new CP-compatible system element for this container.
GCStreamID	AddSystemElement (bool CPCompatible, unsigned int RegistryDesignator, unsigned int SchemeID, unsigned int ElementID, unsigned int SubID=0)
	Define a new system element for this container.
GCStreamID	AddPictureElement (unsigned int ElementType)
	Define a new non-CP picture element for this container.
GCStreamID	AddCPPictureElement (unsigned int ElementType)
	Define a new CP-compatible picture element for this container.
GCStreamID	AddPictureElement (bool CPCompatible, unsigned int ElementType)
	Define a new picture element for this container.
GCStreamID	AddSoundElement (unsigned int ElementType)
	Define a new non-CP sound element for this container.
GCStreamID	AddCPSoundElement (unsigned int ElementType)
	Define a new CP-compatible sound element for this container.
GCStreamID	AddSoundElement (bool CPCompatible, unsigned int ElementType)
	Define a new sound element for this container.
GCStreamID	AddDataElement (unsigned int ElementType)
	Define a new non-CP data element for this container.
GCStreamID	AddCPDataElement (unsigned int ElementType)
	Define a new CP-compatible data element for this container.
GCStreamID	AddDataElement (bool CPCompatible, unsigned int ElementType)
	Define a new data element for this container.
GCStreamID	AddCompoundElement (unsigned int ElementType)
	Define a new compound element for this container.
GCStreamID	AddEssenceElement (unsigned int EssenceType, unsigned int ElementType, int LenSize=0)
	Define a new essence element for this container.
GCStreamID	AddEssenceElement (DataChunkPtr &Key, int LenSize=0, bool NonGC=false)
	Define a new essence element for this container, with a specified key.
GCStreamID	AddEssenceElement (int KeySize, UInt8 *KeyData, int LenSize=0, bool NonGC=false)
	Define a new essence element for this container, with a specified key.
void	AddStreamIndex (GCStreamID ID, IndexManagerPtr &IndexMan, int IndexSubStream, bool IndexFiller=false, bool IndexClip=false)
	Allow this data stream to be indexed and set the index manager.
UInt32	GetTrackNumber (GCStreamID ID)
	Get the track number associated with the specified stream.
void	AssignEssenceUL (GCStreamID ID, ULPtr EssenceUL)
	Assign an essence container (mapping) UL to the specified stream.
void	StartNewCP (void)
	Start a new content package (and write out the prevous one if required).
UInt64	CalcWriteSize (void)
	Calculate how much data will be written if "Flush" is called now.
void	Flush (void)
	Flush any remaining data.
Int64	GetStreamOffset (void)
	Get the current stream offset.
void	SetIndexEditUnit (Position EditUnit)
	Set the index position for the current CP.
Position	GetIndexEditUnit (void)
	Get the index position of the current CP.
void	AddSystemData (GCStreamID ID, UInt64 Size, const UInt8 *Data)
	Add system item data to the current CP.
void	AddSystemData (GCStreamID ID, DataChunkPtr Chunk)
	Add system item data to the current CP.
void	AddSystemData (GCStreamID ID, UInt64 Size, const UInt8 *Data, UUIDPtr ContextID, Length PlaintextOffset=0)
	Add encrypted system item data to the current CP.
void	AddSystemData (GCStreamID ID, DataChunkPtr Chunk, UUIDPtr ContextID, Length PlaintextOffset=0)
	Add encrypted system item data to the current CP.
void	AddEssenceData (GCStreamID ID, UInt64 Size, const UInt8 *Data)
	Add essence data to the current CP.
void	AddEssenceData (GCStreamID ID, DataChunkPtr Chunk)
	Add essence data to the current CP.
void	AddEssenceData (GCStreamID ID, EssenceSourcePtr Source, bool FastClipWrap=false)
	Add essence data to the current CP.
void	AddEssenceData (GCStreamID ID, KLVObjectPtr Source, bool FastClipWrap=false)
	Add an essence item to the current CP with the essence to be read from a KLVObject.
Length	CalcRawSize (KLVObjectPtr Object)
	Calculate how many bytes would be written if the specified object were written with WriteRaw().
void	WriteRaw (KLVObjectPtr Object)
	Write a raw KLVObject to the file - this is written immediately and not buffered in the WriteQueue.
void	SetWriteOrder (GCStreamID ID, Int32 WriteOrder=-1, int Type=-1)
	Set the WriteOrder for the specified stream.
void	SetRelativeWriteOrder (GCStreamID ID, int Type, Int32 Position)
	Set a write-order relative to all items of a specified type.
Int32	GetWriteOrder (GCStreamID ID)
	Get the WriteOrder for the specified stream.
int	GetStreamCount (void)
	Read the count of streams.
Public Attributes
WriteQueueMap	WriteQueue
	Queue of items for the current content package in write order.
Protected Attributes
MXFFilePtr	LinkedFile
	File that will be written to.
UInt32	TheBodySID
	Body SID for this Essence Container.
int	StreamTableSize
	Size of StreamTable.
int	StreamCount
	Number of entries in use in StreamTable.
int	StreamBase
	Base of all stream numbers in keys.
GCStreamData *	StreamTable
	Table of data for streams for this GC.
UInt32	KAGSize
	KAGSize for this Essence Container.
bool	ForceFillerBER4
	True if filler items must have BER lengths forced to 4-byte BER.
Int32	NextWriteOrder
	The "WriteOrder" to use for the next auto "SetWriteOrder()".
Position	IndexEditUnit
	Edit unit of the current CP for use if indexing.
UInt64	StreamOffset
	Current stream offset within this essence container.
std::map< UInt32, GCStreamID >	WriteOrderMap
	Map of all used write orders to stream ID - used to ensure no duplicates.
Classes
struct	WriteBlock
	Structure for items to be written. More...

---

Detailed Description

Class that manages writing of generic container essence.

---

Member Typedef Documentation

typedef std::map<UInt32,WriteBlock> WriteQueueMap

Type for holding the write queue in write order.

---

Constructor & Destructor Documentation

GCWriter	(	MXFFilePtr	File,
		UInt32	BodySID = 0,
		int	Base = 0
	)

Constructor.

~GCWriter

(

)

Destructor.

---

Member Function Documentation

void SetKAG	(	UInt32	KAG,
		bool	ForceBER4 = false
	)			[inline]

Set the KAG for this Essence Container.

UInt32 GetKAG

(

void

)

[inline]

Get the current KAGSize.

GCStreamID AddSystemElement	(	unsigned int	RegistryDesignator,
		unsigned int	SchemeID,
		unsigned int	ElementID,
		unsigned int	SubID = 0
	)			[inline]

Define a new non-CP system element for this container.

GCStreamID AddCPSystemElement	(	unsigned int	RegistryDesignator,
		unsigned int	SchemeID,
		unsigned int	ElementID,
		unsigned int	SubID = 0
	)			[inline]

Define a new CP-compatible system element for this container.

GCStreamID AddSystemElement	(	bool	CPCompatible,
		unsigned int	RegistryDesignator,
		unsigned int	SchemeID,
		unsigned int	ElementID,
		unsigned int	SubID = 0
	)

Define a new system element for this container.

GCStreamID AddPictureElement

(

unsigned int

ElementType

)

[inline]

Define a new non-CP picture element for this container.

GCStreamID AddCPPictureElement

(

unsigned int

ElementType

)

[inline]

Define a new CP-compatible picture element for this container.

GCStreamID AddPictureElement	(	bool	CPCompatible,
		unsigned int	ElementType
	)			[inline]

Define a new picture element for this container.

GCStreamID AddSoundElement

(

unsigned int

ElementType

)

[inline]

Define a new non-CP sound element for this container.

GCStreamID AddCPSoundElement

(

unsigned int

ElementType

)

[inline]

Define a new CP-compatible sound element for this container.

GCStreamID AddSoundElement	(	bool	CPCompatible,
		unsigned int	ElementType
	)			[inline]

Define a new sound element for this container.

GCStreamID AddDataElement

(

unsigned int

ElementType

)

[inline]

Define a new non-CP data element for this container.

GCStreamID AddCPDataElement

(

unsigned int

ElementType

)

[inline]

Define a new CP-compatible data element for this container.

GCStreamID AddDataElement	(	bool	CPCompatible,
		unsigned int	ElementType
	)			[inline]

Define a new data element for this container.

GCStreamID AddCompoundElement

(

unsigned int

ElementType

)

[inline]

Define a new compound element for this container.

GCStreamID AddEssenceElement	(	unsigned int	EssenceType,
		unsigned int	ElementType,
		int	LenSize = 0
	)

Define a new essence element for this container.

GCStreamID AddEssenceElement	(	DataChunkPtr &	Key,
		int	LenSize = 0,
		bool	NonGC = false
	)

Define a new essence element for this container, with a specified key.

GCStreamID AddEssenceElement	(	int	KeySize,
		UInt8 *	KeyData,
		int	LenSize = 0,
		bool	NonGC = false
	)			[inline]

Define a new essence element for this container, with a specified key.

void AddStreamIndex	(	GCStreamID	ID,
		IndexManagerPtr &	IndexMan,
		int	IndexSubStream,
		bool	IndexFiller = false,
		bool	IndexClip = false
	)

Allow this data stream to be indexed and set the index manager.

UInt32 GetTrackNumber

(

GCStreamID

ID

)

Get the track number associated with the specified stream.

Note:

Once this function has been called for a stream, or an element of the stream has been written, the value of "EssenceElementCount" will be frozen, even if new elements are added. (See SMPTE-379M section 7.1)

Unusual results are likely if called with the ID of a system item!

void AssignEssenceUL	(	GCStreamID	ID,
		ULPtr	EssenceUL
	)

Assign an essence container (mapping) UL to the specified stream.

void StartNewCP

(

void

)

Start a new content package (and write out the prevous one if required).

UInt64 CalcWriteSize

(

void

)

Calculate how much data will be written if "Flush" is called now.

Note:

Will return (2^64)-1 if the buffer contains a "FastClipWrap" item

The last type written - KAG alignment is performed between different types

void Flush

(

void

)

Flush any remaining data.

Note:

It is important that any changes to this function are propogated to CalcWriteSize()

Stream offset of the first byte of the key for this KLV - this will later be turned into the size of the (Key+Length) once they are written

The last type written - KAG alignment is performed between different types

Int64 GetStreamOffset

(

void

)

[inline]

Get the current stream offset.

void SetIndexEditUnit

(

Position

EditUnit

)

[inline]

Set the index position for the current CP.

Position GetIndexEditUnit

(

void

)

[inline]

Get the index position of the current CP.

void AddSystemData	(	GCStreamID	ID,
		UInt64	Size,
		const UInt8 *	Data
	)

Add system item data to the current CP.

Template for all GC system item keys

DRAGONS: Version number is hard coded as 1

void AddSystemData	(	GCStreamID	ID,
		DataChunkPtr	Chunk
	)			[inline]

Add system item data to the current CP.

void AddSystemData	(	GCStreamID	ID,
		UInt64	Size,
		const UInt8 *	Data,
		UUIDPtr	ContextID,
		Length	PlaintextOffset = 0
	)

Add encrypted system item data to the current CP.

void AddSystemData	(	GCStreamID	ID,
		DataChunkPtr	Chunk,
		UUIDPtr	ContextID,
		Length	PlaintextOffset = 0
	)			[inline]

Add encrypted system item data to the current CP.

void AddEssenceData	(	GCStreamID	ID,
		UInt64	Size,
		const UInt8 *	Data
	)

Add essence data to the current CP.

void AddEssenceData	(	GCStreamID	ID,
		DataChunkPtr	Chunk
	)			[inline]

Add essence data to the current CP.

void AddEssenceData	(	GCStreamID	ID,
		EssenceSourcePtr	Source,
		bool	FastClipWrap = false
	)

Add essence data to the current CP.

void AddEssenceData	(	GCStreamID	ID,
		KLVObjectPtr	Source,
		bool	FastClipWrap = false
	)

Add an essence item to the current CP with the essence to be read from a KLVObject.

Length CalcRawSize

(

KLVObjectPtr

Object

)

Calculate how many bytes would be written if the specified object were written with WriteRaw().

void WriteRaw

(

KLVObjectPtr

Object

)

Write a raw KLVObject to the file - this is written immediately and not buffered in the WriteQueue.

void SetWriteOrder	(	GCStreamID	ID,
		Int32	WriteOrder = -1,
		int	Type = -1
	)

Set the WriteOrder for the specified stream.

When a GC Content Package is written all elements of each type are written together, with the lowest "Type" number being written first. So all system items are written first, then all picture items, then all sound items etc. Within each type the "WriteOrder" is used to determine the order that each element is written. So the system item with the lowest "WriteOrder" will be written first, then the next lowest up to the system item with the highest "WriteOrder", then the picture item with the lowest "WriteOrder".

Note:

There are GC and CP versions of system items, picture items, sound items and data items. These are grouped with all CP system elements first, then all GC system elements, then all CP picture elements, all GC picture elements etc.

Elements with a WriteOrder set to be < 0x8000 will be written before elements of streams that have not had a write order set. Elements with a WriteOrder >= 0x8000 will be written after elements of streams that have not had a write order set.

void SetRelativeWriteOrder	(	GCStreamID	ID,
		int	Type,
		Int32	Position
	)

Set a write-order relative to all items of a specified type.

This allows a stream to be written "before all audio items" or "after all system items" rather than in its default position for its own type.

Parameters:

	ID	The ID of the stream whose write-order is being set
	Type	The type to position this stream relative to
	Position	A signed position indicating before (-ve) or after (+ve) and strength of positioning

The value of Position (rather than its sign) is important when more than one stream is positioned before or after the same general type. The further Position is from zero, the nearer it will be placed to "immediately before" or "immediately after" all items of the specified type. For example the following list shows the order of some system items and items specified as being before or after system items with a specified relative-position:

Position = -1 Position = -100 Position = -25000 Position = -32768 First System Item ... Last System Item Position = 32767 Position = 15000 Position = 1 Position = 0

Although Position is a UInt32, only the sign bit, and the lowest 15 bits are significant.

Note:

To set a stream's write order to be before all picture essence use Type = 0x05 and Position < 0, using Type = 0x15 will place it between the CP picture essence and GC Picture essence. To set the write order to be after all picture essence use Type = 0x15 and Position >= 0. The same principle applies to other GC/CP types.

Int32 GetWriteOrder

(

GCStreamID

ID

)

Get the WriteOrder for the specified stream.

Returns:

-1 if not found

int GetStreamCount

(

void

)

[inline]

Read the count of streams.

---

Member Data Documentation

MXFFilePtr LinkedFile [protected]

File that will be written to.

UInt32 TheBodySID [protected]

Body SID for this Essence Container.

int StreamTableSize [protected]

Size of StreamTable.

int StreamCount [protected]

Number of entries in use in StreamTable.

int StreamBase [protected]

Base of all stream numbers in keys.

GCStreamData* StreamTable [protected]

Table of data for streams for this GC.

UInt32 KAGSize [protected]

KAGSize for this Essence Container.

bool ForceFillerBER4 [protected]

True if filler items must have BER lengths forced to 4-byte BER.

Int32 NextWriteOrder [protected]

The "WriteOrder" to use for the next auto "SetWriteOrder()".

Position IndexEditUnit [protected]

Edit unit of the current CP for use if indexing.

This property starts at zero and is incremented with each CP written, however the value can be changed by calling SetIndexEditUnit() before calling StartNewCP()

UInt64 StreamOffset [protected]

Current stream offset within this essence container.

std::map<UInt32, GCStreamID> WriteOrderMap [protected]

Map of all used write orders to stream ID - used to ensure no duplicates.

WriteQueueMap WriteQueue

Queue of items for the current content package in write order.

---

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

• essence.h
• essence.cpp

---