BaseTag and VariableTag Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Navigation
• What's a VariableTag?
• Variable Data
• Flags
• Utility
• Further Reading

About

Tags can be added to BaseObject elements to add additional data or functionality (expression). The base class for all tags is BaseTag. Some tags store data of variable length depending on the host object. These extended tags are based on VariableTag and BaseTag.

BaseTag objects are an instance of Tbase, VariableTag objects are an instance of Tvariable.

Note

Tags can be hidden in the Object Manager.

Warning

Since R17 the Take System can add and own tags. See Take System Take System Additional Information.

Access

The currently selected tags can be obtained from the BaseDocument:

• BaseDocument::GetActiveTag(): Returns the currently selected BaseTag.
• BaseDocument::GetActiveTags(): Returns the current multi-selection of BaseTag objects.
• BaseDocument::SetActiveTag(): Adds or removes the given BaseTag to the selection or starts a new selection.

See also BaseDocument Selections.

The tags that are attached to an object are obtained from that object:

• BaseObject::GetFirstTag(): Returns the first tag of the object.
• BaseObject::GetTag(): Returns a tag of the given type if it is hosted by the object.
• BaseObject::GetLastTag(): Returns the last tag of the host object.

See BaseObject Tags.

  // This example removes all "Annotation" tags from the given object.
 
  // loop until no "Annotation" tag can be found anymore
  while (object->GetTag(Tannotation))
  {
    object->KillTag(Tannotation);
  }

A BaseTag may also be returned from a tag itself:

• BaseTag::GetOrigin(): Returns where the tag was cloned from. Used for example to handle linked tags correctly.

Allocation/Deallocation

BaseTag objects are created with the usual tools:

• BaseTag::Alloc(): Creates a new BaseTag.
• BaseTag::Free(): Deletes the given BaseTag.

