ADTF
|
The Data Definiton Language (DDL) is to describe memory content in a formal way.
So, it is possible to provide functionality, executables and utilities those are able to access and display data in a generic way:
The DDL will have some advantages over other ways to describe data like IDL (Interface Description Language), Protocol Buffers or FlatBuffers:
There are also some disadvantages on DDL:
The most important Stream Type instance within ADTF uses the default Stream Meta Type "adtf/default". (See also Stream Type and Stream Meta Type for a common definition)
This Meta Type is define in stream_meta_type_default. It will use 3 important properties:
In ADTF 2 the DDL File was an optional side-by-side file description next to the ADTF DAT File. It described the content of the DAT File.
Since the ADTF DAT File in ADTF 3 contains the complete DDL description if "adtf/default" Meta Type is used, only the units
, datatypes
, enums
and structs
tags are relevant. Within ADTF 3 we do not use the streammetatypes
or streams
tags anymore which are mentioned within page_ddl_specification.
It is possible to create a DDL file before you define any structured data within your code. To make sure the resulting DDL file is valid, we recommend to use the DDL Editor.
ADTF provides a tool that creates C++ headers containing structure definitions and access classes from a given ADTF Media Description file (*.description).
If you are using the adtf_add_filter
, adtf_add_streaming_service
, adtf_add_system_service
CMake macros, you only need to specify your description file within the sources of your target:
This will generate a header named after your description file, that you can include in your source files. In the above case:
You may use following code within your filter if the DDL file contains any valid complex type (struct type) named "tMyType":
If you want the structure definitions to be generated in a namespace use the "MD_NAMESPACE" argument:
If for some reasons you cannot use these macros, there is the adtf_md_generate_cpp
CMake macro provided that will add header generation to existing targets.
The executable of the tool is accessible via the imported adtf::mdgen
target. A non target based CMake macro is provided via adtf_md_generate_from_description
.
An example of the usage of the generation facilities can be found at Demo Media Description Code Generation Filters Plugin.
To describe the MD Generator Tool of the above chapter in more detail we need to tell, that it will create exactly two header files and one cpp-file.
It is possible to use additional MD_ARGUMENTS
within the CMake macro as follows:
Instead of using the stdtypes ( bool , int8_t , uint8_t , ... ) in generated header files this will lead to a usage of adtftypes ( tBool , tInt8 , tUInt8 , ...): |
adtf_add_filter(myfilter
myfilter.cpp
mytypes.description
MD_ARGUMENTS --use-adtftypes)
|
Instead of using enum class for enumerations in generated header files this will lead to a usage of enum only: |
adtf_add_filter(myfilter
myfilter.cpp
mytypes.description
MD_ARGUMENTS --no-scoped-enum)
|
Instead of using the global namepace qualifier for each type usage this will drop the leading '::' : |
adtf_add_filter(myfilter
myfilter.cpp
mytypes.description
MD_ARGUMENTS --no-global-namespace)
|
Instead of using alignment for positioning the elements, this will use padding bytes only: |
adtf_add_filter(myfilter
myfilter.cpp
mytypes.description
MD_ARGUMENTS --padded-only)
|
ADTF provides a additional toolset that creates a description out of struct definitions within a simple C++ header and the necessary access classes.
To do so there are 3 tools provided:
If you are using the adtf_add_filter
, adtf_add_streaming_service
, adtf_add_system_service
CMake macros, you only need to specify your header files to generate descriptions for within the MD_HEADERS of your target:
This will generate the temporary castxml and description file within your build folder. The MD Generator Tool will generate the necessary access template classes within a header, that you can include in your source files. In the above case:
Now you can use following code within your filter like the the example under MD Generator Tool with a complex type named "tMyType":
If for some reasons you cannot use these macros, there is the adtf_md_generate_cpp
CMake macro provided that will add header generation to existing targets.
A non target based CMake macro is provided via adtf_md_generate_from_header
.
An example of the usage of the generation facilities can be found at Demo Media Description Generation Filters Plugin.
To describe the MD Generator Tool of the above chapter in more detail we need to tell, that it will create exactly two header files and one cpp-file.
It is possible to use MD_HEADERS_ARGUMENTS
also combined with the MD_ARGUMENTS
like described above within the CMake macro as follows:
Instead generating all struct types only a description for the type 'tMyType' is generated: |
adtf_add_filter(myfilter
myfilter.cpp
MD_HEADERS mytypes.h
MD_HEADERS_ARGUMENTS --types tMyType)
adtf_add_filter(myfilter
myfilter.cpp
MD_HEADERS mytypes.h
MD_HEADERS_TYPES tMyType)
|
Instead of using the adtftypes ( tBool , tInt8 , tUInt8 , ...) in generated description files this will lead to a forced usage of stdtypes ( bool , int8_t , uint8_t , ... ): |
adtf_add_filter(myfilter
myfilter.cpp
MD_HEADERS mytypes.h
MD_HEADERS_ARGUMENTS --force-datatypes stdtypes)
|
Instead of using the current platform dependent byte order with the generated description, use the given one: LE or BE |
adtf_add_filter(myfilter
myfilter.cpp
MD_HEADERS mytypes.h
MD_HEADERS_ARGUMENTS --byteorder BE)
|
It is also possible to read a file in code and create the description while runtime dynamically. To do so, please use the ddl::DDFile functionality.
It is possible to use the structure API provided via this ddl package. It will create the necessary DDL description while runtime and compile-time:
It is possible to use the type-reflection API provided via DDL package. It will create the necessary DDL description while runtime and compile-time:
This is a very old fashioned way to create your own DDL Decription. We do not recommend to use that, but for completeness it is specified here:
The DDL describes the data layout in 2 separate representations:
alignment
, type
information and arraysize
are relevant attributes. Keep in mind: The byteorder
attribute is absolutely not relevant here, because the values exists always in the same byteorder as the platform and the used compiler for that binary.bytepos
, byteorder
, type
and arraysize
are relevant attributes only.We separate these representations to access the values in a fast way in memory, when deserialized and the deserialized representation will assure that data are described in such a formal way to use it on every single platform. It enables exchanging data between different architectures (big endian, little endian) and processors (Intel, ARM) vie network and file.