DescID Manual

Table of Contents

• About
• DescID
  • Create
  • Functionality
  • Disc I/O
• DescLevel
  • Create
  • Attributes
  • Compare
• Further Reading

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 = ConstDescID(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();
    ApplicationOutput("Scale: " + String::FloatToString(scale));
 
    // 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();
    ApplicationOutput("Size X: " + String::FloatToString(sizeX));

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);
  }

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

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:

• DescID::SetId(): Sets the highest stored level to the given DescLevel.
• DescID::PushId(): Adds the given DescLevel to the stack.
• DescID::PopId(): Removes the last DescLevel from the stack.

    // This example constructs a DescID and uses it to access a parameter.
 
    GeData data;
 
    DescID sizeXID;
    sizeXID.PushId(DescLevel(PRIM_FRACTAL_LEN, DTYPE_VECTOR, 0));
    sizeXID.PushId(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();
    ApplicationOutput("Size X: " + String::FloatToString(sizeX));

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

• DescID::operator[](): Accesses the level at the given index. The index "-1" can be used to access the last DescLevel on the stack.
• DescID::operator=(): Assigns the DescID to the given DescID.
• DescID::operator==(): Returns true if the DescID objects are the same.
• DescID::operator!=(): Returns true if the DescID objects are not the same.
• DescID::operator<<(): Returns the resulting DescID after popping levels from the bottom of the stack.
• DescID::operator+=(): Merges the DescID with the given DescID.
• DescID::operator+(): Merges two DescID objects.

    // This example constructs a DescID and uses it to access a parameter.
 
    GeData data;
 
    DescID sizeXID;
#if API_VERSION < 2023900
    sizeXID += DescLevel(PRIM_FRACTAL_LEN, DTYPE_VECTOR, 0);
    sizeXID += DescLevel(VECTOR_X, DTYPE_REAL, 0);
#else
    sizeXID += ConstDescID(DescLevel(PRIM_FRACTAL_LEN, DTYPE_VECTOR, 0));
    sizeXID += ConstDescID(DescLevel(VECTOR_X, DTYPE_REAL, 0));
#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();
    ApplicationOutput("Size X: " + String::FloatToString(sizeX));

Note

The + operator does not work like an integer addition. Important, when constructing parameter IDs dynamically.

Further functions are:

• DescID::GetDepth(): Returns the number of levels.
• DescID::IsPartOf(): Returns true if the DescID is part of the given DescID.
• DescID::GetHashCode(): Returns a hash code for the DescID.

    // 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];
      ApplicationOutput("ID: " + String::IntToString(level.id));
    }

Disc I/O

DescID objects can be stored in a HyperFile.

• DescID::Read(): Reads the DescID from the given HyperFile.
• DescID::Write(): Stores the DescID to the given 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;
 
  const DescID radiusID = ConstDescID(DescLevel(PRIM_SPHERE_RAD));
 
  // read the "Radius" parameter
  if (!sphere->GetParameter(radiusID, data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  MAXON_SCOPE
  {
    const Float radius = data.GetFloat();
    ApplicationOutput("Radius: " + String::FloatToString(radius));
  }
 
 
  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);
 
  MAXON_SCOPE
  {
    const Float radius = data.GetFloat();
    ApplicationOutput("Radius: " + String::FloatToString(radius));
  }

Attributes

The public attributes of a DescLevel are:

• DescLevel::id: The parameter ID.
• DescLevel::dtype: The parameter type.
• DescLevel::creator: The creator ID. This is the ID of the plugin class that created that parameter.

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

• DescLevel::operator==(): Returns true if the DescLevel objects are the same.
• DescLevel::operator!=(): Returns true if the DescLevel objects are not the same.

Further Reading

• C4DAtom Manual