The tag IDs of many build-in tag types are defined in Tag Types and SelectionTag Types.

  // This example creates a new "Compositing" tag and adds it to the given BaseObject.
 
  BaseTag* const tag = BaseTag::Alloc(Tcompositing);
  if (tag == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  object->InsertTag(tag);
 

VariableTag objects are created with the usual tools, too:

• VariableTag::Alloc(): Creates a new VariableTag.
• VariableTag::Free(): Deletes the given VariableTag.

The tag IDs of many build-in variable tag types are defined in VariableTag Types.

  // This example creates a VertexMap tag with the given point count.
 
  const Int32 pointCount = polygonObject->GetPointCount();
 
  VariableTag* const vetexMapTag = VariableTag::Alloc(Tvertexmap, pointCount);
  if (vetexMapTag == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  polygonObject->InsertTag(vetexMapTag);
 

BaseTag and VariableTag elements can also be handled by the BaseObject that hosts these tags:

• BaseObject::MakeTag(): Creates a new BaseTag of the given type.
• BaseObject::MakeVariableTag(): Creates a new VariableTag of the given type.
• BaseObject::InsertTag(): Inserts the given BaseTag into the object's tag list.
• BaseObject::KillTag(): Deletes a hosted tag of the given type.
• BaseObject::CopyTagsTo(): Copies the tags of this object onto the given BaseObject.

See BaseObject Tags.

  // This example checks if the given object owns a "Protection" tag.
  // If not, the "Protection" tag is created.
 
  BaseTag* protectionTag = object->GetTag(Tprotection);
 
  if (protectionTag == nullptr)
  {
    protectionTag = object->MakeTag(Tprotection);
    if (protectionTag == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
  }

An UVW tag can be created with this dedicated function:

• GenerateUVW(): Creates a UVW tag based on the projection settings of the given Texture tag.

A tag is hosted and owned by a BaseObject.

• BaseTag::GetObject(): Returns the BaseObject that hosts this tag.

Navigation

Tags are organized in a list.

• BaseTag::GetNext(): Returns the next tag in the list.
• BaseTag::GetPred(): Returns the previous tag in the list.

  // This example loops through the tags of the given object.
 
  BaseTag* tag = object->GetFirstTag();
 
  while (tag != nullptr)
  {
    ApplicationOutput("Tag: " + tag->GetName());
 
    tag = tag->GetNext();
  }

What's a VariableTag?

VariableTag is just a means to store a varying amount of data. So it's "variable" in the sense of "capable of being changed", not in the sense of a variable (i.E. a place to store data) which again of course comes from being variable... Take for example a Polygon Object. It needs to store a number of Vectors describing point positions. And it needs to store information about polygons (basically an array of point indexes). While this information could of cause be stored in members of the Polygon Object implementation, one would need to take care of reading/writing/copying this data. Instead one can simply make use of VariableTags (PointTag and PolygonTag in this case), they'll take care of the contained data in these cases. In regards to caching and scene execution pipeline, VariableTags don't do much, as they are only data containers in most cases. So in the above example it's rather the Polygon Object doing something with the data stored in its VariableTags. VariableTags can not be created with the SDK, one can only make use of the existing ones.

Variable Data

Variable tags store an array of elements. Typically dedicated classes exist to access the settings.

The data stored in a VariableTag can be accessed directly from the BaseObject:

• BaseObject::GetTagDataR(): Returns a pointer to the read-only data of the VariableTag.
• BaseObject::GetTagDataW(): Returns a pointer to the writeable data of the VariableTag.
• BaseObject::GetTagDataCount(): Returns the number of elements stored in the VariableTag.

See also BaseObject Tags.

  // This example writes random values into the memory of the object's vertex map tag.
 
  Random random;
 
  Float32* const data = static_cast<Float32*>(polygonObject->GetTagDataW(Tvertexmap));
  if (data)
  {
    for (Int32 i = 0; i < pointCount; ++i)
      data[i] = (Float32)random.Get01();
  }
 

The data can also be accessed with the VariableTag itself.

• VariableTag::GetDataCount(): Returns the number of elements stored in the tag.
• VariableTag::GetDataSize(): Returns the size of one data element in bytes.
• VariableTag::GetLowlevelDataAddressR(): Returns a pointer to the read-only data of the tag.
• VariableTag::GetLowlevelDataAddressW(): Returns a pointer to the writeable data for the variable tag.

  // This example writes random values into the memory of the object's vertex map tag directly.
 
  VariableTag* const vTag = static_cast<VariableTag*>(polygonObject->GetTag(Tvertexmap));
  if (vTag == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "The function exited unexpectedly when accessing the Tag data instance."_s);
 
  const Int32    elements = vTag->GetDataCount();
  Float32* const data = static_cast<Float32*>(vTag->GetLowlevelDataAddressW());
  if (data == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION, "The function exited unexpectedly when accessing the low-level data address of the Tag data."_s);
 
  Random random;
 
  for (Int32 i = 0; i < elements; ++i)
    data[i] = (Float32)random.Get01();
 

Flags

Tag plugins can be registered with several flags. These flags can be accessed with GeListNode::GetInfo().

• TAG_VISIBLE: The tag is visible in the Object Manager.
• TAG_MULTIPLE: Multiple instances of the tag are allowed on one object.
• TAG_HIERARCHICAL: The tag works on subobjects.
• TAG_EXPRESSION: The tag is an expression.
• TAG_ADDTOTAKEGROUP: The tag type is also handled by the Take system.

Utility

These utility functions can return the name of the tag type or return the tag type based on that name.

• GetTagName(): Returns the user presentable name from a tag type ID.
• GetTagType(): Returns a tag type from a tag name.

  // This example prints the name of the tag type of the given tag.
 
  const Int32         type = tag->GetType();
  const maxon::String typeName = GetTagName(type);
 
  ApplicationOutput("Tag Type: "_s + typeName);

Further Reading

• Scene Elements Overview
• BaseObject Manual
• BaseDocument Manual