Notes on Sub-Streams

Sub-Streams Introduction

Certain essence streams may have intimate data related to the essence that is linked as a substream.

Sub-Streams in EssenceSubParsers

An EssenceSubParser may produce a main EssenceSource with sub-streams which are EssenceSources whose data is extracted during the parsing that produces the main source's data. These SubStreams are indicated by members of the EssenceStreamDescriptor::SubStreams properties of members of the EssenceStreamDescriptorList returned by a call to EssenceSubParserBase::IdentifyEssence(). This in turn gets propogated to the EssenceParser::WrapingConfig::SubStreams properties of members of the EssenceParser::WrapingConfigList returned by a call to EssenceParser::ListWrappingOptions().

The value of EssenceStreamDescriptor::ID, and hence EssenceParser::WrapingConfig::Stream, will differ between the main stream and its sub-streams. These stream IDs are passed to EssenceSubParserBase::GetEssenceSource to produce the desired EssenceSource objects. The master stream needs to be requested first, otherwise the EssenceSubParserBase::GetEssenceSource is unlikely to produce a valid sub-stream EssenceSource.

It is worth noting that as the sub-stream data is extracted from the master stream, the master stream is responsible for managing the file handle and other items such as the edit rate.

Attention:

Any EssenceSubParser providing sub-streams must support EssenceSubParserBase::ReValidate(), even if only to reject all attempts to continue into the next file (as this may not be a valid thing to do).

It is the responsibility of the EssenceSubParser to ensure that data for all streams is extracted from the initial file before the master stream returns NULL from its GetEssenceData() method. This is because the file will be closed soon after that call is made.

DRAGONS: There may be a requirement at some point to allow an EssenceSubParser to keep the file open if a huge amount of data is still unread

---