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)
{
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
// 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) + ", " +
}

Further Reading

String::FloatToString
static String FloatToString(Float32 v, Int32 vvk=-1, Int32 nnk=-3)
Definition: c4d_string.h:526
VertexColorTag::Alloc
static VertexColorTag * Alloc(Int32 count)
VertexColorTag::Get
static void Get(ConstVertexColorHandle dataptr, Int32 i, VertexColorStruct &res)
Definition: c4d_basetag.h:863
maxon::Col4::b
T b
Definition: col4.h:35
maxon::Col4::r
T r
Definition: col4.h:33
Float
maxon::Float Float
Definition: ge_sys_math.h:51
PointObject::GetPointCount
Int32 GetPointCount(void) const
Definition: c4d_baseobject.h:1423
PolygonObject::GetPolygonR
const CPolygon * GetPolygonR(void) const
Definition: c4d_baseobject.h:1722
VertexColorTag::GetColor
static maxon::Color32 GetColor(ConstVertexColorHandle dataptr, Neighbor *nb, const CPolygon *vadr, Int32 pIndex)
Float32
maxon::Float32 Float32
Definition: ge_sys_math.h:53
CPolygon
Represents a polygon that can be either a triangle or a quadrangle.
Definition: c4d_baseobject.h:39
BaseTag
Definition: c4d_basetag.h:42
maxon::OK
return OK
Definition: apibase.h:2490
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
HSVToRGB
Vector HSVToRGB(const Vector &col)
ConstVertexColorHandle
const typedef void * ConstVertexColorHandle
Handle for read-only vertex color data. See also VertexColorTag.
Definition: operatingsystem.h:449
maxon::Vec3::z
T z
Definition: vec.h:34
MSG_UPDATE
#define MSG_UPDATE
Must be sent if the bounding box has to be recalculated. (Otherwise use MSG_CHANGE....
Definition: c4d_baselist.h:335
String
Definition: c4d_string.h:35
maxon::Col4
A color consisting of three components R, G, B and an alpha.
Definition: col4.h:14
maxon::Vec3< maxon::Float64, 1 >
Vector32
maxon::Vec3< maxon::Float32, 1 > Vector32
Definition: ge_math.h:127
maxon::Vec3::x
T x
Definition: vec.h:32
PolygonObject::GetPolygonCount
Int32 GetPolygonCount(void) const
Definition: c4d_baseobject.h:1736
maxon::Col4::a
T a
Definition: col4.h:36
maxon::Vec3::y
T y
Definition: vec.h:33
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:45
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:209
C4DAtom::Message
Bool Message(Int32 type, void *data=nullptr)
Definition: c4d_baselist.h:1389
VertexColorTag
Definition: c4d_basetag.h:812
maxon::Col3
A color consisting of three components R, G and B.
Definition: col.h:14
VertexColorTag::GetAlpha
static Float32 GetAlpha(ConstVertexColorHandle dataptr, Neighbor *nb, const CPolygon *vadr, Int32 pIndex)
maxon::Col4::g
T g
Definition: col4.h:34
VertexColorStruct
Definition: operatingsystem.h:641
BaseObject::GetTag
BaseTag * GetTag(Int32 type, Int32 nr=0)
Definition: c4d_baseobject.h:658
VertexColorHandle
void * VertexColorHandle
Handle for vertex color data. See also VertexColorTag.
Definition: operatingsystem.h:448
maxon::Col3::ToString
String ToString(const FormatStatement *formatStatement) const
Definition: col.h:322
VertexColorTag::Set
static void Set(VertexColorHandle dataptr, Int32 i, const VertexColorStruct &s)
Definition: c4d_basetag.h:885
Neighbor::Init
virtual Bool Init(Int32 pcnt, const CPolygon *vadr, Int32 vcnt, BaseSelect *bs)
Neighbor
Definition: c4d_baseobject.h:2448
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:40
BaseObject::InsertTag
void InsertTag(BaseTag *tp, BaseTag *pred=nullptr)
Tvertexcolor
#define Tvertexcolor
Vertex color.
Definition: ge_prepass.h:1283