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
const DescID scaleID = DescLevel { PRIM_FRACTAL_SCALE, DTYPE_REAL, 0 };
// 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 = DescID(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();

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 = DescID(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 = DescID(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);
}

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();
}
// read "Radius" parameter
if (!sphere->GetParameter(radiusID, data, DESCFLAGS_GET::NONE))
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
{
const Float radius = data.GetFloat();
}
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();

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;
sizeXID += DescLevel(VECTOR_X, DTYPE_REAL, 0);
// 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];
}

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();
}
// read the "Radius" parameter
if (!sphere->GetParameter(radiusID, 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 + ")");

Compare

Two DescLevel objects can be compared with:

Further Reading

String::FloatToString
static String FloatToString(Float32 v, Int32 vvk=-1, Int32 nnk=-3)
Definition: c4d_string.h:529
PRIM_FRACTAL_LEN
@ PRIM_FRACTAL_LEN
Definition: ofractal.h:7
DescID
Definition: lib_description.h:328
DTYPE_SUBCONTAINER
@ DTYPE_SUBCONTAINER
Sub-container.
Definition: lib_description.h:58
VECTOR_X
@ VECTOR_X
X component.
Definition: lib_description.h:268
Float
maxon::Float Float
Definition: ge_sys_math.h:66
DescID::GetDepth
Int32 GetDepth() const
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
DescLevel::id
Int32 id
ID of the level.
Definition: lib_description.h:289
ID_USERDATA
#define ID_USERDATA
User data ID.
Definition: lib_description.h:25
PRIM_FRACTAL_SCALE
@ PRIM_FRACTAL_SCALE
Definition: ofractal.h:12
DescLevel::dtype
Int32 dtype
Data type. Either a custom ID or one of these: DTYPE.
Definition: lib_description.h:290
String
Definition: c4d_string.h:38
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:495
GetObjectName
String GetObjectName(Int32 type)
DTYPE_VECTOR
@ DTYPE_VECTOR
Vector
Definition: lib_description.h:70
DescLevel
Represents a level within a DescID.
Definition: lib_description.h:287
GeData
Definition: c4d_gedata.h:82
DescID::PushId
void PushId(const DescLevel &subid)
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
DESCFLAGS_GET::NONE
@ NONE
None.
DescLevel::creator
Int32 creator
Creator ID.
Definition: lib_description.h:291
DTYPE_REAL
@ DTYPE_REAL
Float
Definition: lib_description.h:68
PRIM_SPHERE_RAD
@ PRIM_SPHERE_RAD
Definition: osphere.h:6
C4DAtom::GetParameter
Bool GetParameter(const DescID &id, GeData &t_data, DESCFLAGS_GET flags)
MAXON_SCOPE
#define MAXON_SCOPE
Definition: apibase.h:2659
GeData::GetFloat
Float GetFloat(void) const
Definition: c4d_gedata.h:439