InstanceObject Manual

Table of Contents

• About
• Creation
• Properties
• Multi-Instances
• Further Reading

About

InstanceObject represents an instance object in Cinema 4D. Such an instance object references another scene object. Additionally, it can store multiple matrices for multi-instances.

InstanceObject objects are an instance of Oinstance.

Creation

InstanceObject objects are created with the usual tools (Entity Creation and Destruction Manual (Cinema API)):

• InstanceObject::Alloc(): Creates a new InstanceObject.
• InstanceObject::Free(): Deletes the given InstanceObject.

Properties

The parameters of an InstanceObject are edited as usual using C4DAtom::GetParameter() and C4DAtom::SetParameter(). The parameter IDs are defined in Oinstance.h.

The referenced object can be accessed with the INSTANCEOBJECT_LINK parameter or with these functions:

• InstanceObject::GetReferenceObject(): Returns the referenced BaseObject.
• InstanceObject::SetReferenceObject(): Sets the referenced BaseObject.

Multi-Instances

An InstanceObject can store multiple instance positions. So it can represent not only one but many instances. To turn on the multi-instance mode set the parameter INSTANCEOBJECT_RENDERINSTANCE_MODE to INSTANCEOBJECT_RENDERINSTANCE_MODE_MULTIINSTANCE.

• InstanceObject::IsMultiInstance(): Returns true if the object is in multi-instance mode.

  // This example creates an intance object that uses the given reference object and matrix object.
 
  // create instance object
  InstanceObject* const instance = InstanceObject::Alloc();
  if (instance == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // insert object into the scene
  doc->InsertObject(instance, nullptr, nullptr);
 
  // use the given reference object
  instance->SetReferenceObject(reference) iferr_return;
 
  // use position data provided by the given matrix object
 
  if (!instance->SetParameter(ConstDescID(DescLevel(INSTANCEOBJECT_MULTIPOSITIONINPUT)), matrix, DESCFLAGS_SET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
  if (!instance->SetParameter(ConstDescID(DescLevel(INSTANCEOBJECT_RENDERINSTANCE_MODE)), INSTANCEOBJECT_RENDERINSTANCE_MODE_MULTIINSTANCE, DESCFLAGS_SET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);

For each multi-instance a matrix and a color (maxon::Color64) is stored:

• InstanceObject::GetInstanceCount(): Returns the number of multi-instances. The number of instances is the size of the matrix and color arrays.
• InstanceObject::GetInstanceMatrices(): Returns the array of instance matrices.
• InstanceObject::GetInstanceMatrix(): Returns the matrix of the given instance index.
• InstanceObject::SetInstanceMatrix(): Sets the matrix at the given instance index.
• InstanceObject::SetInstanceMatrices(): Sets the array of instance matrices.
• InstanceObject::GetMatrixDirtyID(): Returns the matrix dirty ID of the given instance index.
• InstanceObject::GetInstanceColors(): Returns the array of instance colors.
• InstanceObject::GetInstanceColor(): Returns the color of the given instance index.
• InstanceObject::SetInstanceColors(): Sets the array of instance colors.

  // This example defines positions and colors and stores them in the given instance object as multi-instance data.
 
  // prepare matrices and colors
  maxon::BaseArray<Matrix>         matrices;
  maxon::BaseArray<maxon::Color64> colors;
 
  const Int count = 100;
  matrices.Resize(count) iferr_return;
  colors.Resize(count) iferr_return;
 
  // generate positions and colors
  Float       position = 0.0;
  const Float step = 300.0;
  Float       hue  = 0.0;
  const Float hueStep = 1.0 / count;
 
  for (Int i = 0; i < count; ++i)
  {
    // matrices
    matrices[i] = MatrixMove(Vector(position, 0.0, 0.0));
    position += step;
    // colors
    const Vector colorHSV { hue, 1.0, 1.0 };
    const Vector colorRGB = HSVToRGB(colorHSV);
    colors[i] = maxon::Color64(colorRGB);
    hue += hueStep;
  }
 
  // store data in the instance object
  instance->SetInstanceMatrices(matrices) iferr_return;
  instance->SetInstanceColors(colors) iferr_return;

The InstanceObject can also store unique IPs to identify an instance (see Generating).

• InstanceObject::GetInstanceUniqueIPs(): Returns the unique IPs.
• InstanceObject::GetInstanceUniqueIP(): Returns the unique IP for the given instance index.
• InstanceObject::SetInstanceUniqueIPs(): Sets the unique IPs.

Multi-instance information can also be accessed with a MultiInstanceData object:

• MultiInstanceData::ExtractInfo(): Loads the multi-instance data from the given InstaceObject.
• MultiInstanceData::Clear(): Clears the internal data.
• MultiInstanceData::instancedObject: The referenced BaseObject.
• MultiInstanceData::instanceMatrices: Array of instance matrices.
• MultiInstanceData::instanceColors: Array of instance colors.
• MultiInstanceData::instanceUniqueIPs: Unique IP, one for each instance.

  // This example reads the multi-instance data from the given instance object using MultiInstanceData.
 
  // read data
  MultiInstanceData data;
  data.ExtractInfo(instanceObject) iferr_return;
 
  // for each position, create a cube object
  for (const Matrix& mg : data.instanceMatrices)
  {
    BaseObject* const cube = BaseObject::Alloc(Ocube);
    if (cube == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    cube->SetMg(mg);
    doc->InsertObject(cube, nullptr, nullptr);
  }

Further Reading

• Scene Elements & Data
• BaseObject Manual
• BaseDocument Manual
• BaseArray Manual