UVWTag Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Access Data
  • Slow
  • Fast
  • Pin
• Further Reading

About

A UVWTag stores UVW coordinates for a (polygon) object. For each polygon a set of four UVW coordinates is stored (UVWStruct). The class UVWTag is based on VariableTag so the typical workflows on handling tags apply, see BaseTag and VariableTag Manual.

UVWTag objects are an instance of Tuvw.

Access

A UVWTag is typically attached to a polygon object.

Note

A polygon object can host multiple UVW tags.

Allocation/Deallocation

UVWTag instances are created with the usual tools.

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

A UVW tag with projection-based UVs can be created with:

• GenerateUVW(): Returns a UVWTag with UVs defined by the projection settings of the given TextureTag.

  // This example checks if the given object hosts a UVW tag.
  // If not, a UVW tag is created.
 
  BaseTag* const foundTag = object->GetTag(Tuvw);
  UVWTag*        uvwTag = static_cast<UVWTag*>(foundTag);
 
  if (uvwTag == nullptr)
  {
    // check if the given object is a polygon object
    if (object->IsInstanceOf(Opolygon))
    {
      PolygonObject* const polyObject = static_cast<PolygonObject*>(object);
      const Int32 polyCount = polyObject->GetPolygonCount();
 
      uvwTag = UVWTag::Alloc(polyCount);
      if (uvwTag == nullptr)
        return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
      polyObject->InsertTag(uvwTag);
    }
  }

Access Data

There are two ways to edit the data stored inside a UVWTag. The "slow" way is to access every set of UVW coordinate independently. The "fast" way works with a data handle that allows direct access to the internal memory.

Slow

The UVW coordinates stored in a UVWTag can be accessed with:

• UVWTag::GetSlow(): Returns the UVW coordinates for the given polygon index.
• UVWTag::SetSlow(): Sets the UVW coordinates for the given polygon index.
• UVWTag::CpySlow(): Copies the UVW coordinates for the given index from the given UVWTag.

  // This example loops through the UVW data stored in the given UVW tag.
 
  const Int32 count = uvwTag->GetDataCount();
 
  for (Int32 i = 0; i < count; ++i)
  {
    ApplicationOutput("UVW Polygon " + String::IntToString(i));
 
    const UVWStruct uvwData = uvwTag->GetSlow(i);
 
    ApplicationOutput("A: " + String::VectorToString(uvwData.a));
    ApplicationOutput("B: " + String::VectorToString(uvwData.b));
    ApplicationOutput("C: " + String::VectorToString(uvwData.c));
    ApplicationOutput("D: " + String::VectorToString(uvwData.d));
  }

Fast

The fast access to the UVW coordinates stored in the UVWTag is provided by a data handle and static functions:

• UVWTag::GetDataAddressR(): Returns a handle to the read-only UVW coordinates.
• UVWTag::GetDataAddressW(): Returns a handle to the writeable UWV coordinates.
• UVWTag::Get(): Returns the UVW coordinates for the given polygon index.
• UVWTag::Set(): Sets the UVW coordinates for the given polygon index.
• UVWTag::Copy(): Copies the UVW coordinates for the given index from the given UVW handle.

  // This example calculates UVW coordinates based on the polygon's world space position.
 
  UVWHandle handle = uvwTag->GetDataAddressW();
 
  const Int32 count = uvwTag->GetDataCount();
 
  for (Int32 i = 0; i < count; ++i)
  {
    UVWStruct uvwData;
 
    // get points in world space
    CPolygon     polygon = polygons[i];
    const Vector a = mg * points[polygon.a];
    const Vector b = mg * points[polygon.b];
    const Vector c = mg * points[polygon.c];
    const Vector d = mg * points[polygon.d];
 
    // define UV coordinates based on the world space position
    // CalculateUVCoordinates() is a custom function
 
    CalculateUVCoordinates(a, uvwData.a);
    CalculateUVCoordinates(b, uvwData.b);
    CalculateUVCoordinates(c, uvwData.c);
    CalculateUVCoordinates(d, uvwData.d);
 
    UVWTag::Set(handle, i, uvwData);
  }
 
  polyObject->Message(MSG_UPDATE);

Pin

Pin are stored by UV tag, you can access them with:

