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)
using	ProgressDelegate = maxon::Delegate< Bool(Float percent)>

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

Functions
BaseDocument *	GetActiveDocument ()
BaseDocument *	GetFirstDocument ()
Bool	LoadFile (const Filename &name, Bool allowAsync)
void	InsertBaseDocument (BaseDocument *doc)
void	SetActiveDocument (BaseDocument *doc)
Bool	CloseAllDocuments ()
void	KillDocument (BaseDocument *&doc)
BaseDocument *	LoadDocument (const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr, const ProgressDelegate &progressDelegate=ProgressDelegate())
Bool	MergeDocument (BaseDocument *doc, const Filename &name, SCENEFILTER loadflags, BaseThread *thread, maxon::String *errorString=nullptr, const ProgressDelegate &progressDelegate=ProgressDelegate())
Bool	SaveDocument (BaseDocument *doc, const Filename &name, SAVEDOCUMENTFLAGS saveflags, Int32 format)
BaseDocument *	IsolateObjects (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)
GETALLASSETSRESULT	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]	flags	Flags: PICKSESSION_FLAG_CANCELED.
[in]	psd	The passed pick session data structure.

ProgressDelegate

using ProgressDelegate = maxon::Delegate<Bool(Float percent)>

used by LoadDocument to inform about the progress of the operation. Return True to continue the operation, False to cancel the operation.

Function Documentation

GetActiveDocument()

BaseDocument* GetActiveDocument

(

)

Gets the active document within the Cinema 4D editor.

Returns

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

GetFirstDocument()

BaseDocument* GetFirstDocument

(

)

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,
		Bool	allowAsync
	)

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

Parameters

[in]	name	The name of the file to load.
[in]	allowAsync	True to allow loading the file async. Pleasee note that the function returns before loading is finished in that case.

Returns

true if the file was loaded successfully or the async job was successfully enqueued, 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]

doc

The 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.

Warning

It's mandatory that the passed doc is already inserted into the Cinema 4D list of documents. This can be done with InsertBaseDocument().

Parameters

[in]

doc

The 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]

doc

The 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,
		const ProgressDelegate &	progressDelegate = ProgressDelegate()
	)

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]	name	The name of the file to load the document from.
[in]	loadflags	The scene filter flags for the loader: SCENEFILTER
[in]	thread	The current thread, or nullptr for the main Cinema 4D thread. The caller owns the pointed thread.
[out]	errorString	Assigned a string if an error occurred.
[in]	progressDelegate	ProgressDelegate to receive the progress. see ProgressDelegate.

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,
		const ProgressDelegate &	progressDelegate = ProgressDelegate()
	)

Merges the file name into the document doc.

Parameters

[in]	doc	The document to merge the loaded document name into. The caller owns the pointed document.
[in]	name	The file to merge into doc.
[in]	loadflags	The scene filter flags for the loader: SCENEFILTER
[in]	thread	The current thread, or nullptr for the main Cinema 4D thread. The caller owns the pointed thread.
[out]	errorString	Assigned a string if an error occurred.
[in]	progressDelegate	ProgressDelegate to receive the progress. see ProgressDelegate.

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]	doc	The document to save to a file. The caller owns the pointed document.
[in]	name	The file to save the document to.
[in]	saveflags	A combination of the flags for saving a document: SAVEDOCUMENTFLAGS
[in]	format	The 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]	doc	The document that contains the objects in the array t_objects. The caller owns the pointed document.
[in]	t_objects	The 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:

MultipassBitmap* bitmap = MultipassBitmap::Alloc(512, 512, COLORMODE::RGB);
bitmap->AddChannel(true, true);
...
RenderDocument(doc, data, nullptr, nullptr, tmp, RENDERFLAGS::EXTERNAL, nullptr);
...
MultipassBitmap::Free(bitmap);

Parameters

[in]	doc	The document to render. Can be a clone of the real document to save memory usage. The caller owns the pointed document.
[in]	rdata	The render data.
[in]	prog	The progress bar hook. Can be nullptr. The caller owns the pointed progress hook.
[in]	private_data	The private data for the progress hook prog, or nullptr. The caller owns the pointed private data.
[in]	bmp	The bitmap to render to, this must have been allocated and initialized with the right size. The caller owns the pointed bitmap.
[in]	renderflags	A combination of the render flags: RENDERFLAGS
[in]	th	The thread to test for a break or nullptr.
[in]	wprog	The write progress hook for the render operation.The caller owns the pointed write progress hook.
[in]	data	The 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]	doc	The document to save as project. The caller owns the pointed document.
[in]	flags	A combination of the save project flags: SAVEPROJECT
[in]	targetPath	The path to save the project to.
[out]	assets	Filled by the found assets.
[out]	missingAssets	Filled by the missing assets.

Returns

true saving the document as a project was successful, otherwise false.

GetAllAssets()

GETALLASSETSRESULT 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]	doc	The document to get the assets from. The caller owns the pointed document.
[in]	allowDialogs	If 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]	assets	Assigned the assets in document doc.
[out]	lastPath	Filled with the last path used. If 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]	flags	Flags to decide which assets should be collected: ASSETDATA_FLAG

Returns

The result if all assets were collected: GETALLASSETSRESULT

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)
  {
    AutoAlloc<AtomArray> objects;
    if (!objects)
      return false;
 
    doc->GetActiveObjects(*objects, true);
 
    BaseContainer* toolData = GetToolData(doc, ID_MODELING_EDGECUT_TOOL);
    if (!toolData)
      return false;
 
    // Undo the step before
    InteractiveModeling_Restart(doc);
 
    ModelingEdgeCut(objects, MODIFY_EDGESELECTION, toolData, doc, win, &msg, true, this);
    EventAdd();
  }
 
  return true;
}

Parameters

[in]

doc

The 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]	doc	The document to animate. Usually GetActiveDocument(). The caller owns the pointed document.
[in]	forward	If true the direction is set to forward, otherwise it is set to backward.
[in]	stop	If 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]	doc	The document to set the time. Usually GetActiveDocument(). The caller owns the pointed document.
[in]	time	The time to set.

StopExternalRenderer()

Bool StopExternalRenderer

(

)

Stops the external renderer.

Returns

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