Callbacks for Self-Installing Plug-ins
 
 
 

Callbacks for Self-Installing Plug-ins

A plug-in must implement the XSILoadPlugin callback, which is responsible for registering plug-in items such as commands and properties.

Plug-in items properties are implemented by callback functions. For example, to implement a custom command, you write an Execute callback. If the command is named, "MyCommand", then Softimage expects a callback function named "MyCommand_Execute".

If the name of a plug-in item includes spaces, you must remove the spaces from the callback function names. For example, if a property is named "My Custom Property"), then the Define callback function for the property must be named "MyCustomProperty_Define".

Callbacks are available in this section organized by plug-in type:


Plug-in Callbacks

Callback Description
XSILoadPlugin When Softimage starts, it looks in certain folders, such as the Application\Plugins folders in the User location and in workgroups, for plug-ins that implement XSILoadPlugin. When Softimage finds a self-installing plug-in, Softimage loads the plug-in and calls its XSILoadPlugin function.

XSILoadPlugin registers plug-in items (such as commands, menus, and properties) and sets plug-in properties (such as the version number and the location of the help file).
XSIUnloadPlugin Fired when Softimage unloads the plug-in.

Command Callbacks

Callback Description
Execute (Command) Fired when the command is invoked. Gets the command arguments (if any), executes the command, and returns the result (if any).
Init (Command) Optional. Fired the first time a command is invoked after the plug-in is loaded. Specifies the return value and arguments of the command.
Undo Optional, C++ API only. Fired when a custom command is being undone. The return value is ignored.
Redo Optional, C++ API only. Fired when a custom command is being redone. The return value is ignored.
TermUndoRedo Optional, C++ API only. Fired when a custom command undo event is removed from the Softimage undo stack. This callback is typically used to release any memory required for undoing this command. The return value is ignored.
Term Optional. Fired when a plug-in is removed from Softimage (just before Softimage calls XSIUnloadPlugin). For example, Term is triggered when you exit Softimage or unload the plug-in.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Operator Callbacks

Callback Description
Define Fired when a operator is applied to an object (for example, using ProjectItem.AddCustomOp or Parameter.AddCustomOp). This is where you add custom parameters to the operator.
DefineLayout Fired immediately after the Define callback is fired for the first time in a Softimage session. You can also force it to fire when you use the PPG.Refresh method. This is where you define the layout of UI controls on the property page for the operator's parameters.
Init (Operator) Fired when an instance of the operator is instantiated. Unlike Define, Init is called both for newly created operators and for operators loaded from persistence. This is where you initialize cached operator data.
OnInit Fired each time the property page is displayed (for example, each time the property is inspected with InspectObj). Allows you to set the initial values of the UI controls.
OnChanged Fired each time a UI control changes value.
OnClicked Fired when a command button is clicked.
OnClosed Fired when the property page is closed via the Close button or the keyboard shortcut.
OnTab Fired when a user clicks a tab.
PPGEvent C++ and C# callback for all property page events (OnInit, OnChanged, OnClicked, OnClosed, and OnTab).
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).
Update Fired whenever an operator is expected to evaluate itself. This is the most important callback, called whenever an operator is expected to evaluate itself.
Note If there are multiple outputs the Update function is called once per output port.

Primitive Callbacks

Callback Description
Define Fired whenever the custom primitive is created. This is where you can add parameters to the custom primitive.
DefineLayout Fired immediately after the Define callback is fired for the first time in a Softimage session. You can also force it to fire when you use the PPG.Refresh method. This is where you define the layout of UI controls on the property page.
PPGEvent C++ callback for all property page events.
Draw Fired when there is a request for the custom primitive to be drawn. At this point the GL state is setup and the plug-in is expected to draw the primitive. The drawing coordinates are set to the object's local space.
BoundingBox Fired when there is a request for the custom primitive's Bounding Box. The plug-in is to populate the lower and upper bounds of the Bounding Box via the callback context attributes.
ConvertToGeom Fired when the custom primitive is passed into the CreatePrim or SIConvert commands. The plug-in is to update the Geometry structure retrieved from the callback to perform the geometry conversion. Only PolygonMesh is currently supported. The 'CustomPrimitiveContext' contains a CustomPrimitiveContext::GetGeometry() method that will return a Geometry object. Since this callback currently only supports PolygonMesh, it is safe to expect a PolygonMesh object, however for future extensibility, it is recommended to check for a valid PolygonMesh.

