SceneHookData Class Reference

#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 ()
 
GeListNodeGet (void) const
 
virtual Bool Message (GeListNode *node, Int32 type, void *data)
 
virtual void GetBubbleHelp (GeListNode *node, String &str)
 
virtual BaseDocumentGetDocument (GeListNode *node)
 
virtual Int32 GetBranchInfo (GeListNode *node, BranchInfo *info, Int32 max, GETBRANCHINFO flags)
 
virtual Bool IsInstanceOf (const GeListNode *node, Int32 type) const
 
virtual Bool IsDocumentRelated (const GeListNode *node, Bool &docrelated) const
 
virtual Bool Init (GeListNode *node)
 
virtual void Free (GeListNode *node)
 
virtual Bool Read (GeListNode *node, HyperFile *hf, Int32 level)
 
virtual Bool Write (GeListNode *node, HyperFile *hf)
 
virtual Bool CopyTo (NodeData *dest, GeListNode *snode, GeListNode *dnode, COPYFLAGS flags, AliasTrans *trn)
 
virtual Bool GetDDescription (GeListNode *node, Description *description, DESCFLAGS_DESC &flags)
 
virtual Bool GetDParameter (GeListNode *node, const DescID &id, GeData &t_data, DESCFLAGS_GET &flags)
 
virtual Bool SetDParameter (GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_SET &flags)
 
virtual Bool GetDEnabling (GeListNode *node, const DescID &id, const GeData &t_data, DESCFLAGS_ENABLE flags, const BaseContainer *itemdesc)
 
virtual Bool TranslateDescID (GeListNode *node, const DescID &id, DescID &res_id, C4DAtom *&res_at)
 
- Public Member Functions inherited from BaseData
 BaseData ()
 
virtual ~BaseData (void)
 
void Destructor (void)
 

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)
 

DisplayControl

virtual Bool DisplayControl (BaseDocument *doc, BaseObject *op, BaseObject *chainstart, BaseDraw *bd, BaseDrawHelp *bh, ControlDisplayStruct &cds)
 
virtual Bool InitDisplayControl (BaseSceneHook *node, BaseDocument *doc, BaseDraw *bd, const AtomArray *active)
 
virtual void FreeDisplayControl (void)
 

Additional Inherited Members

- Protected Attributes inherited from NodeData
GeListNodeprivate_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]nodeThe 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]docThe active document. Cinema 4D owns the pointed document.
[in]btThe 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]nodeThe 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]docThe 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]nodeThe 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]docThe active document. Cinema 4D owns the pointed document.
[in]btThe calling thread. Can be nullptr. Cinema 4D owns the pointed thread.
[in]priorityThe priority of the call to Execute() in the pipeline: EXECUTIONPRIORITY
[in]flagsThe 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:

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

Parameters
[in]nodeThe 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]listThe 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]nodeThe 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]docThe active document. Cinema 4D owns the pointed document.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]winThe window for the active editor view. Cinema 4D owns the pointed editor window.
[in]msgThe 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]nodeThe 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]docThe active document. Cinema 4D owns the pointed document.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]winThe window for the active editor view. Cinema 4D owns the pointed editor window.
[in]msgThe 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:

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]nodeThe 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]docThe active document. Cinema 4D owns the pointed document.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]xThe X coordinate of the mouse cursor relative to the top-left of the active editor view.
[in]yThe Y coordinate of the mouse cursor relative to the top-left of the active editor view.
[in]bcThe 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]nodeThe 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]docThe active document. Cinema 4D owns the pointed document.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]bhThe helper for active the editor view. The caller owns the pointed view helper.
[in]btThe calling thread. Can be nullptr. Cinema 4D owns the pointed thread.
[in]flagsThe 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 
)
virtual

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

Parameters
[in]docThe active document. Cinema 4D owns the pointed document.
[in]opThe active object. Cinema 4D owns the pointed object.
[in]chainstartThe start of the object chain. Cinema 4D owns the pointed object.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]bhThe helper for active the editor view. The caller owns the pointed view helper.
[in]cdsThe 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]nodeThe 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]docThe active document. Cinema 4D owns the pointed document.
[in]bdThe active editor view. Cinema 4D owns the pointed base draw.
[in]activeThe active objects array. Cinema 4D owns the pointed array.
Returns
true if successful, otherwise false.

§ FreeDisplayControl()

virtual void FreeDisplayControl ( void  )
virtual

Free resources allocated in InitDisplayControl.