Getting Started: Data

Table of Contents

• Overview
• Basic Data Types
• Strings
• Data Collections
• Cinema API Data Containers
• Maxon API Data Containers
• Stream Conversions
• Custom Data Types

Overview

• The Maxon API provides typical data types like maxon::Int, maxon::Bool, etc. Developers should use these data types.
• It also provides more complex types like maxon::Vector, maxon::Matrix or maxon::String.
• Instead of low-level C-array one should use build in array types like maxon::BaseArray.
• Arbitrary "classic" data types can be stored in GeData and BaseContainer containers.
• Maxon API data can be stored in maxon::Data and maxon::DataDictionary containers.
• maxon::StreamConversionInterface is an interface for generic data operations e.g. calculation of hash-values or encryption.
• New "classic" data types are based on iCustomDataType and CustomDataTypeClass.
• New Maxon API data types are define with MAXON_DATATYPE.

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 (Cinema API) 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 (Cinema API), Matrix Manual (Cinema API), 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
  const maxon::Matrix translate = maxon::GetTranslationMatrix(Vector(10));
 
  // apply matrix
  const maxon::Vector newPos = translate * pos;
 
  DiagnosticOutput("New Position: @", newPos);

Strings

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

See String Manual (Cinema API) 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
  maxon::BaseArray<maxon::Int32> numbers;
 
  // 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);

Cinema API Data Containers

The container types GeData and BaseContainer are used to store any kind of Cinema API 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
  maxon::Data 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
  maxon::BaseArray<maxon::UChar> hash;
 
  // MD5
  const maxon::StreamConversionRef md5 = maxon::StreamConversions::HashMD5().Create() iferr_return;
  md5.ConvertAll(source, hash) iferr_return;
  const maxon::String md5Hash = maxon::GetHashString(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.