MAXON Data Type

About

With the MAXON API, every class or structure can be registered as a data type. Objects of such a data type can be stored in a maxon::Data container or can be shared as published objects.

Declaration and Registration

A data type is declared in a header file using the attribute MAXON_DATATYPE:

// This example defines a custom class and declares it as a MAXON data type.
#include "maxon/datatype.h"
#include "maxon/string.h"
// ------------------------------
// Triplet of maxon::Int values.
// ------------------------------
class IntegerTriplet
{
public:
IntegerTriplet() : _a(1), _b(1), _c(1) {}
maxon::String ToString(const maxon::FormatStatement* formatStatement) const
{
return FormatString("@, @, @", _a, _b, _c);
}
};
// register as MAXON data type
MAXON_DATATYPE(IntegerTriplet, "net.maxonexample.datatype.integertriplet");

Additionally, the data type must also be registered in a source code file using one of these macros:

// This example registers the given class as a MAXON data type.
// Cinema is also informed about the public member variables.
MAXON_DATATYPE_REGISTER_STRUCT(IntegerTriplet, _a, _b, _c);

Usage

An instance of a class registered as a MAXON API data type can be stored in a maxon::Data container:

// This example configures an object of the custom data type.
// The object is stored in a maxon::Data container.
// configure the object
IntegerTriplet triplet;
triplet._a = 1;
triplet._b = 4;
triplet._c = 9;
// print the content to the console by invoking ToString()
DiagnosticOutput("Triplet: @", triplet);
// storing the object in a maxon::Data container
data.Set(triplet) iferr_return;

The data type class can also be identified with a maxon::DataType object. This maxon::DataType can be obtained with maxon::GetDataType().

// This example accesses the maxon::DataType of the given class
// and uses it to initialize a maxon::Data object.
// get maxon::DataType
const maxon::DataType dataType = maxon::GetDataType<IntegerTriplet>();
// print data type
DiagnosticOutput("Data Type: @", dataType);
// init maxon::Data
data.Init(dataType) iferr_return;
// get object form maxon::Data
const IntegerTriplet triplet = data.Get<IntegerTriplet>() iferr_return;
DiagnosticOutput("@", triplet);

Functions

A custom data type class may define and implement these utility functions. These functions may be called by other parts of the MAXON API when using an instance of the data type:

Note
To add generic functions see also Classes and Functions.

To copy internal data of a data type one has multiple options:

  • implementing a copy constructor and operator.
  • implementing a CopyFrom() function. This is recommended when copying can fail.
// This example shows a custom data type implementing various default functions.
// ------------------------------
// Triplet of maxon::Int values.
// ------------------------------
class AdvancedIntegerTriplet
{
MAXON_DISALLOW_COPY_AND_ASSIGN(AdvancedIntegerTriplet) // no copy constructor, no "=" operator
public:
AdvancedIntegerTriplet()
{
_a = 1;
_b = 1;
_c = 1;
};
AdvancedIntegerTriplet(AdvancedIntegerTriplet&& src) = default;
MAXON_OPERATOR_MOVE_ASSIGNMENT(AdvancedIntegerTriplet);
maxon::Result<void> CopyFrom(const AdvancedIntegerTriplet& src)
{
_a = src._a;
_b = src._b;
_c = src._c;
return maxon::OK;
}
maxon::Bool operator ==(const AdvancedIntegerTriplet& other) const
{
if (_a != other._a)
return false;
if (_b != other._b)
return false;
if (_c != other._c)
return false;
return true;
}
maxon::UInt GetHashCode() const
{
// create hash code based on the internal data
crc.UpdateInt(_a);
crc.UpdateInt(_b);
crc.UpdateInt(_c);
return crc.GetCrc();
}
maxon::String ToString(const maxon::FormatStatement* formatStatement) const
{
return FormatString("@, @, @", _a, _b, _c);
}
{
PrepareDescribe(stream, AdvancedIntegerTriplet);
return maxon::OK;
}
maxon::Int GetMemorySize() const
{
return SIZEOF(AdvancedIntegerTriplet);
}
};
MAXON_DATATYPE(AdvancedIntegerTriplet, "net.maxonexample.datatype.advancedintegertriplet");
// This example uses a custom data type in order to invoke its default funtions.
AdvancedIntegerTriplet triplet;
triplet._a = 100;
triplet._b = 200;
triplet._c = 300;
// call ToString()
DiagnosticOutput("Triplet: @", triplet);
// call GetMemorySize()
tripletArray.Resize(1000) iferr_return;
const maxon::Int size = tripletArray.GetMemorySize();
DiagnosticOutput("Memory Usage: @", size);
// call CopyFrom()
const AdvancedIntegerTriplet newTriplet;
tripletArray.Append(newTriplet) iferr_return;
// call GetHashCode()
const maxon::UInt arrayHash = tripletArray.GetHashCode();
DiagnosticOutput("Hash Value: @", arrayHash);
// call DescribeIO()
// file URL
const maxon::Url url = (targetFolder + "triplet.data"_s)iferr_return;
maxon::Id fileID("net.maxonexample.triplet");
// save to file
maxon::DataFormatWriterRef outputStream = maxon::DataFormatWriterFactories::Binary().Create(url) iferr_return;
outputStream.WriteDocument(fileID, maxon::ConstDataPtr(triplet)) iferr_return;
outputStream.CloseOutput() iferr_return;
// read from file
AdvancedIntegerTriplet loadedTriplet;
maxon::DataFormatReaderRef inputStream = maxon::DataFormatReaderFactories::Binary().Create(url) iferr_return;
inputStream.ReadDocument(fileID, maxon::DataPtr(loadedTriplet)) iferr_return;
inputStream.CloseInput() iferr_return;
DiagnosticOutput("@", loadedTriplet);

