VertexColorTag Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Mode
• Data Access
• Further Reading

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:

• VertexColorTag::Alloc(): Creates a new VertexColorTag.
• VertexColorTag::Free(): Destroys the given VertexColorTag.

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.

• VertexColorTag::IsPerPointColor(): Returns true if the tag is in point mode.
• VertexColorTag::SetPerPointMode(): If the given argument is true the tag is set to point mode, otherwise to 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:

• VertexColorTag::GetDataAddressR(): Returns a read-only data handle.
• VertexColorTag::GetDataAddressW(): Returns a read-and-write data handle.
• VertexColorHandle: The read-and-write handle.
• ConstVertexColorHandle: The read only 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.

• VertexColorTag::Get(ConstVertexColorHandle dataptr, Int32 i, VertexColorStruct& res): Returns the polygon vertex colors.
• VertexColorTag::Set(VertexColorHandle dataptr, Int32 i, const VertexColorStruct& s): Sets the polygon vertex colors.
• VertexColorStruct: The data structure that stores up to four colors for the polygon.

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

• VertexColorTag::GetColor(): Returns the color of the given vertex index.
• VertexColorTag::SetColor(): Sets the color of the given vertex index.

These functions access the alpha part as a Float32 value:

• VertexColorTag::GetAlpha(): Returns the alpha value of the given vertex index.
• VertexColorTag::SetAlpha(): Sets the alpha value of the given vertex index.

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

• VertexColorTag::Get(ConstVertexColorHandle dataptr, Neighbor* nb, const CPolygon* vadr, Int32 pIndex): Returns the RGBA values of the given vertex index.
• VertexColorTag::Set(VertexColorHandle dataptr, Neighbor* nb, const CPolygon* vadr, Int32 pIndex, const maxon::ColorA32& color): Sets the RGBA values of the given vertex index.

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

• Modeling
• BaseTag and VariableTag Manual
• BaseObject Manual
• Primitive Data Types Manual (Classic)
• Vector Manual (Classic)