c4d_basedocument.h File Reference

Classes

class  BaseSceneHook
 
class  MultipassObject
 
class  RenderData
 
class  LayerObject
 
struct  LayerData
 
struct  PickSessionDataStruct
 
class  BaseDocument
 
class  Hierarchy
 
class  PriorityList
 

Namespaces

 maxon
 

Macros

#define SELECTION_NEW
 
#define SELECTION_ADD
 
#define SELECTION_SUB
 
#define PICKSESSION_FLAG_CANCELED
 
#define BASEDOCUMENT_PREVIEWSCENE_MARKER
 

Typedefs

typedef void(* PickSessionCallBack) (Int32 flags, const PickSessionDataStruct *psd)
 

Enumerations

enum  {
  Mcamera,
  Mobject,
  Mtexture,
  Mtextureaxis,
  Mpoints,
  Medges,
  Mpolygons,
  Manimation,
  Mkinematic,
  Mmodel,
  Mpaint,
  Muvpoints,
  Muvpolygons,
  Mpolyedgepoint,
  Medgepoint,
  Mworkplane,
  M2dtracks,
  Mdrag
}
 

Functions

BaseDocumentGetActiveDocument (void)
 
BaseDocumentGetFirstDocument (void)
 
Bool LoadFile (const Filename &name)
 
void InsertBaseDocument (BaseDocument *doc)
 
void SetActiveDocument (BaseDocument *doc)
 
Bool CloseAllDocuments ()
 
void KillDocument (BaseDocument *&doc)
 
BaseDocumentLoadDocument (const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr)
 
Bool MergeDocument (BaseDocument *doc, const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr)
 
Bool SaveDocument (BaseDocument *doc, const Filename &name, SAVEDOCUMENTFLAGS saveflags, Int32 format)
 
BaseDocumentIsolateObjects (BaseDocument *doc, const AtomArray &t_objects)
 
RENDERRESULT RenderDocument (BaseDocument *doc, const BaseContainer &rdata, ProgressHook *prog, void *private_data, BaseBitmap *bmp, RENDERFLAGS renderflags, BaseThread *th, WriteProgressHook *wprog=nullptr, void *data=nullptr)
 
Bool SaveProject (BaseDocument *doc, SAVEPROJECT flags, Filename targetPath, maxon::BaseArray< AssetEntry > *assets=nullptr, maxon::BaseArray< AssetEntry > *missingAssets=nullptr)
 
Bool GetAllAssets (BaseDocument *doc, Bool allowDialogs, maxon::BaseArray< AssetEntry > &assets, Filename &lastPath, ASSETDATA_FLAG flags=ASSETDATA_FLAG::NONE)
 
Bool InteractiveModeling_Rewind (BaseDocument *doc)
 
Bool InteractiveModeling_Restart (BaseDocument *doc)
 
void RunAnimation (BaseDocument *doc, Bool forward, Bool stop)
 
void SetDocumentTime (BaseDocument *doc, const BaseTime &time)
 
Bool StopExternalRenderer ()
 

Macro Definition Documentation

◆ PICKSESSION_FLAG_CANCELED

#define PICKSESSION_FLAG_CANCELED

Pick session was canceled.

◆ BASEDOCUMENT_PREVIEWSCENE_MARKER

#define BASEDOCUMENT_PREVIEWSCENE_MARKER

doc->GetDataInstance()->GetBool(BASEDOCUMENT_PREVIEWSCENE_MARKER) returns if the scene is a material preview scene

Typedef Documentation

◆ PickSessionCallBack

typedef void(* PickSessionCallBack) (Int32 flags, const PickSessionDataStruct *psd)

Pick session callback. Called when a pick session has been started.
Used to change the state of the pick session button for instance and to check if a pick session has been canceled.

See also
PickSessionDataStruct for an example.
Parameters
[in]flagsFlags: PICKSESSION_FLAG_CANCELED.
[in]psdThe passed pick session data structure.

Function Documentation

◆ GetActiveDocument()

BaseDocument* GetActiveDocument ( void  )

Gets the active document within the Cinema 4D editor.

Returns
The active document. Cinema 4D owns the pointed document.

◆ GetFirstDocument()

BaseDocument* GetFirstDocument ( void  )

