#include <c4d_scenehookdata.h>

Inheritance diagram for SceneHookData:

Detailed Description

A data class for creating scene hook plugins.
A scene hook is called on every scene prepare, for example before redraw and before rendering.

Use RegisterSceneHookPlugin() to register a scene hook plugin.

Warning: Make sure that a scene hook plugin is 100% stable and not too slow before releasing it. A crashing scene hook is a potential disaster!

Public Member Functions
virtual Bool	MouseInput (BaseSceneHook node, BaseDocument doc, BaseDraw bd, EditorWindow win, const BaseContainer &msg)

virtual Bool	KeyboardInput (BaseSceneHook node, BaseDocument doc, BaseDraw bd, EditorWindow win, const BaseContainer &msg)

virtual Bool	GetCursorInfo (BaseSceneHook node, BaseDocument doc, BaseDraw *bd, Float x, Float y, BaseContainer &bc)

virtual Bool	Draw (BaseSceneHook node, BaseDocument doc, BaseDraw bd, BaseDrawHelp bh, BaseThread *bt, SCENEHOOKDRAW flags)

Public Member Functions inherited from NodeData
	NodeData ()

GeListNode *	Get ()

const GeListNode *	Get () const

virtual Bool	Message (GeListNode node, Int32 type, void data)

virtual void	GetBubbleHelp (GeListNode *node, maxon::String &str)

virtual const BaseDocument *	GetDocument (const GeListNode *node) const

virtual maxon::Result< Bool >	GetBranchInfo (const GeListNode *node, const maxon::ValueReceiver< const BranchInfo & > &info, GETBRANCHINFO flags) const

virtual Bool	IsInstanceOf (const GeListNode *node, Int32 type) const

virtual Bool	IsDocumentRelated (const GeListNode *node, Bool &docrelated) const

virtual maxon::Result< Bool >	GetAccessedObjects (const BaseList2D *node, METHOD_ID method, AccessedObjectsCallback &access) const

virtual maxon::Result< maxon::GenericData >	GroupChanges (BaseList2D *node)

virtual Bool	Init (GeListNode *node, Bool isCloneInit)

virtual void	Free (GeListNode *node)

virtual Bool	Read (GeListNode node, HyperFile hf, Int32 level)

virtual Bool	Write (const GeListNode node, HyperFile hf) const

virtual Bool	CopyTo (NodeData dest, const GeListNode snode, GeListNode dnode, COPYFLAGS flags, AliasTrans trn) const

virtual Bool	GetDDescription (const GeListNode node, Description description, DESCFLAGS_DESC &flags) const

virtual Bool	GetDParameter (const GeListNode *node, const DescID &id, GeData &t_data, DESCFLAGS_GET &flags) const

virtual Bool	SetDParameter (GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_SET &flags)

virtual Bool	GetDEnabling (const GeListNode node, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE flags, const BaseContainer itemdesc) const

virtual Bool	TranslateDescID (GeListNode node, const DescID &id, DescID &res_id, C4DAtom &res_at)

Public Member Functions inherited from BaseData
virtual	~BaseData ()

void	Destructor ()

Init/Free SceneHook
virtual EXECUTIONRESULT	InitSceneHook (BaseSceneHook node, BaseDocument doc, BaseThread *bt)

virtual void	FreeSceneHook (BaseSceneHook node, BaseDocument doc)

Execute
virtual EXECUTIONRESULT	Execute (BaseSceneHook node, BaseDocument doc, BaseThread *bt, Int32 priority, EXECUTIONFLAGS flags)

virtual Bool	AddToExecution (BaseSceneHook node, PriorityList list)

virtual EXECUTIONRESULT	Visit (BaseSceneHook node, BaseDocument doc, BaseThread bt, BaseObject op, EXECUTIONFLAGS flags)

DisplayControl
virtual Bool	DisplayControl (BaseDocument doc, BaseObject op, BaseObject chainstart, BaseDraw bd, BaseDrawHelp *bh, ControlDisplayStruct &cds) const

virtual Bool	InitDisplayControl (BaseSceneHook node, BaseDocument doc, BaseDraw bd, const AtomArray active)

virtual void	FreeDisplayControl ()

Additional Inherited Members
Protected Attributes inherited from NodeData
GeListNode *	private_link

Member Function Documentation

◆ InitSceneHook()

virtual EXECUTIONRESULT InitSceneHook	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseThread *	bt
	)

virtual

Called to initialize the scene hook, before all scene hooks and expressions in a scene are calculated.
Allocate here temporary data in the node.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bt	The calling thread. Can be nullptr. Cinema 4D owns the pointed thread.

