ADTF  3.18.3
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<stream_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::FormatName, "A(8)R(8)G(8)B(8)");
}
Copyright © Audi Electronics Venture GmbH.
tResult set_property(IConfiguration &oConfiguration, const char *strNameOfValue, VALUETYPE oValue)
Set the property.
Namespace for the ADTF Streaming SDK.
Namespace for the ADTF uCOM3 SDK.
static constexpr const tChar *const FormatName
Name for the Property of the format name - see imageformat_definition and Generic Pixel Format.
static constexpr const tChar *const PixelWidth
Name for the Property of the pixel width.
static constexpr const tChar *const PixelHeight
Name for the Property of the pixel height.

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 stream_type 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 void SetProperties(const adtf::ucom::iobject_ptr<adtf::base::IProperties>& pProperties)
{
//we set the default values of the stream type
pProperties->SetProperty(adtf::base::property<uint16_t>(SecretContentID, 0));
pProperties->SetProperty(adtf::base::property<adtf_util::cString>(Version, "cppDev 2020-1.0"));
}
};
char tChar
The tChar defines the type for platform character set (platform and compiler dependent type).
Base object pointer to realize binary compatible reference counting in interface methods.

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<stream_type<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<uint32_t>>();
// 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));
#define RETURN_IF_FAILED(s)
Return if expression is failed, which requires the calling function's return type to be tResult.
tResult create_pin(DATA_BINDING_IMPL_TYPE &oDataBindingImpl, cSampleWriter &oWriter, const char *strNameOfWriterAndPin, const ucom::iobject_ptr< const IStreamType > &pStreamType, ucom::iobject_ptr< IOutPin > &pPinCreated)
Creates a cOutPin and registers it at the given oDataBindingImpl instance.
Definition: pin_creation.h:37

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 int32_t
auto pPlainType = make_object_ptr<stream_type_plain<int32_t>>();
//we create a structure description and its default DDL type
struct INT32
{
int32_t m_nValue;
};
auto oDescriptionForINT32 = structure<INT32>("INT32");
oDescriptionForINT32.Add("m_nValue", &INT32::m_nValue);
auto pDDLType = make_object_ptr<stream_type_default<>>(oDescriptionForINT32);
//we create an image type
tStreamImageFormat oFormat = { ADTF_IMAGE_FORMAT(ABGR_32), 800, 600, 0, PLATFORM_BYTEORDER };
auto pImageType = make_object_ptr<stream_type_image<>>(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"
#define PLATFORM_BYTEORDER
defines a link to __get_platform_byteorder.
Definition: constants.h:124
Namespace for the ADTF Media Description SDK.
tResult is_compatible(const ant::IStreamType &oCheckedType, const ant::IStreamType &oExpectedType)
Checks whether oCheckedType is compatible with oExpectedType.
Container namespace to predefine some common imageformats within ADTF - see also Generic Pixel Format...
#define ADTF_IMAGE_FORMAT(_FORMAT_)
Helper Macro to get the FormatName of the predefined Format within stream_image_format.

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.
Generator class
flash::stream_type by calling:
stream_type<stream_meta_type_anonymous>();
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: bool, uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t, float, double or plain array T[], std::array, std::vector of them.
Generator class
stream_type_plain
Properties
PlainTypeProperty ... "c-type" : Valid values for this "c-type" property are:
DataEndianess

... "data_endianess" : This is relevant for all value types greater than 1 byte.

The endianess of the content is relevant for all value types greater than 1 byte and is only set if current platform endianess is different to PLATFORM_LITTLE_ENDIAN_8.

ArraySize

... "array_size" : Array size for the used type is only relevant for array types:

  • for single arithmetic type (bool, all ints, float, double) the value is 1
  • for dynamic arrays (i.e. std::vector<bool>, all ints, float, double) the value is 0 (content is dynamic)
  • for static arrays (i.e std::array<bool, N>, all ints, float, double) the value is N (content is fixed array size)

[optional] set strMDStructProperty

... "md_struct" : The "md_struct" property will be set to a valid struct type that describes the "c-type" (see also Stream Meta Type "adtf/default")

[optional] set strMDDefinitionsProperty ... "md_definitions" : The "md_md_definitions" property will contain a valid struct description that describes the "c-type" (see also Stream Meta Type "adtf/default")
IsCompatible
Compatible to all other Stream Types of any Stream Meta Type, where the following conditions are met:
  • the property value of the properties PlainTypeProperty are equal in both types.
  • the property value of the properties ArraySize are equal or the expected ArraySize is 0
  • the property value of the properties DataEndianess are equal in both types if value type is greater than 1 byte
Fully documentation: penguin::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".
Generator class
stream_type_default
stream_type_default_array
Properties
strMDStructProperty

... "md_struct" : This property contains a complex type name / struct name out of the complete self-contained DDL definition in strMDDefinitionsProperty. See also Demo Media Description Code Generation Filters Plugin.

strMDDefinitionsProperty

... "md_definitions" : This property contains a complete self-contained DDL definition which should contain the description of the complex type set in strMDStructProperty. See stream_type_default for creating the type with the help of the template adtf::mediadescription::description. See also Demo Media Description Code Generation Filters Plugin.

strMDDataSerialized

... "md_data_serialized" : This property defines wether the sample data are serialized (true) or not serialized (false). By default the value is set to false! This determines that the DDL definitons for deserialized interpretation is used. For more information on serialized/deserialized see page_ddl_specification and Serialization of "adtf/default" Samples.

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.
Generator class
stream_type_image
Properties
FormatName

... "format_name" : Formatname of the image - see adtf::streaming::ant::imageformat_definition.

MaxByteSize

... "max_byte_size" : Maximal byte size of the image.

PixelWidth

... "pixel_width" : Pixel width of the image.

PixelHeight

... "pixel_height" : Pixel height of the image.

DataEndianess

... "data_endianess" : Endianess of the image (usually pixel endianess) - by default this is PLATFORM_BYTEORDER (PLATFORM_BIG_ENDIAN_8 or PLATFORM_LITTLE_ENDIAN_8).

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.
Generator class
stream_type_audio
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.
Creator class
cSubStreamTypes
Properties
SubStreams

... "substreams" : This Property determine if substreams are supported or not (true or false). 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

Stream Meta Type "adtf/string"

Namespace
Defined in namespace adtf::mediadescription
Stream Meta Type concept class
adtf::mediadescription::stream_meta_type_string
Description
Generator class
stream_type_string
Properties
DataEndianess

... "data_endianess" : Valid values are PLATFORM_LITTLE_ENDIAN_8 and PLATFORM_BIG_ENDIAN_8

Encoding ... "encoding" : Valid values for this "encoding" property are:
  • unspecified - for unspecified encodings, where i.e the receiver will determine the encoding while stream type change
  • c-char - for plain char (8Bit) used in c++ programs, where no special encoding information is used
  • utf8 - utf8 (8Bit)
  • w-char - for plain wchar (16Bit !) used in c++ programs, where no special encoding information is used
  • utf16 - utf16 (16Bit)
IsCompatible
Compatible to all other Stream Types of any Stream Meta Type, where the following conditions are met:
  • the property value of the property Encoding are equal in both types.
  • the property value of the property Encoding is EncodingValueUnspecified at expected side
  • the property value of the property DataEndianess is equal in both types if the Encoding identifies a character size greater than 1 byte
Fully documentation: adtf::mediadescription::penguin::stream_meta_type_string::IsCompatible