This reference page is linked to from the following overview topics: Thread Safety, Plug-in Base Classes.
Detailed Description
- See also:
- Class SpecialFX, Class SFXParamDlg, Class
IRendParams, Class ShadeContext, Class Point3, Class Color, Class Interval.
- Description:
- This is the base class for the creation of Atmospheric plug-ins. Developers may
look to the text below for information on the techniques used to
create these types of effects:
Kenton Musgrave, Darwyn Peachey, Ken Perlin, Steven Worley, Texturing and Modeling A Procedural Approach (Cambridge, MA: Academic Press, Inc., 1994). ISBN: 0-12-228760-6.
Chapter 6 on Hypertexture, particularly the section on 'Raymarching', describes essentially the method 3ds Max uses.
#include <sfx.h>
Inheritance diagram for Atmospheric:
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) |
| IOResult | Load (ILoad *iload) |
| virtual AtmosParamDlg * | CreateParamDialog (IRendParams *ip) |
| virtual BOOL | SetDlgThing (AtmosParamDlg *dlg) |
| virtual void | Shade (ShadeContext &sc, const Point3 &p0, const Point3 &p1, Color &color, Color &trans, BOOL isBG=FALSE)=0 |
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.
Reimplemented in MSPluginSpecialFX< Atmospheric >.
{ 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.
Reimplemented in IXRefAtmospheric.
{ return ATMOSPHERIC_CLASS_ID; }
- Remarks:
- Implemented by the system.
To facilitate naming atmospheric effects, a 'name' string has been added to the base class. This method should be called from the developers sub-classed Atmospheric plug-in to save the name.
Reimplemented from SpecialFX.
Reimplemented in MSPluginSpecialFX< Atmospheric >.
{ return SpecialFX::Save(isave); }
- Remarks:
- Implemented by the system.
To facilitate naming atmospheric effects, a 'name' string has been added to the base class. This method should be called from the developers sub-classed Atmospheric plug-in to load the name.
Reimplemented from SpecialFX.
Reimplemented in MSPluginSpecialFX< Atmospheric >.
{ return SpecialFX::Load(iload); }
| virtual AtmosParamDlg* CreateParamDialog | ( | IRendParams * | ip | ) | [inline, virtual] |
- Remarks:
- This method creates and returns a new instance of a class derived from AtmosParamDlg 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 atmospheric effect so it may display its parameters.
- Returns:
- A new instance of a class derived from
AtmosParamDlg.
Note: typedef SFXParamDlg AtmosParamDlg;
- Default Implementation:
- {return NULL;}
Reimplemented from SpecialFX.
Reimplemented in MSPluginAtmos, and MSAtmosXtnd.
{ return NULL; }
| virtual BOOL SetDlgThing | ( | AtmosParamDlg * | dlg | ) | [inline, virtual] |
- Remarks:
- You should implement this if you are using the ParamMap2
AUTO_UI system and the effect has secondary dialogs that have
something other than the incoming effect as their 'thing'. Called
once for each secondary dialog for you to install the correct
thing. Return TRUE if you process the dialog, FALSE otherwise, in
which case the incoming effect will be set into the dialog.
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:
- AtmosParamDlg* dlg
Points to the ParamDlg.
- Default Implementation:
- { return FALSE; }
Reimplemented from SpecialFX.
Reimplemented in MSPluginAtmos, and MSAtmosXtnd.
{ return FALSE; }
| virtual void Shade | ( | ShadeContext & | sc, |
| const Point3 & | p0, | ||
| const Point3 & | p1, | ||
| Color & | color, | ||
| Color & | trans, | ||
| BOOL | isBG = FALSE |
||
| ) | [pure virtual] |
- Remarks:
- This is the function that is called to apply the atmospheric
effect. The line segment defined by the world space points
p0 and p1 represent a segment of volume that needs to
be shaded. This line segment is a line along the ray defined by the
line between the viewer's eye (the camera) and the pixel being
rendered in the image plane and continuing through world space.
This ray is broken up into segments, with the boundaries defined by
surfaces. If there are no surfaces, there will just be a single
segment from the eye point going off into space (p1 will be
a large number). If there is a surface that is hit, and the surface
is opaque, there will still be one segment from the eye to the
surface. If the surface is transparent there may be two segments,
the segment before and the segment after. Therefore the ray may be
broken up into many segments depending on the number of transparent
surfaces hit.
The shader does not need to be directly concerned with this however. It only knows it's shading the segment between p0 and p1. It will get called repeatedly for different pixels and different segments.
The output of this method is the computed color and transparency.
An example implementation of this method is 3ds Max's Simple Fog. It takes the distance of the line segment and essentially interpolates towards the fog color based on the distance. This is a very simple effect.
3ds Max's Volume Fog traverses along the segment and evaluates its 3D noise function. It integrates the density across the segment, and uses the density to compute the fog color.
- Parameters:
- ShadeContext& sc
The ShadeContext.
const Point3& p0
The start point of the segment to shade. This point (and p1) are in an undefined 'internal' space specific to the renderer (which for the 3ds Max renderer is in fact is camera space). To get to world space the plug-in would call sc.PointTo(p0,REF_WORLD).
const Point3& p1
The end point of the segment to shade.
Color& color
This method shades the volume between p0 and p1 and modifies this color.
Color& trans
This method shades the volume between p0 and p1 and modifies this transparency.
BOOL isBG=FALSE
TRUE if the background is being shaded; otherwise FALSE. If TRUE then p1 will be infinity (a large number). This is used when the option to not fog the background is on.
Implemented in MSPluginAtmos, and MSAtmosXtnd.
