Main Index : Reference :

BaseDocument

Description

Definition

[BaseDocument] GetActiveDocument();

class BaseDocument : BaseList2D
{
public:
  BaseDocument();

  [BaseObject] GetFirstObject();
  [BaseObject] GetActiveObject(); 
  [BaseMaterial] GetFirstMaterial();
  [BaseMaterial] GetActiveMaterial(); 
  [RenderData] GetFirstRenderData();
  
  [bool] SetActiveMat([BaseMat] mat);
  [bool] SetActiveObject([BaseObject] op);
  [bool] SetActiveTag([BaseObject] op, [BaseTag] tag);
  [bool] SetActiveRenderData([RenderData] rd);

  [bool] InsertObject([BaseObject] op, [[BaseObject] parent = NULL], 
                      [[BaseObject] prev = NULL]);
  [bool] InsertMaterial([BaseMaterial] mat, [[BaseMaterial] prev = NULL});
  [bool] InsertRenderData([RenderData] rd, [[RenderData] prev = NULL]);

  [int] GetFps();
  [float] GetLOD();

  [BaseTime] GetTime();
  [BaseTime] GetMinTime();
  [BaseTime] GetMaxTime();
  [BaseTime] GetLoopMinTime();
  [BaseTime] GetLoopMaxTime();

  [bool] SetFps([int] fps);
  [bool] SetLOD([float] lod);

  [bool] SetTime([BaseTime] t);
  [bool] SetMinTime([BaseTime] t);
  [bool] SetMaxTime([BaseTime] t);
  [bool] SetLoopMinTime([BaseTime] t);
  [bool] SetLoopMaxTime([BaseTime] t);

  [Filename] GetFilename();
  [bool] SetFilename([Filename] file);
  
  [bool] Save([Filename] f);

  [BaseObject] FindObject([Marker,string] o);
  [BaseMaterial] FindMaterial([Marker,string] m);
  
  [bool] AnimateDocument([int] flags);
  [bool] AnimateObject([BaseObject] op, [BaseTime] time, [int] flags);

  [bool] StartUndo();
  [bool] AddUndo([int] type, [BaseObject, BaseMaterial, 
                 BaseTag, BaseSequence, BaseTrack] data);
  [bool] EndUndo();

  [bool] DoUndo();
  [bool] DoRedo();

  [bool] MultiMessage([int] type, [[any type] data]);

  // Base draw access 
  [BaseList2D] GetActiveBaseDraw();
  [BaseList2D] GetRenderBaseDraw();
  [BaseList2D] GetBaseDraw([int] index);  

  // Tool access 
  [BaseList2D] GetActiveTool();
  [BaseList2D] GetSnapTool();
}

Explanation

Functions

GetActiveDocument()

Returns the currently active document.

Members

GetFirstObject()

Returns the first object in the scene, or NULL if there are no objects. The rest of the objects can be accessed by navigating through the hierarchy with the inherited GetNext(), GetPrev(), GetUp() and GetDown() member functions of the BaseObject class.

GetActiveObject()

Returns the first of the currently active objects in the documen, or NULL if there are no active objects.

GetFirstMaterial()

Returns the first material of the scene, or NULL if there are no materials. The rest the materials can be accessed by navigating along the materials list with the inherited GetNext() and GetPrev() member functions of the BaseMaterial class.

GetActiveMaterial()

Returns the first of the currently active materials in the documen, or NULL if there are no active materials.

GetFirstRenderData()

Returns the first render setting data of the document. The rest the render settings can be accessed by navigating along the render setting list with the inherited GetNext() and GetPrev() member functions of the RenderData class.

SetActiveMat( mat )

Makes mat the active material. Returns TRUE if successful.

SetActiveObject( op )

Makes op the active object. Returns TRUE if successful.

SetActiveTag( op, tag )

Makes tag the active tag of the object op. Returns TRUE if successful.

SetActiveRenderData( rd )

Makes rd the active render setting. Returns TRUE if successful.

InsertObject( op, [parent], [prev])

