BaseDocument Manual

About

A BaseDocument represents a Cinema 4D scene with all its content. Cinema 4D can manage multiple open scenes simultaneously in a document list. It is possible to load, create, edit, render and save scenes in the background. A document contains:

  • Objects, materials and tags
  • Render settings
  • Document settings
  • Layers
  • Takes
  • Scene hooks
  • Undo actions
Warning
The active BaseDocument is the scene currently displayed in the editor. This active BaseDocument must not be edited from another thread than the main thread. Watch out for functions marked as "called in a thread context". If one needs to change the document from an asynchronous dialog, StopAllThreads() must be called before.

BaseDocument objects are an instance of Tbasedocument.

// This example shows how to create a virtual document, add a cube and render the document.
// create document
if (virtualDoc == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// create and add a new cube
if (cube == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
virtualDoc->InsertObject(cube, nullptr, nullptr);
// prepare bitmap
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Int32 width = 1280;
const Int32 height = 720;
const IMAGERESULT imageRes = bitmap->Init(width, height);
if (imageRes != IMAGERESULT::OK)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// define render settings
RenderData* const rdata = virtualDoc->GetActiveRenderData();
if (rdata == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
BaseContainer renderSettings = rdata->GetData();
renderSettings.SetFloat(RDATA_XRES, width);
renderSettings.SetFloat(RDATA_YRES, height);
// render the document
const RENDERRESULT res = RenderDocument(virtualDoc, renderSettings,
nullptr, nullptr, bitmap, flags, nullptr);
if (res != RENDERRESULT::OK)
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
// show result
ShowBitmap(bitmap);

Access

Cinema 4D can handle multiple open scenes in a document list:

To navigate the document list GetNext() and GetPred() can be used:

// This example iterates through all BaseDocuments in the document list.
// The active BaseDocument is marked with a star.
const BaseDocument* const activeDocument = GetActiveDocument();
if (activeDocument == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
while (document != nullptr)
{
const GeMarker& docMarker = document->GetMarker();
const GeMarker& activeDocMarker = activeDocument->GetMarker();
// use GeMarker to compare identity of the BaseDocuments
if (docMarker.IsEqual(activeDocMarker))
{
ApplicationOutput("Document: " + document->GetDocumentName().GetString() + " *");
}
else
{
ApplicationOutput("Document: " + document->GetDocumentName().GetString());
}
document = document->GetNext();
}
Note
GetActiveDocument() and GetFirstDocument() only work in Cinema 4D versions that have an active document (not in Team Render Client, Command Line etc.). Use GetActiveDocument() only in combination with dialogs etc. but NEVER in NodeData based plugins or expressions.
GeListNode::GetDocument() returns the BaseDocument that hosts a given entity. Use this method to access the document in a NodeData based plugin and all functions that are part of the execution or drawing pipeline. But never forget to check for nullptr, as there are situations where elements are not part of any document at all.

Allocation/Deallocation

A BaseDocument can be created with the usual tools:

AutoAlloc can be used to handle a temporary document. A new document can be added to the document list:

// This example creates a new BaseDocument and inserts it
// into the list of documents.
// create new document
BaseDocument* const newDocument = BaseDocument::Alloc();
if (newDocument == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// insert document as the active document.
InsertBaseDocument(newDocument);
SetActiveDocument(newDocument);
// set document file name
newDocument->SetDocumentName("new_document.c4d");
// update Cinema
Note
BaseDocuments can also be created by loading Cinema 4D files. See Disc I/O below.

Destroy

A dynamically created BaseDocument should be destroyed with BaseDocument::Free(). To remove a BaseDocument from the document list use KillDocument().

Copy

BaseDocument is based on C4DAtom and can be cloned using C4DAtom::GetClone():

// This example clones the given document add adds it to the document list.
C4DAtom* const cloneAtom = doc->GetClone(COPYFLAGS::NONE, nullptr);
BaseDocument* const cloneDocument = static_cast<BaseDocument*>(cloneAtom);
if (cloneDocument == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
InsertBaseDocument(cloneDocument);
SetActiveDocument(cloneDocument);
cloneDocument->SetDocumentName("clone.c4d");

Preview Image

When a scene is saved the current editor image is saved with the BaseDocument to create a thumbnail preview image.

// This example shows the preview bitmap in the Picture Viewer.
BaseBitmap* const bitmap = doc->GetDocPreviewBitmap();
if (bitmap != nullptr)
{
ShowBitmap(bitmap);
}

Properties

Data

Multiple settings are stored inside the BaseDocument. The different types of settings are defined in DOCUMENTSETTINGS, the parameter IDs in ddoc.h.

// This example switches the statue of the "Use Generators" setting.
const Bool useGenerators = data.GetBool(DOCUMENT_USEGENERATORS);
// set new settings
BaseContainer settings;
settings.SetBool(DOCUMENT_USEGENERATORS, !useGenerators);

and

// This example accesses the document settings to set the "Author" setting.
if (settings == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
settings->SetString(DOCUMENT_INFO_AUTHOR, "User"_s);
Note
BaseDocument::GetSettingsInstance() won't work with DOCUMENTSETTINGS::GENERAL.

Objects

A BaseDocument hosts multiple BaseObject based scene objects. These objects are organized in an object tree.

Note
Using BaseDocument::InsertObject() will trigger the message MSG_DOCUMENTINFO_TYPE_OBJECT_INSERT.

See also BaseObject Manual.

// This example searches for an object named "Cube".
// If it cannot be found a new cube with that name will be created.
BaseObject* const object = doc->SearchObject("Cube"_s);
if (object != nullptr)
{
ApplicationOutput("found \"Cube\""_s);
return maxon::OK;
}
BaseObject* const cubeObject = BaseObject::Alloc(Ocube);
if (cubeObject == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
cubeObject->SetName("Cube"_s);
doc->InsertObject(cubeObject, nullptr, nullptr);

In some cases multiple instances of a certain object class can be inserted into the scene but only one instance will be used (e.g. the Sky object). This is typically the "highest" instance.

// This example searches for the highest (and thus used) stage object
BaseObject* const stageObject = doc->GetHighest(Ostage, false);
if (stageObject == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
ApplicationOutput("Found stage object \"" + stageObject->GetName() + "\"");

Materials

A BaseDocument hosts multiple BaseMaterial based materials. These materials are stored in a list and can be applied to objects in the scene.

See also BaseMaterial Manual

// This example searches for a material with the given name.
// If the material cannot be found, a new material with that
// name will be created and inserted into the document.
// search material
BaseMaterial* const material = doc->SearchMaterial("Green"_s);
if (material)
{
ApplicationOutput("Found \"Green\""_s);
return maxon::OK;
}
// create material
BaseMaterial* const greenMaterial = BaseMaterial::Alloc(Mmaterial);
if (greenMaterial == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
greenMaterial->SetName("Green"_s);
// insert material into the document
doc->InsertMaterial(greenMaterial);

Selections

Inside a scene multiple objects, materials or tags can be selected.

// This example prints the name and type of all selected scene elements.
if (selection == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
doc->GetSelection(selection);
const Int32 cnt = selection->GetCount();
if (cnt == 0)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
for (Int32 i = 0; i < cnt; ++i)
{
C4DAtom* const element = selection->GetIndex(i);
// check if the given C4DAtom is a BaseList2D element
const Bool validElement = element != nullptr;
if (validElement && element->IsInstanceOf(Tbaselist2d))
{
BaseList2D* baseList2D = static_cast<BaseList2D*>(element);
ApplicationOutput(baseList2D->GetName() + " (" + baseList2D->GetTypeName() + ")");
}
else
{
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
}
}

Object selections can be managed separately:

Note
To get the position of the anchor of an object multi-selection one can use BaseDocument::GetHelperAxis().
To correctly add objects to the selection of active objects with BaseDocument::SetActiveObject() one must update internal caches by calling BaseDocument::GetActiveObject() after an object was added to the selection.
// This example gets all selected null objects.
// For each null object a cube is created at its position.
// The new cubes will be selected instead of the original nulls.
// get all selected null objects
if (selection == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
doc->GetActiveObjectsFilter(selection, true, Onull, NOTOK);
const Int32 cnt = selection->GetCount();
if (cnt == 0)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// clear object selection
doc->SetActiveObject(nullptr);
for (Int32 i = 0; i < cnt; ++i)
{
C4DAtom* element = selection->GetIndex(i);
const BaseObject* const nullobject = static_cast<BaseObject*>(element);
if (nullobject == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// create a cube
if (cube == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Matrix nullMg = nullobject->GetMg();
cube->SetMg(nullMg);
doc->InsertObject(cube, nullptr, nullptr);
}

Material selections can be managed separately, too:

// This example gets the material that is assigned to the given object.
// If a material is found, it will be selected.
// get texture tag
BaseTag* const tag = object->GetTag(Ttexture);
if (tag == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// get material
TextureTag* const ttag = static_cast<TextureTag*>(tag);
BaseMaterial* const material = ttag->GetMaterial();
// set active material
if (material != nullptr)

Finally tag selections can be managed:

// This example loops through all selected tags.
// If a tag is a Texture Tag, the given material is applied.
// get all selected tags
if (tags == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
doc->GetActiveTags(tags);
const Int32 cnt = tags->GetCount();
if (cnt == 0)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
for (Int32 i = 0; i < cnt; i++)
{
C4DAtom* const tag = tags->GetIndex(i);
if (tag == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// check if texture tag
if (tag->GetType() == Ttexture)
{
// set material
TextureTag* ttag = static_cast<TextureTag*>(tag);
ttag->SetMaterial(material);
}
}

RenderData

RenderData objects represent the render settings stored in a document. They allow access to the actual settings, multipass objects and post effects.

See also RenderData Manual.

// This example adds a new RenderData to the document and set this RenderData as the active one.
RenderData* const renderData = RenderData::Alloc();
if (renderData == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
renderData->SetName("Preview Render Settings"_s);
doc->InsertRenderDataLast(renderData);
doc->SetActiveRenderData(renderData);

Scene Hooks

Scene hooks are used to add additional data to the document or to influence the execution pipeline. These scene hooks are stored in the document:

// This example accesses the Dynamics scene hook to disable Dynamics globally.
// gets the dynamics scene hook
BaseSceneHook* const dynamicsHook = doc->FindSceneHook(180000100);
if (dynamicsHook == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
BaseContainer& bc = dynamicsHook->GetDataInstanceRef();
bc.SetBool(WORLD_ENABLED, false);

Layers

Layers are used to organize a document. A layer is represented by a LayerObject and these LayerObject objects are organized in a tree:

See also Layer Manual.

// 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());

Takes

Takes allow to handle multiple versions of a scene within the same document. The takes of a document are stored in a TakeData object:

// 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);

See Take System Overview

Changed Mode

The change status of a document indicates that the scene was changed after the last time it was saved. The status is displayed with a little star (*) in the application title bar.

// This example closes and frees the currently active document only if it is not "dirty".
if (activeDoc == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// check dirty state of the document
if (activeDoc->GetChanged() == false)
KillDocument(activeDoc);

Document Name and Path

A document is presented in the application using its filename. Because of this the name of the document cannot be obtained with BaseList2D::GetName() that returns a String and not a Filename.

// This example checks the suffix of the current document name.
const Filename docName = doc->GetDocumentName();
const String suffix = docName.GetSuffix();
// check if the suffix is defined
if (suffix.IsPopulated())
{
if (suffix == "c4d")
ApplicationOutput("Cinema 4D File"_s);
else
ApplicationOutput("Filetype: " + suffix);
}
else
{
ApplicationOutput("unsaved document"_s);
}

Level of Detail

The level of detail defines how detailed certain objects are displayed in the editor. This is typically used in custom ObjectData based generators.

// This example sets the LOD to the level set in the current render settings.
// check if the document uses render LOD in the editor
if (doc->GetRenderLod() == false)
{
RenderData* const renderData = doc->GetActiveRenderData();
if (renderData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const BaseContainer bc = renderData->GetDataInstanceRef();
const Float lod = bc.GetFloat(RDATA_LOD);
// set new LOD
doc->SetLOD(lod);
}
Note
The LOD buttons in the editor represent the values 25%, 50% and 100%.

Time

The current timeline position of a document and the timeline size is defined using BaseTime objects.

Note
Setting the current time will not animate the document. See paragraph Animate below.

Current time:

// This example jumps one second ahead and updates the document.
const BaseTime now = doc->GetTime();
const BaseTime target = now + BaseTime(1.0);
doc->SetTime(target);
// animate document
doc->ExecutePasses(nullptr, true, true, true, BUILDFLAGS::NONE);

Framerate:

Note
The framerate defined in the render settings is independent from the document framerate.
In the viewport, and for a render in the viewport, it will return the project's setting FrameRate.
Rendering elsewhere, it will return the RenderData FrameRate setting.
// This example synchronizes the document framerate with the render framerate.
RenderData* const renderData = doc->GetActiveRenderData();
if (renderData == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const BaseContainer bc = renderData->GetDataInstanceRef();
const Int32 fps = bc.GetInt32(RDATA_FRAMERATE);
doc->SetFps(fps);

Timeline dimensions:

Used Time:

Loop Preview:

// This example moves the timeline loop to the start of the timeline.
const BaseTime minTime = doc->GetMinTime();
// current loop duration
const BaseTime loopDuration = doc->GetLoopMaxTime() - doc->GetLoopMinTime();
// move loop to the start
doc->SetLoopMinTime(minTime);
doc->SetLoopMaxTime(minTime + loopDuration);

Mode

A document can be in different modes defining which elements should be edited (objects, points, edges, etc.).

// This example sets the document mode based on the currently active selection tag.
BaseTag* const tag = doc->GetActiveTag();
if (tag == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// check tag type
switch (tag->GetType())
{
case Tpointselection: doc->SetMode(Mpoints); break;
case Tpolygonselection: doc->SetMode(Mpolygons); break;
case Tedgeselection: doc->SetMode(Medges); break;
}

Active Tool

The currently active tool is stored in the document.

// This example switches the mode and enables and configures the "Knife" tool.
if (tool == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
Note
To edit the settings of the Move/Scale/Rotate tools the actual plugin instance has to be accessed with FindPlugin().

Axis and Plane

The helper axis represents the position of the handles used to move a multi-selection.

// This example creates a null object at the position of the helper axis.
// The currently selected objects (stored in "selection") are placed under that null object.
// check if model mode
if (doc->GetMode() != Mmodel)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
// get helper object and matrix
const BaseObject* const helperAxis = doc->GetHelperAxis();
if (helperAxis == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
const Matrix matrix = helperAxis->GetMg();
// create null object
BaseObject* const nullObject = BaseObject::Alloc(Onull);
if (nullObject == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
doc->InsertObject(nullObject, nullptr, nullptr);
nullObject->SetMg(matrix);
// make selected object child of the new null
for (Int32 i = 0; i < objectCnt; ++i)
{
C4DAtom* element = selection->GetIndex(i);
BaseObject* const baseObject = static_cast<BaseObject*>(element);
if (baseObject == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const Matrix position = baseObject->GetMg();
baseObject->Remove();
doc->InsertObject(baseObject, nullObject, nullptr);
baseObject->SetMg(position);
}

Editor Windows

An editor window is represented by a BaseDraw object. Such a BaseDraw object allows access to the currently used camera. The render view is the editor window used to define the camera that will be used while rendering the final image.

See also BaseView / BaseDraw Manual.

// This example accesses the active BaseDraw to get its camera.
// Then it moves the active object into the view of that camera.
BaseDraw* const baseDraw = doc->GetActiveBaseDraw();
if (baseDraw == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
BaseObject* const cameraObject = baseDraw->GetEditorCamera();
// move active object into the camera view
const Matrix cameraMatrix = cameraObject->GetMg();
Matrix targetPosition = activeObject->GetMg();
targetPosition.off = cameraMatrix.off + (900.0 * cameraMatrix.sqmat.v3);
activeObject->SetMg(targetPosition);

Net Context

If the document is currently handled inside a Team Render context can be checked using the net render context:

// This example checks if the current context is a Team Render context.
// If so, the error message will be printed just to the console, not displayed as a message box.
const BaseDocument* const doc = op->GetDocument();
if (context)
ApplicationOutput("Some Error occured!"_s);
else
MessageDialog("Some Error occured!"_s);

Functionality

Animate

Scene elements can be animated by setting keyframes with specific values at a specific time. The BaseDocument class offers functions to create such keyframes:

// This example creates automatically keys for the given object if "Auto Key" is enabled.
BaseObject* undoObject = static_cast<BaseObject*>(cubeObject->GetClone(COPYFLAGS::NONE, nullptr));
if (undoObject == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// edit the object
// create auto keys if "Auto Key" is enabled.
doc->AutoKey(undoObject, cubeObject, true, true, true, true, true, true);
BaseObject::Free(undoObject);

See also Animation Tracks.

To apply keyframe animation, expressions, generators and deformers the document has to be animated.

// This example executes the document at different frames
// and prints the position of the "Cube" object.
// save current frame
const BaseTime originalTime = doc->GetTime();
for (Int32 i = 0; i < 30; ++i)
{
BaseTime time(i, doc->GetFps());
doc->SetTime(time);
doc->ExecutePasses(nullptr, true, true, true, BUILDFLAGS::INTERNALRENDERER);
BaseObject* const cube = doc->SearchObject("Cube"_s);
if (cube)
{
const Vector position = cube->GetMg().off;
ApplicationOutput("Cube Position: " + String::VectorToString(position));
}
}
// reset frame
doc->SetTime(originalTime);

When a new keyframe is created a default template is used. This template can be edited:

// This example changes the default key of the document.
if (key == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
Bool overdub;
doc->GetDefaultKey(key, overdub);
// new keys should use linear interpolation
doc->SetDefaultKey(key, overdub);

The result of simulations is often iterative: The current frame depends on the results of previous calculations. To calculate the state of a particle simulation at a certain frame all frames before that have to be calculated:

// This example reads the emitter end time from the given particle object.
// The document time is set to this frame and SetRewind() is called to animate
// all frame before that frame.
GeData data;
// access PARTICLEOBJECT_STOP parameter
DescID particleStopID(PARTICLEOBJECT_STOP);
if (particleEmitter->GetParameter(particleStopID, data, DESCFLAGS_GET::NONE) == false)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
const BaseTime endTime = data.GetTime();
doc->SetTime(endTime);
doc->SetRewind();

Undo

The undo system of Cinema 4D allows to store operations in undo actions that can be executed to undo and redo user interaction.

See also Undo System Manual.

// This example creates a cube object and adds it to the document with an undo step.
if (cube == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
doc->StartUndo();
doc->InsertObject(cube, nullptr, nullptr);
doc->EndUndo();

Undo actions can be executed:

Pick Session

A pick session can be used to select multiple objects.

See PickSessionDataStruct.

Send Messages

Convert and Export

The objects of a BaseDocument can be converted to polygon objects and associated sounds and textures can be collected:

// This example prints the file paths of all textures of the given material selection.
const BaseContainer textures = doc->GetAllTextures(materials);
BrowseContainer browse(&textures);
Int32 id;
GeData* data;
// loop through elements of the BaseContainer
while (browse.GetNext(&id, &data))
{
// check if the found element is a Filename
if (data != nullptr)
{
if (data->GetType() == DA_FILENAME)
ApplicationOutput("Texture: " + data->GetFilename().GetString());
}
}
  • IsolateObjects(): Creates a new document that contains only copies of the given objects and their materials.
// This example creates a new BaseDocument containing the objects from the given selection.
// The new document is added to the document list and set as the active document.
BaseDocument* const newDoc = IsolateObjects(doc, selection);
if (newDoc == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
newDoc->SetDocumentName("isolated_objects.c4d");

Disc I/O

A BaseDocument can be created by reading if from a file on disc. It is possible to load *.c4d files and supported import file formats.

The list of recently opened scene files is accessed with:

// This example loads the given c4d file and prints its min. and max. frame to the console.
// check if the Filename references a "c4d" file
if (filename.CheckSuffix("c4d"_s))
{
BaseDocument* loadedDoc = LoadDocument(filename, SCENEFILTER::NONE, nullptr);
if (loadedDoc == nullptr)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(filename, MAXONCONVERTMODE::NONE), "Could not load document."_s);
const Int32 fps = loadedDoc->GetFps();
const Int32 startFrame = loadedDoc->GetMinTime().GetFrame(fps);
const Int32 endFrame = loadedDoc->GetMaxTime().GetFrame(fps);
BaseDocument::Free(loadedDoc);
// convert to String to print the data to the console
const String fileStr = filename.GetString();
const String startFrameStr = String::IntToString(startFrame);
const String endFrameStr = String::IntToString(endFrame);
// print to console
ApplicationOutput("Document " + fileStr + ": " + startFrameStr + " - " + endFrameStr);
}
  • SaveDocument(): Saves the document to a Cinema 4D file or to a supported export file format.
  • SaveProject(): Saves the document like the "Save Project with Assets" command.
// This example creates a new BaseDocument, adds an cube to it to save it to file.
if (tempDoc == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
if (cube == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
tempDoc->InsertObject(cube, nullptr, nullptr);
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(savepath, MAXONCONVERTMODE::NONE), "Could not save document."_s);

Render

A BaseDocument can be rendered independently from the GUI and the Picture Viewer into a BaseBitmap (see BaseBitmap Manual).

// This example loads the given c4d file.
// One frame of the loaded document is rendered and displayed in the Picture Viewer.
BaseDocument* const loadedDoc = LoadDocument(filename, flags, nullptr);
if (loadedDoc == nullptr)
return maxon::IoError(MAXON_SOURCE_LOCATION, MaxonConvert(filename, MAXONCONVERTMODE::NONE), "Could not load document."_s);
// auto free the loaded document
docFree.Assign(loadedDoc);
RenderData* const rdata = loadedDoc->GetActiveRenderData();
if (rdata == nullptr)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
BaseContainer renderSettings = rdata->GetData();
// just render one frame
const BaseTime startFrame = renderSettings.GetTime(RDATA_FRAMEFROM, BaseTime());
renderSettings.SetTime(RDATA_FRAMETO, startFrame);
// prepare target bitmap
if (bitmap == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
const Int32 width = renderSettings.GetInt32(RDATA_XRES);
const Int32 height = renderSettings.GetInt32(RDATA_YRES);
const IMAGERESULT imageRes = bitmap->Init(width, height);
if (imageRes != IMAGERESULT::OK)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// render the image
const RENDERRESULT res = RenderDocument(loadedDoc, renderSettings,
nullptr, nullptr, bitmap, renderFlags, nullptr);
if (res != RENDERRESULT::OK)
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
// show result
ShowBitmap(bitmap);

Messages

On certain events (load, save, render,...) a MSG_DOCUMENTINFO message is sent to elements contained in a document.

// This example catches MSG_DOCUMENTINFO in a ObjectData::Message() function.
// When the document is loaded the value of a old (legacy) parameter is copied
// into a new parameter.
{
DocumentInfoData* const msg = static_cast<DocumentInfoData*>(data);
if (msg == nullptr)
return false;
// switch message sub-type
switch (msg->type)
{
{
BaseObject* const op = static_cast<BaseObject*>(node);
if (!op)
return false;
bc.SetInt32(NEW_PARAMETER, bc.GetInt32(OLD_PARAMETER));
ApplicationOutput("document is loaded"_s);
break;
}
}
break;
}

Futher document related messages:

Further Reading

ID_MODELING_KNIFE_LINE
#define ID_MODELING_KNIFE_LINE
Definition: modelingids.h:42
Ostage
#define Ostage
Stage.
Definition: ge_prepass.h:1013
Medges
@ Medges
Edge edit mode.
Definition: c4d_basedocument.h:1716
DocumentInfoData
Message struct for the MSG_DOCUMENTINFO message.
Definition: c4d_baselist.h:1002
BaseList2D::GetData
BaseContainer GetData()
Definition: c4d_baselist.h:2296
RDATA_FRAMETO
@ RDATA_FRAMETO
Definition: drendersettings.h:165
PARTICLEOBJECT_STOP
@ PARTICLEOBJECT_STOP
Definition: oparticle.h:29
DOCUMENT_USEGENERATORS
@ DOCUMENT_USEGENERATORS
Definition: ddoc.h:24
IMAGERESULT::OK
@ OK
Image loaded/created.
BaseDocument::GetActiveObjectsFilter
void GetActiveObjectsFilter(AtomArray &selection, Bool children, Int32 type, Int32 instanceof) const
Tpointselection
#define Tpointselection
Point selection - SelectionTag.
Definition: ge_prepass.h:1255
BaseDocument::SetData
void SetData(DOCUMENTSETTINGS type, const BaseContainer &bc)
BaseList2D
Definition: c4d_baselist.h:2174
MessageDialog
void MessageDialog(const maxon::String &str)
GetActiveDocument
BaseDocument * GetActiveDocument(void)
BaseContainer::SetTime
void SetTime(Int32 id, const BaseTime &b)
Definition: c4d_basecontainer.h:590
BaseDocument::InsertObject
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
DOCUMENTSETTINGS::DOCUMENT
@ DOCUMENT
Document settings.
BaseDocument::SearchObject
BaseObject * SearchObject(const maxon::String &str)
LayerObject
Definition: c4d_basedocument.h:245
BaseTime
Definition: c4d_basetime.h:24
RENDERRESULT
RENDERRESULT
Definition: ge_prepass.h:412
maxon::SqrMat3::v3
V v3
The Z axis.
Definition: matrix.h:31
BaseDocument::GetFps
Int32 GetFps(void) const
AutoFree::Assign
void Assign(TYPE *p)
Definition: ge_autoptr.h:225
SCENEFILTER
SCENEFILTER
Definition: ge_prepass.h:290
C4DAtom::GetClone
C4DAtom * GetClone(COPYFLAGS flags, AliasTrans *trn)
Definition: c4d_baselist.h:1447
BaseObject
Definition: c4d_baseobject.h:224
TextureTag
Definition: c4d_basetag.h:646
BaseDocument::SetFps
void SetFps(Int32 fps)
maxon::Mat3< maxon::Vector64 >
PRIM_CUBE_SUBZ
@ PRIM_CUBE_SUBZ
Definition: ocube.h:10
DescID
Definition: lib_description.h:328
Filename::GetSuffix
String GetSuffix(void) const
GeData::GetType
Int32 GetType(void) const
Definition: c4d_gedata.h:407
BaseContainer::SetInt32
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:505
BaseTake
Definition: lib_takesystem.h:319
BaseDocument::SearchMaterial
BaseMaterial * SearchMaterial(const maxon::String &str)
BaseContainer::SetString
void SetString(Int32 id, const maxon::String &s)
Definition: c4d_basecontainer.h:569
SetActiveDocument
void SetActiveDocument(BaseDocument *doc)
MDATA_KNIFELINE_ANGLE_CONSTRAINT
@ MDATA_KNIFELINE_ANGLE_CONSTRAINT
Definition: toolknifeline.h:16
BaseDocument::SetAction
void SetAction(Int32 a)
Float
maxon::Float Float
Definition: ge_sys_math.h:66
BaseDocument::SetRewind
void SetRewind(Int32 flags=0)
GeListHead::GetFirst
GeListNode * GetFirst()
Definition: c4d_baselist.h:2067
BaseDocument::AddUndo
Bool AddUndo(UNDOTYPE type, void *data, Bool allowFromThread=false)
Onull
#define Onull
Null.
Definition: ge_prepass.h:1015
BaseDocument::SetActiveMaterial
void SetActiveMaterial(BaseMaterial *mat, Int32 mode=0)
Mpolygons
@ Mpolygons
Polygon edit mode.
Definition: c4d_basedocument.h:1717
BaseDocument::SetLOD
void SetLOD(Float lod)
BaseObject::SetMg
void SetMg(const Matrix &m)
Definition: c4d_baseobject.h:488
BaseDocument::SetDefaultKey
void SetDefaultKey(CKey *pKey, Bool bOverdub)
RenderDocument
RENDERRESULT RenderDocument(BaseDocument *doc, const BaseContainer &rdata, ProgressHook *prog, void *private_data, BaseBitmap *bmp, RENDERFLAGS renderflags, BaseThread *th, WriteProgressHook *wprog=nullptr, void *data=nullptr)
BaseDocument::Alloc
static BaseDocument * Alloc(void)
SCENEFILTER::NONE
@ NONE
None.
BaseDocument::SetTime
void SetTime(const BaseTime &t)
BUILDFLAGS::NONE
@ NONE
None.
SaveDocument
Bool SaveDocument(BaseDocument *doc, const Filename &name, SAVEDOCUMENTFLAGS saveflags, Int32 format)
RENDERFLAGS
RENDERFLAGS
Definition: ge_prepass.h:4457
BaseObject::GetMg
Matrix GetMg() const
Definition: c4d_baseobject.h:482
BaseTag
Definition: c4d_basetag.h:46
Filename
Manages file and path names.
Definition: c4d_file.h:93
MSG_DOCUMENTINFO
#define MSG_DOCUMENTINFO
Sent as broadcast message by the document when it is loaded, saved , merged etc. The corresponding da...
Definition: c4d_baselist.h:445
maxon::OK
return OK
Definition: apibase.h:2546
BaseList2D::GetMarker
const GeMarker & GetMarker() const
Definition: c4d_baselist.h:2395
TakeData::AddTake
BaseTake * AddTake(const String &name, BaseTake *parent, BaseTake *cloneFrom)
AutoFree
Definition: ge_autoptr.h:151
BaseDocument::GetSelection
void GetSelection(AtomArray &selection) const
LoadDocument
BaseDocument * LoadDocument(const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr)
Mpoints
@ Mpoints
Point edit mode.
Definition: c4d_basedocument.h:1715
BaseTime::GetFrame
Int32 GetFrame(Float fps) const
Definition: c4d_basetime.h:107
AtomArray::GetCount
Int32 GetCount() const
Definition: c4d_baselist.h:1649
maxon::String::IsPopulated
Bool IsPopulated() const
Definition: string.h:1412
MAXONCONVERTMODE::NONE
@ NONE
No check if file exists under case-sensitive drives.
Ocube
#define Ocube
Cube.
Definition: ge_prepass.h:1047
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
BaseContainer::GetFloat
Float GetFloat(Int32 id, Float preset=0.0) const
Definition: c4d_basecontainer.h:335
BaseDocument::ExecutePasses
Bool ExecutePasses(BaseThread *bt, Bool animation, Bool expressions, Bool caches, BUILDFLAGS flags)
BaseDocument::SetActiveRenderData
void SetActiveRenderData(RenderData *rd)
BaseDocument::GetActiveTag
BaseTag * GetActiveTag(void)
BaseContainer::SetBool
void SetBool(Int32 id, Bool b)
Definition: c4d_basecontainer.h:498
CKey::SetInterpolation
void SetInterpolation(CCurve *seq, CINTERPOLATION inter)
Definition: c4d_canimation.h:214
DESCFLAGS_SET::NONE
@ NONE
None.
BaseBitmap::Init
static IMAGERESULT Init(BaseBitmap *&res, const Filename &name, Int32 frame=-1, Bool *ismovie=nullptr, BitmapLoaderPlugin **loaderplugin=nullptr, const maxon::Delegate< void(Float progress)> &progressCallback=nullptr)
KillDocument
void KillDocument(BaseDocument *&doc)
BaseDocument::GetLayerObjectRoot
GeListHead * GetLayerObjectRoot(void)
BaseDocument::GetActiveBaseDraw
BaseDraw * GetActiveBaseDraw(void)
BaseDraw
Definition: c4d_basedraw.h:747
TakeData
Definition: lib_takesystem.h:573
BaseDocument::GetRenderLod
Bool GetRenderLod(void)
DOCUMENT_INFO_AUTHOR
@ DOCUMENT_INFO_AUTHOR
Definition: ddoc.h:46
GeData::GetTime
const BaseTime & GetTime(void) const
Definition: c4d_gedata.h:481
BaseDocument::GetHighest
BaseObject * GetHighest(Int32 type, Bool editor)
BaseDocument::SetActiveObject
void SetActiveObject(BaseObject *op, Int32 mode=0)
MaxonConvert
maxon::Url MaxonConvert(const Filename &fn, MAXONCONVERTMODE convertMode)
GetFirstDocument
BaseDocument * GetFirstDocument(void)
Filename::GetString
String GetString(void) const
PRIM_CUBE_SUBY
@ PRIM_CUBE_SUBY
Definition: ocube.h:9
RenderData::Alloc
static RenderData * Alloc(void)
BaseDocument::GetHelperAxis
BaseObject * GetHelperAxis(void)
BaseContainer::GetTime
BaseTime GetTime(Int32 id, const BaseTime &preset=BaseTime()) const
Definition: c4d_basecontainer.h:411
GeMarker::IsEqual
Bool IsEqual(const GeMarker &m) const
Definition: c4d_baselist.h:1317
BaseDocument::SetLoopMaxTime
void SetLoopMaxTime(const BaseTime &t)
String
Definition: c4d_string.h:38
BaseDocument::InsertMaterial
void InsertMaterial(BaseMaterial *mat, BaseMaterial *pred=nullptr, Bool checknames=false)
GeMarker
A unique marker that identifies an object.
Definition: c4d_baselist.h:1286
String::IntToString
static String IntToString(Int32 v)
Definition: c4d_string.h:495
RENDERRESULT::OK
@ OK
Function was successful.
SCENEFILTER::OBJECTS
@ OBJECTS
Load/save objects.
TextureTag::SetMaterial
void SetMaterial(BaseMaterial *mat)
C4DAtom::SetParameter
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
BaseDocument::GetActiveTags
void GetActiveTags(AtomArray &selection) const
maxon::Vec3< maxon::Float64, 1 >
BaseDocument::SetMode
void SetMode(Int32 m)
BaseDocument::GetTime
BaseTime GetTime(void) const
BaseList2D::GetDataInstanceRef
const BaseContainer & GetDataInstanceRef() const
Definition: c4d_baselist.h:2329
BaseDocument::GetDocPreviewBitmap
BaseBitmap * GetDocPreviewBitmap()
maxon::Mat3::sqmat
SqrMat3< V > sqmat
The 3×3 matrix for rotation, scale and shear.
Definition: matrix.h:282
TakeData::SetCurrentTake
Bool SetCurrentTake(BaseTake *take)
FORMAT_C4DEXPORT
#define FORMAT_C4DEXPORT
Cinema&#160;4D export.
Definition: ge_prepass.h:3310
BaseDocument::GetTakeData
TakeData * GetTakeData()
InsertBaseDocument
void InsertBaseDocument(BaseDocument *doc)
TextureTag::GetMaterial
BaseMaterial * GetMaterial(Bool ignoredoc=false)
BaseDocument::GetMinTime
BaseTime GetMinTime(void)
BaseDocument::GetLoopMinTime
BaseTime GetLoopMinTime(void)
BaseSceneHook
Definition: c4d_basedocument.h:43
NOTOK
#define NOTOK
Definition: ge_sys_math.h:267
Tbaselist2d
#define Tbaselist2d
2D list.
Definition: ge_prepass.h:943
GetToolData
BaseContainer * GetToolData(BaseDocument *doc, Int32 pluginid)
BaseDraw::GetEditorCamera
BaseObject * GetEditorCamera(void)
Definition: c4d_basedraw.h:868
BaseDocument::SetLoopMinTime
void SetLoopMinTime(const BaseTime &t)
BaseDocument::GetChanged
Bool GetChanged(void)
RDATA_LOD
@ RDATA_LOD
Definition: drendersettings.h:63
GeData
Definition: c4d_gedata.h:82
C4DAtom
Definition: c4d_baselist.h:1361
GeData::GetFilename
const Filename & GetFilename(void) const
Definition: c4d_gedata.h:475
BaseList2D::SetName
void SetName(const maxon::String &name)
Definition: c4d_baselist.h:2354
BaseDocument::StartUndo
Bool StartUndo(void)
Int32
maxon::Int32 Int32
Definition: ge_sys_math.h:60
GeListNode::GetDocument
BaseDocument * GetDocument()
Definition: c4d_baselist.h:1945
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:208
GeListNode::Remove
void Remove()
Definition: c4d_baselist.h:1884
BaseDocument::GetDefaultKey
Bool GetDefaultKey(CKey *pKey, Bool &bOverdub) const
ShowBitmap
Bool ShowBitmap(const Filename &fn)
WORLD_ENABLED
@ WORLD_ENABLED
Definition: dynworldobject.h:6
NetRenderDocumentContext
Definition: lib_net.h:828
BaseDocument::Free
static void Free(BaseDocument *&bl)
BaseContainer::GetBool
Bool GetBool(Int32 id, Bool preset=false) const
Definition: c4d_basecontainer.h:295
BaseContainer::SetFloat
void SetFloat(Int32 id, Float r)
Definition: c4d_basecontainer.h:533
BaseDocument::FindSceneHook
BaseSceneHook * FindSceneHook(Int32 id) const
Definition: c4d_basedocument.h:1234
Mmodel
@ Mmodel
Model mode.
Definition: c4d_basedocument.h:1720
Ttexture
#define Ttexture
Texture - TextureTag.
Definition: ge_prepass.h:1243
SELECTION_ADD
#define SELECTION_ADD
Adds to the current selection.
Definition: c4d_basedocument.h:383
BaseDocument::GetNetRenderDocumentContext
NetRenderDocumentContext * GetNetRenderDocumentContext() const
BaseDocument::EndUndo
Bool EndUndo(void)
DA_FILENAME
@ DA_FILENAME
Filename.
Definition: c4d_gedata.h:48
RDATA_FRAMERATE
@ RDATA_FRAMERATE
Definition: drendersettings.h:171
BaseDocument::SetDocumentName
void SetDocumentName(const Filename &fn)
PRIM_CUBE_SUBX
@ PRIM_CUBE_SUBX
Definition: ocube.h:8
BaseDocument::InsertRenderDataLast
void InsertRenderDataLast(RenderData *rd)
CINTERPOLATION::LINEAR
@ LINEAR
Linear.
SAVEDOCUMENTFLAGS::DONTADDTORECENTLIST
@ DONTADDTORECENTLIST
Do not add the saved document to the recent file list.
Mmaterial
#define Mmaterial
Standard material.
Definition: ge_prepass.h:955
BaseDocument::GetActiveRenderData
RenderData * GetActiveRenderData(void)
BaseMaterial::Alloc
static BaseMaterial * Alloc(Int32 type)
BaseObject::Alloc
static BaseObject * Alloc(Int32 type)
BaseDocument::GetLoopMaxTime
BaseTime GetLoopMaxTime(void)
BaseBitmap
Definition: c4d_basebitmap.h:413
EventAdd
void EventAdd(EVENT eventflag=EVENT::NONE)
BUILDFLAGS::INTERNALRENDERER
@ INTERNALRENDERER
Rendering in the editor.
maxon::Mat3::off
V off
The translation vector.
Definition: matrix.h:279
AutoAlloc
Definition: ge_autoptr.h:36
DESCFLAGS_GET::NONE
@ NONE
None.
Tedgeselection
#define Tedgeselection
Edge selection - SelectionTag. The edges are encodes like this: (4*poly)+edge, where edge goes from 0...
Definition: ge_prepass.h:1272
BaseObject::Free
static void Free(BaseObject *&bl)
RDATA_YRES
@ RDATA_YRES
Definition: drendersettings.h:153
IsolateObjects
BaseDocument * IsolateObjects(BaseDocument *doc, const AtomArray &t_objects)
UNDOTYPE::NEWOBJ
@ NEWOBJ
New object/material/tag etc. was created. (Needs to be called after action.)
RenderData
Definition: c4d_basedocument.h:136
Tpolygonselection
#define Tpolygonselection
Polygon selection - SelectionTag.
Definition: ge_prepass.h:1254
Bool
maxon::Bool Bool
Definition: ge_sys_math.h:55
MSG_DOCUMENTINFO_TYPE_LOAD
#define MSG_DOCUMENTINFO_TYPE_LOAD
Document was loaded.
Definition: c4d_baselist.h:457
BrowseContainer
Definition: c4d_gedata.h:673
C4DAtom::IsInstanceOf
Bool IsInstanceOf(Int32 id) const
Definition: c4d_baselist.h:1403
RDATA_XRES
@ RDATA_XRES
Definition: drendersettings.h:152
BaseList2D::GetName
String GetName() const
Definition: c4d_baselist.h:2348
IMAGERESULT
IMAGERESULT
Definition: ge_prepass.h:3691
BaseDocument::GetData
BaseContainer GetData(DOCUMENTSETTINGS type)
String::VectorToString
static String VectorToString(const Vector32 &v, Int32 nnk=-1)
Definition: c4d_string.h:571
BaseDocument::AutoKey
void AutoKey(BaseList2D *undo, BaseList2D *op, Bool recursive, Bool pos, Bool scale, Bool rot, Bool param, Bool pla)
Definition: c4d_basedocument.h:1093
C4DAtom::GetType
Int32 GetType() const
Definition: c4d_baselist.h:1378
BaseMaterial
Definition: c4d_basematerial.h:27
BaseContainer::GetInt32
Int32 GetInt32(Int32 id, Int32 preset=0) const
Definition: c4d_basecontainer.h:303
BaseDocument::GetSettingsInstance
BaseContainer * GetSettingsInstance(Int32 type)
BaseDocument::GetDocumentName
Filename GetDocumentName(void)
BaseDocument::GetMode
Int32 GetMode(void) const
BaseDocument::GetNext
BaseDocument * GetNext(void)
Definition: c4d_basedocument.h:527
DOCUMENTSETTINGS::GENERAL
@ GENERAL
General settings.
GeListHead
Definition: c4d_baselist.h:2010
BaseDocument
Definition: c4d_basedocument.h:490
DocumentInfoData::type
Int32 type
The message type: MSG_DOCUMENTINFO_TYPE.
Definition: c4d_baselist.h:1009
BaseDocument::GetAllTextures
BaseContainer GetAllTextures(const AtomArray *ar)
BaseDocument::GetMaxTime
BaseTime GetMaxTime(void)
COPYFLAGS::NONE
@ NONE
None.
BaseContainer
Definition: c4d_basecontainer.h:46
SELECTION_NEW
#define SELECTION_NEW
Starts a new selection.
Definition: c4d_basedocument.h:382
BaseList2D::GetTypeName
String GetTypeName()
RDATA_FRAMEFROM
@ RDATA_FRAMEFROM
Definition: drendersettings.h:164
SCENEFILTER::MATERIALS
@ MATERIALS
Load/save materials.
AtomArray::GetIndex
C4DAtom * GetIndex(Int32 idx) const
Definition: c4d_baselist.h:1664
RENDERFLAGS::NODOCUMENTCLONE
@ NODOCUMENTCLONE
Set to avoid an automatic clone of the scene sent to RenderDocument().