BaseOverrideGroup Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Navigation
• Read
• Override Group
  • Objects
  • Tags
  • Modes
• Further Reading

About

A BaseOverrideGroup acts like a virtual null object. It can have multiple child objects. Tags applied to the group are applied to the child objects.

Warning

Override groups add tags to the scene and own these tags. It is not possible to delete these tags. NBIT::TAKE_LOCK can be used to check if a tag is owned by a BaseOverrideGroup.

  // This code creates a take with an override group for each selected material
  // and adds the object "object" to the newly created group.
 
  // get the active object
  BaseObject* const object = doc->GetActiveObject();
  if (object == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // get all active materials
  AutoAlloc<AtomArray> materials;
  if (materials == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->GetActiveMaterials(materials);
 
  // loop through all active materials
  for (Int32 i = 0; i < materials->GetCount(); ++i)
  {
    C4DAtom* const      mat = materials->GetIndex(i);
    BaseMaterial* const material = static_cast<BaseMaterial*>(mat);
 
    // create a new take
    const String    materialName = material->GetName();
    BaseTake* const take = takeData->AddTake(materialName, nullptr, nullptr);
    if (take == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // create an override group
    BaseOverrideGroup* const group = take->AddOverrideGroup();
    if (group == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // add the object to the group
    group->AddToGroup(takeData, object);
 
    // create a texture tag referencing this material
    BaseTag* const tag = group->AddTag(takeData, Ttexture, material);
    if (tag == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // set projection to UVW
    tag->SetParameter(DescID(TEXTURETAG_PROJECTION), TEXTURETAG_PROJECTION_UVW, DESCFLAGS_SET::NONE);
  }

Access

Existing override groups are accessed from the host BaseTake:

• BaseTake::GetFirstOverrideGroup(): Returns the first override group of the take.
• BaseTake::GetOverrideGroups(): Returns an array with all override groups of the take.

  // This example checks all override groups if they contain the object "activeObject".
 
  AutoAlloc<AtomArray> overrideGroups;
  if (overrideGroups == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  take->GetOverrideGroups(overrideGroups);
 
  // loop through all BaseOverrideGroups
  for (Int32 i = 0; i < overrideGroups->GetCount(); ++i)
  {
    BaseOverrideGroup* const group = static_cast<BaseOverrideGroup*>(overrideGroups->GetIndex(i));
    if (group == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // check if the override group contains the given object
    if (group->Find(takeData, activeObject))
      ApplicationOutput("Override Group " + group->GetName() + " contains the active object!");
  }

Allocation/Deallocation

A BaseOverrideGroup is created using the host BaseTake.

• BaseTake::AddOverrideGroup(): Adds a new override group.
• BaseTake::DeleteOverrideGroup(): Deletes a given override group.

  // This example accesss the BaseOverrideGroup from the
  // given take and set the group name.
 
  BaseOverrideGroup* const group = take->AddOverrideGroup();
  if (group == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  group->SetName("New Override Group"_s);

Navigation

BaseOverrideGroup instances are organized in a simple BaseList2D list.

• BaseOverrideGroup::GetNext(): Returns the next override group in the list or nullptr.
• BaseOverrideGroup::GetPred(): Returns the previous override group in the list or nullptr.

  // This example loops through all override groups and checks which groups are currently selected
 
  BaseOverrideGroup* overrideGroup = take->GetFirstOverrideGroup();
 
  while (overrideGroup != nullptr)
  {
    ApplicationOutput("OverrideGroup: " + overrideGroup->GetName());
 
    // check if override group is selected
    if (overrideGroup->GetBit(BIT_ACTIVE))
      ApplicationOutput("This is an active group.");
 
    overrideGroup = overrideGroup->GetNext();
  }

Read

• BaseOverrideGroup::GetTake(): Returns the host BaseTake.

Override Group

Objects

A BaseOverrideGroup acts like a null object. Different scene objects can be added to this group.

• BaseOverrideGroup::AddToGroup(): Adds the given object to the group.
• BaseOverrideGroup::GetObjectsInGroup(): Returns the objects of the group.
• BaseOverrideGroup::RemoveFromGroup(): Removes the given object from the group.
• BaseOverrideGroup::Find(): Checks if the given object is part of the group.

  // This example adds the currently selected objects to the BaseOverrideGroup "group".
 
  AutoAlloc<AtomArray> objects;
  if (objects == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->GetActiveObjects(objects, GETACTIVEOBJECTFLAGS::NONE);
 
  // loop through all active objects
  for (Int32 i = 0; i < objects->GetCount(); ++i)
  {
    BaseObject* const object = static_cast<BaseObject*>(objects->GetIndex(i));
    group->AddToGroup(takeData, object);
  }

Tags

Override groups act as virtual null objects that can host different tags. If a take is applied, this tag is added to the objects in question.

• BaseOverrideGroup::AddTag(): Adds the tag of the given type to the group. If the tag is a texture tag, the given material is used.
• BaseOverrideGroup::GetTag(): Returns the tag of the given type or nullptr.
• BaseOverrideGroup::RemoveTag(): Removes the tag of the given type.

  // This example simply adds and configures the compositing tag.
  BaseTag* const compositingTag = group->AddTag(takeData, Tcompositing, nullptr);
  if (compositingTag == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  compositingTag->SetParameter(DescID(COMPOSITINGTAG_ENABLECHN0), true, DESCFLAGS_SET::NONE);

Modes

With these modes it is possible to control the visibility of the assigned objects when rendering and in the viewport.

• BaseOverrideGroup::SetEditorMode(): Sets the editor mode.
• BaseOverrideGroup::GetEditorMode(): Gets the editor mode.
• BaseOverrideGroup::SetRenderMode(): Sets the render mode.
• BaseOverrideGroup::GetRenderMode(): Gets the render mode.

The modes are:

• MODE_OFF : off; elements are not visible.
• MODE_ON : on; elements are always visible.
• MODE_UNDEF : undefined; the parent mode applies.

  // This code adds the currently selected objects to a new group in the current take.
  // The objects of this group will only be visible in the renderer but not in the editor.
 
  BaseTake* const take = takeData->GetCurrentTake();
  if (take == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // get all active objects
  AutoAlloc<AtomArray> objects;
  if (objects == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->GetActiveObjects(objects, GETACTIVEOBJECTFLAGS::NONE);
 
  // create an override group
  BaseOverrideGroup* const group = take->AddOverrideGroup();
  if (group == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  group->SetName("Render Objects"_s);
  group->SetEditorMode(MODE_OFF); // invisible in editor
  group->SetRenderMode(MODE_ON);  // visible in renderer
 
  // loop through all active objects
  for (Int32 i = 0; i < objects->GetCount(); ++i)
  {
    // add object to group
    BaseObject* const object = static_cast<BaseObject*>(objects->GetIndex(i));
    group->AddToGroup(takeData, object);
  }

Further Reading

• Scene Data Overview
• BaseDocument Manual
• Take System Overview
• TakeData Manual
• BaseTake Manual
• BaseOverride Manual