Class ToneOperator
See Also: Class SpecialFX, Class ToneOperatorInterface, Class IRendParams, Class RendParams, Class RenderGlobalContext, Class RenderMapsContext, Class ShadeContext, Class Interval.
class ToneOperator : public SpecialFX
Description:
This class is available in release 4.0 and later only.
This is the base class for the creation of Tone Operator plug-ins. A Tone Operator performs two functions:
1. It converts physically based values to RGB for filtering and display. The renderer calls the tone operator immediately after Mtl::Shade is called.
2. It balances physical and non-physical lighting.
The tone operator balances the physical and non-physical lighting by providing a scale relationship between them. The scale converts physical candelas to the non-physical value 1.0. Physically based objects in the 3ds max scene use this scale to convert their values for use by the renderer and materials. The tone operator then converts the scaled value to RGB for display.
An example of this is the tone operator for a radiosity plug-in. 3ds max works in a lighting space where values run from 0 to 1 and don't have any meaning. Pre-rendered Reflection maps, Refraction maps and self-illumination maps also use a 0 to 1 scale without any meaning. A radiosity plug-in introduces physical values to 3ds max that range from 0 to 90000 for the sun.
So the question is "How do we mix these values with physical values?" One solution is to use a scale. Physical values are scaled to "3ds max" values. Then they are processed by the shaders and materials, and then the scaled values are converted to RGB by ScaledToRGB.
So the PhysicalUnits, ScalePhysical and ScaleRGB are used to convert from 3ds max lighting values to physical lighting values. We can use this to balance 3ds max lights with physical lights, and to assign physical values to 3ds max lights when we want to use them in a radiosity solution.
The tone operator may include a UI that allows the user to set the scale, or it can set the scale apriori. The scale is also used for reflection maps, which are usually implemented in 32 bit bitmaps. If the scale is set too high, reflection maps can show banding because of rounding errors. If the scale is set too low, reflection maps can wash out because of clipping values to 0…255.
The tone operator uses the standard Special Effects parameter dialog class for its user interface.
Note: typedef SFXParamDlg ToneOpParamDlg;
Methods:
public:
Prototype:
virtual ToneOpParamDlg *CreateParamDialog(IRendParams *ip);
Remarks:
This method creates the rollup pages in the render panel that lets the user edit the tone operator’s parameters. You can use IRendParams::AddRollupPage and IRendParams::DeleteRollupPage to manage your rollup pages directly. Or, if your parameters are stored in a ParamBlock2 object, you can use CreateRParamMap2 and DestroyRParamMap2 to manage the rollups. You may return NULL, if no UI is required.
Parameters:
IRendParams *ip
Points to the render parameter dialog interface. You may call the methods of that class using this pointer.
Return Value:
Pointer to the tone operator dialog.
Default Implementation:
{ return NULL; }
Prototype:
virtual void SetActive(bool active, TimeValue t);
Remarks:
Implemented by the Plug-In.
This method indicates whether the tone operator is active. The default implementation does not use the TimeValue t. The result of the default implementation can be retrieved using SpecialFX::GetActive. If you override this method and change the mechanism for storing this state, you should also override SpecialFX::GetActive so the correct state is returned.
Parameters:
bool active
A boolean indicating if the tone operator is active.
TimeValue t
The time at which the active check is made.
Default Implementation:
if (active ^ (TestAFlag(A_ATMOS_DISABLED) == 0)) {
if (active) {
ClearAFlag(A_ATMOS_DISABLED);
}
else {
SetAFlag(A_ATMOS_DISABLED);
}
NotifyDependents(FOREVER, PART_ALL, REFMSG_CHANGE);
}
Prototype:
virtual BOOL SetDlgThing(ToneOpParamDlg* dlg);
Remarks:
Implemented by the Plug-In.
Implement this if you are using the ParamMap2 AUTO_UI system and the atmosphere 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.
Parameters:
ToneOpParamDlg* dlg
Points tot he tone operator dialog.
Return Value:
Return TRUE if you process the dialog, FALSE otherwise.
Prototype:
virtual bool IsPhysicalSpace() const;
Remarks:
Implemented by the Plug-In.
Returns a boolean which indicates if this tone operator really maps physical values to RGB. This method is provided so shaders can determine whether the shading calculations are in physical or RGB space.
Default Implementation:
{ return true; }
Prototype:
virtual void Update(TimeValue t, Interval& valid);
Remarks:
This method is called once per frame when the renderer begins. This gives the tone operator the chance to cache any values it uses internally so they don't have to be computed on every pixel. But, this method should not be used to perform any very long tasks. This would be the likely method that caches the frames physical scaling value.
Parameters:
TimeValue t
The time at which the rendering is beginning.
Interval& valid
The validity interval for the update.
Default Implementation:
{ }
Prototype:
virtual bool BuildMaps(TimeValue t, RenderMapsContext& rmc);
Remarks:
This method is called for the operator to do any work it needs to do prior to rendering. You may use this method to perform a subrender to sample the rendered output for histogramming or automatic exposure.
Parameters:
TimeValue t
The time at which the rendering is taking place.
RenderMapsContext& rmc
The context of the map rendering.
Return Value:
True means this method succeeded. False means it didn't. This method should return false if it the sub-render fails or if it can't allocate memory or some other error occurs. If BuildMaps returns false, the render is aborted.
Default Implementation:
{ return true; }
Prototype:
virtual void ScaledToRGB(float energy[3]) = 0;
Remarks:
This method maps a scaled energy value into RGB. This version converts a color value. The converted color value is stored in energy.
This method assumes that Update() has been called to cache the various values needed by the tone operator.
Note: By using a float array to pass in color values, we can use the same routine to handle the various classes used to store color information, for example, Color, AColor and Point3.
Parameters:
float energy[3]
The input energy value to convert. The converted color value is stored here as well. The red, green and blue components are stored in that order in the array. The valid ranges are -infinity to +infinity, but the returned value is clipped by the renderer very quickly to [0,1]. The tone operator can do it's own clipping, but it isn't required.
Prototype:
virtual float ScaledToRGB(float energy) = 0;
Remarks:
This method maps a scaled energy value to monochrome. The converted monochrome value is returned. This method assumes that Update() has been called to cache the various values needed by the tone operator.
Parameters:
float energy
The input energy value to convert.
Prototype:
virtual float GetPhysicalUnit(TimeValue t,Interval& valid = Interval(0,0)) const = 0;
Remarks:
Implemented by the Plug-In.
This method returns the physical value that is scaled to 1.
Parameters:
TimeValue t
The time at which to return the value.
Interval& valid = Interval(0,0)
The validity interval for the value.
Prototype:
virtual void SetPhysicalUnit(float value, TimeValue t) = 0;
Remarks:
Implemented by the Plug-In.
This method sets the physical value that is scale to 1. This is simply a programatic method to change the physical scaling of the tone operator. Valid values are (0,+infinity).
Parameters:
TimeValue t
The time at which to set the value.
Interval& valid = Interval(0,0)
The validity interval for the value.
Prototype:
virtual void ScalePhysical(float energy[3]) const = 0;
Remarks:
Implemented by the Plug-In.
This method is used to scale a physical color value so it may be used in the renderer.
This method assumes that Update has been called to cache the various values needed by the tone operator.
Note: By using a float array to pass in color values, we can use the same routine to handle the various classes used to store color information, for example, Color, AColor and Point3.
Parameters:
float energy[3]
The input and output (converted) color value. The colors are stored as red=energy[0], green=energy[1], and blue=energy[2].
Prototype:
virtual float ScalePhysical(float energy) const = 0;
Remarks:
Implemented by the Plug-In.
This method is used to scale a physical monochrome value so it may be used in the renderer.
This method assumes that Update has been called to cache the various values needed by the tone operator.
Parameters:
float energy
The input value to scale.
Return Value:
The scaled output value is returned.
Prototype:
virtual void ScaleRGB(float color[3]) const = 0;
Remarks:
Implemented by the Plug-In.
This method is called to scale RGB values (the inverse of ScalePhysical()).
This method assumes that Update has been called to cache the various values needed by the tone operator.
Parameters:
float color[3]
The input values to scale and storage for the output scaled values as well. The colors are stored as red=energy[0], green=energy[1], and blue=energy[2]. The output values are in the range 0-1.
Prototype:
virtual float ScaleRGB(float color) const = 0;
Remarks:
Implemented by the Plug-In.
This method is called to scale a monochrome value (the inverse of ScalePhysical()).
Parameters:
float color
The input value to scale.
Return Value:
The scaled output value is returned.
Prototype:
bool GetProcessBackground();
Remarks:
Returns the state of A_TONEOP_PROCESS_BG, indicating whether the ToneOperator will be processing the background.
Prototype:
void SetProcessBackground(bool active);
Remarks:
This method allows you to set A_TONEOP_PROCESS_BG.
Parameters:
bool active
TRUE to activate, FALSE to deactivate.