Open Search
    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:66
    @ 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:210
    @ 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:2897
    @ 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:60
    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