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 (Classic)):

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:

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.

// This example creates an intance object that uses the given reference object and matrix object.
// create instance object
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
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);

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

// This example defines positions and colors and stores them in the given instance object as multi-instance data.
// prepare matrices and 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).

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

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

Further Reading

InstanceObject::SetReferenceObject
maxon::Result< void > SetReferenceObject(BaseObject *refObj)
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
Int
maxon::Int Int
Definition: ge_sys_math.h:49
maxon::Color64
Col3< Float64, 1 > Color64
Definition: vector.h:78
BaseObject
Definition: c4d_baseobject.h:220
maxon::Mat3< maxon::Vector64 >
Float
maxon::Float Float
Definition: ge_sys_math.h:51
InstanceObject::SetInstanceColors
maxon::Result< void > SetInstanceColors(const maxon::BaseArray< maxon::Color64 > &colors)
BaseObject::SetMg
void SetMg(const Matrix &m)
Definition: c4d_baseobject.h:484
maxon::BaseArray::Resize
ResultMem Resize(Int newCnt, COLLECTION_RESIZE_FLAGS resizeFlags=COLLECTION_RESIZE_FLAGS::DEFAULT)
Definition: basearray.h:1077
INSTANCEOBJECT_MULTIPOSITIONINPUT
@ INSTANCEOBJECT_MULTIPOSITIONINPUT
Definition: oinstance.h:11
iferr_return
#define iferr_return
Definition: resultbase.h:1434
Ocube
#define Ocube
Cube.
Definition: ge_prepass.h:1037
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
HSVToRGB
Vector HSVToRGB(const Vector &col)
maxon::BaseArray
Definition: basearray.h:366
DESCFLAGS_SET::NONE
@ NONE
None.
InstanceObject
Definition: lib_instanceobject.h:33
MultiInstanceData::ExtractInfo
maxon::Result< void > ExtractInfo(InstanceObject *obj)
Definition: lib_instanceobject.h:229
InstanceObject::Alloc
static InstanceObject * Alloc()
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
INSTANCEOBJECT_RENDERINSTANCE_MODE
@ INSTANCEOBJECT_RENDERINSTANCE_MODE
Definition: oinstance.h:7
maxon::Vec3< maxon::Float64, 1 >
MultiInstanceData::instanceMatrices
maxon::BaseArray< Matrix > instanceMatrices
Global matrices, one for each instance.
Definition: lib_instanceobject.h:264
MatrixMove
Matrix MatrixMove(const Vector &t)
Vector
maxon::Vec3< maxon::Float64, 1 > Vector
Definition: ge_math.h:133
BaseObject::Alloc
static BaseObject * Alloc(Int32 type)
MultiInstanceData
Definition: lib_instanceobject.h:210
INSTANCEOBJECT_RENDERINSTANCE_MODE_MULTIINSTANCE
@ INSTANCEOBJECT_RENDERINSTANCE_MODE_MULTIINSTANCE
Definition: oinstance.h:10
InstanceObject::SetInstanceMatrices
maxon::Result< void > SetInstanceMatrices(const maxon::BaseArray< Matrix > &matrices)