BaseList2D Manual

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:

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();
renderData->InsertMultipass(multipass);

Read-Only Properties

The following properties can be accessed:

// This example prints the name and type name of the active object.
BaseObject* const object = doc->GetActiveObject();
if (!object)
return maxon::OK;
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.

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 || !SUPER::Init(node))
return false;
// get the "real" object
BaseObject* const obj = static_cast<BaseObject*>(node);
// get data container
// 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.

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

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:

// This example changes the name of the selected object.
BaseObject* const object = doc->GetActiveObject();
if (!object)
return maxon::OK;
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.

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.

// This example creates a shader and adds it to the given material.
if (shader == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
material->InsertShader(shader);

See also GeListNode Lists and Trees.

Marker

A BaseList2D based element owns a GeMarker object.

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

// 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))
{
// check if the memory block has the size of an Int32 number
if (bytes == sizeof(Int32))
{
const Int32 data = *(Int32*)memory;
}
}
}

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.

// This example checks if an animation track for the given parameter exists.
// If no track exists it is created.
// check if track exists
if (track)
return maxon::OK;
// create track
if (!track)
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:

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

// 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)
{
// get layer data
const LayerData* const ld = object->GetLayerData(doc);
if (ld)
{
// 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.

The flags are:

// 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)
else

Functionality

BaseList2D based elements can be edited with these functions:

// 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.
BaseObject* const clone = static_cast<BaseObject*>(object->GetClone(COPYFLAGS::NONE, nullptr));
if (!clone)
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