Layer Manual

Table of Contents

• About
• LayerObject
  • Access
  • Allocation/Deallocation
  • Navigation
• LayerData
  • Access
  • Properties
• Utility
• Further Reading

About

Layers are used to organize a Cinema 4D scene. A layer is represented by a LayerObject, its settings are stored in a LayerData object.

  // This example creates new layers with distinct colors.
 
  GeListHead* const root = doc->GetLayerObjectRoot();
  if (root == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // create 10 layers with variations
  for (Int32 i = 0; i < 20; ++i)
  {
    LayerObject* const newLayer = LayerObject::Alloc();
    if (newLayer == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // new color
    const Vector hsv { Float(i) * 0.05, 1.0, 1.0 };
    const Vector rgb = HSVToRGB(hsv);
 
    // define layerData
    LayerData layerData;
    layerData.color = rgb;
    layerData.solo  = false;
 
    // set layer settings
    newLayer->SetLayerData(doc, layerData);
    newLayer->SetName("Layer " + String::IntToString(i));
 
    // insert layer
    root->InsertLast(newLayer);
  }

LayerObject

A LayerObject represents a layer of a Cinema 4D scene. It is used to assign an element to this layer and to edit the layer.

LayerObject objects are an instance of Olayer.

Access

The LayerObject assigned to an element can be accessed and set with these ::BaseList2D functions:

• BaseList2D::GetLayerObject(): Returns the LayerObject representing the element's layer or nullptr.
• BaseList2D::SetLayerObject(): Used to set the layer of the element.

Layers are organized in a tree. The root element of that tree is stored in the BaseDocument:

• BaseDocument::GetLayerObjectRoot(): Returns the GeListHead that is the root of the layer tree.

  // This example gets the layer root object to access the first layer.
 
  GeListHead* const layers = doc->GetLayerObjectRoot();
  if (layers == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  LayerObject* const layer = static_cast<LayerObject*>(layers->GetFirst());
 
  if (layer != nullptr)
    ApplicationOutput("First Layer: " + layer->GetName());

Note

To check if a given LayerObject is currently selected in the Layer Manager, read the bit BIT_ACTIVE.

Allocation/Deallocation

LayerObject objects are created with the usual tools:

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

  // This example creates a new layer and assigns it to the "object" entity.
 
  GeListHead* const root = doc->GetLayerObjectRoot();
  if (root == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  LayerObject* const newLayer = LayerObject::Alloc();
  if (newLayer == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  newLayer->SetName("This is a new layer"_s);
  root->InsertLast(newLayer);
 
  // assign
  object->SetLayerObject(newLayer);

Navigation

LayerObject objects are based on ::GeListNode and are organized in a tree. This tree can be navigated with:

• LayerObject::GetNext(): Returns the next LayerObject.
• LayerObject::GetPred(): Returns the previous LayerObject.
• LayerObject::GetUp(): Returns the parent LayerObject.
• LayerObject::GetDown(): Returns the child LayerObject.
• LayerObject::GetDownLast(): Returns the last child LayerObject.

  // This example checks if the given object is has a layer.
  // If so, the topmost parent of that layer is assigned instead.
 
  BaseObject* const object = doc->GetActiveObject();
  if (object == nullptr)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  LayerObject* const layer = object->GetLayerObject(doc);
 
  if (layer != nullptr)
  {
    LayerObject* parentLayer = layer;
 
    // search for topmost layer
    while (parentLayer->GetUp())
    {
      parentLayer = parentLayer->GetUp();
    }
 
    // assign parent layer
    object->SetLayerObject(parentLayer);
  }

Note

If a layer is folded in the Layer Manager is controlled with the bit BIT_OFOLD.

LayerData

A LayerData object represents the settings of a layer.

Access

The applied layer settings of an element are accessed with these ::BaseList2D functions:

• BaseList2D::GetLayerData(): Returns the layer data of the object's layer.
• BaseList2D::SetLayerData(): Sets the layer data of the object's layer.

These functions can be used on the given element or on a LayerObject object.

  // This example get the object's LayerData and prints the color to the console.
 
  const LayerData* const layerData = object->GetLayerData(doc, true);
 
  if (layerData != nullptr)
  {
    ApplicationOutput("Color: " + String::VectorToString(layerData->color));
  }

Properties

These are the properties of a layer stored in a LayerData object. These properties define how a layer changes the behavior of an element that is assigned to that layer:

• LayerData::solo: solo mode.
• LayerData::view: visible in the editor view.
• LayerData::render: visible in render view.
• LayerData::manager: visible in the Object Manager and the Timeline.
• LayerData::locked: not selectable.
• LayerData::generators: turns generators off.
• LayerData::deformers: turns deformers off.
• LayerData::expressions: turns expressions off.
• LayerData::animation: turns animations off.
• LayerData::color: the layer color.
• LayerData::xref: elements will not be exported using Xref.

  // This example creates a new, locked layer and assigns all active objects.
 
  // create layer
  GeListHead* const root = doc->GetLayerObjectRoot();
  if (root == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  LayerObject* const newLayer = LayerObject::Alloc();
  if (newLayer == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // setup layer and add it to the layer list
  LayerData layerData;
  layerData.locked = true;
  layerData.solo = false;
  newLayer->SetLayerData(doc, layerData);
  newLayer->SetName("Locked"_s);
 
  root->InsertLast(newLayer);
 
  // get object selection
  AutoAlloc<AtomArray> objects;
  if (objects == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  doc->GetActiveObjects(objects, GETACTIVEOBJECTFLAGS::NONE);
 
  // check every objects
  for (Int32 i = 0; i < objects->GetCount(); ++i)
  {
    BaseObject* const object = static_cast<BaseObject*>(objects->GetIndex(i));
    if (object == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    object->SetLayerObject(newLayer);
  }

Note

When one edits the solo bit it is also necessary to change the ::NBIT::SOLO_LAYER of the BaseDocument with GeListNode::ChangeNBit() either using ::NBITCONTROL::SET or ::NBITCONTROL:: CLEAR.

Utility

• IsObjectEnabled(): Checks if the given object should be visible in the viewport, including checking the layers.

Further Reading

• Scene Data Overview
• BaseDocument Manual
• BaseList2D Manual