ADTF  3.13.0
Stream Type and Stream Meta Type


Stream Types as descriptions for sample content

The Stream Type is to describe the data content of the Sample. It is part of the Data Pipe sent from one Filter to another Filter. The Stream Type describes the data content by

  • a unique name (the Stream Meta Type name)
  • a concrete set of key/value pairs, so called "Properties" or "Config".
Example
One possible instance is a description for a video stream with a unique type name "adtf/image".
A video stream may be described via following properties:
  • pixel_width - 800 ... The width of one frame of the video stream as a tInt32 - integer value of 800.
  • pixel_height - 600 ... The height of one frame of the video stream as a tInt32 - integer value of 600.
  • format_name - "A(8)R(8)G(8)B(8)" ... The format name of the of the video stream as a string value of "A(8)R(8)G(8)B(8)" describing the pixelformat.
To instantiate such a Stream Type we may use the class cStreamType or the template stream_type.
Example Usage
void create_streamtype_video()
{
using namespace adtf::ucom;
using namespace adtf::streaming;
//creating an instance of the Stream Type
//we MUST use a predefined Stream Meta Type for the name and the predefined properties !
object_ptr<IStreamType> pStreamType = make_object_ptr<cStreamType>(stream_meta_type_image());
//set the values of the properties
//the names of the properties are defined at "stream_meta_type_image" struct
set_property(*pStreamType, stream_meta_type_image::PixelWidth, 800);
set_property(*pStreamType, stream_meta_type_image::PixelHeight, 600);
set_property(*pStreamType, stream_meta_type_image::FormatName, "A(8)R(8)G(8)B(8)");
}

Stream Meta Type

The possible Stream Types will be defined by known Stream Meta Types, which defines the possible unique name and the set of possible properties corresponding to that name. As shown in the example above, an instance of a Stream Type can only be created with such a Stream Meta Type definiton. The Stream Meta Type must implement the IStreamMetaType interface. This interface will provide following information:

For more information on IsCompatible functionality see also the Chapter: AcceptType and IsCompatible implementations.

Custom Stream Meta Types

The Stream Type implementation class cStreamType will use a templated CTOR:

template <typename MetaType>
cStreamType(const MetaType&)
{
//...
}

It will use the generator class stream_meta_type, which defines the unique name of the Stream Meta Type by a variable MetaTypeName. Additionally, a set of existing properties and there default values are set within the static function SetProperties.

Use following implementation for own Stream Meta Type definitions:

struct my_custom_stream_meta_type
{
//you must define the Metatype name as a variable "MetaTypeName"
static constexpr const tChar *const MetaTypeName = "cppDev/my_custom_type";
//this is a property to define a property name which identifies the content by the help of a number
static constexpr const tChar *const SecretContentID = "secret_content_id";
static constexpr const tChar *const Version = "version_of_type";
static tVoid SetProperties(const adtf::ucom::iobject_ptr<adtf::base::IProperties>& pProperties)
{
//we set the default values of the stream type
pProperties->SetProperty(adtf::base::property<tUInt16>(SecretContentID, 0));
pProperties->SetProperty(adtf::base::property<adtf_util::cString>(Version, "cppDev 2020-1.0"));
}
};

If you want to use the custom Stream Type use following code:

//usage of the @ref my_custom_stream_meta_type
void usage_of_own_type()
{
using namespace adtf::ucom;
using namespace adtf::streaming;
//we create a streamtype
//we MUST use a predefined stream meta type for the name and the predefined properties !
object_ptr<IStreamType> pStreamType = make_object_ptr<cStreamType>(my_custom_stream_meta_type());
//we set the secret content to the 12ish content and leave the version by default
set_property(*pStreamType, my_custom_stream_meta_type::SecretContentID, 12);
}

Another example can be found at following page: Demo Custom Stream Type Filters Plugin.

AcceptType and IsCompatible implementations

One important part of the Data Pipe between Filters are Stream Type updates. Before a Sample was received at least one Stream Type will be received that describes the sample content. Usually, the implementation can handle only incoming data with one clear defined Stream Type. This clear defined type is usually set while setting up the readers for a corresponding pin:

// Create a stream type for plain c-type data
object_ptr<IStreamType> pStreamType = make_object_ptr<stream_type_plain<tUInt32>>();
// Create the pins for the Readers ..
RETURN_IF_FAILED(create_pin(*this, m_oReader1, "in1", pStreamType));
RETURN_IF_FAILED(create_pin(*this, m_oReader2, "in2", pStreamType));

While receiving a Stream Type the default implementation of the cSampleReader will call internally an AcceptType function to accept or reject the incoming type. This implementation uses either the given user callback function (flash::cSampleReader::SetAcceptTypeCallback) or the implementation of the ant::IStreamMetaType::IsCompatible function of the current valid type. To do so, the Stream Meta Type implementation of the current valid type is retrieved and its IsCompatible function is used.

Note
These IsCompatible implementations will not automatically check the unique Stream Meta Type name for equality!
Sometimes it will have a look at the values of the properties only. For a complete overview of all delivered Stream Meta Types, their properties and the IsCompatible implementation see next chapter: Default Stream Meta Types in ADTF.

operator== and is_compatible

