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:
| 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. |
| 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). |
| 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.
|
| 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. |
| 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. |
| 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). |
| 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). |
| 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). |
| 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). |
| 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). |
| 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). |
| 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). |
| 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). |
| 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). |
| 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. |