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);
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:202
Float64 Float
Definition: apibase.h:211
int32_t Int32
32 bit signed integer datatype.
Definition: apibase.h:190
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:170

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);
void Py_ssize_t * pos
Definition: dictobject.h:50
maxon::Vec3< maxon::Float64, 1 > Vector
Definition: ge_math.h:141
Mat3< Vec3< FLOAT > > GetTranslationMatrix(const Vec3< FLOAT > &translation)
Calculates a matrix to move / translate.

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);
Definition: string.h:1237

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);
Definition: basearray.h:415
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append(ARG &&x)
Appends a new element at the end of the array and constructs it using the forwarded value.
Definition: basearray.h:628
#define iferr_return
Definition: resultbase.h:1524

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);
PyObject * value
Definition: abstract.h:715
Definition: c4d_basecontainer.h:48
Int32 GetInt32(Int32 id, Int32 preset=0) const
Definition: c4d_basecontainer.h:348
Bool SetData(Int32 id, const GeData &n)
Definition: c4d_basecontainer.h:274
const GeData & GetData(Int32 id) const
Definition: c4d_basecontainer.h:290
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:587
Definition: c4d_gedata.h:83
void SetInt32(Int32 v)
Definition: c4d_gedata.h:645
Int32 GetInt32() const
Definition: c4d_gedata.h:456
maxon::Int32 Int32
Definition: ge_sys_math.h:56

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
// 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);
const maxon::Data & GetData() const
Definition: c4d_gedata.h:535
Definition: datatypebase.h:1740
Definition: datatypebase.h:1229
Result< void > Set(T &&data)
Definition: datatypebase.h:1378
Result< typename std::conditional< GetCollectionKind< T >::value==COLLECTION_KIND::ARRAY, T, typename ByValueParam< T >::type >::type > Get() const
Definition: datatypebase.h:1389

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" };
// prepare target buffer
// MD5
const maxon::StreamConversionRef md5 = maxon::StreamConversions::HashMD5().Create() iferr_return;
md5.ConvertAll(source, hash) iferr_return;
DiagnosticOutput("MD5 Hash: @", md5Hash);
PyObject Py_hash_t hash
Definition: dictobject.h:35
const Py_UNICODE * source
Definition: unicodeobject.h:54
Result< String > GetHashString(const BaseArray< UChar > &hashValue)
PyObject * text
Definition: pycore_traceback.h:70

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.