BaseList2D Manual

Table of Contents

• About
• Allocation/Deallocation
• Read-Only Properties
• Properties
  • Data
  • Bits
  • Name
  • Node
  • Shader
  • Marker
  • Unique ID
  • Animation Tracks
  • Keyframe Selection
  • Layer
  • DescID State
• Functionality
• Further Reading

About

The class BaseList2D is based on C4DAtom and GeListNode. It is a base class for many entities of the classic Cinema 4D API and adds additional functionality.

BaseList2D objects are an instance of Tbaselist2d.

Allocation/Deallocation

BaseList2D elements can be created with the usual tools:

• BaseList2D::Alloc(): Creates a new BaseList2D object with the given type ID.
• BaseList2D::Free(): Destroys the given BaseList2D object.

Note

For most BaseList2D based classes dedicated "Alloc" and "Free" functions exist.

    // This example creates an object buffer multipass.
 
    MultipassObject* const multipass = static_cast<MultipassObject*>(BaseList2D::Alloc(Zmultipass));
    if (multipass == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    BaseContainer& data = multipass->GetDataInstanceRef();
    data.SetInt32(MULTIPASSOBJECT_TYPE, VPBUFFER_OBJECTBUFFER);
    data.SetInt32(MULTIPASSOBJECT_OBJECTBUFFER, 99);
 
    renderData->InsertMultipass(multipass);

Read-Only Properties

The following properties can be accessed:

• BaseList2D::GetBubbleHelp(): Returns the bubble help text.
• BaseList2D::GetIcon(): Fills the given icon data.
• BaseList2D::GetTypeName(): Returns the name of the element's type.
• BaseList2D::GetMain(): Returns the parent of the owning GeListHead. See Heads and Branches.

  // This example prints the name and type name of the active object.
 
  BaseObject* const object = doc->GetActiveObject();
  if (object == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  ApplicationOutput("The object: \"" + object->GetName() + "\" is a \"" + object->GetTypeName() + "\"");

Properties

Data

BaseList2D based objects store an internal BaseContainer. This BaseContainer can store various information, like for example (but not restricted to) the values of parameters of an object or tag.

• BaseList2D::GetData(): Returns a copy of the internal BaseContainer.
• BaseList2D::SetData(): The internal data is merged or replaced with the given BaseContainer.
• BaseList2D::GetDataInstance(): Returns a pointer to the internal BaseContainer.
• BaseList2D::GetDataInstanceRef(): Returns a reference to the internal BaseContainer.

See BaseContainer Manual.

  // This example implements NodeData::Init() in a plugin class.
  // It sets the default values of the plugin's parameters.
 
  virtual Bool Init(GeListNode* node)
  {
    if (node == nullptr || !SUPER::Init(node))
      return false;
 
    // get the "real" object
    BaseObject* const obj = static_cast<BaseObject*>(node);
 
    // get data container
    BaseContainer& data = obj->GetDataInstanceRef();
 
    // set default parameter values
    data.SetBool(EXAMPLE_GENERATOR_PARAMETER_BOOL, true);
    data.SetInt32(EXAMPLE_GENERATOR_PARAMETER_VALUE, 123);
 

Note

Typically one should use C4DAtom::SetParameter() and C4DAtom::GetParameter() to access parameters, instead of accessing the BaseContainer directly. See C4DAtom Parameters.

Bits

Various properties are not stored in parameters but are set using bits. See BIT.

• BaseList2D::SetBit(): Sets the given bit.
• BaseList2D::GetBit(): Returns true if the given bit is set.
• BaseList2D::DelBit(): Deletes the given bit.
• BaseList2D::ToggleBit(): Toggles the given bit.
• BaseList2D::GetAllBits(): Returns all bits of the element.
• BaseList2D::SetAllBits(): Sets all bits of the element.

  // This example disables the first video post.
 
  RenderData* const rd = doc->GetActiveRenderData();
  if (rd == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  BaseVideoPost* const vp = rd->GetFirstVideoPost();
  if (vp != nullptr)
    vp->SetBit(BIT_VPDISABLED);

See also GeListNode NBits.

Name

A BaseList2D based element can have a name. Often this name is used in Cinema 4D's UI, like names of objects in the Object Manager:

• BaseList2D::GetName(): Returns the element's name.
• BaseList2D::SetName(): Sets the element's name.

  // This example changes the name of the selected object.
 
  BaseObject* const object = doc->GetActiveObject();
  if (object == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  object->SetName("This is the selected object"_s);

Note

While BaseDocument is as well derived from BaseList2D, the "name" of a document is a Filename set with BaseDocument::SetDocumentName(). See BaseDocument Document Name and Path.

Node

BaseList2D contain function to deal with NimbusRef.

• BaseList2D::GetNimbusRef() Get the NimbusRef from the object

Note

The returned result should be assign to a NimbusBaseRef.

• BaseList2D::RemoveNimbusRef() Remove NimbusRef from the object
• BaseList2D::GetAllNimbusRefs() Retrieve all the NimbusRef assigned to the object.
• BaseList2D::IsNodeBased() Checks whether the object contains nodes.

Shader

By default a BaseList2D based element can host a list of shaders. If a new shader is created and used by the element, it must be inserted into the element's shader list.

• BaseList2D::GetFirstShader(): Returns the first shader of the shader list.
• BaseList2D::InsertShader(): Inserts the given shader into the shader list.

  // This example creates a shader and adds it to the given material.
 
  BaseShader* const shader = BaseShader::Alloc(Xbrick);
  if (shader == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  material->InsertShader(shader);
  material->SetParameter(DescID { MATERIAL_COLOR_SHADER }, shader, DESCFLAGS_SET::NONE);

See also GeListNode Lists and Trees.

Marker

A BaseList2D based element owns a GeMarker object.

• BaseList2D::GetMarker(): Returns the element's marker.
• BaseList2D::SetMarker(): Sets the element's marker.

See GeMarker Manual for more information.

  // This example gets the name and the marker of the given BaseObject.
  // The name is used to search for an object with the same name in the document.
  // The marker is used to check if the found object is also the original object.
 
  const String    objectName = object->GetName();
  const GeMarker& marker = object->GetMarker();
 
  // search object with the same name
  const BaseObject* const foundObject = doc->SearchObject(objectName);
  if (foundObject != nullptr)
  {
    // check if it is the same object
    const GeMarker& foundObjectMarker = foundObject->GetMarker();
 
    // compare if the markers are equal
    if (foundObjectMarker.Compare(marker) == 0)
      ApplicationOutput("The found object is the original object"_s);
    else
      ApplicationOutput("The found object is not the original object"_s);
  }

Unique ID

BaseList2D based elements can store an array of unique IDs. These IDs are typically used to identify scenes and elements written by external applications using the Melange library.

• BaseList2D::AddUniqueID(): Adds a new unique ID.
• BaseList2D::FindUniqueID(): Returns true if a unique ID for the given application ID was found.
• BaseList2D::GetUniqueIDCount(): Returns the number of stored IDs.
• BaseList2D::GetUniqueIDIndex(): Gets the data of the given application ID.
• MAXON_CREATOR_ID: The application ID that accesses the internally stored GeMarker.

  // This example adds a new ID to the given object.
  // After that all stored IDs are checked.
 
  // adding a new ID
  const Int32 ID = 1111111;
  Int32       value = 123456;
  object->AddUniqueID(ID, (Char*)&value, sizeof(Int32));
 
 
  Int32       appID  = 0;
  const Char* memory = nullptr;
  Int         bytes  = 0;
 
  // looping through all IDs
  for (Int32 i = 0; i < object->GetUniqueIDCount(); ++i)
  {
    // get the unique ID data stored at the given index
    if (object->GetUniqueIDIndex(i, appID, memory, bytes))
    {
      ApplicationOutput("ID: " + String::IntToString(appID));
 
      // check if the memory block has the size of an Int32 number
      if (bytes == sizeof(Int32))
      {
        const Int32 data = *(Int32*)memory;
        ApplicationOutput("Value: " + String::IntToString(data));
      }
    }
  }

Animation Tracks

BaseList2D based elements store a list of CTrack objects (see also Heads and Branches). A CTrack stores the animation data for a given parameter.

• BaseList2D::GetCTrackRoot(): Returns the GeListHead that stores the element's tracks.
• BaseList2D::GetFirstCTrack(): Returns the first CTrack in the list.
• BaseList2D::FindCTrack(): Returns the CTrack for the given parameter ID.
• BaseList2D::InsertTrackSorted(): Adds the given CTrack to the object. The object takes ownership.

  // This example checks if an animation track for the given parameter exists.
  // If no track exists it is created.
 
  const DescID paramID = DescLevel { PRIM_SPHERE_RAD, DTYPE_REAL, 0 };
 
  // check if track exists
  CTrack* track = sphere->FindCTrack(paramID);
  if (track != nullptr)
    return maxon::OK;
 
  // create track
  track = CTrack::Alloc(sphere, paramID);
  if (track == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // insert track
  sphere->InsertTrackSorted(track);

See Animation Overview.

Keyframe Selection

Parameters can be part of a so called keyframe selection:

• BaseList2D::ClearKeyframeSelection(): Clears the keyframe selection.
• BaseList2D::FindKeyframeSelection(): Returns true if the given parameter ID is part of the keyframe selection.
• BaseList2D::SetKeyframeSelection(): Sets the keyframe selection status of the given parameter ID.
• BaseList2D::KeyframeSelectionContent(): Returns true if there are any parameters in the current keyframe selection.

  // This example checks if there is a keyframe selection on the given object.
  // If yes, all available description IDs are checked if they are part of that selection.
 
  AutoAlloc<Description> description;
  if (description == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // check if  any parameters on the object are part of the keyframe selection
  if (object->KeyframeSelectionContent())
  {
    // read description from the 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 the description
    while (description->GetNext(handle, &bc, id, gid))
    {
      // check if the parameter ID is part of the keyframe selection
      if (object->FindKeyframeSelection(id) && bc)
      {
        ApplicationOutput("Parameter \"" + bc->GetString(DESC_NAME) + "\" is part of the keyframe selection");
      }
    }
  }

See also C4DAtom Parameter Properties and Animate.

Layer

A BaseList2D based element can be part of a layer:

• BaseList2D::GetLayerObject(): Returns the LayerObject representing the element's layer or nullptr.
• BaseList2D::SetLayerObject(): Sets the layer of the element.
• BaseList2D::GetLayerData(): Returns the layer data of the object's layer.
• BaseList2D::SetLayerData(): Sets the layer data of the object's layer.

  // This example gets the LayerObject from the given object
  // and checks if it should be visible or not.
 
  // get layer object
  LayerObject* const layer = object->GetLayerObject(doc);
  if (layer != nullptr)
  {
    // get layer data
    const LayerData* const ld = object->GetLayerData(doc);
 
    if (ld != nullptr)
    {
      // check if elements should be visible in the Editor
      if (ld->view)
        ApplicationOutput("visible"_s);
      else
        ApplicationOutput("invisible"_s);
    }
  }

See also Layer Manual.

DescID State

For each parameter ID a certain state can be defined. This is typically managed by the Xref or Take system.

• BaseList2D::SetDescIDState(): Sets the state of the given parameter ID.
• BaseList2D::GetDescIDState(): Returns the state of the given parameter ID.

The flags are:

• DESCIDSTATE::NONE : None.
• DESCIDSTATE::LOCKED : Description element is locked.
• DESCIDSTATE::HIDDEN : Description element is hidden.
• DESCIDSTATE::OVERRIDE : Description is overridden.
• DESCIDSTATE::FORBIDOVERRIDE : Description cannot be overridden.

  // This example toggles the "locked" state of the sphere's "Radius" parameter.
 
  const DESCIDSTATE state = sphere->GetDescIDState(PRIM_SPHERE_RAD, true);
  if (state & DESCIDSTATE::LOCKED)
    sphere->SetDescIDState(PRIM_SPHERE_RAD, ~DESCIDSTATE::LOCKED & state);
  else
    sphere->SetDescIDState(PRIM_SPHERE_RAD, DESCIDSTATE::LOCKED | state);

Functionality

BaseList2D based elements can be edited with these functions:

• BaseList2D::TransferGoal(): Changes all BaseLink objects pointing to this element to point to the given BaseList2D.
• BaseList2D::Scale(): Scales all parameters with length units with the given factor.
• BaseList2D::Edit(): Triggers the edit action for the object by sending the MSG_EDIT message (see Interaction).

  // This example creates a clone of the given object.
  // This clone is scaled and all links pointing to the
  // original object are redirected to the clone.
 
  C4DAtom* const    atomClone = object->GetClone(COPYFLAGS::NONE, nullptr);
  BaseObject* const clone = static_cast<BaseObject*>(atomClone);
  if (clone == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->InsertObject(clone, nullptr, nullptr);
 
  // scale the clone's float parameters
  clone->Scale(2.0);
 
  // all links should now refer to the clone
  object->TransferGoal(clone, false);
 
  // edit the clone
  clone->Edit();

Further Reading

• C4DAtom Manual
• GeListNode Manual
• DescID Manual
• GeMarker Manual
• Layer Manual