Property Callbacks

Callback Description
Define Fired when a property is added to an object (for example, using SceneItem.AddProperty, Renderer.AddProperty, etc.). This is where you add parameters to the property.
DefineLayout Fired immediately after the Define callback is fired for the first time in a Softimage session. You can also force it to fire when you use the PPG.Refresh method. This is where you define the layout of UI controls on the property page.
OnInit Fired each time the property page is displayed (for example, each time the property is inspected with InspectObj). Allows you to change and redraw the UI controls.
OnChanged Fired each time a UI control changes value.
OnClicked Fired when a command button is clicked.
OnClosed Fired when the property page is closed via the Close button or the keyboard shortcut.
OnTab Fired when a user clicks a tab.
PPGEvent C++ and C# callback for all property page events (OnInit, OnChanged, OnClicked, OnClosed, and OnTab).
Term Fired when a property is deleted.
OnBeginValueChange (GridData) Fired before applying modifications to a grid data parameter.
OnEndValueChange (GridData) Fired after modifications have been applied to a grid data parameter.
OnBeginSelectionChange (GridData) Fired before applying a selection change to a grid widget associated with a grid data parameter.
OnEndSelectionChange (GridData) Fired after a selection change has been applied to a grid widget associated with a grid data parameter.
OnButtonClicked (GridData) Fired when a button gets clicked in a grid widget associated with a grid data parameter.
OnHeaderDoubleClick (GridData) Fired when a header gets double-clicked in a grid widget associated with a grid data parameter.
OnContextMenuInit (GridData) Fired when a mouse right-click occurs over a grid widget associated with a grid data parameter.
OnContextMenuSelected (GridData) Fired when a contextual menu item is selected over a grid widget associated with a grid data parameter.

Event Callbacks

Callback Description
OnEvent Fired when the associated event occurs (for example, the OnEvent callback for a siOnSelectionChange event fires when a user selects or deselects objects).
Term Fired when a property is deleted.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Filter Callbacks

Callback Description
Match Fired when a user selects objects in 3D views and the schematic. Match determines whether an element matches the filter requirements.
Subset Fired when a user selects subcomponents in a 3D view, or to filter the nodes displayed in an explorer view. Subset takes a collection of elements (objects or subcomponents) and determines the subset of elements that match the filter requirements.
IsApplicable Fired by Softimage to determine whether a filter applies to the current selection (for example, a subcomponent filter does not apply to 3D objects).
Init (Filter) Fired after the plug-in loaded (that is, after XSILoadPlugin returns). For example, Init is fired when you start Softimage or load the plug-in in the Plugin Manager.
Term Fired when a plug-in is removed from Softimage (just before Softimage calls XSIUnloadPlugin). For example, Term is triggered when you exit Softimage or unload the plug-in.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Graphic Sequencer Callbacks

Callback Description
Init (Graphic Sequencer) Fired after the plug-in loaded (that is, after XSILoadPlugin returns). For example, Init is fired when you start Softimage or load the plug-in in the Plugin Manager. This is where you register a viewport mode or callback with the graphic sequencer.
Execute (Graphic Sequencer) Executes the viewport mode or callback.
Term (Graphic Sequencer) Optional. This is where you initialize and free any instance-specific data used by a viewport mode or callback.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Menu Callbacks

Callback Description
Init (Menu) For dynamic menus, this callback is fired every time the menu is accessed. For static menus, this callback is fired the first time the menu is accessed after the plug-in is loaded. This is where you add items and commands to a menu.
Menu Item Callbacks Fired when a user selects the menu item. The name of a menu item callback is specified in the call to Menu.AddCallbackItem in the Init callback.
Term Fired when a plug-in is removed from Softimage (just before Softimage calls XSIUnloadPlugin). For example, Term is triggered when you exit Softimage or unload or update the plug-in.

