Substreams

Table of Contents

• Substream Definition and Sample Handling
• Substream Request Handling

Substreams have been introduced in ADTF 3.7.0 to address handling of large amounts of different signals or complex data structures by multiplexing them on single output pin/sample stream.

This includes two new concepts:

Substream Definition and Sample Handling

Using substreams is one possibility to reduce pin and connection appearance within the Data Pipe of the Filter Graph.

Substreams are defined by using a special stream type with the "adtf/substreams" stream meta type (stream_meta_type_substreams) This stream type stores the following information for each substream:

• Name, the name of the substream (i.e. the name of the signal of which the samples are streamed via this substream).
• Id, a numeric id identifing the samples of the substream.
• Stream Type, the stream type of the substream.

See adtf::filter::hollow::cSubStreamTypes for information on how to create such a substream stream type.

Each sample transmitted via such a sample stream is then assigned the id of the substream that it belongs to, see ISample::SetSubStreamId and set_sample_substream_id().

To select samples of a specific substreams for processing in other ADTF filters we provide a special sample stream implementation (Substream Selector), that will select and forward only the stream types and samples of a single substream.

You can use the Substream Dissector to dissect a "normal" sample stream into substreams containing all individual elements.

We provide the following programming examples on how to use substreams:

• Demo Substream Generator Plugin
• Substream Dumper Plugin

Substream Request Handling

In order to handle dynamic processing of substreams we introduced the substream request handling architecture. This mechanism enables consumers the inform sources about the data that they are interested in. So by default all substream sources will not provide any data if no one requests anything.

The new IStreamingRequests interface is forwarded transparently via sample streams. Via this interface a consumer can tell a source which substream samples it likes to recieve. For convenience access to this interface is provided via the default sample reader implementation (cSampleReader::RequestSamples). To provide request support for substreams you can use the requestable_writer template, but most of the time just use the adtf::filter::hollow::cGraphObject::CreateRequestableOutputPin method.

Note

All sinks like components (recorders, displays, ...) that consume substreams are required to request transmission of the substreams that they are interested in. They will not receive any data otherwise.

During playback, requests on streams originating from the player will proceeed, but do not have any effect on which samples are transmitted via the sample stream.

We provide the following programming examples on how to provide request support for substreams:

• Demo Requestable Substream Generator Plugin