[bool] InsertObject([BaseObject] op, [[BaseObject] parent = NULL], 
                    [[BaseObject] prev = NULL]);

Inserts the object op into the document's object hierarchy. The insertion position can either be specified by the parent parameter, inserting the object as the first child of the specified parent, or by the prev parameter, inserting the object below the specified prev object. If neither is given, the object is inserted at the top of the hierarchy. Returns TRUE if successful.

InsertMaterial( mat, [prev] )

Inserts the material mat into the document's material list. Optionally one can specify the insertion position with the prev parameter, giving the material before (just to the left of) the wanted position. Otherwise the material is inserted at the first position in the list. Returns TRUE if successful.

InsertRenderData( rd, [prev] )

Inserts the render setting data rd into the document's render setting list. Optionally one can specify the insertion position with the prev parameter, giving the render setting before (right above) the wanted position. Otherwise the render setting is inserted at the first position in the list. Returns TRUE if successful.

GetFps()

Returns the document's frame rate as the number of frames per second.

GetLOD()

Returns the document's level of detail (LOD) percentage.

GetTime()

Returns the current document time as a BaseTime object.

GetMinTime()

Returns the minimum time of the document as a BaseTime object.

GetMaxTime()

Returns the maximum time of the document as a BaseTime object.

GetLoopMinTime()

Returns the time of the left boundary of the document's preview range (loop range) as a BaseTime object.

GetLoopMaxTime()

Returns the time of the right boundary of the document's preview range (loop range) as a BaseTime object.

SetFps( fps )

Sets the documents frame rate to fps. Returns TRUE if successful.

SetLOD( lod )

Sets the documents level of detail (LOD) to lod. Returns TRUE if successful.

SetTime( t )

Sets the document's time to the BaseTime object t. Returns TRUE if successful.

SetMinTime( t )

Sets the document's minimum time to the BaseTime object t. Returns TRUE if successful.

SetMaxTime( t )

Sets the document's maximum time to the BaseTime object t. Returns TRUE if successful.

SetLoopMinTime( t )

Sets the left boundary of the document's preview range (loop range) to the BaseTime object t. Returns TRUE if successful.

SetLoopMaxTime( t )

Sets the right boundary of the document's preview range (loop range) to the BaseTime object t. Returns TRUE if successful.

GetFilename()

Returns the document's current file name.

SetFilename( file )

Sets the document's file name to file. Returns TRUE if successful.

Save( f )

Saves the document to the file specified by the FileName object f. Returns TRUE if successful.

FindObject( o )

Finds the object specified by o and returns it. One can either specify the object by name or by marker. If several objects have the same name, the uppermost match is returned. Returns NULL if no object was found.

FindMaterial( m )

Finds the material specified by m and returns it. One can either specify the material by name or by marker. If several material have the same name, the first match is returned. Returns NULL if no object was found.

AnimateDocument( flags )

Animates the whole scene. Set the destination time before calling the function with doc->SetTime(). The possible flags values are:

Flag	Explanation
ANIMATE_NO_PARTICLES	Ignores particles and particle modifiers. Using this flag may result in a scene with wrong particle positions
ANIMATE_QUICK	Some internal tracks need quite a time to compute. Use this flag to speed up the animation process. This may result in a scene with wrong object positions and states.
ANIMATE_NOT_KEYFRAME	Turns off the calculation of all keyframeable tracks.
ANIMATE_NOT_UPWARDS	Only useful for AnimateObject(). Sometimes an effect needs evaluation of the parent objects first. This flag forbids evaluation of the parents, so that only the object itself will be animated

So where are these flags needed? For example if one wants to play an animation from frame 0 to frame 100 to get the correct positions of particles at frame 100 one normally don't need to compute complex effects like morph tracks. Hence one can use ANIMATE_QUICK. Most of them are only used internally for speedups, they are just noted here for completion.

AnimateObject( op, time, flags )