Returns: The execution result: EXECUTIONRESULT

◆ FreeSceneHook()

virtual void FreeSceneHook	(	BaseSceneHook *	node,
		BaseDocument *	doc
	)

virtual

Called to free the scene hook, after all scene hooks and expressions in a scene are calculated, before the drawing starts.
Free here temporary data allocated in InitSceneHook.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.

◆ Execute()

virtual EXECUTIONRESULT Execute	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseThread *	bt,
		Int32	priority,
		EXECUTIONFLAGS	flags
	)

virtual

Called at the point in the priority pipeline specified by AddToExecution, or by RegisterSceneHookPlugin.

Note: This function is called in a thread context. See the important information about threading.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bt	The calling thread. Can be nullptr. Cinema 4D owns the pointed thread.
[in]	priority	The priority of the call to Execute() in the pipeline: EXECUTIONPRIORITY
[in]	flags	The execution flags: EXECUTIONFLAGS

Returns: The execution result: EXECUTIONRESULT

◆ AddToExecution()

virtual Bool AddToExecution	(	BaseSceneHook *	node,
		PriorityList *	list
	)

virtual

Called to add execution priorities.
By default returns false. In that case Cinema 4D will call Execute() at the priority specified by the RegisterSceneHookPlugin() call for the scene hook.
If overridden then insert points of execution in the list and return true. Heres is an example:

list->Add(node, EXECUTIONPRIORITY_ANIMATION, EXECUTIONFLAGS::NONE);

list->Add(node, EXECUTIONPRIORITY_GENERATOR, EXECUTIONFLAGS::NONE);

cinema::EXECUTIONFLAGS::NONE

@ NONE

None.

EXECUTIONPRIORITY_ANIMATION

#define EXECUTIONPRIORITY_ANIMATION

Animation.

Definition: ge_prepass.h:3973

EXECUTIONPRIORITY_GENERATOR

#define EXECUTIONPRIORITY_GENERATOR

Generators.

Definition: ge_prepass.h:3977

Cinema 4D will then call Execute() 2 times.

A scene hook can also add itself to Cinema 4D's pre- and post-pass which are done right before and after scene execution. For this, you have to set one of the PREPASS/POSTPASS flags in combination with further PASS_* flags in the EXECUTIONFLAGS passed to list->Add(). Cinema 4D will then call Visit() according to the set bits.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	list	The priority list to add execution points to. Cinema 4D owns the pointed priority list.

Returns: true if priority was added to the execution list, otherwise false.

◆ MouseInput()

virtual Bool MouseInput	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseDraw *	bd,
		EditorWindow *	win,
		const BaseContainer &	msg
	)

virtual

Called when the user clicks with the mouse in any of the editors views.

Note: Make sure this function is used only when the user is somehow working with the scene hook plugin, so that other plugins can also use this hook when it is their turn.

Warning: At least call SceneHookData::MouseInput(node, doc, bd, win, msg) as last return, so that other plugins can also use this hook when it is their turn.
If true is returned the right-click will not be evaluated anymore in the editor views.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bd	The active editor view. Cinema 4D owns the pointed base draw.
[in]	win	The window for the active editor view. Cinema 4D owns the pointed editor window.
[in]	msg	The mouse message container. See Input Events.

Returns: true if successful, otherwise false.

◆ KeyboardInput()

virtual Bool KeyboardInput	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseDraw *	bd,
		EditorWindow *	win,
		const BaseContainer &	msg
	)

virtual

Called when the user types something in any of the editors views.

Note: Make sure this function is used only when the user is somehow working with the scene hook plugin, so that other plugins can also use this hook when it is their turn.

Warning: At least call SceneHookData::KeyboardInput(node, doc, bd, win, msg) as last return, so that other plugins can also use this hook when it is their turn.
If true is returned the keyboard will be blocked in the editor views.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bd	The active editor view. Cinema 4D owns the pointed base draw.
[in]	win	The window for the active editor view. Cinema 4D owns the pointed editor window.
[in]	msg	The keyboard message container. See Input Events.

Returns: true if successful, otherwise false.

◆ GetCursorInfo()

virtual Bool GetCursorInfo	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseDraw *	bd,
		Float	x,
		Float	y,
		BaseContainer &	bc
	)

virtual

Called when the cursor is over the editor views to get the state of the mouse pointer.
Set the bubble help and cursor, for example:

bc.SetString(RESULT_BUBBLEHELP, "My Tools Help");

bc.SetInt32(RESULT_CURSOR, MOUSE_POINT_HAND);

cinema::RESULT_BUBBLEHELP

@ RESULT_BUBBLEHELP

