Getting Started: Data

Overview

Basic Data Types

The MAXON API provides basic data types in an OS-independent way. Basic data types exist in both 32 and 64 bit size (e.g. maxon::Int32 and maxon::Int64). maxon::Int is the same as maxon::Int64.

See Primitive Data Types Manual (Classic) and Basic Data Types.

// This example performs some simple mathematical operations with the
// basic data types provided by the MAXON API.
// add two values
const maxon::Int32 valueA = 123;
const maxon::Int32 valueB = 456;
const maxon::Int32 sum = valueA + valueB;
// get ratio
const maxon::Int referenceValue = 1000;
const maxon::Float ratio = maxon::Float(sum) / maxon::Float(referenceValue);
DiagnosticOutput("Ratio: @", ratio);

There are also special vector and matrix classes. See Vector Manual (Classic), Matrix Manual (Classic), Vectors and Matrices.

// This example translates the given position using a newly constructed matrix.
// old position
const maxon::Vector pos(100, 100, 100);
// create matrix
// apply matrix
const maxon::Vector newPos = translate * pos;
DiagnosticOutput("New Position: @", newPos);

Strings

The API includes both the classic String as well as maxon::String. The String class is based on maxon::String.

See String Manual (Classic) and String Manual.

// This example performs various string operations.
const maxon::String foo("foo");
const maxon::String bar("bar");
const maxon::String fooBar = foo + " "_s + bar;
DiagnosticOutput("Text: @", fooBar);
const maxon::String fooBarUppercase = fooBar.ToUpper();
DiagnosticOutput("All Caps: @", fooBarUppercase);

Data Collections

Data can be stored and handled in array, mash maps and lists. These classes allow fast and safe handling of dynamic data.

See BaseArray Manual, Arrays Manual and MAXON API Containers & Data Collections.

// This example creates a BaseArray and fills it with some numbers.
// The stores values are printed to the console.
// create array
// insert data into the array
numbers.Append(0) iferr_return;
numbers.Append(1) iferr_return;
numbers.Append(1) iferr_return;
numbers.Append(2) iferr_return;
numbers.Append(3) iferr_return;
numbers.Append(5) iferr_return;
numbers.Append(8) iferr_return;
// check all elements
for (const maxon::Int32& number : numbers)
{
DiagnosticOutput("Number: @", number);
}
// get specific element
const maxon::Int32 number = numbers[0];
DiagnosticOutput("Number: @", number);

Classic Data Containers

The container types GeData and BaseContainer are used to store any kind of classic data type. The typical use case is to store the parameter values of objects that are based on C4DAtom like BaseObject, BaseMaterial etc.

See GeData Manual, BaseContainer Manual and C4DAtom Manual.

// This example stores some data in a GeData and BaseContainer object.
// define IDs
const ::Int32 VALUE_A = 1;
const ::Int32 VALUE_B = 2;
::Int32 value = 123;
// store data in GeData
GeData data;
data.SetInt32(value);
// store data in BaseContainer
BaseContainer container;
container.SetData(VALUE_A, data);
container.SetInt32(VALUE_B, 456);
// access data
const ::Int32 firstValue = container.GetInt32(VALUE_A);
DiagnosticOutput("First Value: @", firstValue);
const GeData& secondValueData = container.GetData(VALUE_B);
const ::Int32 secondValue = secondValueData.GetInt32();
DiagnosticOutput("Second Value: @", secondValue);

MAXON API Data Containers

The MAXON API equivalent to GeData and BaseContainer are maxon::Data and maxon::DataDictionary. These classes are used to store any kind of MAXON API data type. A maxon::DataDictionary is often used to define settings of a complex operation.

See Data Manual and DataDictionary Manual.

// This example stores data in Data and DataDictionary objects.
// define IDs
const Int32 VALUE_A = 1;
const Int32 VALUE_B = 2;
const maxon::Int32 value = 123;
// store data in maxon::Data
data.Set(value) iferr_return;
// store data in maxon::DataDictionary
maxon::DataDictionary dictionary;
dictionary.Set(VALUE_A, data) iferr_return;
dictionary.Set(VALUE_B, maxon::Int32(456)) iferr_return;
// acess data
const maxon::Int32 firstValue = dictionary.Get<maxon::Int32>(VALUE_A) iferr_return;
DiagnosticOutput("First Value: @", firstValue);
const maxon::Data secondValueData = dictionary.GetData(maxon::ConstDataPtr(VALUE_B)) iferr_return;
const maxon::Int32 secondValue = secondValueData.Get<maxon::Int32>() iferr_return;
DiagnosticOutput("Second Value: @", secondValue);

Stream Conversions

maxon::StreamConversionInterface is a generic interface for any kind of data conversion. Examples are data compression, encryption or the calculation of hash values.

See Stream Conversions Manual.

// This example calculates the MD5 hash of a given maxon::String using StreamConversions.
// source text
const maxon::String text("Hello World");
const maxon::BaseArray<maxon::Char> source = text.GetCString() iferr_return;
// prepare target buffer
// MD5
const maxon::StreamConversionRef md5 = maxon::StreamConversions::HashMD5().Create() iferr_return;
md5.ConvertAll(source, hash) iferr_return;
DiagnosticOutput("MD5 Hash: @", md5Hash);

Custom Data Types

Classic custom data types are based on iCustomDataType and CustomDataTypeClass. Such custom data types can be stored in GeData and BaseContainer objects.

New MAXON API data types are registered using the MAXON_DATATYPE attribute. Such data types can be stored in maxon::Data and maxon:DataDictionary objects.

See MAXON Data Type.