Class RadiosityEffect
See Also: : Class ObjLightDesc, Class RadiosityInterface, Class IRadiosityEffectExtension, Class NodeDisplayCallback, Class IRadiosityPreferences
class RadiosityEffect : public SpecialFX
Description:
This class is only available in release 5 or later.
The class provides the interfaces for creating Advanced Lighting plug-ins in 3ds max. RadiosityEffect plug-ins are controlled through the Advanced Lighting dialog from the render menu.
A RadiosityEffect behaves as a light in the scene. An implementation of RadiosityEffect must also provide an implementation of ObjLightDesc, to be returned from RadiosityEffect::CreateLightDesc(). This ObjLightDesc is then used by the renderer to apply the radiosity light during a render.
The architecture is designed to support scene based lighting solvers (which use a precalculated solution), as well as image based solvers (which calculate their solution at render time). The method RunProcess() and its relatives, StopProcess(), AbortProcess(), and WaitForCompletion() are called by the system to request processing of a scene based solution. Image based solvers only need stub implementations of these methods.
See also Class NodeDisplayCallback. A RadiosityEffect can use a NodeDisplayCallback to control the viewport display of scene geometry. In particular, it is possible for a lighting solution to be displayed interactively in the viewport if the NodeDisplayCallback provides geometry with appropriate vertex illumination.
A RadiosityEffect may want to reference objects in the scene to detect events which invalidate its lighting solution. A problem arises that the RadiosityEffect can become inundated with reference messages, so to address this problem the RadiosityEffect should ignore any message where the PART_EXCLUDE_RADIOSITY flag is set in the PartID of the message. Any message where ((partID|PART_EXCLUDE_RADIOSITY)!=0) is an event that the system deems should not invalidate the radiosity, for example, when texture display in viewport is turned on or off.
See also IsInterestedInChannels() in Class IRadiosityEffectExtension.
All methods of this class are implemented by the plug-in.
Methods:
Prototype:
virtual void SetActive(bool active, TimeValue t)
Remarks:
Enables or disables the radiosity effect. Corresponds to the Active checkbox in the Advanced Lighting dialog. Although a TimeValue parameter is passed to this method, the active state of the plug-in is not animatable. Plug-ins should call the default implementation of SetActive(), optionally adding their own code.
Parameters:
bool active
Specifies whether the plug-in is active or inactive
TimeValue t
Specifies the current scene time when the method is called.
Prototype:
virtual IOResult Merge(ILoad* iload, )
Remarks:
Reserved for future versions. Not currently used
Default Implementation:
{ return IO_OK; }
Prototype:
virtual RadiosityParamDlg *CreateParamDlg(IRendParams *ip)
Remarks:
This method creates and returns a new instance of RadiosityParamDlg to manager the user interface. This displays one or more rollouts in the Advanced Lighting dialog. A typical implementation would call ClassDesc2::CreateParamDialogs() to instantiate the RadiosityParamDlg.
Parameters:
IRendParams *ip
This is the interface given to the plug-in so it may display its parameters.
Return Value:
The instance of RadiosityParamDlg to manager the plug-in’s UI
Default Implementation:
{ return NULL; }
Prototype:
virtual BOOL SetDlgThing(RadiosityParamDlg *ip)
Remarks:
Implement this if you are using the ParamMap2 AUTO_UI system and the RadiosityEffect 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 in a texture map plug-in).
Parameters:
RadiosityParamDlg *ip
Points to the ParamDlg.
Return Value:
Return TRUE if you process the dialog; otherwise FALSE
Default Implementation:
{ return FALSE; }
Prototype:
virtual bool UseLight(INode* node)
Remarks:
Returns whether the given light should render it’s illumination in the production render. If the return value is true, the light is disabled while rendering.
This is used to allow the radiosity plug-in to override lights in the scene with light from it’s own solution.
Parameters:
INode* node
The INode of the light.
Return Value:
Return true if the light should be enabled while rendering; or false if it should be disabled
Default Implementation:
{ return true; }
Prototype:
virtual int NumLightDesc() const = 0
Return Value:
The number of ObjLightDesc objects the RadisoityEffect will return from CreateLightDesc()
Prototype:
virtual void CreateLightDesc(ObjLightDesc** buffer) = 0
Remarks:
Creates light objects that the renderer can use to get the RadiosityEffect’s contribution. CreateLightDesc() creates a number of ObjLightDesc objects indicated by NumLightDesc(), and stores their addresses in the buffer. Caller is responsible for ensuring that the buffer is large enough.
Note: the caller will delete the ObjLightDesc objects when the render is completed, so this method should dynamically allocate the ObjLightDesc instances, rather than providing static instances.
Parameters:
ObjLightDesc** buffer
The buffer into which the ObjLightDesc pointers should be stored.
Prototype:
virtual void RunProcess(TimeValue t, RenderGlobalContext* rgc, bool interactiveRender) = 0
Remarks:
Called by the system to start the radiosity processing. This should start the process from the beginning, or where it stopped previously, if applicable. The method should launch a separate thread and return immediately; the system will call WaitForCompletion() to wait for the thread to complete.
This is specific to solvers which use a pre-calculated solution. Other solvers need only a stub implementation.
Parameters:
TimeValue t
Specifies the scene time when the method is called.
RenderGlobalContext* rgc
This can be used to retrieve information about the global rendering environment.
bool interactiveRender
Specifies whether the lighting solution is being calculated for interactive rendering. Note that the default renderer does not support interactive rendering with Advanced Lighting, but other plug-in renderers might potentially do so, in which case the RadiosityEffect should attempt to generate a fast, lower quality solution for interactive display.
Prototype:
virtual void StopProcess(bool allowAbort = true) = 0
Remarks:
Stop the lighting calculation. If possible, the RadiosityEffect should attempt to reach an intermediate solution, so that calculation can be continued later. However, this may take awhile, and If allowAbort is true, the RadiosityEffect is expected to prompt the user with a dialog, asking if they wish to abort.
Parameters:
bool allowAbort node
If true, the RadisoityEffect is expected to prompt the user with a dialog so they may abort the process of stopping the calculation and saving an intermediate solution
Prototype:
virtual void AbortProcess() = 0
Remarks:
Abort the lighting calculation. The RadiosityEffect should to abort immediately, without saving an intermediate solution.
Prototype:
virtual void WaitForCompletion(RendContext* rc = NULL, DWORD timeout = INFINITE) = 0
Remarks:
This is called by the system when waiting for the lighting calculation to finish. This method should not return to the caller until the calculation is complete, or when the timeout (in milliseconds) expires. The RendContext can be used to display the progress of the calculation to the user, and to check if the cancel button is pressed.
Parameters:
RendContext* rc
Use this to display a progress bar for the user, or to detect when the user hits the cancel button.
DWORD timeout
An amount of time (measured in milliseconds) that the system is willing to wait. The method should measure its own running time and return to the caller when the timeout expires.
Prototype:
virtual bool NeedsCamVerts(TimeValue t, RenderGlobalContext* rgc, bool interactiveRender, bool saveMem)
Remarks:
Indicates whether the RadiosityEffect plug-in wants the renderer to build camera-space vertices.
Parameters:
TimeValue* t
Specifies the current scene time when the method is called.
RenderGlobalContext* rgc
This can be used to retrieve information about the global rendering environment.
bool interactiveRender
Specifies whether the lighting solution is being calculated for interactive rendering. Note that the default renderer does not support interactive rendering with Advanced Lighting, but other plug-in renderers might potentially do so, in which case the RadiosityEffect should attempt to generate a fast, lower quality solution for interactive display.
bool saveMem
True if the user has selected “Conserve Memory” in the Render Dialog, under the “MAX Default Scanline A-Buffer” rollout, or if the render is occurring in the material editor.
Return Value:
True if the RadiosityEffect wants the renderer to calculate camera-space vertices, false otherwise.
Default Implementation:
{ return false; }