DescID Manual

About

Parameters of C4DAtom based elements are identified using a DescID object. Such a DescID object is composed of several levels of DescLevel objects. In this way DescIDs can reflect the structure of complex data types. For example a Vector consists of three Float values. With the first DescLevel the Vector is accessed as a whole, with the second DescLevel the three Float components can be accessed individually.

// This example reads two parameters from the given "Landscape" object.
GeData data;
// get the "Scale" parameter
// read the "Scale" parameter
if (!landscape->GetParameter(scaleID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Float scale = data.GetFloat();
// get the x component of the "Size" parameter
const DescLevel fractalLenLevel(PRIM_FRACTAL_LEN, DTYPE_VECTOR, 0);
const DescLevel vectorXLevel(VECTOR_X, DTYPE_REAL, 0);
const DescID sizeXID = CreateDescID(fractalLenLevel, vectorXLevel);
// read the x-component of the "Size" parameter
if (!landscape->GetParameter(sizeXID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Float sizeX = data.GetFloat();
Definition: lib_description.h:355
Definition: c4d_gedata.h:83
Float GetFloat() const
Definition: c4d_gedata.h:468
static String FloatToString(Float32 v, Int32 vvk=-1, Int32 nnk=-3)
Definition: c4d_string.h:531
maxon::Float Float
Definition: ge_sys_math.h:62
@ DTYPE_VECTOR
Vector
Definition: lib_description.h:70
@ DTYPE_REAL
Float
Definition: lib_description.h:68
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:204
@ VECTOR_X
X component.
Definition: lib_description.h:279
#define ConstDescID(...)
Definition: lib_description.h:594
#define CreateDescID(...)
Definition: lib_description.h:595
@ PRIM_FRACTAL_SCALE
Definition: ofractal.h:12
@ PRIM_FRACTAL_LEN
Definition: ofractal.h:7
Represents a level within a DescID.
Definition: lib_description.h:298

User data parameters are stored in a sub-container with the ID ID_USERDATA.

// This example reads the user data parameters 1 and 2 of the given object.
GeData data;
const DescLevel userDataLevel(ID_USERDATA, DTYPE_SUBCONTAINER, 0);
const DescLevel firstParameter(1, DTYPE_REAL, 0);
const DescID floatParameterID = CreateDescID(userDataLevel, firstParameter);
// read the user data parameter 1
if (object->GetParameter(floatParameterID, data, DESCFLAGS_GET::NONE))
{
const String floatStr = String::FloatToString(data.GetFloat());
ApplicationOutput("Float value: " + floatStr);
}
const DescLevel secondParameter(2, DTYPE_VECTOR, 0);
const DescLevel vectorXLevel(VECTOR_X, DTYPE_REAL, 0);
const DescID vectorSubParameterID = CreateDescID(userDataLevel, secondParameter, vectorXLevel);
// read the x-component of the user data parameter 2
if (object->GetParameter(vectorSubParameterID, data, DESCFLAGS_GET::NONE))
{
const String floatStr = String::FloatToString(data.GetFloat());
ApplicationOutput("Vector X value: " + floatStr);
}
Definition: c4d_string.h:41
@ DTYPE_SUBCONTAINER
Sub-container.
Definition: lib_description.h:58
#define ID_USERDATA
User data ID.
Definition: lib_description.h:25
Definition: object.h:105

DescID

A DescID object identifies a parameter.

Note
A DescID can be stored in a GeData or BaseContainer using the custom data type CUSTOMDATATYPE_DESCID.

Create

DescID objects can be created with different constructors:

// This example reads the "Radius" parameter of the given sphere object
// with differently constructed DescIDs.
GeData data;
// read "Radius" parameter
if (!sphere->GetParameter(radiusID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
{
const Float radius = data.GetFloat();
}
const DescID radiusIDFullyQualified = ConstDescID(DescLevel(PRIM_SPHERE_RAD, DTYPE_REAL, 0));
// read "Radius" parameter
if (!sphere->GetParameter(radiusIDFullyQualified, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
{
const Float radius = data.GetFloat();
}
#define MAXON_SCOPE
Definition: apibase.h:2886
@ PRIM_SPHERE_RAD
Definition: osphere.h:6
Note
Typically a DescID constructed by using only the parameter ID is sufficient. For specialized uses like animation tracks or takes the fully constructed DescID might be needed.

Functionality

A complex DescID object with several levels can be constructed with these tools:

// This example constructs a DescID and uses it to access a parameter.
GeData data;
DescID sizeXID;
// read the x-component of the "Size" parameter
if (!landscape->GetParameter(sizeXID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Float sizeX = data.GetFloat();
void PushId(const DescLevel &subid)

The levels of a DescID object can also be edited with these operators:

// This example constructs a DescID and uses it to access a parameter.
GeData data;
DescID sizeXID;
#if API_VERSION < 2023900
sizeXID += DescLevel(VECTOR_X, DTYPE_REAL, 0);
#else
#endif
// read the x-component of the "Size" parameter
if (!landscape->GetParameter(sizeXID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Float sizeX = data.GetFloat();
Note
The + operator does not work like an integer addition. Important, when constructing parameter IDs dynamically.

Further functions are:

// This example loops through the levels of the given DescID.
const Int32 depth = descID.GetDepth();
for (Int32 i = 0; i < depth; ++i)
{
const DescLevel level = descID[i];
}
Py_ssize_t i
Definition: abstract.h:645
static String IntToString(Int32 v)
Definition: c4d_string.h:497
maxon::Int32 Int32
Definition: ge_sys_math.h:56
PyObject PyObject PyObject int level
Definition: import.h:58

Disc I/O

DescID objects can be stored in a HyperFile.

DescLevel

A DescLevel represents a level of a DescID parameter ID.

Create

DescLevel objects can be created with different constructors:

// This example reads the "Radius" parameter of the given sphere object
// with differently constructed DescLevels.
GeData data;
// read the "Radius" parameter
if (!sphere->GetParameter(radiusID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
{
const Float radius = data.GetFloat();
}
const DescID radiusIDFullyQualified = ConstDescID(DescLevel(PRIM_SPHERE_RAD, DTYPE_REAL, 0));
// read the "Radius" parameter
if (!sphere->GetParameter(radiusIDFullyQualified, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
{
const Float radius = data.GetFloat();
}

Attributes

The public attributes of a DescLevel are:

// This example prints the components of the first level of the given DescID.
// GetObjectName() assumes that the creator ID is the ID of a BaseObject.
const DescLevel level = descID[0];
const String levelIdStr = String::IntToString(level.id);
ApplicationOutput("ID: " + levelIdStr);
const String levelDtypeStr = String::IntToString(level.dtype);
ApplicationOutput("Type: " + levelDtypeStr);
const String levelCreatorStr = String::IntToString(level.creator);
const String levelCreatorName = GetObjectName(level.creator);
ApplicationOutput("Creator: " + levelCreatorStr + " (" + levelCreatorName + ")");
String GetObjectName(Int32 type)

Compare

Two DescLevel objects can be compared with:

Further Reading