operator== and operator!=
The operator== will only check the Stream Meta Type names of the given Stream Type (IStreamType) and compares them.
is_compatible
The global function is_compatible will follow the IsCompatible implementation of the right-hand side Stream Type oExpectedType and its corresponding the Stream Meta Type. Mind, the Stream Meta Type of oExpectedType defines the IsCompatible comparison method. For example:
using namespace adtf::ucom;
using namespace adtf::streaming;
using namespace adtf::mediadescription;
//we create a plain type for tInt32
auto pPlainType = create_adtf_plain_stream_type<tInt32>();
//we create a structure description and its default DDL type
struct INT32
{
tInt32 m_nValue;
};
auto oDescriptionForINT32 = structure<INT32>("INT32");
oDescriptionForINT32.Add("m_nValue", &INT32::m_nValue);
auto pDDLType = create_adtf_default_stream_type(oDescriptionForINT32);
//we create an image type
tStreamImageFormat oFormat = { ADTF_IMAGE_FORMAT(ABGR_32), 800, 600, 0, PLATFORM_BYTEORDER };
auto pImageType = create_adtf_image_stream_type(oFormat);
//evaluate the compatibility by the is_compatible return value
tResult oErrCompat = ERR_NOERROR;
//using is_compatible pPlainType to check and pDDLType expected
oErrCompat = is_compatible(pPlainType, pDDLType); //ERR_NOERROR -> "adtf/default" meta type checks for existing "md_struct" and "md_description" properties
// using stream_type_plain will set these properties (but plain-type itself
// does not really need it)
//using is_compatible pDDLType to check and pPlainType expected
oErrCompat = is_compatible(pDDLType, pPlainType); //ERR_FAILED -> "adtf/plaintype" meta type checks for existing "c-type" property
// and expects the value
//using is_compatible pDDLType to check and pImageType expected
oErrCompat = is_compatible(pDDLType, pImageType); //ERR_FAILED -> "adtf/image" meta type checks for the same meta type name "adtf/image"
// "adtf/default" != "adtf/image"

Default Stream Meta Types in ADTF

This section will give an overview of all default ADTF Stream Meta Types and there properties.

Stream Meta Type "adtf/anonymous"

Namespace
Defined in namespace adtf::streaming.
Stream Meta Type concept class
stream_meta_type_anonymous
Description
Use this Stream Meta Type only if no property should be set and you do not share and record these data.
Properties
No properties.
IsCompatible
This implementation of IsCompatible will always return ERR_NOERROR and accept all other Stream Meta Type names.
Fully documentation: ant::stream_meta_type_anonymous::IsCompatible

Stream Meta Type "adtf/plaintype"

Namespace
Defined in namespace adtf::streaming
Stream Meta Type concept class
stream_meta_type_plain
Description
Use this Stream Meta Type if your sample data will be any of this type: tBool, tUInt8, tInt8, tUInt16, tInt16, tUInt32, tInt32, tUInt64, tInt64, tFloat32 or tFloat64.
Properties
IsCompatible
Compatible to all other Stream Types of any Stream Meta Type, where the following conditions are met: Fully documentation: ant::stream_meta_type_plain::IsCompatible

Stream Meta Type "adtf/default"

Namespace
Defined in namespace adtf::mediadescription
Stream Meta Type concept class
adtf::mediadescription::stream_meta_type_default
Description
Use this Stream Meta Type if your sample data are structured and the memory layout can be described via DDL - see also Usage of Stream Meta Type "adtf/default".
Properties
IsCompatible
Compatible to all other Stream Types of any Stream Meta Type, where the following conditions are met: Fully documentation: adtf::mediadescription::ant::stream_meta_type_default::IsCompatible

Stream Meta Type "adtf/image"

Namespace
Defined in namespace adtf::streaming
Stream Meta Type concept class
stream_meta_type_image
Description
Use this Stream Meta Type for describing a video stream with single frames and there format and set the values with set_stream_type_image_format.
Properties
IsCompatible
Uses the default implementation of IsCompatible and will return ERR_NOERROR only if:
  • GetMetaTypeName of oTypeToCheck is equal to GetMetaTypeName of oTypeExpected
  • GetVersion of oTypeToCheck is equal to GetVersion of oTypeExpected
Fully documentation: ant::cStreamMetaType::IsCompatible

Stream Meta Type "adtf/audio"

Namespace
Defined in namespace adtf::streaming
Stream Meta Type concept class
stream_meta_type_audio
Description
Use this Stream Meta Type for describing a audio stream with samples and sample rate.
Properties
  • FormatName
    "format_name" : Name for the Property of the format name.
  • ChannelCount
    "channel_count" : Name for the Property for the amount of channels.
  • SampleRateHz
    "sample_rate_hz" : Name for the Property for the sample rate in hz.
  • BitsPerSample
    "bits_per_sample" : Name for the Property for number of bits per sample.
  • SampleCount
    "sample_count" : Name for the Property for number of samples
IsCompatible
Uses the default implementation of IsCompatible and will return ERR_NOERROR only if:
  • GetMetaTypeName of oTypeToCheck is equal to GetMetaTypeName of oTypeExpected
  • GetVersion of oTypeToCheck is equal to GetVersion of oTypeExpected
Fully documentation: ant::cStreamMetaType::IsCompatible

Stream Meta Type "adtf/substreams"

Namespace
Defined in namespace adtf::streaming
Stream Meta Type concept class
stream_meta_type_substreams
Description
Use cSubStreamTypes to create a Stream Type instance for this Stream Meta Type - see also Substreams.
Properties
  • SubStreams
    "substreams" : This Property determine if substreams are supported or not (tTrue or tFalse). Subproperties will identify the concreate Substream Type.
  • SubStreamsRequestProperties
    "substreams_request_properties" : This Property determine if substreams are requestable and currently requested.
IsCompatible
This implementation of IsCompatible will accept all other Stream Meta Types and will return ERR_NOERROR only if:
  • Property SubStreams are equal
  • the all existing SubstreamName in oTypeExpected also exists in oTypeToCheck (Currently the Stream Meta Type of the Substream ist not checked)
Fully documentation: hollow::stream_meta_type_substreams::IsCompatible

Copyright © Audi Electronics Venture GmbH. All rights reserved. (Generated on Tue Sep 28 2021 by doxygen 1.8.14)