Term is fired only if Init (Menu) was fired at some point. If the menu was never opened, then Term has nothing to do.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Custom Display (View) Callbacks

Callback Description
Init (Custom Display) Fired after the plug-in loaded (that is, after XSILoadPlugin returns). For example, Init is fired when you start Softimage or load the plug-in in the Plugin Manager. Used to initialize the custom display window.
Notify Fired when something happens in the scene, such as a parameter change or selection change.
Term (Custom Display) Fired when the top-level window is destroyed.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Renderer Callbacks

Callback Description
Init (Renderer) Fired after the plug-in loaded (that is, after XSILoadPlugin returns). For example, Init is fired when you start Softimage or load the plug-in in the Plugin Manager. Used to tell Softimage which process types the rendering engine supports, which custom property to use for the renderer options, and which image file formats it can output.
Process Fired whenever the rendering engine is requested to perform a process (for example, render a frame). This is the most important callback for a custom renderer plug-in.
Abort Fired when the Render Manager needs to abort a process. This callback function is simply the messenger, it should trigger an abort and return as quickly as possible.
Query Fired when the Render Manager needs to query the renderer for some information.
Quality Optional. Called by the Render Manager to both return the current "quality" level of the render options and to set a preset for the given quality level.
Cleanup Optional. Fired when the current scene is being destroyed, or if the specific render process (region, pass render, etc.) requests that data be cleaned up after the process has completed.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

ICENode Callbacks

Callback Description
Init (ICE Nodes) Fired after the plug-in loaded (that is, after XSILoadPlugin returns). For example, Init is fired when you start Softimage or load the plug-in in the Plugin Manager. This is where you initialize cached user data.
BeginEvaluate This callback must be implemented for each registered ICENode. The evaluation phase can be called in single-threaded or in multi-threaded context depending on the threading processing mode in use.
EndEvaluate This optional callback is a single-threaded task for freeing up memory, cleaning resources, or anything required to undone the work performed in BeginEvaluate.
Evaluate This optional callback is called during a single-threaded phase where memory is usually allocated in preparation for the multi-threaded evaluation phase.
SubmitEvaluationPhaseInfo This callback is required in the multi-phase evaluation mode for specifying the ports to be pulled for the current evaluation phase.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Shader Callbacks

Callback Description
DefineInfo Fired after the shader plug-in loads (that is, after XSILoadPlugin returns). For example, DefineInfo is fired when you start Softimage or load the plug-in in the Plugin Manager. This is where you register a custom shader definition so that it will appear in the Render Tree preset list.
Define (Shader) Fired when a shader is instantiated in the render tree or by connecting it to a parameter. This callback is responsible for populating the definition, including the list of parameters and any PPGLayout required by the custom shader.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Shader Parser Callbacks

Callback Description
QueryParserSettings Fired at startup or when updating the preset manager prior to when the ParseInfo callback fires. Tells Softimage where to find the files to parse and what extension(s) to look for.
ParseInfo Fired when Softimage parses a file matching the location and type set in the QueryParserSettings callback. The ParseInfo callback is responsible for building the list of shader definitions from the information in the file.
Parse Fired when a shader implemented with this parser's language is instantiated. Parses the associated shader file and populates the shader definition with its parameter definitions and attributes.
Unload, Reload Fired when the plug-in is cached (reloaded) and uncached (unloaded). By default, all plug-ins are cached, but users can remove a plug-in from the cache (by right-clicking a plug-in in the plug-in tree and clearing the Cached checkmark).

Realtime Shader Callbacks

Callback Description
RTS_GetVersion (Realtime Shaders) Must be implemented by every Realtime Shader plug-in.
Init (Realtime Shaders) Fired the first time the shader is instantiated in a session.
GetAttributeList Enables a shader to tell Softimage which attribute it needs in order to perform rendering.
Execute (Realtime Shaders) Main entry point for rendering the realtime shader.
Term (Realtime Shaders) Fired when the shader is deleted.