This reference page is linked to from the following overview topics: Plug-in Base Classes.

Detailed Description

See also:: Class ObjLightDesc, Class RadiosityInterface, Class IRadiosityEffectExtension, Class NodeDisplayCallback, Class IRadiosityPreferences

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.

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 virtual.

#include <radiosity.h>

Inheritance diagram for RadiosityEffect:

Public Types
enum	CompletionCode { PROCESS_COMPLETED, PROCESS_TIMED_OUT, PROCESS_CANCELED, PROCESS_ABORTED }
Public Member Functions
RefResult	NotifyRefChanged (Interval changeInt, RefTargetHandle hTarget, PartID &partID, RefMessage message)
	Receives and responds to messages.
SClass_ID	SuperClassID ()
	Retrieves a constant representing the type of the plugin.
IOResult	Save (ISave *isave)
	Saves name.
IOResult	Load (ILoad *iload)
	Loads name.
virtual void	SetActive (bool active, TimeValue t)
	Enables or disables the radiosity effect.
virtual IOResult	Merge (ILoad *iload, const Class_ID &id)
	Merges this radiosity solution into the current solution.
virtual RadiosityParamDlg *	CreateParamDialog (IRendParams *ip)
	Put up a modal dialog that lets the user edit the plug-ins parameters.
virtual BOOL	SetDlgThing (RadiosityParamDlg *dlg)
	Called once for each secondary dialog for you to install the correct thing.
virtual bool	UseLight (INode *node, bool recalcSolution=false)
	Returns whether the given light should render it's illumination in the production render.
virtual int	NumLightDesc () const =0
	Create light objects that the renderer can use to get the radiosity contribution.
virtual void	CreateLightDesc (ObjLightDesc **buffer)=0
	Creates light objects that the renderer can use to get the RadiosityEffect's contribution.
virtual void	RunProcess (TimeValue t, RenderGlobalContext *rgc, bool interactiveRender)=0
	Called by the system to start the radiosity processing.
virtual void	StopProcess (bool allowAbort=true)=0
	Stop the lighting calculation.
virtual void	AbortProcess ()=0
	Abort the lighting calculation.
virtual CompletionCode	WaitForCompletion (RendContext *rc=NULL, DWORD timeout=INFINITE)=0
	Wait for radiosity process to complete.
virtual bool	NeedsCamVerts (TimeValue t, RenderGlobalContext *rgc, bool interactiveRender, bool saveMem)
	Called right before RunProcess.

Member Enumeration Documentation

enum CompletionCode

Search for all occurrences

Enumerator:

PROCESS_COMPLETED	Search for all occurrences
PROCESS_TIMED_OUT	Search for all occurrences
PROCESS_CANCELED	Search for all occurrences
PROCESS_ABORTED	Search for all occurrences

                        {
        PROCESS_COMPLETED,
        PROCESS_TIMED_OUT,
        PROCESS_CANCELED,
        PROCESS_ABORTED
    };

Member Function Documentation

RefResult NotifyRefChanged	(	Interval	changeInt,
		RefTargetHandle	hTarget,
		PartID &	partID,
		RefMessage	message
	)		`[inline, virtual]`

Search for all occurrences

Receives and responds to messages.

A plugin which makes references must implement a method to receive and respond to messages broadcast by its dependents. This is done by implementing NotifyRefChanged(). The plugin developer usually implements this method as a switch statement where each case is one of the messages the plugin needs to respond to. The Method StdNotifyRefChanged calls this, which can change the partID to new value. If it doesn't depend on the particular message& partID, it should return REF_DONTCARE.

For developer that need to update a dialog box with data about an object you reference note the following related to this method: This method may be called many times. For instance, say you have a dialog box that displays data about an object you reference. This method will get called many time during the drag operations on that object. If you updated the display every time you'd wind up with a lot of 'flicker' in the dialog box. Rather than updating the dialog box each time, you should just invalidate the window in response to the NotifyRefChanged() call. Then, as the user drags the mouse your window will still receive paint messages. If the scene is complex the user may have to pause (but not let up on the mouse) to allow the paint message to go through since they have a low priority. This is the way many windows in 3ds Max work.

Parameters:

changeInt	- This is the interval of time over which the message is active. Currently, all plug-ins will receive FOREVER for this interval.
hTarget	- This is the handle of the reference target the message was sent by. The reference maker uses this handle to know specifically which reference target sent the message.
partID	- This contains information specific to the message passed in. Some messages don't use the partID at all. See the section List of Reference Messages for more information about the meaning of the partID for some common messages.
message	- The message parameters passed into this method is the specific message which needs to be handled.

Returns:: The return value from this method is of type RefResult. This is usually REF_SUCCEED indicating the message was processed. Sometimes, the return value may be REF_STOP. This return value is used to stop the message from being propagated to the dependents of the item.

Implements ReferenceMaker.

                                               {return REF_SUCCEED;}

SClass_ID SuperClassID ( ) [inline, virtual]

Search for all occurrences

Retrieves a constant representing the type of the plugin.

Returns:: A super class id that uniquely identifies the type (category) of the plugin. Note that several plugin classes can be of the same type, thus return the same super class id. Plugins are uniquely identified by their class ids. List of Super Class IDs.