Gets the first document in the list of documents within Cinema 4D.

Returns
The first document. Cinema 4D owns the pointed document.

◆ LoadFile()

Bool LoadFile ( const Filename name)

Asks Cinema 4D to load a file. This can be a document, an image, a layout or a lib4d/cat4d file.

Parameters
[in]nameThe name of the file to load.
Returns
true if the file was loaded successfully, otherwise false.

◆ InsertBaseDocument()

void InsertBaseDocument ( BaseDocument doc)

Inserts a document into the list of documents within Cinema 4D.

Note
SetActiveDocument() is called implicitly.
Warning
If the current active document is empty then it will be destroyed in the process of inserting the new document.
Be careful passing a document pointing to the previous active one.
Parameters
[in]docThe document to insert. Cinema 4D takes over the ownership of the pointed document.

◆ SetActiveDocument()

void SetActiveDocument ( BaseDocument doc)

Sets the document in the editor that the user is editing, this is the active document.

Parameters
[in]docThe document to become active. The caller owns the pointed document.

◆ CloseAllDocuments()

Bool CloseAllDocuments ( )

Closes all open documents.

Returns
true if all documents have been closed, otherwise false.

◆ KillDocument()

void KillDocument ( BaseDocument *&  doc)

Removes and frees all resources of the passed document.

Parameters
[in,out]docThe document to destruct. If the pointer is nullptr nothing happens. The pointer is assigned nullptr afterwards.

◆ LoadDocument()

BaseDocument* LoadDocument ( const Filename name,
SCENEFILTER  loadflags,
BaseThread thread,
maxon::String errorString = nullptr 
)

Similar to LoadFile() but this time the document is not put into the editors list of documents and it gives control over the loaded document.

Parameters
[in]nameThe name of the file to load the document from.
[in]loadflagsThe scene filter flags for the loader: SCENEFILTER
[in]threadThe current thread, or nullptr for the main Cinema 4D thread. The caller owns the pointed thread.
[out]errorStringAssigned a string if an error occurred.
Returns
The document that was loaded, or nullptr if it failed.

◆ MergeDocument()

Bool MergeDocument ( BaseDocument doc,
const Filename name,
SCENEFILTER  loadflags,
BaseThread thread,
maxon::String errorString = nullptr 
)

Merges the file name into the document doc.

Parameters
[in]docThe document to merge the loaded document name into. The caller owns the pointed document.
[in]nameThe file to merge into doc.
[in]loadflagsThe scene filter flags for the loader: SCENEFILTER
[in]threadThe current thread, or nullptr for the main Cinema 4D thread. The caller owns the pointed thread.
[in]errorStringAssigned a string if an error occurred.
Returns
true if merging the file name into the document doc was successful, otherwise false.

◆ SaveDocument()

Bool SaveDocument ( BaseDocument doc,
const Filename name,
SAVEDOCUMENTFLAGS  saveflags,
Int32  format 
)

Saves a document to a file.

Parameters
[in]docThe document to save to a file. The caller owns the pointed document.
[in]nameThe file to save the document to.
[in]saveflagsA combination of the flags for saving a document: SAVEDOCUMENTFLAGS
[in]formatThe file format to save the document as: FORMAT_FILES
Returns
true if the document was saved successful, otherwise false.

◆ IsolateObjects()

BaseDocument* IsolateObjects ( BaseDocument doc,
const AtomArray t_objects 
)

A helper routine to copy the objects t_objects of document doc to a new document returned.
All materials associated are also copied over and the links are corrected.

Parameters
[in]docThe document that contains the objects in the array t_objects. The caller owns the pointed document.
[in]t_objectsThe objects to isolate.
Returns
The document containing the isolated objects. The caller owns the pointed document.

◆ 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 
)

Renders a document to a bitmap.

