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