VertexColorTag Manual

Table of Contents

About

The VertexColorTag is used to add additional color information to a polygon object. The tag can be either in point mode or polygon mode. In point mode it will store color information for each vertex of the object. In polygon mode it will store color information for each vertex of each polygon of the object.

A VertexColorTag is based on VariableTag and is an instance of Tvertexcolor.

Access

An existing VertexColorTag can be accessed from its host object.

// This example accesses the vertex color tag of the given BaseObject.
BaseTag* const tag = object->GetTag(Tvertexcolor);
if (tag == nullptr)
return maxon::OK;
VertexColorTag* const vct = static_cast<VertexColorTag*>(tag);

Allocation/Deallocation

VertexColorTag instances are created with the usual tools:

Note
The VertexColorTag is always allocated in point mode.

See also Tags and BaseTag and VariableTag Manual.

// This example checks if the given polygon object hosts a vertex color tag.
// It not, a new vertex color tag is allocated and added.
BaseTag* tag = polyObject->GetTag(Tvertexcolor);
if (tag == nullptr)
{
const Int32 pointCount = polyObject->GetPointCount();
tag = VertexColorTag::Alloc(pointCount);
if (tag == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
polyObject->InsertTag(tag);
}

Mode

A VertexColorTag can either be in point mode or polygon mode.

Warning
The mode of a tag must be changed with VertexColorTag::SetPerPointMode(). It is not enough to change the parameter ID_VERTEXCOLOR_VERTEXCOLORMODE.
Note
In point mode VariableTag::GetDataCount() returns the number of points, in polygon mode the number of polygons.
// This example switches the mode of the given vertex color tag.
const Bool pointMode = vcTag->IsPerPointColor();
vcTag->SetPerPointMode(!pointMode);

Data Access

The data stored in the VertexColorTag can be accessed using a read or write handle:

Warning
These handles become invalid after changing the mode (see Mode).
Note
It is possible to set values greater than 1.0.

These two functions can only be used in polygon mode. They access the polygon vertex colors of the given polygon index.

// This example sets the polygon colors stored in the given vertex color tag.
// The points of each point of the polygon receive the same color.
// check if polygon mode
if (vcTag->IsPerPointColor())
return maxon::OK;
// get the handle
VertexColorHandle handle = vcTag->GetDataAddressW();
// color variation over each polygon
const Float stepSize = 1.0f / Float(polyCount);
Float hue = 0.0;
// for each polygon set a different color
for (Int32 i = 0; i < polyCount; ++i)
{
VertexColorStruct vcs;
VertexColorTag::Get(handle, i, vcs);
// create new color
const Vector hsv { hue, 1.0, 1.0 };
const Vector32 rgb = (Vector32)HSVToRGB(hsv);
hue += stepSize;
// assign the color to each point of the given polygon
for (Int32 p = 0; p < 4; ++p)
vcs[p] = maxon::ColorA32(rgb.x, rgb.y, rgb.z, 1.0);
// set the values
VertexColorTag::Set(handle, i, vcs);
}
// update host object
polyObject->Message(MSG_UPDATE);

The following functions can be used to access vertex colors in both point and polygon mode.

Warning
In point mode one must not hand over the pointers for the Neighbor object and the polygon array.

These functions access the RGB color as a maxon::Color32 value:

These functions access the alpha part as a Float32 value:

// This example reads the vertex colors in both point and polygon mode.
// get the settings of the polygon object
const Int32 pointCount = polyObject->GetPointCount();
const Int32 polyCount = polyObject->GetPolygonCount();
const CPolygon* const polys = polyObject->GetPolygonR();
// Neighbor object needed in polygon vertex mode
Neighbor neighbor;
// initialize Neighbor object
if (!neighbor.Init(pointCount, polys, polyCount, nullptr))
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
// get the handle
ConstVertexColorHandle handle = vcTag->GetDataAddressR();
// check all vertice
for (Int32 i = 0; i < pointCount; ++i)
{
// vertex color and alpha
maxon::Color32 resultColor;
Float32 alpha;
// in point mode the color has to be accessed differently
if (vcTag->IsPerPointColor())
{
resultColor = VertexColorTag::GetColor(handle, nullptr, nullptr, i);
alpha = VertexColorTag::GetAlpha(handle, nullptr, nullptr, i);
}
else
{
resultColor = VertexColorTag::GetColor(handle, &neighbor, polys, i);
alpha = VertexColorTag::GetAlpha(handle, &neighbor, polys, i);
}
const String colorStr = resultColor.ToString(nullptr);
const String alphaStr = String::FloatToString(alpha);
ApplicationOutput("Color: " + colorStr + ", Alpha: " + alphaStr);
}

These functions handle the RGBA values in form of a maxon::ColorA32 structure.

// This example reads the vertex colors in both point and polygon mode.
// get the handle
ConstVertexColorHandle handle = vcTag->GetDataAddressR();
// check all vertice
for (Int32 i = 0; i < pointCount; ++i)
{
// vertex color and alpha
maxon::ColorA32 rgba;
// in point mode the color has to be accessed differently
if (vcTag->IsPerPointColor())
rgba = VertexColorTag::Get(handle, nullptr, nullptr, i);
else
rgba = VertexColorTag::Get(handle, &neighbor, polys, i);
ApplicationOutput("Color: " +
String::FloatToString(rgba.r) + ", " +
String::FloatToString(rgba.g) + ", " +
String::FloatToString(rgba.b) + ", " +
String::FloatToString(rgba.a));
}

Further Reading