DataType Manual

About

A maxon::DataType object represents a registered data type of the MAXON API. It is used to check the type of some given data at run time or to write generic template code.

Creation

The maxon::DataType object representing a specific data type can be accessed with maxon::GetDataType():

// This example gets the maxon::DataType for the given type.
const maxon::DataType dt = maxon::GetDataType<maxon::Int32>();
DiagnosticOutput("DataType: @", dt);
Note
Further utility functions can be found in the maxon::DataTypeLib.

Conversion

The maxon::DataType object is used to register and apply specific conversions from and to the defined data type.

Available conversion types are:

// This example adds a conversion for a custom data type and uses it to convert it into a maxon::Vector.
// add conversion
maxon::DataType::AddConversion<maxon::Vector, IntegerTriplet>(
[](maxon::Vector& dest, const IntegerTriplet& src) -> maxon::Result<void>
{
dest.x = maxon::Float(src._a);
dest.y = maxon::Float(src._b);
dest.z = maxon::Float(src._c);
return maxon::OK;
// convert
// prepare data
IntegerTriplet triplet;
triplet._a = 10; triplet._b = 20; triplet._c = 30;
// get DataType
const maxon::DataType dt = maxon::GetDataType<maxon::Vector>();
if (dt)
{
// convert
maxon::Generic* const generic = reinterpret_cast<maxon::Generic*>(&vec);
dt.Convert(*generic, ptr, ignore) iferr_return;
DiagnosticOutput("Vector: @", vec);
}

DataType Comparison

Two maxon:DataType objects can be compared using the "==" operator or with some more sophisticated functions:

Value Comparison

Using the maxon::DataType object it is also possible two compare two object of this data type:

// This example shows a template function that compares two values
// of the given type and prints the result to the debug console.
template <typename T> static maxon::Result<void> CompareAndPrint(T a, T b)
{
const maxon::DataType dt = maxon::GetDataType<T>();
if (!dt)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Unknown data type."_s);
if (!dt->IsEqual(&a, &b, maxon::EQUALITY::DEEP))
{
const maxon::COMPARERESULT res = dt->Compare(&a, &b);
DiagnosticOutput("Compare result: @", res);
}
else
{
DiagnosticOutput("Values are equal.");
}
return maxon::OK;
}

Construct

The maxon::DataType object can be used to create new object instances of the define type:

  • maxon::DataType::Create(): Returns a new instance of the type.
  • maxon::DataType::Construct(): Creates multiple instances of the type.
  • maxon::DataType::MoveConstruct(): Moves constructs multiple instances of the type.
  • maxon::DataType::Destruct(): Destroys multiple instances of the type.
  • maxon::DataType::MoveFrom(): Moves multiple instances of the type to a target location.
  • maxon::DataType::CopyFrom(): Copies multiple instances of the type to the target location.
// This example shows a template function that will only work if used with a certain type.
template <typename T> static maxon::Result<void> FillIntNumbers(void* mem, maxon::Int count)
{
// get data type
const maxon::DataType dt = maxon::GetDataType<T>();
if (!dt)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Unknown data type."_s);
// compare to legit data types
const maxon::DataType int_dt = maxon::GetDataType<maxon::Int>();
const maxon::DataType uint_dt = maxon::GetDataType<maxon::UInt>();
const maxon::Bool isIntDataType = dt == int_dt;
const maxon::Bool isUIntDataType = dt == uint_dt;
if (!(isIntDataType || isUIntDataType))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "Template function used with invalid type."_s);
// create numbers
dt->Construct(mem, 0, count);
return maxon::OK;
}

Interfaces

Also interfaces are registered as a maxon::DataType.

  • maxon::DataType::GetImplementation(): Returns the interface implementation of this type.
  • maxon::DataType::GetInterfaces(): Returns the interfaces of this object type.

Disc I/O

Data stored in an object of a given maxon::DataType can be written to a file. How this is done is described by a maxon::DataSerializeInterface object.

Properties

The maxon::DataType object gives access to various properties of the described data type:

// This example gets a maxon::String and a maxon::Id of the given maxon::DataType.
const maxon::String name = dt.ToString(nullptr);
const maxon::Id id = dt.GetId();
DiagnosticOutput("Data Type @, (@)", name, id);

The maxon::DataType object also provides information on the type of data:

// This example accesses basic information on the given maxon::DataType and prints it to the debug console.
const maxon::Int size = dt.GetSize();
DiagnosticOutput("Size @, Alignment @", size, alignment);
const maxon::VALUEKIND valueKind = dt->GetValueKind();
const maxon::String settings = maxon::ToString<maxon::FormatStatement>(valueKind, nullptr, false);
DiagnosticOutput("Type settings: @", settings);

It is possible to register a data type using MAXON_DATATYPE_REGISTER_STRUCT. This will inform Cinema 4D about public members of the type. The maxon::DataType object can be used to list these public members.

See also maxon::TypeArguments and maxon::Member.

// This example accesses and loops through all registered named members
// of the given maxon::DataType.
const maxon::VALUEKIND kind = dt.GetValueKind();
// check if structure
{
const maxon::TupleDataType tupleData = dt.GetTupleType();
if (tupleData)
{
const maxon::TypeArguments& args = tupleData.GetTypeArguments();
// loop through all members
for (maxon::Int i = 0; i < args.count; ++i)
{
const maxon::Member member = args.args[i];
const maxon::Id memberName = member.name;
const maxon::DataType memberType = member.type;
DiagnosticOutput("Member @ (@)", memberName, memberType);
}
}
}

Further Reading

maxon::DataTypeImpl::Construct
void Construct(void *dest) const
Definition: datatypebase.h:394
maxon::CONVERSION_FLAGS
CONVERSION_FLAGS
Definition: datatypebase.h:59
maxon::DataType::ToString
String ToString(const FormatStatement *formatStatement) const
maxon::DataType
Definition: datatypebase.h:726
maxon::DataType::GetTupleType
const TupleDataType & GetTupleType() const
Definition: datatypebase.h:915
maxon::DataTypeImpl::GetValueKind
VALUEKIND GetValueKind() const
Definition: datatypebase.h:252
maxon::String
Definition: string.h:1197
maxon::OK
return OK
Definition: apibase.h:2518
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:177
maxon::DataTypeImpl::IsEqual
Bool IsEqual(const void *s1, const void *s2, EQUALITY equality) const
Definition: datatypebase.h:515
maxon::TypeArguments::count
Int count
The number of type arguments which are types.
Definition: datatypelib.h:337
maxon::Id
Definition: apibaseid.h:250
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::ConstDataPtr
Definition: datatypebase.h:1730
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
maxon::DataType::GetSize
Int GetSize() const
Definition: datatypebase.h:783
maxon::Float
Float64 Float
Definition: apibase.h:193
maxon::TypeArguments
Definition: datatypelib.h:324
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
maxon::VALUEKIND
VALUEKIND
Definition: apibase.h:2206
maxon::Vec3::z
T z
Definition: vec.h:34
maxon::src
const T & src
Definition: apibase.h:2511
maxon::CONVERSION_FLAGS::WIDENING_LOSSY
@ WIDENING_LOSSY
The conversion contains a widening conversion which is always possible, but it might result in loss o...
maxon::Result< void >
maxon::Vec3< Float, 1 >
maxon::DataType::Convert
Result< void > Convert(Generic &dest, const ConstDataPtr &src, CONVERSION_FLAGS ignore=CONVERSION_FLAGS::NONE) const
maxon::Vec3::x
T x
Definition: vec.h:32
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:184
maxon::DataType::GetTypeArguments
const TypeArguments & GetTypeArguments() const
Definition: datatypebase.h:881
maxon::TupleDataType
Definition: datatypelib.h:657
maxon::alignment
Int alignment
Definition: apibase.h:647
maxon::Vec3::y
T y
Definition: vec.h:33
maxon::CONVERSION_FLAGS::NONE
@ NONE
When no other flags are set, the conversion is a one-to-one correspondence (such as from Float to Tim...
maxon::DataTypeImpl::Compare
COMPARERESULT Compare(const void *s1, const void *s2) const
Definition: datatypebase.h:523
maxon::Member
Member represents a member of struct-like types or function signatures. A member is just a pair of a ...
Definition: datatypelib.h:272
maxon::Member::type
DataType type
The type of the member.
Definition: datatypelib.h:302
maxon::DataType::GetAlignment
Int GetAlignment() const
Definition: datatypebase.h:789
maxon::VALUEKIND::STRUCT
@ STRUCT
The data type has an underlying TupleDataType with named members.
maxon::Member::name
InternedId name
The name of the member, this may be empty where anonymous members are allowed.
Definition: datatypelib.h:303
maxon::EQUALITY::DEEP
@ DEEP
A deep equality-test shall be done. For pointers or (non-copy-on-write) references the referenced obj...
maxon::DataType::GetValueKind
VALUEKIND GetValueKind() const
Definition: datatypebase.h:796
maxon::DataType::GetId
const Id & GetId() const
Definition: datatypebase.h:774
maxon::TypeArguments::args
Member args[MAXON_FLEXIBLE_ARRAY_LENGTH]
The type arguments which are (optionally named) types.
Definition: datatypelib.h:340
maxon::COMPARERESULT
COMPARERESULT
Data type for comparison results.
Definition: compare.h:20