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);
Definition: c4d_basecontainer.h:48
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:587
const BaseContainer & GetDataInstanceRef() const
Definition: c4d_baselist.h:2518
static BaseList2D * Alloc(Int32 type)
Definition: c4d_basedocument.h:112
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define VPBUFFER_OBJECTBUFFER
Object buffer multipass channel.
Definition: c4d_videopostdata.h:141
#define Zmultipass
Definition: ge_prepass.h:1295
@ MULTIPASSOBJECT_TYPE
Definition: zmultipass.h:6
@ MULTIPASSOBJECT_OBJECTBUFFER
Definition: zmultipass.h:8

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 == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
ApplicationOutput("The object: \"" + object->GetName() + "\" is a \"" + object->GetTypeName() + "\"");
Definition: c4d_baseobject.h:248
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
const char * doc
Definition: pyerrors.h:226
Definition: object.h:105

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, Bool isCloneInit)
{
if (node == nullptr || !SUPER::Init(node, isCloneInit))
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);
void SetBool(Int32 id, Bool b)
Definition: c4d_basecontainer.h:580
Represents a C4DAtom that resides in a 4D list.
Definition: c4d_baselist.h:1976
PyObject * obj
Definition: complexobject.h:60
maxon::Bool Bool
Definition: ge_sys_math.h:51
struct _node node
Definition: node.h:10
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 != nullptr)
void SetBit(Int32 mask)
Definition: c4d_baselist.h:2434
Definition: c4d_videopost.h:24
Definition: c4d_basedocument.h:143
BaseVideoPost * GetFirstVideoPost()
#define BIT_VPDISABLED
Videopost is disabled.
Definition: ge_prepass.h:927

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

Note
The returned result should be assign to a NimbusBaseRef.

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);
material->SetParameter(ConstDescID(DescLevel(MATERIAL_COLOR_SHADER)), shader, DESCFLAGS_SET::NONE);
Definition: c4d_basechannel.h:36
static BaseShader * Alloc(Int32 type)
#define Xbrick
Brick.
Definition: ge_prepass.h:1325
#define ConstDescID(...)
Definition: lib_description.h:594
@ MATERIAL_COLOR_SHADER
Definition: mmaterial.h:294
Represents a level within a DescID.
Definition: lib_description.h:298

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 != 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);
}
const GeMarker & GetMarker() const
Definition: c4d_baselist.h:2591
A unique marker that identifies an object.
Definition: c4d_baselist.h:1446
Int32 Compare(const GeMarker &m) const
Definition: c4d_baselist.h:1483
Definition: c4d_string.h:41

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;
}
}
}
Py_ssize_t i
Definition: abstract.h:645
PyObject * value
Definition: abstract.h:715
static String IntToString(Int32 v)
Definition: c4d_string.h:497
void const void * bytes
Definition: bytesobject.h:117
maxon::Char Char
Definition: ge_sys_math.h:52
maxon::Int32 Int32
Definition: ge_sys_math.h:56
maxon::Int Int
Definition: ge_sys_math.h:60

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
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);
const CTrack * FindCTrack(const DescID &id) const
Definition: c4d_baselist.h:2884
Definition: c4d_canimation.h:671
static CTrack * Alloc(BaseList2D *bl, const DescID &id)
Definition: lib_description.h:355
return OK
Definition: apibase.h:2735
@ DTYPE_REAL
Float
Definition: lib_description.h:68
@ PRIM_SPHERE_RAD
Definition: osphere.h:6

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");
}
}
}
Definition: ge_autoptr.h:37
String GetString(Int32 id, const maxon::String &preset=maxon::String()) const
Definition: c4d_basecontainer.h:432
@ DESC_NAME
String Name for standalone use.
Definition: lib_description.h:91

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 != 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);
}
}
LayerObject * GetLayerObject(const BaseDocument *doc)
Definition: c4d_baselist.h:2823
Definition: c4d_basedocument.h:252
Definition: c4d_basedocument.h:318
Bool view
Visible in editor view.
Definition: c4d_basedocument.h:352

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(ConstDescID(DescLevel(PRIM_SPHERE_RAD)), true);
else
DESCIDSTATE
Definition: ge_prepass.h:5530
@ LOCKED
Description element is locked.
Definition: grammar.h:37

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.
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();
Bool Scale(Float scale)
Definition: c4d_baselist.h:2716
Bool Edit()
Definition: c4d_baselist.h:1521
C4DAtom * GetClone(COPYFLAGS flags, AliasTrans *trn) const
Definition: c4d_baselist.h:1606
@ NONE
None.

Further Reading