C4DAtom Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Type
• Copy
• Disc I/O
• Parameter Properties
• Parameters
• Dirty States
• Messages
• Further Reading

About

C4DAtom is the base class for many entities in the Cinema API API. Along with GeListNode and BaseList2D it implements the basic functionality of most Cinema API 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.

• BaseLink::GetLinkAtom(): Evaluates the link and returns a pointer to the linked C4DAtomGoal.
• GeData::GetLinkAtom(): Returns the C4DAtomGoal object referenced by the stored BaseLink object.

  // 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(ConstDescID(DescLevel(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 != nullptr)
  {
    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:

• C4DAtom::GetClassification(): Returns the classification of the entity. Typical classifications are:
  • Obase: Scene object
  • Tbase: Tag
  • Mbase: Material
  • Xbase: Shader
  • Olayer: Layer
  • VPbase: Video Post
  • CTbase: Animation Track
  • Rbase: Render setting
• C4DAtom::IsInstanceOf(): Returns true if the entity is an instance of the given type.
• C4DAtom::GetType(): Returns the type of the entity.
• C4DAtom::GetRealType(): This function is mostly used in conjunction with Xpresso nodes.
• C4DAtom::GetDiskType(): Returns normally the same value as GetClassification(). Typically not used by plugins.

    // 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.
          atom->SetParameter(ConstDescID(DescLevel(FFDOBJECT_SIZE)), Vector(500, 500, 500), DESCFLAGS_SET::USERINTERACTION);
          EventAdd();
        }
      }
    }

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:

• C4DAtom::CopyTo(): Copies the values of an entity into a given destination entity.
• C4DAtom::GetClone(): Returns a newly allocated clone of the entity.

The copy flags are:

• COPYFLAGS::NONE : None.
• COPYFLAGS::NO_HIERARCHY : Copy without children.
• COPYFLAGS::NO_ANIMATION : Copy without tracks, sequences or keys.
• COPYFLAGS::NO_BITS : Do not copy BaseList2D bits.
• COPYFLAGS::NO_MATERIALPREVIEW : Do not create a new material preview.
• COPYFLAGS::NO_BRANCHES : Do not copy branches, for example tags on an object. Automatically implies COPYFLAGS::NO_ANIMATION, as animation is a branch.
• COPYFLAGS::NO_NGONS : Do not copy N-gons.
• COPYFLAGS::RECURSIONCHECK : Checks and avoids instances to cause recursions.

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.
 
  AutoAlloc<AliasTrans> alias;
  // check if the AliasTrans was allocated
  // and can be initiated
  if (alias == nullptr || !alias->Init(doc))
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->GetActiveObjects(objectSelection, GETACTIVEOBJECTFLAGS::NONE);
 
  const Int32 selectionCount = objectSelection->GetCount();
  if (selectionCount == 0)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  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.

• C4DAtom::Read(): Reads the entity from the given HyperFile.
• C4DAtom::Write(): Writes the entity to the given HyperFile.

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

• C4DAtom::ReadObject(): Reads the entity from the given HyperFile.
• C4DAtom::WriteObject(): Writes the entity to the given HyperFile.

Warning

These functions are generally not recommended for third party plugins.

Parameter Properties

Parameter descriptions and IDs are managed with these functions:

• C4DAtom::GetDescription(): Gets the currently used parameter description of the entity. See Description and Description Manual.
• C4DAtom::GetDynamicDescription(): Gets the user data parameter description of the entity. See DynamicDescription and DynamicDescription Manual.
• C4DAtom::GetEnabling(): Returns true if the given parameter is currently enabled.
• C4DAtom::TranslateDescID(): Objects can redirect parameter access with this function. For very generic functionality this function must be called to make sure to handle always the correct parameter and object.

  // This example prints the names of all parameters in the current parameter description.
 
  AutoAlloc<Description> 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.

• C4DAtom::GetParameter(): Reads the value of the parameter with the given ID.
• C4DAtom::SetParameter(): Sets the value of the parameter with the given ID.

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 == nullptr || !cube->IsInstanceOf(Ocube))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  GeData       data;
  const DescID cubeLenID = ConstDescID(DescLevel(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.

• C4DAtom::GetDirty(): Returns the dirty count for the given flags.
• C4DAtom::SetDirty(): Increases the dirty count for the given flags. Mostly used to make a custom plugin class dirty.

The dirty flags are:

• DIRTYFLAGS::NONE : None.
• DIRTYFLAGS::MATRIX : Matrix changed.
• DIRTYFLAGS::DATA : Container changed.
• DIRTYFLAGS::SELECT : Check all valid selections of the object, e.g. points, edge, polys.
• DIRTYFLAGS::CACHE : Check if the cache of an object has been changed (rebuilt).
• DIRTYFLAGS::CHILDREN : Check if the children are dirty.
• DIRTYFLAGS::DESCRIPTION : Description changed.
• DIRTYFLAGS::SELECTION_OBJECTS : For BaseDocument, object selections have changed.
• DIRTYFLAGS::SELECTION_TAGS : For BaseDocument, tag selections have changed.
• DIRTYFLAGS::SELECTION_MATERIALS : For BaseDocument, material selections have changed.
• DIRTYFLAGS::ALL : Check all dirty flags.

  // 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.

• C4DAtom::GetHDirty(): Returns the dirty count for the given flags.
• C4DAtom::SetHDirty(): Increases the dirty count for the given flags. Mostly used to make a custom plugin class dirty.

The hierarchy dirty flags are:

• HDIRTYFLAGS::NONE : None.
• HDIRTYFLAGS::ANIMATION : Animation mask.
• HDIRTYFLAGS::OBJECT : Object data mask.
• HDIRTYFLAGS::OBJECT_MATRIX : Object matrix mask.
• HDIRTYFLAGS::OBJECT_HIERARCHY : Object hierarchy mask.
• HDIRTYFLAGS::TAG : Tag data mask.
• HDIRTYFLAGS::MATERIAL : Material data mask.
• HDIRTYFLAGS::SHADER : Shader data mask.
• HDIRTYFLAGS::RENDERSETTINGS : Render settings mask.
• HDIRTYFLAGS::VP : Videopost mask.
• HDIRTYFLAGS::FILTER : Filter data mask.
• HDIRTYFLAGS::NBITS : N-bits data mask.
• HDIRTYFLAGS::ALL : All.

  // 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))
  {
    mat->SetParameter(ConstDescID(DescLevel(MATERIAL_COLOR_COLOR)), Vector(255, 0, 0), DESCFLAGS_SET::NONE);
  }
 
  // 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:

• C4DAtom::Message(): Sends a synchronous message to the entity. Valid message IDs are listed in MSG.
• C4DAtom::MultiMessage(): In case of a GeListNode the message is also sent to the child objects. This is typically used with a BaseDocument.

  // 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 == nullptr || !activeObject->IsInstanceOf(Opoint))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  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

• GeListNode Manual
• BaseList2D Manual
• DescID Manual
• AtomArray Manual
• BaseLink Manual
• Description Manual
• DynamicDescription Manual