Public Types | Public Member Functions

RadiosityEffect Class Reference

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


Search for all occurrences

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:
Inheritance graph
[legend]

List of all members.

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


Member Function Documentation

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

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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