Works the same as AnimateDocument() but only animates the object op (and maybe it's parents). For example, if one wants to program a look ahead of 10 frames then one has to animate the object with time equal to the current time + 10 frames. After calling AnimateObject() one can then just get the object position as normal. See AnimateDocument() for flags values.

StartUndo()

New in CINEMA 4D V6 is the option to have multiple undo steps collected together in a single step. Therefore you have to enclose all AddUndo() calls within StartUndo() and EndUndo() calls, otherwise funny things will happen. The only exception to this rule is that calls to MenuPlugin::Execute() are automatically enclosed within an undo block.

AddUndo( type, data )

[bool] AddUndo([int] type, [BaseObject, BaseMaterial, 
               BaseTag, BaseSequence, BaseTrack] data);

Adds undo information for an operation. The object that is affected should be sent as data. Returns TRUE if successful. These are the possible undo types.

Undo type	Explanation
UNDO_OBJECT_REC	Saves the full data of an object and all of its children.
UNDO_OBJECT	Saves the full data of an object.
UNDO_OBJECT_BASEDATA_REC	Saves only the base data of an object and all of its children.
UNDO_OBJECT_BASEDATA	Saves only the base data of an object.
UNDO_OBJECT_NEW	Undos the creation of an object.
UNDO_OBJECT_DEL	Undos the deletion of an object.
UNDO_OBJECT_ACTIVE	Undos the activation of an object.
UNDO_OBJECT_SELECTION	Saves the current selection of an object.
UNDO_MATERIAL_DATA	Saves the data of a material.
UNDO_MATERIAL_NEW	Undos the creation of a material.
UNDO_MATERIAL_DEL	Undos the deletion of a material.
UNDO_TAG_DATA	Saves the data of a tag.
UNDO_TAG_NEW	Undos the creation of a tag.
UNDO_TAG_DEL	Undos the deletion of a tag.
UNDO_KEY_DATA	Saves the data of a key.
UNDO_KEY_NEW	Undos the creation of a key.
UNDO_KEY_DEL	Undos the deletion of a key.
UNDO_SEQUENCE_DATA	Saves the data of a sequence.
UNDO_SEQUENCE_NEW	Undos the creation of a sequence.
UNDO_SEQUENCE_DEL	Undos the deletion of a sequence.
UNDO_TRACK_DATA	Saves the track data.
UNDO_TRACK_NEW	Undos the creation of a track.
UNDO_TRACK_DEL	Undos the deletion of a track.

Here's an example of how to use the undo functions:

doc->StartUndo();

doc->AddUndo(OBJECT_BASEDATA, op);
op->SetName("Change");

doc->AddUndo(OBJECT_BASEDATA, op);
op->SetPosition(vector(100,0,0));

doc->EndUndo();

EndUndo()

Ends the current undo step block. See StartUndo() for more information.

DoUndo()

Like choosing Undo from the menu. Returns TRUE if successful.

DoRedo()

Like choosing Redo from the menu. Returns TRUE if successful.

MultiMessage( type, [data] )

Sends the specified message to the document as well as to all child elements in the document, like objects and materials. To send a message only to the document itself, use the Message() function of the BaseList2D class. Returns TRUE if successful.

GetActiveBaseDraw()

Returns the currently active base draw. You can use this to access draw parameters, like doc->GetActiveBaseDraw()#BASEDRAW_DATA_SDISPLAYACTIVE = BASEDRAW_SDISPLAY_GOURAUD.

GetRenderBaseDraw()

Returns the current render base draw. You can use this to access draw parameters, like doc->GetActiveBaseDraw()#BASEDRAW_DATA_CAMERA = doc->FindObject("NewCamera");.

GetBaseDraw( index )

Returns the base draw with the specified index. If the index is out of bounds NIL is returned..

GetActiveTool()

Returns the currently active tool. You can use this to access tool parameters, like doc->GetActiveTool()#MDATA_MAGNET_RESTRICT_X. You can also find out which tool is active with doc->GetActiveTool()->GetType()==ID_MODELING_MAGNET_TOOL.

GetSnapTool()

Returns the snapping tool. You can use this to access snap parameters, like doc->GetSnapTool()#ID_SNAPSETTINGS:SNAP_ENABLE=TRUE;.