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