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
.
if (virtualDoc == nullptr )
if (cube == nullptr )
if (bitmap == nullptr )
const Int32 width = 1280;
const Int32 height = 720;
if (rdata == nullptr )
nullptr , nullptr , bitmap, flags, nullptr );
Access
Cinema 4D can handle multiple open scenes in a document list:
To navigate the document list GetNext() and GetPred() can be used:
if (activeDocument == nullptr )
while (document != nullptr )
{
if (docMarker.
IsEqual (activeDocMarker))
{
}
else
{
}
}
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:
if (newDocument == nullptr )
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() :
if (cloneDocument == nullptr )
Preview Image
When a scene is saved the current editor image is saved with the BaseDocument to create a thumbnail preview image.
if (bitmap != nullptr )
{
}
Properties
Data
Multiple settings are stored inside the BaseDocument . The different types of settings are defined in DOCUMENTSETTINGS , the parameter IDs in ddoc.h
.
and
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 .
if (object != nullptr )
{
}
if (cubeObject == 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.
if (stageObject == nullptr )
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
if (material)
{
}
if (greenMaterial == nullptr )
Selections
Inside a scene multiple objects, materials or tags can be selected.
if (selection == nullptr )
if (cnt == 0)
for (
Int32 i = 0; i < cnt; ++i)
{
const Bool validElement = element !=
nullptr ;
{
}
else
{
}
}
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.
if (selection == nullptr )
if (cnt == 0)
for (
Int32 i = 0; i < cnt; ++i)
{
if (nullobject == nullptr )
if (cube == nullptr )
}
Material selections can be managed separately, too:
if (tag == nullptr )
if (material != nullptr )
Finally tag selections can be managed:
if (tags == nullptr )
if (cnt == 0)
for (
Int32 i = 0; i < cnt; i++)
{
if (tag == nullptr )
{
}
}
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 .
if (renderData == nullptr )
renderData->
SetName (
"Preview Render Settings" _s);
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:
if (dynamicsHook == nullptr )
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 .
if (layers == nullptr )
if (layer != nullptr )
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:
if (takeData == nullptr )
BaseTake *
const newTake = takeData->
AddTake (
"This is a new take" ,
nullptr ,
nullptr );
if (newTake == nullptr )
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.
if (activeDoc == nullptr )
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 .
{
if (suffix == "c4d" )
else
}
else
{
}
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.
{
if (renderData == nullptr )
}
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:
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.
if (renderData == nullptr )
Timeline dimensions:
Used Time:
Loop Preview:
Mode
A document can be in different modes defining which elements should be edited (objects, points, edges, etc.).
Active Tool
The currently active tool is stored in the document.
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.
if (helperAxis == nullptr )
if (nullObject == nullptr )
nullObject->
SetMg (matrix);
for (
Int32 i = 0; i < objectCnt; ++i)
{
if (baseObject == 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 .
if (baseDraw == nullptr )
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:
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:
if (undoObject == nullptr )
doc->
AutoKey (undoObject, cubeObject,
true ,
true ,
true ,
true ,
true ,
true );
See also Animation Tracks .
To apply keyframe animation, expressions, generators and deformers the document has to be animated.
for (
Int32 i = 0; i < 30; ++i)
{
if (cube)
{
}
}
When a new keyframe is created a default template is used. This template can be edited:
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:
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 .
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:
while (browse.GetNext(&id , &data))
{
if (data != nullptr )
{
}
}
IsolateObjects() : Creates a new document that contains only copies of the given objects and their materials.
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:
if (filename.CheckSuffix("c4d" _s))
{
if (loadedDoc == nullptr )
const String fileStr = filename.GetString();
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.
if (tempDoc == nullptr )
if (cube == nullptr )
Render
A BaseDocument can be rendered independently from the GUI and the Picture Viewer into a BaseBitmap (see BaseBitmap Manual ).
if (loadedDoc == nullptr )
if (rdata == nullptr )
if (bitmap == nullptr )
nullptr , nullptr , bitmap, renderFlags, nullptr );
Messages
On certain events (load, save, render,...) a MSG_DOCUMENTINFO message is sent to elements contained in a document.
{
if (msg == nullptr )
return false ;
{
{
if (!op)
return false ;
break ;
}
}
break ;
}
Futher document related messages:
Further Reading
#define Ostage
Stage.
Definition: ge_prepass.h:1007
@ Medges
Edge edit mode.
Definition: c4d_basedocument.h:1703
Message struct for the MSG_DOCUMENTINFO message.
Definition: c4d_baselist.h:986
BaseContainer GetData()
Definition: c4d_baselist.h:2266
@ PRIM_CUBE_SUBY
Definition: ocube.h:9
@ OK
Image loaded/created.
void GetActiveObjectsFilter(AtomArray &selection, Bool children, Int32 type, Int32 instanceof) const
#define Tpointselection
Point selection - SelectionTag.
Definition: ge_prepass.h:1248
void SetData(DOCUMENTSETTINGS type, const BaseContainer &bc)
Definition: c4d_baselist.h:2144
void MessageDialog(const maxon::String &str)
BaseDocument * GetActiveDocument(void)
@ PARTICLEOBJECT_STOP
Definition: oparticle.h:29
void SetTime(Int32 id, const BaseTime &b)
Definition: c4d_basecontainer.h:590
void InsertObject(BaseObject *op, BaseObject *parent, BaseObject *pred, Bool checknames=false)
@ DOCUMENT
Document settings.
BaseObject * SearchObject(const maxon::String &str)
@ RDATA_YRES
Definition: drendersettings.h:153
Definition: c4d_basedocument.h:245
Definition: c4d_basetime.h:24
RENDERRESULT
Definition: ge_prepass.h:409
V v3
The Z axis.
Definition: matrix.h:31
void Assign(TYPE *p)
Definition: ge_autoptr.h:225
SCENEFILTER
Definition: ge_prepass.h:287
@ PRIM_CUBE_SUBX
Definition: ocube.h:8
C4DAtom * GetClone(COPYFLAGS flags, AliasTrans *trn)
Definition: c4d_baselist.h:1417
Definition: c4d_baseobject.h:224
Definition: c4d_basetag.h:646
Definition: lib_description.h:327
String GetSuffix(void) const
Int32 GetType(void) const
Definition: c4d_gedata.h:407
void SetInt32(Int32 id, Int32 l)
Definition: c4d_basecontainer.h:505
Definition: lib_takesystem.h:319
BaseMaterial * SearchMaterial(const maxon::String &str)
void SetString(Int32 id, const maxon::String &s)
Definition: c4d_basecontainer.h:569
void SetActiveDocument(BaseDocument *doc)
@ RDATA_FRAMETO
Definition: drendersettings.h:165
maxon::Float Float
Definition: ge_sys_math.h:64
@ RDATA_FRAMERATE
Definition: drendersettings.h:171
void SetRewind(Int32 flags=0)
GeListNode * GetFirst()
Definition: c4d_baselist.h:2037
Bool AddUndo(UNDOTYPE type, void *data, Bool allowFromThread=false)
#define Onull
Null.
Definition: ge_prepass.h:1009
void SetActiveMaterial(BaseMaterial *mat, Int32 mode=0)
@ Mpolygons
Polygon edit mode.
Definition: c4d_basedocument.h:1704
void SetMg(const Matrix &m)
Definition: c4d_baseobject.h:488
void SetDefaultKey(CKey *pKey, Bool bOverdub)
RENDERRESULT RenderDocument(BaseDocument *doc, const BaseContainer &rdata, ProgressHook *prog, void *private_data, BaseBitmap *bmp, RENDERFLAGS renderflags, BaseThread *th, WriteProgressHook *wprog=nullptr, void *data=nullptr)
static BaseDocument * Alloc(void)
void SetTime(const BaseTime &t)
Bool SaveDocument(BaseDocument *doc, const Filename &name, SAVEDOCUMENTFLAGS saveflags, Int32 format)
RENDERFLAGS
Definition: ge_prepass.h:4423
Matrix GetMg() const
Definition: c4d_baseobject.h:482
Definition: c4d_basetag.h:46
Manages file and path names.
Definition: c4d_file.h:93
#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
return OK
Definition: apibase.h:2532
const GeMarker & GetMarker() const
Definition: c4d_baselist.h:2365
BaseTake * AddTake(const String &name, BaseTake *parent, BaseTake *cloneFrom)
Definition: ge_autoptr.h:151
void GetSelection(AtomArray &selection) const
BaseDocument * LoadDocument(const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr)
@ Mpoints
Point edit mode.
Definition: c4d_basedocument.h:1702
Int32 GetFrame(Float fps) const
Definition: c4d_basetime.h:107
Int32 GetCount() const
Definition: c4d_baselist.h:1619
Bool IsPopulated() const
Definition: string.h:1396
@ NONE
No check if file exists under case-sensitive drives.
#define Ocube
Cube.
Definition: ge_prepass.h:1040
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
Float GetFloat(Int32 id, Float preset=0.0) const
Definition: c4d_basecontainer.h:335
Bool ExecutePasses(BaseThread *bt, Bool animation, Bool expressions, Bool caches, BUILDFLAGS flags)
void SetActiveRenderData(RenderData *rd)
BaseTag * GetActiveTag(void)
void SetBool(Int32 id, Bool b)
Definition: c4d_basecontainer.h:498
void SetInterpolation(CCurve *seq, CINTERPOLATION inter)
Definition: c4d_canimation.h:214
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)
void KillDocument(BaseDocument *&doc)
GeListHead * GetLayerObjectRoot(void)
BaseDraw * GetActiveBaseDraw(void)
Definition: c4d_basedraw.h:747
Definition: lib_takesystem.h:573
const BaseTime & GetTime(void) const
Definition: c4d_gedata.h:481
BaseObject * GetHighest(Int32 type, Bool editor)
void SetActiveObject(BaseObject *op, Int32 mode=0)
maxon::Url MaxonConvert(const Filename &fn, MAXONCONVERTMODE convertMode)
BaseDocument * GetFirstDocument(void)
String GetString(void) const
static RenderData * Alloc(void)
BaseObject * GetHelperAxis(void)
BaseTime GetTime(Int32 id, const BaseTime &preset=BaseTime()) const
Definition: c4d_basecontainer.h:411
Bool IsEqual(const GeMarker &m) const
Definition: c4d_baselist.h:1287
void SetLoopMaxTime(const BaseTime &t)
Definition: c4d_string.h:38
void InsertMaterial(BaseMaterial *mat, BaseMaterial *pred=nullptr, Bool checknames=false)
A unique marker that identifies an object.
Definition: c4d_baselist.h:1256
static String IntToString(Int32 v)
Definition: c4d_string.h:495
@ OK
Function was successful.
@ OBJECTS
Load/save objects.
void SetMaterial(BaseMaterial *mat)
Bool SetParameter(const DescID &id, const GeData &t_data, DESCFLAGS_SET flags)
void GetActiveTags(AtomArray &selection) const
BaseTime GetTime(void) const
const BaseContainer & GetDataInstanceRef() const
Definition: c4d_baselist.h:2299
BaseBitmap * GetDocPreviewBitmap()
SqrMat3< V > sqmat
The 3×3 matrix for rotation, scale and shear.
Definition: matrix.h:282
Bool SetCurrentTake(BaseTake *take)
#define FORMAT_C4DEXPORT
Cinema 4D export.
Definition: ge_prepass.h:3280
void InsertBaseDocument(BaseDocument *doc)
BaseMaterial * GetMaterial(Bool ignoredoc=false)
BaseTime GetMinTime(void)
BaseTime GetLoopMinTime(void)
@ RDATA_XRES
Definition: drendersettings.h:152
Definition: c4d_basedocument.h:43
#define NOTOK
Definition: ge_sys_math.h:265
#define Tbaselist2d
2D list.
Definition: ge_prepass.h:938
BaseObject * GetEditorCamera(void)
Definition: c4d_basedraw.h:868
void SetLoopMinTime(const BaseTime &t)
Definition: c4d_gedata.h:82
@ DOCUMENT_INFO_AUTHOR
Definition: ddoc.h:46
Definition: c4d_baselist.h:1331
const Filename & GetFilename(void) const
Definition: c4d_gedata.h:475
void SetName(const maxon::String &name)
Definition: c4d_baselist.h:2324
maxon::Int32 Int32
Definition: ge_sys_math.h:58
@ RDATA_LOD
Definition: drendersettings.h:63
BaseDocument * GetDocument()
Definition: c4d_baselist.h:1915
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:207
void Remove()
Definition: c4d_baselist.h:1854
Bool GetDefaultKey(CKey *pKey, Bool &bOverdub) const
Bool ShowBitmap(const Filename &fn)
@ WORLD_ENABLED
Definition: dynworldobject.h:6
Definition: lib_net.h:828
static void Free(BaseDocument *&bl)
Bool GetBool(Int32 id, Bool preset=false) const
Definition: c4d_basecontainer.h:295
void SetFloat(Int32 id, Float r)
Definition: c4d_basecontainer.h:533
BaseSceneHook * FindSceneHook(Int32 id) const
Definition: c4d_basedocument.h:1234
@ Mmodel
Model mode.
Definition: c4d_basedocument.h:1707
#define Ttexture
Texture - TextureTag.
Definition: ge_prepass.h:1236
#define SELECTION_ADD
Adds to the current selection.
Definition: c4d_basedocument.h:383
NetRenderDocumentContext * GetNetRenderDocumentContext() const
@ DA_FILENAME
Filename.
Definition: c4d_gedata.h:48
void SetDocumentName(const Filename &fn)
void InsertRenderDataLast(RenderData *rd)
@ DONTADDTORECENTLIST
Do not add the saved document to the recent file list.
#define Mmaterial
Standard material.
Definition: ge_prepass.h:950
RenderData * GetActiveRenderData(void)
static BaseMaterial * Alloc(Int32 type)
static BaseObject * Alloc(Int32 type)
BaseTime GetLoopMaxTime(void)
Definition: c4d_basebitmap.h:410
void EventAdd(EVENT eventflag=EVENT::NONE)
@ INTERNALRENDERER
Rendering in the editor.
V off
The translation vector.
Definition: matrix.h:279
Definition: ge_autoptr.h:36
#define Tedgeselection
Edge selection - SelectionTag. The edges are encodes like this: (4*poly)+edge, where edge goes from 0...
Definition: ge_prepass.h:1265
static void Free(BaseObject *&bl)
BaseDocument * IsolateObjects(BaseDocument *doc, const AtomArray &t_objects)
@ NEWOBJ
New object/material/tag etc. was created. (Needs to be called after action.)
Definition: c4d_basedocument.h:136
#define Tpolygonselection
Polygon selection - SelectionTag.
Definition: ge_prepass.h:1247
maxon::Bool Bool
Definition: ge_sys_math.h:53
#define MSG_DOCUMENTINFO_TYPE_LOAD
Document was loaded.
Definition: c4d_baselist.h:457
Definition: c4d_gedata.h:673
Bool IsInstanceOf(Int32 id) const
Definition: c4d_baselist.h:1373
String GetName() const
Definition: c4d_baselist.h:2318
IMAGERESULT
Definition: ge_prepass.h:3659
BaseContainer GetData(DOCUMENTSETTINGS type)
static String VectorToString(const Vector32 &v, Int32 nnk=-1)
Definition: c4d_string.h:571
void AutoKey(BaseList2D *undo, BaseList2D *op, Bool recursive, Bool pos, Bool scale, Bool rot, Bool param, Bool pla)
Definition: c4d_basedocument.h:1093
@ DOCUMENT_USEGENERATORS
Definition: ddoc.h:24
Int32 GetType() const
Definition: c4d_baselist.h:1348
Definition: c4d_basematerial.h:27
Int32 GetInt32(Int32 id, Int32 preset=0) const
Definition: c4d_basecontainer.h:303
BaseContainer * GetSettingsInstance(Int32 type)
Filename GetDocumentName(void)
Int32 GetMode(void) const
@ PRIM_CUBE_SUBZ
Definition: ocube.h:10
@ RDATA_FRAMEFROM
Definition: drendersettings.h:164
BaseDocument * GetNext(void)
Definition: c4d_basedocument.h:527
@ GENERAL
General settings.
Definition: c4d_baselist.h:1980
Definition: c4d_basedocument.h:490
Int32 type
The message type: MSG_DOCUMENTINFO_TYPE.
Definition: c4d_baselist.h:993
BaseContainer GetAllTextures(const AtomArray *ar)
BaseTime GetMaxTime(void)
Definition: c4d_basecontainer.h:46
#define SELECTION_NEW
Starts a new selection.
Definition: c4d_basedocument.h:382
@ MATERIALS
Load/save materials.
C4DAtom * GetIndex(Int32 idx) const
Definition: c4d_baselist.h:1634
@ NODOCUMENTCLONE
Set to avoid an automatic clone of the scene sent to RenderDocument().