Stream Type and Stream Meta Type

Table of Contents

• Stream Types as descriptions for sample content
• Stream Meta Type
• Custom Stream Meta Types
• AcceptType and IsCompatible implementations
  • operator== and is_compatible
• Default Stream Meta Types in ADTF
  • Stream Meta Type "adtf/anonymous"
  • Stream Meta Type "adtf/plaintype"
  • Stream Meta Type "adtf/default"
  • Stream Meta Type "adtf/image"
  • Stream Meta Type "adtf/audio"
  • Stream Meta Type "adtf/substreams"
  • Stream Meta Type "adtf/string"

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

#include <adtfstreaming3/adtf_streaming3.h>
 
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::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:

• GetMetaTypeName ... Gets the unique meta type name.
• GetVersion ... Get version of a Stream Type.
• GetDefaultConfig ... Get the default configuration values for a Stream Type.
• IsCompatible ... Compares the Stream Type oTypeToCheck based on this meta type - see Default Stream Meta Types in ADTF for a summary of implementations.

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"));
    }
};

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));

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
    using namespace adtf::streaming::stream_image_format;
    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"
 

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: BOOL -> bool -> please use stream_type_plain<bool> to create the type UINT8 -> uint8_t -> please use stream_type_plain<uint8_t> to create the type INT8 -> int8_t -> please use stream_type_plain<int8_t> to create the type UINT16 -> uint16_t -> please use stream_type_plain<uint16_t> to create the type INT16 -> int16_t -> please use stream_type_plain<int16_t> to create the type UINT32 -> uint32_t -> please use stream_type_plain<uint32_t> to create the type INT32 -> int32_t -> please use stream_type_plain<int32_t> to create the type UINT64 -> uint64_t -> please use stream_type_plain<uint64_t> to create the type INT64 -> int64_t -> please use stream_type_plain<int64_t> to create the type FLOAT32 -> float -> please use stream_type_plain<float> to create the type FLOAT64 -> double -> please use stream_type_plain<double> to create the type BOOL_ARRAY -> std::array<bool, SIZE_N> or std::vector<bool> -> please use stream_type_plain<std::array<bool, SIZE_N>> or stream_type_plain<std::vector<bool>> to create the type UINT8_ARRAY -> std::array<uint8_t, SIZE_N> or std::vector<uint8_t> -> please use stream_type_plain<std::array<uint8_t, SIZE_N>> or stream_type_plain<std::vector<uint8_t>> to create the type INT8_ARRAY -> std::array<int8_t, SIZE_N> or std::vector<int8_t> -> please use stream_type_plain<std::array<int8_t, SIZE_N>> or stream_type_plain<std::vector<int8_t>> to create the type UINT16_ARRAY -> std::array<uint16_t, SIZE_N> or std::vector<uint16_t> -> please use stream_type_plain<std::array<uint16_t, SIZE_N>> or stream_type_plain<std::vector<uint16_t>> to create the type INT16_ARRAY -> std::array<int16_t, SIZE_N> or std::vector<int16_t> -> please use stream_type_plain<std::array<int16_t, SIZE_N>> or stream_type_plain<std::vector<int16_t>> to create the type UINT32_ARRAY -> std::array<uint32_t, SIZE_N> or std::vector<uint32_t> -> please use stream_type_plain<std::array<uint32_t, SIZE_N>> or stream_type_plain<std::vector<uint32_t>> to create the type INT32_ARRAY -> std::array<int32_t, SIZE_N> or std::vector<int32_t> -> please use stream_type_plain<std::array<int32_t, SIZE_N>> or stream_type_plain<std::vector<int32_t>> to create the type UINT64_ARRAY -> std::array<uint64_t, SIZE_N> or std::vector<uint64_t> -> please use stream_type_plain<std::array<uint64_t, SIZE_N>> or stream_type_plain<std::vector<uint64_t>> to create the type INT64_ARRAY -> std::array<int64_t, SIZE_N> or std::vector<int64_t> -> please use stream_type_plain<std::array<int64_t, SIZE_N>> or stream_type_plain<std::vector<int64_t>> to create the type FLOAT32_ARRAY -> std::array<float, SIZE_N> or std::vector<float> -> please use stream_type_plain<std::array<float, SIZE_N>> or stream_type_plain<std::vector<float>> to create the type FLOAT64_ARRAY -> std::array<double, SIZE_N> or std::vector<double> -> please use stream_type_plain<std::array<double, SIZE_N>> or stream_type_plain<std::vector<double>> to create the type
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 Specification - 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:

• the property value of the properties strMDDataSerialized are equal in both types (both serialized or both deserialized, default is "md_serialized"="false")
• the property values of strMDStructProperty and strMDDefinitionsProperty must be exactly the same, OR
• if the property values strMDStructProperty and strMDDefinitionsProperty are not equal the given complex types in strMDStructProperty must be semantically equal (see adtf_ddl::cDDLCompare::IsEqualType)

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