BaseTag and VariableTag Manual

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:

See also BaseDocument Selections.

The tags that are attached to an object are obtained from that 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:

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.
if (!tag)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
object->InsertTag(tag);

VariableTag objects are created with the usual tools, too:

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)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
polygonObject->InsertTag(vetexMapTag);

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

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)
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.

Navigation

Tags are organized in a list.

// This example loops through the tags of the given object.
BaseTag* tag = object->GetFirstTag();
while (tag)
{
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:

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.

// 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)
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)
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().

Utility

These utility functions can return the name of the tag type or return the tag type based on that 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