Further Reading

datatype.h
maxon::DataSerializeInterface
Definition: dataserialize.h:205
maxon::DescribeIO
Result< void > DescribeIO(const T &s, const DataSerializeInterface &dsi)
Definition: datatypefunctions.h:21
Describe
#define Describe(name, memberName, type, flags)
Definition: dataserialize.h:293
string.h
maxon::Crc32C::UpdateInt
MAXON_ATTRIBUTE_FORCE_INLINE void UpdateInt(Int i)
Definition: crc32c.h:541
maxon::DataType
Definition: datatypebase.h:726
maxon::Data::Init
Result< void > Init(const DataType &type)
Definition: datatypebase.h:1161
maxon::String
Definition: string.h:1197
MAXON_DATATYPE
#define MAXON_DATATYPE(type, id)
Definition: datatype.h:309
maxon::Data
Definition: datatypebase.h:1143
maxon::DataPtr
Definition: datatypebase.h:1981
maxon::OK
return OK
Definition: apibase.h:2518
maxon::DESCRIBEFLAGS::NONE
static const ValueType NONE
Default.
Definition: dataserialize.h:136
maxon::BaseArray::Resize
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1077
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:177
PrepareDescribe
#define PrepareDescribe(streamClass, className)
Definition: dataserialize.h:267
maxon::Id
Definition: apibaseid.h:250
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::ConstDataPtr
Definition: datatypebase.h:1730
maxon::Data::Get
Result< typename std::conditional< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, T, typename ByValueParam< T >::type >::type > Get() const
Definition: datatypebase.h:1352
ToString
maxon::String ToString(const Filename &val, const maxon::FormatStatement *formatStatement, maxon::Bool checkDatatype=false)
maxon::Data::Set
Result< void > Set(T &&data)
Definition: datatypebase.h:1341
maxon::BaseArray
Definition: basearray.h:366
maxon::ArrayBase0< BaseArray< T, BASEARRAY_DEFAULT_CHUNK_SIZE, BASEARRAYFLAGS::NONE, DefaultAllocator >, T, BaseArrayData< T, DefaultAllocator, STD_IS_REPLACEMENT(empty, DefaultAllocator)>, DefaultCompare >::GetHashCode
HashInt GetHashCode() const
Definition: collection.h:885
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
maxon::Crc32C::GetCrc
UInt32 GetCrc() const
Definition: crc32c.h:64
maxon::Url
Definition: url.h:819
MAXON_DISALLOW_COPY_AND_ASSIGN
#define MAXON_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: classhelpers.h:293
maxon::src
const T & src
Definition: apibase.h:2511
maxon::Result< void >
maxon::BaseArray::Append
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append()
Definition: basearray.h:569
SIZEOF
#define SIZEOF(x)
Calculates the size of a datatype or element.
Definition: apibasemath.h:205
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:184
iferr_scope
#define iferr_scope
Definition: resultbase.h:1343
MAXON_OPERATOR_MOVE_ASSIGNMENT
#define MAXON_OPERATOR_MOVE_ASSIGNMENT(TypeName)
Definition: classhelpers.h:322
FormatString
#define FormatString(...)
Definition: string.h:2031
maxon::FormatStatement
Class to store formatting statements.
Definition: string.h:1960
maxon::Crc32C
Definition: crc32c.h:26
MAXON_DATATYPE_REGISTER_STRUCT
#define MAXON_DATATYPE_REGISTER_STRUCT(type,...)
Definition: datatype.h:419
maxon::UInt
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:185
operator==
Bool operator==(const BaseTime &t1, const BaseTime &t2)
Definition: c4d_basetime.h:254
maxon::BaseArray::GetMemorySize
Int GetMemorySize() const
Definition: basearray.h:1318