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* root = doc->GetLayerObjectRoot();
    if (!root)
      return false;

    // create 10 layers with variations
    for (Int32 i = 0; i < 20; ++i)
    {
      LayerObject* newLayer = LayerObject::Alloc();

      if (newLayer)
      {
        // new color
        const Vector hsv = Vector(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);
      }

    }

    EventAdd();

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* layers = doc->GetLayerObjectRoot();

    if (layers != nullptr)
    {
      LayerObject* layer = static_cast<LayerObject*>(layers->GetFirst());

      if (layer != nullptr)
        GePrint("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* root = doc->GetLayerObjectRoot();
if (!root)
  return false;

LayerObject* newLayer = LayerObject::Alloc();
if (!newLayer)
  return false;

newLayer->SetName("This is a new layer");
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* object = doc->GetActiveObject();

    if (!object)
      return false;

    LayerObject* layer = object->GetLayerObject(doc);

    if (layer)
    {
      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* layerData = object->GetLayerData(doc, true);

    if (layerData)
    {
      GePrint("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* root = doc->GetLayerObjectRoot();
    if (!root)
      return false;

    LayerObject* newLayer = LayerObject::Alloc();
    if (!newLayer)
      return false;

    // setup layer and add it to the layer list
    LayerData layerData;
    layerData.locked = true;
    layerData.solo = false;
    newLayer->SetLayerData(doc, layerData);
    newLayer->SetName("Locked");

    root->InsertLast(newLayer);

    // get object selection
    AutoAlloc<AtomArray> objects;
    if (!objects)
      return false;

    doc->GetActiveObjects(objects, GETACTIVEOBJECTFLAGS_0);

    // check every objects
    for (Int32 i = 0; i < objects->GetCount(); ++i)
    {
      BaseObject* object = static_cast<BaseObject*>(objects->GetIndex(i));

      object->SetLayerObject(newLayer);
    }

    EventAdd();

Note

When one disables the solo bit it is also necessary to change the NBIT_SOLO_LAYER of the BaseDocument with GeListNode::ChangeNBit().

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