Primitive Data Types Manual (Cinema API)

Table of Contents

• About
• Bool
  • Access
  • Disc I/O
• Char
  • Disc I/O
• Integer
  • Access
  • Convert
  • Disc I/O
• Float
  • Access
  • Compare
  • Convert
  • Disc I/O
• Further Reading

About

Primitive data types are the building blocks for data stored within Cinema 4D. These data types are typically based on the standard data types of C++ and are available in a 32 and 64 bit version.

Note

To perform mathematical operations using these data types use the build-in functions, see Mathematical Functions Manual (Cinema API).

Warning

An overview over Maxon API primitive data types can be found here: Basic Data Types.

  // This example reads the "Fillet" settings of the selected Cube object
  // and writes them into a HyperFile.
 
  Bool  doFillet = false;
  Float filletRadius = 20.0;
  Int32 filletSubidivision = 5;
 
  // get parameters
 
  GeData data;
 
  // read the "Fillet" parameter
  if (!cube->GetParameter(ConstDescID(DescLevel(PRIM_CUBE_DOFILLET)), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  doFillet = data.GetBool();
 
  // read the "Fillet Radius" parameter
  if (!cube->GetParameter(ConstDescID(DescLevel(PRIM_CUBE_FRAD)), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  filletRadius = data.GetFloat();
 
  // read the "Fillet Subdivision" parameter
  if (!cube->GetParameter(ConstDescID(DescLevel(PRIM_CUBE_SUBF)), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  filletSubidivision = data.GetInt32();
 
  // save to HyperFile
  AutoAlloc<HyperFile> hyperFile;
  if (hyperFile == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // open the HyperFile to write
  if (!hyperFile->Open('cube', filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
    return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(filename, MAXONCONVERTMODE::NONE), "Could not open file."_s);
 
  hyperFile->WriteBool(doFillet);
  hyperFile->WriteFloat(filletRadius);
  hyperFile->WriteInt32(filletSubidivision);
  hyperFile->Close();

Bool

Boolean values are used for logical operations:

• ::Bool: Defined as int.

Access

::Bool variables can be created on demand or can be obtained from other entities.

Access ::Bool values stored in a BaseContainer:

• BaseContainer::GetBool(): Returns the ::Bool value stored at the given ID.
• BaseContainer::SetBool(): Sets the ::Bool value stored at the given ID.

See also BaseContainer Manual.

Access ::Bool values stored in a GeData object (GeData type is ::DA_LONG):

• GeData::GetBool(): Returns the ::Bool value.
• GeData::SetInt32(): Returns the ::Int32 value.

See also GeData Manual.

  // This example stores and reads a Boolean value in the GeData object.
 
  GeData data;
  data.SetInt32(false);
 
  // Boolean values are internally stored as integers
  if (data.GetType() == DA_LONG)
  {
    // get Boolean value
    if (data.GetBool())
      ApplicationOutput("is true");
    else
      ApplicationOutput("is false");
  }

Disc I/O

A ::Bool value can be stored in a BaseFile or a HyperFile:

• BaseFile::ReadBool(): Reads the ::Bool value from the BaseFile.
• BaseFile::WriteBool(): Writes the ::Bool value to the BaseFile.
• HyperFile::ReadBool(): Reads the ::Bool value from the HyperFile.
• HyperFile::WriteBool(): Writes the ::Bool value to the HyperFile.

See also BaseFile Manual on Bool and HyperFile Manual on Bool.

Char

A character variable contains a single symbol and is typically the smallest piece of memory.

• ::Char: Signed 8 bit character, defined as char.
• ::UChar: Unsigned 8 bit character, defined as unsigned char.
• ::Utf16Char: Defined as UInt16.
• ::Utf32Char: Defined as UInt32.

    // This example converts the given String into a C-String to use it with the standard library.
 
    const String string { "foobar" };
 
    // convert to c string and insert into std string.
    Char*       cstring = string.GetCStringCopy();
    std::string stdString { cstring };
 
    DeleteMem(cstring);

Disc I/O

A character can be stored in a BaseFile or HyperFile:

• BaseFile::ReadChar(): Reads the ::Char from the BaseFile.
• BaseFile::WriteChar(): Writes the ::Char to the BaseFile.
• BaseFile::ReadUChar(): Reads the ::UChar from the BaseFile.
• BaseFile::WriteUChar(): Writes the ::UChar to the BaseFile.
• HyperFile::ReadChar(): Reads the ::Char from the HyperFile.
• HyperFile::WriteChar(): Writes the ::Char to the HyperFile.
• HyperFile::ReadUChar(): Reads the ::UChar from the HyperFile.
• HyperFile::WriteUChar(): Writes the ::UChar to the HyperFile.

Note

To read and write ::Utf16Char and ::Utf32Char use BaseFile::ReadBytes() and BaseFile::WriteBytes().

See also BaseFile Manual on Char and HyperFile Manual on Char.

Integer

Integer variables contain whole numbers. Both signed and unsigned variations are available, both in 16, 32 and 64 bit.

• ::Int16: Defined as short int.
• ::UInt16: Defined as unsigned short int.
• ::Int32: Defined as signed int.
• ::UInt32: Defined as unsigned int.
• ::Int64: Defined as signed long long.
• ::UInt64: Defined as unsigned long long.
• ::Int: Defined as Int64.
• ::UInt: Defined as UInt64.

Note

If larger integer numbers are needed the class maxon::BigInteger can be used.

Access

Integer values can be created by casting them from float values. To do this safely these macros should be used:

• SAFEINT(): Safely converts a float value into ::Int.
• SAFEINT32(): Safely converts a float value into ::Int32.
• SAFEINT64(): Safely converts a float value into ::Int64.
• MINVALUE_INT32_FLOAT32: The minimum ::Float32 value that can be represented by ::Int32.
• MAXVALUE_INT32_FLOAT32: The maximum ::Float32 value that can be represented by ::Int32.
• MINVALUE_INT64_FLOAT64: The minimum ::Float64 value that can be represented by ::Int64.
• MAXVALUE_INT64_FLOAT64: The maximum ::Float64 value that can be represented by ::Int64.

Warning

Never try to cast an integer pointer into a float pointer or vice versa.

  // This example performs a float point operation and safely converts the result to an integer.
 
  const Float32 percentage = 0.23f;
  const Int32   width = 1280;
 
  const Float32 pos = Float32(width) * percentage;
  const Int32   pixel = SAFEINT32(pos);
 
  ApplicationOutput("Pixel: " + String::IntToString(pixel));

Integer variables can be obtained from other entities.

Access integer values stored in a BaseContainer:

• BaseContainer::GetInt32(): Returns the ::Int32 value stored at the given ID.
• BaseContainer::SetInt32(): Sets the ::Int32 value stored at the given ID.
• BaseContainer::GetUInt32(): Returns the ::UInt32 value stored at the given ID.
• BaseContainer::SetUInt32(): Sets the ::UInt32 value stored at the given ID.
• BaseContainer::GetInt64(): Returns the ::Int64 value stored at the given ID.
• BaseContainer::SetInt64(): Sets the ::Int64 value stored at the given ID.
• BaseContainer::GetUInt64(): Returns the ::UInt64 value stored at the given ID.
• BaseContainer::SetUInt64(): Sets the ::UInt64 value stored at the given ID.

See also BaseContainer Manual.

Access ::Int32 or ::Int64 values stored in a GeData object (GeData type is ::DA_LONG or ::DA_LLONG):

• GeData::GetInt32(): Returns the ::Int32 value.
• GeData::SetInt32(): Sets the ::Int32 value.
• GeData::GetInt64(): Returns the ::Int64 value.
• GeData::SetInt64(): Sets the ::Int64 value.

See also GeData Manual.

String objects can be parsed to get the numeric value represented by the string:

• String::ParseToInt32(): Converts the string into an ::Int32 value.
• String::ToInt32(): Converts the string to an ::Int32 value.
• String::ToInt64(): Converts the string to an ::Int64 value.
• String::ToUInt32(): Converts the string to a ::UInt32 value.
• String::ToUInt64(): Converts the string to a ::UInt64 value.
• String::ToInt(): Converts the string to an ::Int value.
• String::ToUInt(): Converts the string to a ::UInt value.
• StringToNumber(): Converts a string to a data value of type ::Float, ::Int32 or ::BaseTime.

See also String Manual (Cinema API).

  // This example converts a string into an integer number.
 
  const String bottles = "99 bottles of beer on the wall";
  const String number  = bottles.Left(2);
 
  const Int32 numberOfBottles = number.ToInt32(nullptr);

Convert

To display them in the GUI, integer numbers also can be converted to String objects:

• String::HexToString(): Converts the number to a hexadecimal representation.
• String::IntToString(): Converts the given integer value to a string.
• String::UIntToString(): Converts the given unsigned integer value to a string.

See also String Manual (Cinema API).

  // This example prints the number of selected objects to the console.
  AutoAlloc<AtomArray> selection;
  if (selection == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->GetActiveObjects(selection, GETACTIVEOBJECTFLAGS::NONE);
 
  const Int32 selCount = selection->GetCount();
 
  ApplicationOutput(String::IntToString(selCount) + " object(s) selected");

Disc I/O

An integer value can be stored in a BaseFile or a HyperFile:

• BaseFile::ReadInt16(): Reads the ::Int16 value from the BaseFile.
• BaseFile::WriteInt16(): Writes the ::Int16 value to the BaseFile.
• BaseFile::ReadUInt16(): Reads the ::UInt16 value from the BaseFile.
• BaseFile::WriteUInt16(): Writes the ::UInt16 value to the BaseFile.
• BaseFile::ReadInt32(): Reads the ::Int32 value from the BaseFile.
• BaseFile::WriteInt32(): Writes the ::Int32 value to the BaseFile.
• BaseFile::ReadUInt32(): Reads the ::UInt32 value from the BaseFile.
• BaseFile::WriteUInt32(): Writes the ::UInt32 value to the BaseFile.
• BaseFile::ReadInt64(): Reads the ::Int64 value from the BaseFile.
• BaseFile::WriteInt64(): Writes the ::Int64 value to the BaseFile.
• BaseFile::ReadUInt64(): Reads the ::UInt64 value from the BaseFile.
• BaseFile::WriteUInt64(): Writes the ::UInt64 value to the BaseFile.
• HyperFile::ReadInt16(): Reads the ::Int16 value from the HyperFile.
• HyperFile::WriteInt16(): Writes the ::Int16 value to the HyperFile.
• HyperFile::ReadUInt16(): Reads the ::UInt16 value from the HyperFile.
• HyperFile::WriteUInt16(): Writes the ::UInt16 value to the HyperFile.
• HyperFile::ReadInt32(): Reads the ::Int32 value from the HyperFile.
• HyperFile::WriteInt32(): Writes the ::Int32 value to the HyperFile.
• HyperFile::ReadUInt32(): Reads the ::UInt32 value from the HyperFile.
• HyperFile::WriteUInt32(): Writes the ::UInt32 value to the HyperFile.
• HyperFile::ReadInt64(): Reads the ::Int64 value from the HyperFile.
• HyperFile::WriteInt64(): Writes the ::Int64 value to the HyperFile.
• HyperFile::ReadUInt64(): Reads the ::UInt64 value from the HyperFile.
• HyperFile::WriteUInt64(): Writes the ::UInt64 value to the HyperFile.

See also BaseFile Manual on Integer and HyperFile Manual on Integer.

Float

Floating point numbers present rational numbers with limited precision. Variations are available in 32 and 64 bit.

• ::Float32: Defined as float.
  • MINVALUE_FLOAT32: The minimum value a ::Float32 can represent.
  • MAXVALUE_FLOAT32: The maximum value a ::Float32 can represent.
• ::Float64: Defined as double.
  • MINVALUE_FLOAT64: The minimum value a ::Float64 can represent.
  • MAXVALUE_FLOAT64: The maximum value a ::Float64 can represent.
• ::Float: Defined as Float64.
  • MINVALUE_FLOAT: The minimum value a ::Float can represent.
  • MAXVALUE_FLOAT: The maximum value a ::Float can represent.

Access

Floating point variables can be obtained from other entities.

Access float values stored in a BaseContainer:

• BaseContainer::GetFloat(): Returns the ::Float value stored at the given ID.
• BaseContainer::SetFloat(): Sets the ::Float value stored at the given ID.

See also BaseContainer Manual.

Access float values stored in a GeData object (GeData type is ::DA_REAL):

• GeData::GetFloat(): Returns the ::Float value.
• GeData::SetFloat(): Sets the ::Float value.

See also GeData Manual.

Of course it is also possible to cast integer types into float values. Just be aware of the limited precision of different float formats.

Warning

Never try to cast an integer pointer into a float pointer or vice versa.

String objects can be parsed to get the numeric value represented by the string:

• String::ParseToFloat(): Converts the string into a ::Float value.
• String::ToFloat(): Converts the string to a ::Float value.
• StringToNumber(): Converts a string to a data value of type ::Float, ::Int32 or ::BaseTime.

Compare

Since floating point values are only stored with limited precision they cannot represent every value perfectly. This is especially critical when it is needed to compare two floating point values:

• CompareFloatTolerant(): Returns true if two floats are close to each other on a bit basis.
• CheckFloat(): Returns true if the given ::Float is a valid floating point number.
• RepairFloat(): Repairs floating point values.

  // This example compares the result of a float operation with a given float value.
 
  const Float32 x = 0.1f;
  const Float32 y = 0.2f;
  const Float32 reference = 0.3f;
 
  const Float32 sum = x + y;
 
  // compare float values
  if (CompareFloatTolerant(sum, reference))
    ApplicationOutput("The float values are really close to each other.");

Convert

To display them in the GUI, floating point numbers also can be converted to String objects:

• String::FloatToString(): Converts the given float value to a string.

  // This example converts the given float value to a String with two digits after the comma.
 
  const Float32 value = 123.456f;
 
  ApplicationOutput("Value: " + String::FloatToString(value, -1, 2));

Disc I/O

A floating point value can be stored in a BaseFile or a HyperFile:

• BaseFile::ReadFloat32(): Reads the ::Float32 value from the BaseFile.
• BaseFile::WriteFloat32(): Writes the ::Float32 value to the BaseFile.
• BaseFile::ReadFloat64(): Reads the ::Float64 value from the BaseFile.
• BaseFile::WriteFloat64(): Writes the ::Float64 value to the BaseFile.
• HyperFile::ReadFloat(): Reads the ::Float value from the HyperFile.
• HyperFile::WriteFloat(): Writes the ::Float value to the HyperFile.
• HyperFile::ReadFloat32(): Reads the ::Float32 value from the HyperFile.
• HyperFile::WriteFloat32(): Writes the ::Float32 value to the HyperFile.
• HyperFile::ReadFloat64(): Reads the ::Float64 value from the HyperFile.
• HyperFile::WriteFloat64(): Writes the ::Float64 value to the HyperFile.

See also BaseFile Manual on Float and HyperFile Manual on Float.

Further Reading

• GeData Manual
• BaseContainer Manual
• Vector Manual (Cinema API)
• Matrix Manual (Cinema API)
• String Manual (Cinema API)