• UVWTag::GetPinSelection(): Returns the pined UV point selection.
• UVWTag::AddToPinSelection(): Adds the passed UV Point selection to the pined UV point selection.
• UVWTag::RemoveFromPinSelection(): Removes the passed UV Point selection to the pined UV point selection.

    // This example sets the current active Point Selection to the UV Point pinned.
  // Get object
  BaseObject* const obj = doc->GetActiveObject();
  if (obj == nullptr || ! obj->IsInstanceOf(Opoint))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Should be a Point Object"_s);
 
  // Retrieves the fist uvwtag
  UVWTag* uvTag = static_cast<UVWTag*>(obj->GetTag(Tuvw));
  if (uvTag == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Retrieves the Pin Selection Stored in the uvTag
  const BaseSelect& pinSelection = uvTag->GetPinSelection();
  if (pinSelection.GetCount() == 0)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Retrieves the current Point Selection stored in the PointObject
  BaseSelect* ptSelect = ToPoint(obj)->GetPointS();
  if (ptSelect == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  ptSelect->DeselectAll();
 
  // Convert UV Point baseSelect to PointObject BaseSelect
  // UV Points are indexed by 4 * polygon + point where @c polygon is the polygon index and c point is the point index between 0 and 3 (a, b, c, d).
  const CPolygon* polys = ToPoly(obj)->GetPolygonR();
  Int32 seg = 0, smin, smax, idx;
  while (pinSelection.GetRange(seg++, LIMIT<Int32>::MAX, &smin, &smax))
  {
    // For each sequance of range
    for (idx = smin; idx <= smax; idx++)
    {
      // Retrieves the polygon ID and the Cpolygon ID
      Int32 polyId = idx / 4;
      Int32 cpolyPtId = idx % 4;
 
      // Retrieve the real PtID from the Cpolygon
      Int32 ptId = polys[polyId][cpolyPtId];
 
      ptSelect->Select(ptId);
    }
  }
 
    EventAdd();

    // This example sets the UV Point pinned to the current active Point Selection.
  // Get object
  BaseObject* const obj = doc->GetActiveObject();
  if (obj == nullptr || ! obj->IsInstanceOf(Opoint))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Should be a Point Object"_s);
 
  // Retrieves the fist uvwtag
  UVWTag* uvTag = static_cast<UVWTag*>(obj->GetTag(Tuvw));
  if (uvTag == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Retrieves the current Point Selection stored in the PointObject
  BaseSelect* ptSelect = ToPoint(obj)->GetPointS();
  if (ptSelect == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Allocate a new pinSelection To Set
  AutoAlloc<BaseSelect> pinsToSet;
 
  // Convert PointObject BaseSelect to Uv Point baseSelect
  // UV Points are indexed by 4 * polygon + point where c polygon is the polygon index and c point is the point index between 0 and 3 (a, b, c, d).
  // Retrieves the read array of all Cpolygon
  const CPolygon* poly = ToPoly(obj)->GetPolygonR();
  if (poly == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Retrieves an array of the selection state
  const maxon::AutoMem<UChar> ptArray = ptSelect->ToArray(ToPoint(obj)->GetPointCount());
  if (ptArray == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  for (Int32 i = 0; i <  ToPoly(obj)->GetPolygonCount(); ++i)
  {
    const CPolygon* pp = poly + i;
    if (pp == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    if (ptArray[pp->a])
      pinsToSet->Select(i * 4 + 0);
 
    if (ptArray[pp->b])
      pinsToSet->Select(i * 4 + 1);
 
    if (ptArray[pp->c])
      pinsToSet->Select(i * 4 + 2);
 
    if (ptArray[pp->d])
      pinsToSet->Select(i * 4 + 3);
  }
 
  // Clears the current Pin Selection
  uvTag->ClearPinSelection();
 
  // Adds the built selection to the current pin selection
  uvTag->AddToPinSelection(pinsToSet);
 
  EventAdd();

    // This example removes from the UV Point pinned, the current active Point Selection.
  // Get object
  BaseObject* const obj = doc->GetActiveObject();
  if (obj == nullptr || ! obj->IsInstanceOf(Opoint))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Should be a Point Object"_s);
 
  // Retrieves the fist uvwtag
  UVWTag* uvTag = static_cast<UVWTag*>(obj->GetTag(Tuvw));
  if (uvTag == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Retrieves the current Point Selection stored in the PointObject
  BaseSelect* ptSelect = ToPoint(obj)->GetPointS();
  if (ptSelect == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Allocate a new pinSelection To Set
  AutoAlloc<BaseSelect> pinsToSet;
 
  // Convert PointObject BaseSelect to Uv Point baseSelect
  // UV Points are indexed by 4 * polygon + point where c polygon is the polygon index and c point is the point index between 0 and 3 (a, b, c, d).
  // Retrieves the read array of all Cpolygon
  const CPolygon* poly = ToPoly(obj)->GetPolygonR();
  if (poly == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Retrieves an array of the selection state
  const maxon::AutoMem<UChar> ptArray = ptSelect->ToArray(ToPoint(obj)->GetPointCount());
  if (ptArray == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  for (Int32 i = 0; i <  ToPoly(obj)->GetPolygonCount(); ++i)
  {
    const CPolygon* pp = poly + i;
    if (pp == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    if (ptArray[pp->a])
      pinsToSet->Select(i * 4 + 0);
 
    if (ptArray[pp->b])
      pinsToSet->Select(i * 4 + 1);
 
    if (ptArray[pp->c])
      pinsToSet->Select(i * 4 + 2);
 
    if (ptArray[pp->d])
      pinsToSet->Select(i * 4 + 3);
  }
 
  // Removes the built selection to the current pin selection
  uvTag->RemoveFromPinSelection(pinsToSet);
 
  EventAdd();

While it's not stored directly in the UVWTag you may need to retrieve UV seems of an object:

• GetUVSeams(): Returns the UV seams of a BaseObject.

    // This example select edge corresponding to the UV seams of the current object
  // Gets object
  BaseObject* const obj = doc->GetActiveObject();
  if (obj == nullptr || ! obj->IsInstanceOf(Opoint))
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, "Should be a Point Object"_s);
 
  const EdgeBaseSelect* uvSeams = GetUVSeams(obj);
  if (uvSeams == nullptr || uvSeams->GetCount() == 0)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Retrieves the current Edge Selection stored in the Polygon Object
  BaseSelect* edgeSelect = ToPoly(obj)->GetEdgeS();
  if (edgeSelect == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // Deselect all the currently selected edge
  edgeSelect->DeselectAll();
 
  // Copies the UV seams to the Polygon Edge selection.
  uvSeams->CopyTo(edgeSelect);
 
  EventAdd();

Further Reading

• Modeling
• NormalTag Manual
• BaseObject Manual
• BaseTag and VariableTag Manual