String Bubble help text.

Definition: gui.h:568

cinema::RESULT_CURSOR

@ RESULT_CURSOR

Int32 Mouse cursor: MOUSE

Definition: gui.h:567

cinema::MOUSE_POINT_HAND

static const Int32 MOUSE_POINT_HAND

Point hand cursor.

Definition: ge_prepass.h:2767

Note: Make sure this function is used only when the user is somehow working with the scene hook plugin, so that other plugins can also use this hook when it is their turn.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bd	The active editor view. Cinema 4D owns the pointed base draw.
[in]	x	The X coordinate of the mouse cursor relative to the top-left of the active editor view.
[in]	y	The Y coordinate of the mouse cursor relative to the top-left of the active editor view.
[in]	bc	The container to store the cursor information in: BFM_GETCURSORINFO_RESULT

Returns: true if successful, otherwise false.

◆ Draw()

virtual Bool Draw	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseDraw *	bd,
		BaseDrawHelp *	bh,
		BaseThread *	bt,
		SCENEHOOKDRAW	flags
	)

virtual

Called when the display is updated to display arbitrary visual elements in the editor views.

Note: This function is called in a thread context. See the important information about threading.; Make sure this function is used only when the user is somehow working with the scene hook plugin, so that other plugins can also use this hook when it is their turn.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bd	The active editor view. Cinema 4D owns the pointed base draw.
[in]	bh	The helper for active the editor view. The caller owns the pointed view helper.
[in]	bt	The calling thread. Can be nullptr. Cinema 4D owns the pointed thread.
[in]	flags	The draw flags: SCENEHOOKDRAW

Returns: true if successful, otherwise false.

◆ DisplayControl()

virtual Bool DisplayControl	(	BaseDocument *	doc,
		BaseObject *	op,
		BaseObject *	chainstart,
		BaseDraw *	bd,
		BaseDrawHelp *	bh,
		ControlDisplayStruct &	cds
	)		const

virtual

Called to set information about how the active object should be displayed.

Parameters

[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	op	The active object. Cinema 4D owns the pointed object.
[in]	chainstart	The start of the object chain. Cinema 4D owns the pointed object.
[in]	bd	The active editor view. Cinema 4D owns the pointed base draw.
[in]	bh	The helper for active the editor view. The caller owns the pointed view helper.
[in]	cds	The display control settings.

Returns: true if successful, otherwise false.

◆ InitDisplayControl()

virtual Bool InitDisplayControl	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseDraw *	bd,
		const AtomArray *	active
	)

virtual

Initialize resources for the display control used in DisplayControl.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bd	The active editor view. Cinema 4D owns the pointed base draw.
[in]	active	The active objects array. Cinema 4D owns the pointed array.

Returns: true if successful, otherwise false.

◆ FreeDisplayControl()

virtual void FreeDisplayControl ( )

virtual

Free resources allocated in InitDisplayControl.

◆ Visit()

virtual EXECUTIONRESULT Visit	(	BaseSceneHook *	node,
		BaseDocument *	doc,
		BaseThread *	bt,
		BaseObject *	op,
		EXECUTIONFLAGS	flags
	)

virtual

Called for the traversed objects during pre-pass and post-pass of Cinema 4D according to the EXECUTIONFLAGS set up during AddToExecution. You should make use of this mechanism when your scene hook has to traverse the whole object hierarchy, because it's much faster if there's just one common traversal for all scene hooks (each object of the hierarchy has to be loaded into CPU cache just once and can then be handled by all scene hooks).

Note: This function is called in a thread context. See the important information about threading.

Parameters

[in]	node	The BaseSceneHook connected with the SceneHookData instance. Equal to `static_cast`<BaseSceneHook*>Get(). Provided for speed and convenience. Cinema 4D owns the pointed scene hook.
[in]	doc	The active document. Cinema 4D owns the pointed document.
[in]	bt	The calling thread. Can be nullptr. Cinema 4D owns the pointed thread.
[in]	op	The object being visited currently. Cinema 4D owns the pointed object.
[in]	flags	The execution flags: EXECUTIONFLAGS

Returns: The execution result: EXECUTIONRESULT

Detailed Description

Public Member Functions

Init/Free SceneHook

Execute

DisplayControl

Additional Inherited Members

Member Function Documentation

◆ InitSceneHook()

◆ FreeSceneHook()

◆ Execute()

◆ AddToExecution()

◆ MouseInput()

◆ KeyboardInput()

◆ GetCursorInfo()

◆ Draw()

◆ DisplayControl()

◆ InitDisplayControl()

◆ FreeDisplayControl()

◆ Visit()