C4DAtom Manual

About

C4DAtom is the base class for many entities in the classic Cinema 4D API. Along with GeListNode and BaseList2D it implements the basic functionality of most classic entities. C4DAtomGoal is the extension of the C4DAtom class that allows to create safe references to an C4DAtom entity with a BaseLink.

Access

A pointer to a C4DAtom is typically provided by resolving a BaseLink to an entity. See BaseLink Manual.

// This example gets the link of the given "Instance Object" and accesses the linked C4DAtom.
GeData data;
// read the "Reference Object" parameter
if (!instanceObject->GetParameter(DescID(INSTANCEOBJECT_LINK), data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const BaseLink* const link = data.GetBaseLink();
if (link == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const C4DAtom* const linkedAtom = link->GetLinkAtom(doc);
if (linkedAtom)
{
ApplicationOutput("Got linked C4DAtom"_s);
}

C4DAtom pointers to any kind of entity are often stored in AtomArray objects. See AtomArray Manual.

Allocation/Deallocation

C4DAtom instances cannot be created directly. Only instances of C4DAtom based classes can be created.

Type

C4DAtom gives access to information about the type and class of the specific entity:

// This example checks if the given C4DAtom is a BaseObject.
// If so it checks if the atom is also a point object.
// check the classification
const Int32 classification = atom->GetClassification();
if (classification == Obase)
{
const BaseObject* const baseObject = static_cast<BaseObject*>(atom);
const Vector position = baseObject->GetMg().off;
ApplicationOutput("Position: " + String::VectorToString(position));
// check if it is an instance of a given class
if (atom->IsInstanceOf(Opoint))
{
PointObject* const pointObject = static_cast<PointObject*>(atom);
const Int32 pointCount = pointObject->GetPointCount();
ApplicationOutput("Point Count: " + String::IntToString(pointCount));
// check the specific type
if (atom->GetType() == Offd)
{
// If this point object is a FFD object, change its grid size.
}
}
}
Note
C4DAtom::IsInstanceOf() can also be used to check the classification and element type.
C4DAtom::GetType() can be used to get the ID of any entity that is not listed in the documentation.

Copy

C4DAtom based entities are easily copied and cloned:

The copy flags are:

The AliasTrans argument of these functions is optional. If an AliasTrans instance is provided it is used to update BaseLink parameters of the copied entities. If a BaseLink references an element that is also copied the BaseLink is changed to reference the copy of the originally referenced entity.

// This example clones the objects defined in the given AtomArray.
// The clones are created using an AliasTrans object.
// So if an object is referenced by another object in the object list
// this reference is redirected to the clone of the original object.
// check if the AliasTrans was allocated
// and can be initiated
if (!alias || !alias->Init(doc))
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Int32 selectionCount = objectSelection->GetCount();
if (selectionCount == 0)
return maxon::OK;
for (Int32 i = 0; i < selectionCount; ++i)
{
BaseObject* const object = static_cast<BaseObject*>(objectSelection->GetIndex(i));
if (object == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
BaseObject* const clone = static_cast<BaseObject*>(object->GetClone(COPYFLAGS::NONE, alias));
if (clone == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const String objectName = object->GetName();
clone->SetName(objectName + " clone");
doc->InsertObject(clone, nullptr, nullptr);
}
// this fixes links to elements that are not part of the given object selection
alias->Translate(true);

Disc I/O

A C4DAtom based element can be read from and written to a HyperFile.

If the entity is handled inside another read/write function (NodeData::Read() and NodeData::Write()) these functions must be used:

Warning
These functions are generally not recommended for third party plugins.

Parameter Properties

Parameter descriptions and IDs are managed with these functions:

// This example prints the names of all parameters in the current parameter description.
if (description == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// get the Description of the given object
if (!object->GetDescription(description, DESCFLAGS_DESC::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
void* handle = description->BrowseInit();
const BaseContainer* bc = nullptr;
DescID id, gid;
// loop through all elements of the description
while (description->GetNext(handle, &bc, id, gid))
{
ApplicationOutput("Parameter Name: " + bc->GetString(DESC_NAME));
}
description->BrowseFree(handle);

Parameters

The value of parameters should be changed with C4DAtom::GetParameter() and C4DAtom::SetParameter(). In this way one can be sure, the parameters are set correctly even if the entity does not store the data in its BaseContainer.

Note
Some parameters must be set with DESCFLAGS_SET::USERINTERACTION.
// This example gets the active object of the given BaseDocument.
// If it is a "Cube" its size is increased.
BaseObject* const cube = doc->GetActiveObject();
// check if the active object is a "Cube" object
if (!cube || !cube->IsInstanceOf(Ocube))
return maxon::OK;
GeData data;
const DescID cubeLenID(PRIM_CUBE_LEN);
// read the "Size" parameter
if (!cube->GetParameter(cubeLenID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
Vector size = data.GetVector();
size = size + Vector(100);
cube->SetParameter(cubeLenID, size, DESCFLAGS_SET::NONE);
Note
Parameter IDs are defined with DescID objects. See DescID Manual.

Dirty States

The dirty status of an entity is a number that is increased every time the entity is changed.

The dirty flags are:

// This example checks the dirty states of the given BaseObject before and after an edit.
// Get the current dirty checksums
UInt32 dataDirtyStatus = baseObject->GetDirty(DIRTYFLAGS::DATA);
UInt32 matrixDirtyStatus = baseObject->GetDirty(DIRTYFLAGS::MATRIX);
ApplicationOutput("Data Status: " + String::UIntToString(dataDirtyStatus));
ApplicationOutput("Martix Status: " + String::UIntToString(matrixDirtyStatus));
// edit the object's data
baseObject->SetName("New Name"_s);
// Check the dirty checksums
dataDirtyStatus = baseObject->GetDirty(DIRTYFLAGS::DATA);
matrixDirtyStatus = baseObject->GetDirty(DIRTYFLAGS::MATRIX);
ApplicationOutput("Data Status: " + String::UIntToString(dataDirtyStatus));
ApplicationOutput("Martix Status: " + String::UIntToString(matrixDirtyStatus));

Hierarchy dirty (HDirty) states are used to check if the given entity or some child elements in the hierarchy were changed. Typically used with a BaseDocument or a GeListHead.

The hierarchy dirty flags are:

// Get the current dirty checksums
UInt32 materialsDirtyState = doc->GetHDirty(HDIRTYFLAGS::MATERIAL);
UInt32 objectsDirtyState = doc->GetHDirty(HDIRTYFLAGS::OBJECT);
ApplicationOutput("Materials Status: " + String::UIntToString(materialsDirtyState));
ApplicationOutput("Objects Status: " + String::UIntToString(objectsDirtyState));
// edit a material
BaseMaterial* const mat = doc->GetActiveMaterial();
// check if the active material is a Cinema 4D standard material
if (mat && mat->IsInstanceOf(Mmaterial))
{
}
// check the dirty checksums
materialsDirtyState = doc->GetHDirty(HDIRTYFLAGS::MATERIAL);
objectsDirtyState = doc->GetHDirty(HDIRTYFLAGS::OBJECT);
ApplicationOutput("Materials Status: " + String::UIntToString(materialsDirtyState));
ApplicationOutput("Objects Status: " + String::UIntToString(objectsDirtyState));

Messages

Entities in Cinema 4D often communicate by sending messages to each other. Such a message can be used to inform the element about some event or to retrieve data from the element. A message can be sent to an entity with these functions:

// This example gets the active object and checks if it is a point object.
// If so its points are moved in object space.
// The object itself is informed about this edit with the message MSG_UPDATE.
BaseObject* const activeObject = doc->GetActiveObject();
// check if the active object is a point object
if (!activeObject || !activeObject->IsInstanceOf(Opoint))
return maxon::OK;
PointObject* const pointObject = static_cast<PointObject*>(activeObject);
Vector* const points = pointObject->GetPointW();
if (points == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Int32 pointCount = pointObject->GetPointCount();
for (Int32 i = 0; i < pointCount; ++i)
points[i] = points[i] + Vector(0, 100, 0);
pointObject->Message(MSG_UPDATE);

See also NodeData::Message() Manual.

Further Reading