Class SpecialFX
See Also: Class ReferenceTarget, Class SFXParamDlg, Class IRendParams, Class Atmospheric, Class Effect, Class AppendGizmoRestore, Class DeleteGizmoRestore.
class SpecialFX : public ReferenceTarget
Description:
This class is available in release 3.0 and later only.
This is the base class for Atmospheric, Renderer Effect, and Shader Plug-Ins. It contains a few methods common to each of those plug-in classes.
Data Members:
public:
TSTR name;
This is the name which appears in Track View.
Methods:
public:
Prototype:
virtual BOOL Active(TimeValue t);
Remarks:
Implemented by the Plug-In.
Returns TRUE if the effect is active; otherwise FALSE.
Parameters:
TimeValue t
The time at which to check.
Default Implementation:
{ return FALSE; }
Prototype:
virtual TSTR GetName();
Remarks:
Implemented by the Plug-In.
This method is used to retrieve the name for the plug-in. This name will appear in the track view and the list of current atmospheric or rendering effects.
Prototype:
virtual void Update(TimeValue t, Interval& valid);
Remarks:
Implemented by the Plug-In.
This method is called once per frame when the renderer begins. This gives the atmospheric or rendering effect the chance to cache any values it uses internally so they don't have to be computed on every frame.
Parameters:
TimeValue t
The current time of the call.
Interval& valid
The validity interval of the cache created by the plug-in. The plug-in may set this for its own use. The plug-in can then check if the cache is up to date and update it if not.
Prototype:
virtual SFXParamDlg *CreateParamDialog(IRendParams *ip);
Remarks:
This method is available in release 4.0 and later only.
This method creates and returns a new instance of a class derived from SFXParamDlg to manage the user interface. This put up a modal dialog that lets the user edit the plug-ins parameters.
Parameters:
IRendParams *ip
This is the interface given to the plug-in so it may display its parameters.
Default Implementation:
{ return NULL; }
Prototype:
virtual BOOL SetDlgThing(SFXParamDlg* dlg);
Remarks:
This method is available in release 4.0 and later only.
Implement this if you are using the ParamMap2 AUTO_UI system and the effect has secondary dialogs that don't have the effect as their 'thing'. Called once for each secondary dialog for you to install the correct thing.
Note: Developers needing more information on this method can see the remarks for MtlBase::CreateParamDlg() which describes a similar example of this method in use (in that case it's for use by a texture map plug-in).
Parameters:
SFXParamDlg* dlg
Points to the ParamDlg.
Return Value:
Return TRUE if you process the dialog; otherwise FALSE.
Default Implementation:
{ return FALSE; }
Prototype:
virtual int NumGizmos();
Remarks:
Implemented by the Plug-In.
If an atmospheric or rendering effect has references to gizmos or other objects in the scene it can optionally provide access to the object list. This method returns the number of gizmos or objects the plug-in has.
Default Implementation:
{return 0;}
Prototype:
virtual INode *GetGizmo(int i);
Remarks:
Implemented by the Plug-In.
Returns a pointer to the 'i-th' gizmo or object node.
Parameters:
int i
The index of the gizmo to return.
Default Implementation:
{return NULL;}
Prototype:
virtual void DeleteGizmo(int i);
Remarks:
Implemented by the Plug-In.
Deletes the 'i-th' gizmo or object from those used by the plug-in.
Parameters:
int i
The index of the gizmo to delete.
Default Implementation:
{}
Prototype:
virtual void AppendGizmo(INode *node);
Remarks:
Implemented by the Plug-In.
Adds the specified node to the end of the list of gizmos used by the plug-in.
Parameters:
INode *node
Points to the node to append.
Default Implementation:
{}
Prototype:
virtual BOOL OKGizmo(INode *node);
Remarks:
Implemented by the Plug-In.
This method is called to approve a node for possible use as gizmo. Return TRUE if the node is okay; otherwise FALSE.
Parameters:
INode *node
The node to check.
Default Implementation:
{ return FALSE; }
Prototype:
virtual void EditGizmo(INode *node);
Remarks:
Implemented by the Plug-In.
This method is called to select the specified gizmo and displays parameters for it (if any).
In the Special Effects section of the light dialog there is a button labelled 'Setup'. The Setup button brings up the Environment dialog (for Atmospherics) or the Render Effects dialog (for Render Effects) and selects the choosen effect. It also selects the "gizmo" within that effect, so if there are particular parameters for each gizmo the user will see them. Pressing that button causes this method to be called.
Parameters:
INode *node
The gizmo node.
Default Implementation:
{}
Prototype:
virtual void InsertGizmo(int i, INode *node);
Remarks:
Implemented by the Plug-In.
Inserts the specified gizmo node into the list of gizmos. This method must be defined to use the DeleteGizmoRestore class.
Parameters:
int i
The zero based index of the position in the list of where the insertion should take place.
INode *node
The gizmo node to insert.
Default Implementation:
{ assert(0); }
Prototype:
IOResult Save(ISave *isave);
Remarks:
Implemented by the System.
To facilitate naming atmospheric or rendering effects, a 'name' string has been added to the base class. This method should be called from the developers sub-classed Atmospheric or Effects plug-in to save the name.
Prototype:
IOResult Load(ILoad *iload);
Remarks:
Implemented by the System.
To facilitate naming atmospheric or rendering effects, a 'name' string has been added to the base class. This method should be called from the developers sub-classed Atmospheric or Effects plug-in to load the name.