See also:: SClass_ID

Reimplemented from ReferenceTarget.

{return RADIOSITY_CLASS_ID;}

IOResult Save ( ISave * isave ) [inline, virtual]

Search for all occurrences

Saves name.

These should be called at the start of a plug-in's save and load methods.

Reimplemented from SpecialFX.

{ return SpecialFX::Save(isave); }

IOResult Load ( ILoad * iload ) [inline, virtual]

Search for all occurrences

Loads name.

These should be called at the start of a plug-in's save and load methods.

Reimplemented from SpecialFX.

{ return SpecialFX::Load(iload); }

virtual void SetActive	(	bool	active,
		TimeValue	t
	)		`[inline, virtual]`

Search for all occurrences

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:

active	- Specifies whether the plug-in is active or inactive
t	- Specifies the current scene time when the method is called.

    {
        if (active ^ (TestAFlag(A_ATMOS_DISABLED) == 0)) {
            if (active) {
                ClearAFlag(A_ATMOS_DISABLED);
            }
            else {
                SetAFlag(A_ATMOS_DISABLED);
            }
            NotifyDependents(FOREVER, (PartID)PART_ALL, REFMSG_CHANGE);
        }
    }

virtual IOResult Merge	(	ILoad *	iload,
		const Class_ID &	id
	)		`[inline, virtual]`

Search for all occurrences

Merges this radiosity solution into the current solution.

This method is called for the currently selected radiosity plugin, when merging objects from a file that also has a radiosity plugin. The default behaviour does not merge the solutions.

Parameters:

[in]	iload	- The file loader used to merge this radiosity solution
[in]	id	- Identifies the class of the radiosity plugin being loaded.

Returns:: IO_OK if the merge succeeded.

{ return IO_OK; }

virtual RadiosityParamDlg* CreateParamDialog ( IRendParams * ip ) [inline, virtual]

Search for all occurrences

Put up a modal dialog that lets the user edit the plug-ins parameters.

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:

ip	- This is the interface given to the plug-in so it may display its parameters.

Returns:: The instance of RadiosityParamDlg to manager the plug-in's UI

Reimplemented from SpecialFX.

{ return NULL; }

virtual BOOL SetDlgThing ( RadiosityParamDlg * dlg ) [inline, virtual]

Search for all occurrences

Called once for each secondary dialog for you to install the correct thing.

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'.

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:

dlg	- Points to the ParamDlg.

Returns:: Return TRUE if you process the dialog; otherwise FALSE

Reimplemented from SpecialFX.

{ return FALSE; }

virtual bool UseLight	(	INode *	node,
		bool	recalcSolution = `false`
	)		`[inline, virtual]`

Search for all occurrences

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:

node	- The INode of the light.

Returns:: Return true if the light should be enabled while rendering; or false if it should be disabled

{ return true; }

virtual int NumLightDesc ( ) const [pure virtual]

Search for all occurrences

Create light objects that the renderer can use to get the radiosity contribution.

NumLightDesc returns the number of ObjLightDesc objects the radiosity plugin needs for rendering. CreateLightDesc creates all of the ObjLightDesc objects, and stores their addresses in buffer. Buffer must be large enough to hold all of the addresses.

Returns:: The number of ObjLightDesc objects the RadisoityEffect will return from CreateLightDesc()

virtual void CreateLightDesc ( ObjLightDesc ** buffer ) [pure virtual]

Search for all occurrences

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:

buffer - The buffer into which the ObjLightDesc pointers should be stored.

virtual void RunProcess	(	TimeValue	t,
		RenderGlobalContext *	rgc,
		bool	interactiveRender
	)		`[pure virtual]`

Search for all occurrences

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:

t	- Specifies the scene time when the method is called.
rgc	- This can be used to retrieve information about the global rendering environment.
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.

virtual void StopProcess ( bool allowAbort = true ) [pure virtual]

Search for all occurrences

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:

allowAbort - 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

virtual void AbortProcess ( ) [pure virtual]

Search for all occurrences

Abort the lighting calculation.

The RadiosityEffect should to abort immediately, without saving an intermediate solution.

virtual CompletionCode WaitForCompletion	(	RendContext *	rc = `NULL`,
		DWORD	timeout = `INFINITE`
	)		`[pure virtual]`

Search for all occurrences

Wait for radiosity process to complete.

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:

rc	- Use this to display a progress bar for the user, or to detect when the user hits the cancel button.
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.

virtual bool NeedsCamVerts	(	TimeValue	t,
		RenderGlobalContext *	rgc,
		bool	interactiveRender,
		bool	saveMem
	)		`[inline, virtual]`

Search for all occurrences

Called right before RunProcess.

Indicates whether the RadiosityEffect plug-in wants the renderer to build camera-space vertices.

Parameters:

t	- Specifies the current scene time when the method is called.
rgc	- This can be used to retrieve information about the global rendering environment.
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.
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.

Returns:: True if the RadiosityEffect wants the renderer to calculate camera-space vertices, false otherwise.

      { return false; }

RadiosityEffect Class Reference

Detailed Description

Public Types

Public Member Functions

Member Enumeration Documentation

Member Function Documentation