MAXON Data Type

Table of Contents

• About
• Declaration and Registration
• Usage
• Functions
• Further Reading

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:

• MAXON_DATATYPE_REGISTER: Registers the given class as a data type.
• MAXON_DATATYPE_REGISTER_STRUCT: Registers the given class and its public member variables as a data type.

// 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:

• DescribeIO(): Describes how the internal data of the object should be written to file. See DescribeIO Manual.
• ToString(): Returns a maxon::String representation of the object. See FormatStatement Manual.
• GetHashCode(): Returns a hash value for the object. To implement this one can use maxon::Crc32C, maxon::DefaultCompare or MAXON_HASHCODE.
• GetMemorySize(): Returns the memory size of the object.

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

• Data & Algorithms
• Data Manual
• DataType Manual
• Published Objects