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

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
// 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 != nullptr)

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.

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

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

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

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

BaseList2D::KeyframeSelectionContent
Bool KeyframeSelectionContent()
BaseShader
Definition: c4d_basechannel.h:31
CTrack::Alloc
static CTrack * Alloc(BaseList2D *bl, const DescID &id)
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
BaseDocument::SearchObject
BaseObject * SearchObject(const maxon::String &str)
LayerObject
Definition: c4d_basedocument.h:235
BaseList2D::GetUniqueIDIndex
Bool GetUniqueIDIndex(Int32 idx, Int32 &id, const Char *&mem, Int &bytes) const
Definition: c4d_baselist.h:2408
Int
maxon::Int Int
Definition: ge_sys_math.h:49
C4DAtom::GetClone
C4DAtom * GetClone(COPYFLAGS flags, AliasTrans *trn)
Definition: c4d_baselist.h:1412
BaseObject
Definition: c4d_baseobject.h:220
DescID
Definition: lib_description.h:315
BaseContainer::SetInt32
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:501
C4DAtom::GetDescription
Bool GetDescription(Description *description, DESCFLAGS_DESC flags)
maxon::OK
return OK
Definition: apibase.h:2490
BaseList2D::GetMarker
const GeMarker & GetMarker() const
Definition: c4d_baselist.h:2360
RenderData::GetFirstVideoPost
BaseVideoPost * GetFirstVideoPost()
BaseList2D::SetDescIDState
Bool SetDescIDState(const DescID &id, DESCIDSTATE descidstate)
GeMarker::Compare
Int32 Compare(const GeMarker &m) const
Definition: c4d_baselist.h:1289
MATERIAL_COLOR_SHADER
@ MATERIAL_COLOR_SHADER
Definition: mmaterial.h:272
BaseList2D::InsertTrackSorted
void InsertTrackSorted(CTrack *track)
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
BaseList2D::FindCTrack
CTrack * FindCTrack(const DescID &id)
BaseList2D::SetBit
void SetBit(Int32 mask)
Definition: c4d_baselist.h:2195
BaseContainer::SetBool
void SetBool(Int32 id, Bool b)
Definition: c4d_basecontainer.h:494
DESCFLAGS_SET::NONE
@ NONE
None.
RenderData::InsertMultipass
void InsertMultipass(MultipassObject *obj, MultipassObject *pred=nullptr)
CTrack
Definition: c4d_canimation.h:635
BaseList2D::Edit
Bool Edit()
DESCFLAGS_DESC::NONE
@ NONE
None.
BaseList2D::Alloc
static BaseList2D * Alloc(Int32 type)
MULTIPASSOBJECT_TYPE
@ MULTIPASSOBJECT_TYPE
Definition: zmultipass.h:6
Xbrick
#define Xbrick
Brick.
Definition: ge_prepass.h:1160
GeListNode
Represents a C4DAtom that resides in a 4D list.
Definition: c4d_baselist.h:1762
LayerData::view
Bool view
Visible in editor view.
Definition: c4d_basedocument.h:336
String
Definition: c4d_string.h:35
GeMarker
A unique marker that identifies an object.
Definition: c4d_baselist.h:1251
PRIM_SPHERE_RAD
@ PRIM_SPHERE_RAD
Definition: osphere.h:6
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:492
Description::GetNext
Bool GetNext(void *handle, const BaseContainer **bc, DescID &id, DescID &groupid)
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
LayerData
Definition: c4d_basedocument.h:301
BaseList2D::GetLayerObject
LayerObject * GetLayerObject(BaseDocument *doc)
BaseList2D::GetDataInstanceRef
const BaseContainer & GetDataInstanceRef() const
Definition: c4d_baselist.h:2294
BaseShader::Alloc
static BaseShader * Alloc(Int32 type)
DescLevel
Represents a level within a DescID.
Definition: lib_description.h:274
BaseVideoPost
Definition: c4d_videopost.h:19
MULTIPASSOBJECT_OBJECTBUFFER
@ MULTIPASSOBJECT_OBJECTBUFFER
Definition: zmultipass.h:8
C4DAtom
Definition: c4d_baselist.h:1326
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:45
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:209
VPBUFFER_OBJECTBUFFER
#define VPBUFFER_OBJECTBUFFER
Object buffer multipass channel.
Definition: c4d_videopostdata.h:136
BIT_VPDISABLED
#define BIT_VPDISABLED
Videopost is disabled.
Definition: ge_prepass.h:867
Description::BrowseInit
void * BrowseInit()
BaseDocument::GetActiveRenderData
RenderData * GetActiveRenderData(void)
BaseList2D::Scale
Bool Scale(Float scale)
Definition: c4d_baselist.h:2478
AutoAlloc
Definition: ge_autoptr.h:32
BaseContainer::GetString
String GetString(Int32 id, const maxon::String &preset=maxon::String()) const
Definition: c4d_basecontainer.h:383
DESC_NAME
@ DESC_NAME
String Name for standalone use.
Definition: lib_description.h:87
RenderData
Definition: c4d_basedocument.h:126
MultipassObject
Definition: c4d_basedocument.h:95
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:40
BaseDocument::GetActiveObject
BaseObject * GetActiveObject(void)
BaseList2D::GetName
String GetName() const
Definition: c4d_baselist.h:2313
Zmultipass
#define Zmultipass
Definition: ge_prepass.h:1130
DESCIDSTATE::LOCKED
@ LOCKED
Description element is locked.
DTYPE_REAL
@ DTYPE_REAL
Float
Definition: lib_description.h:64
BaseList2D::FindKeyframeSelection
Bool FindKeyframeSelection(const DescID &id)
Char
maxon::Char Char
Definition: ge_sys_math.h:41
COPYFLAGS::NONE
@ NONE
None.
BaseList2D::GetDescIDState
DESCIDSTATE GetDescIDState(const DescID &id, Bool tolerant) const
BaseContainer
Definition: c4d_basecontainer.h:42
BaseList2D::GetTypeName
String GetTypeName()
BaseList2D::InsertShader
void InsertShader(BaseShader *shader, BaseShader *pred=nullptr)
Definition: c4d_baselist.h:2523
DESCIDSTATE
DESCIDSTATE
Definition: ge_prepass.h:5185