MAXON Data Type

Table of Contents

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::Int _a;
maxon::Int _b;
maxon::Int _c;
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
maxon::Data data;
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
maxon::Data 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;
};
maxon::Int _a;
maxon::Int _b;
maxon::Int _c;
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
maxon::Crc32C crc;
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);
}
static maxon::Result<void> DescribeIO(const maxon::DataSerializeInterface& stream)
{
iferr_scope;
PrepareDescribe(stream, AdvancedIntegerTriplet);
Describe("_a", _a, maxon::Int, maxon::DESCRIBEFLAGS::NONE) iferr_return;
Describe("_b", _b, maxon::Int, maxon::DESCRIBEFLAGS::NONE) iferr_return;
Describe("_c", _c, maxon::Int, maxon::DESCRIBEFLAGS::NONE) iferr_return;
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()
maxon::BaseArray<AdvancedIntegerTriplet> tripletArray;
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