Using Custom Data Types with CGF Channels

CGF Channels can be extended to allocate and transport custom data types that are defined by applications.

POD vs non-POD

All data types to be used with CGF Channels must be declared. A data type can be plain-old-data (POD), which is not the same as std::is_pod. POD types from Channel's perspective means that the data type is a single contiguous chunk of memory, with no pointers. Primitive types and structs of primitive types are POD. CGF Channels, given a type is POD, can handle all allocation and transport of that data type automatically. A data type that is not POD cannot be handled automatically by CGF Channels. Applications must define implementations for CGF Channels to be able to allocate and transport said types.

Declaring Custom Data Types

Any data type an application wishes to transport with CGF Channels must be declared using macros. In order to use a PortInput/Output of DataType, the macro declaration for the data type must be in the include path of the application. Otherwise a static assertion will be triggered because CGF Channels will not know how to handle the data type.

DWFRAMEWORK_DECLARE_PACKET_TYPE_POD(DataType) - declares a data type DataType as POD. Nothing further is needed to be able to use DataType with CGF Channels.

In order to handle data types which are non-POD, applications must define a class that extends the IChannelPacket interface. The IChannelPacket interface will be used by CGF Channels to allocate and transport the type without knowing the definition of that data type. Once an application has defined its implementations of IChannelPacket for its types, it must register constructors for its implementations using ChannelFactory::registerPacketConstructor(), which is a static function that can be called during load-time. Each IChannelPacket class is registered with a unique id for the data type it is meant to handle. Behind the scenes, whenever CGF Channels needs to identify a data type, it uses the unique id, including to verify that connected producers and consumers are expecting the same data type as well as to match the data type to the IChannelPacket class that should be used for it.

Similar to the POD case, an application must declare non-POD types using a macro.

DWFRAMEWORK_DECLARE_PACKET_TYPE_RELATION(DataType, SpecimenType, TypeID) - declares DataType as non-POD. SpecimenType is the parameter to be passed by application to the IChannelPacket implementation that describes how to allocate DataType, and TypeID is the unique type id for DataType.

The TypeID cannot be in the interval [DWFRAMEWORK_PACKET_ID_DEFAULT, DWFRAMEWORK_MAX_INTERNAL_TYPES), as those type IDs may be taken by CGF for CGF built-in data types.

Defining Custom Data Type Handling

See CGF Channel Sample source code for reference of implementing custom type handling.