About

A TakeData object stores the take system related data of a BaseDocument.

Access

A TakeData object is returned by the host BaseDocument:

BaseDocument::GetTakeData(): Returns the document's TakeData object.

  // This example accesses the take data
  // fromn the given BaseDocument.
 
  TakeData* const takeData = doc->GetTakeData();
  if (takeData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);

Read-Only Properties

The TakeData object allows access to its parent document and to different settings of the Take Manager.

TakeData::GetOverrideEnabling(): Returns the bitmask for the current override modes.
TakeData::CheckOverrideEnabling(): Checks if a specific override mode is enabled.
TakeData::GetDocument(): Returns the BaseDocument for this TakeData.
TakeData::GetTakeMode(): Returns the document's take mode:
- TAKE_MODE::MANUAL : Parameters are not editable and overrides must be created manually.
- TAKE_MODE::AUTO : Parameters are editable and overrides are created on change.

Note: The take mode can be toggled with command 431000081. See Command Utility Manual.

Takes

Accessing Takes

Existing takes are accessed from the TakeData object:

TakeData::GetMainTake(): Returns the main take.
TakeData::GetCurrentTake(): Returns the currently selected take.
TakeData::SetCurrentTake(): Sets the given take as the current take.
TakeData::GetTakeSelection(): Gets the selection of takes.

  // This example checks if the current Take is the main take.
  // If not, the main take becomes the current take.
 
  // gets the current take
  BaseTake* const currentTake = takeData->GetCurrentTake();
  if (currentTake == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // check if the current take is the main take
  if (currentTake->IsMain() == false)
  {
    // if not, make the main take the current take
    BaseTake* const mainTake = takeData->GetMainTake();
    takeData->SetCurrentTake(mainTake);
  }

Create Takes

The TakeData object creates and deletes takes:

TakeData::AddTake(): Adds a new take.
TakeData::InsertTake(): Moves a take in the hierarchy.
TakeData::DeleteTake(): Deletes the given take.
TakeData::ResetSystem(): Deletes all takes.

  // This example simply creates a new take and makes it the current one.
 
  TakeData* const takeData = doc->GetTakeData();
  if (takeData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  BaseTake* const newTake = takeData->AddTake("This is a new take", nullptr, nullptr);
  if (newTake == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  takeData->SetCurrentTake(newTake);

Overrides

The TakeData object also provides access to the override backup for a given override and parameter:

TakeData::FindOverrideCounterPart(): Returns the BaseOverride and BaseTake that stores the backup value.

  // This example searches for the BaseOverride of the given material and its color parameter.
  // If found, the color value is applied to the backup value to transfer the state of this take
  // to the backup take (which might be the main take).
 
  BaseTake* const take = takeData->GetCurrentTake();
  if (take == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // check if this is the main take
  if (take->IsMain())
    return maxon::OK;
 
  // search for the override of the given material
  BaseOverride* const baseOverride = take->FindOverride(takeData, material);
  if (baseOverride == nullptr)
    return maxon::OK;
 
  const DescID id { DescLevel { MATERIAL_COLOR_COLOR, DTYPE_COLOR, 0 } };
 
  // find the backup
  BaseTake* result = nullptr;
  BaseOverride* const backup = takeData->FindOverrideCounterPart(baseOverride, id, result);
  if (backup == nullptr)
    return maxon::OK;
 
  GeData data;
 
  // read the value of the take
  baseOverride->GetParameter(id, data, DESCFLAGS_GET::NONE);
 
  // set it as the new backup
  backup->SetParameter(id, data, DESCFLAGS_SET::NONE);
  backup->UpdateSceneNode(takeData, id);

Undo States

Several functions of the Take system like TakeData::AddTake() or TakeData::DeleteTake() create an undo step when used. This might not be necessary in some cases, so it is possible to disable the take system's undo state.

TakeData::SetUndoState(): Enables and disables the global undo state.
TakeData::GetUndoState(): Reads the current global undo state.

  // This example disables the undo state of the take system
  // since it operates on a BaseDocument that is not
  // the active BaseDocument.
 
  // create a new document
  AutoAlloc<BaseDocument> takeTemplateDoc;
  if (takeTemplateDoc == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  TakeData* const takeData = takeTemplateDoc->GetTakeData();
  if (takeData == nullptr)
    return maxon::OK;
 
  // disable undos since they are not needed in this situation
  takeData->SetUndoState(false);
 
  // add some takes
  takeData->AddTake("Take 1", nullptr, nullptr);
  takeData->AddTake("Take 2", nullptr, nullptr);
 
  // save the document
  SaveDocument(takeTemplateDoc, savePath, SAVEDOCUMENTFLAGS::NONE, FORMAT_C4DEXPORT);

Convert

With TakeData::TakeToDocument() it is possible to create a BaseDocument with the state of the selected take.

  // This example only loops through the child takes of the main take,
  // but not through further child takes. The folder to save the files
  // must be defined with "folder".
 
  const BaseTake* const mainTake  = takeData->GetMainTake();
  BaseTake*             childTake = mainTake->GetDown();
  while (childTake != nullptr)
  {
    // create a BaseDocument with this take's settings
    BaseDocument* takeDoc = takeData->TakeToDocument(childTake);
    if (takeDoc == nullptr)
      return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
    // create the final Filename
    // two takes could have the same name so one should check if this file already exists
    const String   file = childTake->GetName() + ".c4d";
    const Filename filename = folder + file;
 
    // save the document as a Cinema 4D file
    SaveDocument(takeDoc, filename, SAVEDOCUMENTFLAGS::NONE, FORMAT_C4DEXPORT);
 
    // free the document
    BaseDocument::Free(takeDoc);
 
    childTake = childTake->GetNext();
  }

Disc I/O

With TakeData::SaveTakesWithAssets() it is possible to save all takes as a separate project.

  // This example saves each take with assets.
 
  TakeData* const takeData = doc->GetTakeData();
  if (takeData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  takeData->SaveTakesWithAssets(false);

Table of Contents