Note
A MultipassBitmap must be passed to render the image with an alpha channel:
bitmap->AddChannel(true, true);
...
RenderDocument(doc, data, nullptr, nullptr, tmp, RENDERFLAGS::EXTERNAL, nullptr);
...
MultipassBitmap::Free(bitmap);
Parameters
[in]docThe document to render. Can be a clone of the real document to save memory usage. The caller owns the pointed document.
[in]rdataThe render data.
[in]progThe progress bar hook. Can be nullptr. The caller owns the pointed progress hook.
[in]private_dataThe private data for the progress hook prog, or nullptr. The caller owns the pointed private data.
[in]bmpThe bitmap to render to, this must have been allocated and initialized with the right size. The caller owns the pointed bitmap.
[in]renderflagsA combination of the render flags: RENDERFLAGS
[in]thThe thread to test for a break or nullptr.
[in]wprogThe write progress hook for the render operation.The caller owns the pointed write progress hook.
[in]dataThe private data for the write progress hook wprog.
Returns
A render result: RENDERRESULT

◆ SaveProject()

Bool SaveProject ( BaseDocument doc,
SAVEPROJECT  flags,
Filename  targetPath,
maxon::BaseArray< AssetEntry > *  assets = nullptr,
maxon::BaseArray< AssetEntry > *  missingAssets = nullptr 
)

Saves the document as a project (menu "Save Project with Assets").

Parameters
[in]docThe document to save as project. The caller owns the pointed document.
[in]flagsA combination of the save project flags: SAVEPROJECT
[in]targetPathThe path to save the project to.
[out]assetsAssigned the found assets.
[out]missingAssetsAssigned the missing assets.
Returns
true saving the document as a project was successful, otherwise false.

◆ GetAllAssets()

Bool GetAllAssets ( BaseDocument doc,
Bool  allowDialogs,
maxon::BaseArray< AssetEntry > &  assets,
Filename lastPath,
ASSETDATA_FLAG  flags = ASSETDATA_FLAG::NONE 
)

Retrieves all assets from a document. It is e.g. used by "Save Project with Assets" menu and SaveProject().

Parameters
[in]docThe document to get the assets from. The caller owns the pointed document.
[in]allowDialogsIf true this function can open dialogs. For example a file select dialog will be opened if a node of the scene points to a file which does not exist anymore.
[in]assetsAssigned the assets in document doc.
[in]lastPathIf a file dialog is opened and the user selects the missing file on the hard disk, the folder of this asset is assigned to lastPath.
The developer can store this value somewhere and pass it next time so Cinema 4D know where to look first before asking the user again.
[in]flagsFlags to decide which assets should be collected: ASSETDATA_FLAG
Returns
true the assets were collected successfully, otherwise false.

◆ InteractiveModeling_Rewind()

Bool InteractiveModeling_Rewind ( BaseDocument doc)

Private.

◆ InteractiveModeling_Restart()

Bool InteractiveModeling_Restart ( BaseDocument doc)

Used for modeling tools with GUI input. Applies the last modeling undo so that new values of the modeling tool can be applied.
Here is an example from the edge cut code:

Bool EdgeCutTool::MouseInput(BaseDocument* doc, BaseContainer& data, BaseDraw* draw, EditorWindow* win, const BaseContainer& msg)
{
if (!doc)
return false;
if (doc->GetMode() == Medges)
{
if (!objects)
return false;
doc->GetActiveObjects(*objects, true);
if (!toolData)
return false;
// Undo the step before
ModelingEdgeCut(objects, MODIFY_EDGESELECTION, toolData, doc, win, &msg, true, this);
}
return true;
}
Parameters
[in]docThe document for the operation. The caller owns the pointed document.
Returns
true if successful, otherwise false.

◆ RunAnimation()

void RunAnimation ( BaseDocument doc,
Bool  forward,
Bool  stop 
)

Controls the animation in a document.

Parameters
[in]docThe document to animate. Usually GetActiveDocument(). The caller owns the pointed document.
[in]forwardIf true the direction is set to forward, otherwise it is set to backward.
[in]stopIf true the animation is stopped, otherwise it is running.

◆ SetDocumentTime()

void SetDocumentTime ( BaseDocument doc,
const BaseTime time 
)

Controls the time of a document.

Note
Unlike BaseDocument::SetTime() this function handles running animation.
Parameters
[in]docThe document to set the time. Usually GetActiveDocument(). The caller owns the pointed document.
[in]timeThe time to set.

◆ StopExternalRenderer()

Bool StopExternalRenderer ( )

Stops the external renderer.

Returns
true if the external rendering has been canceled, otherwise false.