Class IParamBlock
See Also: Class ReferenceTarget, Class IParamArray, Parameter Maps, Class ParamBlockDescID, Class Control.
class IParamBlock : public ReferenceTarget, public IParamArray
Description:
This class provides methods to work with parameter blocks. For more details on parameter blocks see Parameter Blocks.
Methods:
Prototype:
virtual BOOL SetValue(int i, TimeValue t, float v)=0;
Remarks:
Implemented by the System.
Whenever the developer needs to store a value into the parameter block, the SetValue() method is used. There are overloaded functions for each type of value to set (int, float, Point3, and Color). Each method has three parameters. Below is the float version - the others are similar.
Parameters:
int i
This is the index into the ParamBlockDesc array of the parameter to set.
TimeValue t
The time at which to set the value.
float v
The value to store.
Return Value:
If the value was set TRUE is returned; otherwise FALSE is returned.
Prototype:
virtual BOOL SetValue(int i, TimeValue t, int v)=0;
Remarks:
This is the integer version of above.
Prototype:
virtual BOOL SetValue(int i, TimeValue t, Point3& v)=0;
Remarks:
This is the Point3 version of above.
Prototype:
virtual BOOL SetValue(int i, TimeValue t, Color& v)=0;
Remarks:
This is the Color version of above.
Prototype:
virtual BOOL GetValue(int i, TimeValue t, float &v, Interval &ivalid)=0;
Remarks:
Implemented by the System.
Whenever the developer needs to retrieve a value from the parameter block, the GetValue() method is used. There are overloaded functions for each type of value to retrieve (int, float, Point3, and Color).
Important Note: Developers need to do range checking on values returned from a parameter block -- a spinner custom control will not necessarily ensure that the values entered by a user and stored by a parameter block are fixed to the values allowed by the spinner. For example, the spinner control ensures that it only displays, and the user is only allowed to input, values within the specified ranges. However the spinner is just a front end to a controller which actually controls the value. The user can thus circumvent the spinner constraints by editing the controller directly (via function curves in track view, key info, etc.). Therefore, when a plug-in gets a value from a controller (or a parameter block, which may use a controller) it is its responsibility to clamp the value to a valid range.
The GetValue() method updates the interval passed in. This method is frequently used by developers to 'whittle' down an interval. When a parameter of a parameter block is animated, for any given time there is a interval over which the parameter is constant. If the parameter is constantly changing the interval is instantaneous. If the parameter does not change for a certain period the interval will be longer. If the parameter never changes the interval will be FOREVER. By passing an interval to the GetValue() method you ask the parameter block to 'intersect' the interval passed in with the interval of the parameter. Intersecting two intervals means returning a new interval whose start value is the greater of the two, and whose end value is smaller of the two. In this way, the resulting interval represents a combined period of constancy for the two intervals.
This technique is used to compute a validity interval for an object. The developer starts an interval off as FOREVER, then intersects this interval with each of its animated parameters (by calling GetValue()). GetValue() 'whittles' down the interval with each call. When all the parameters have been intersected the result is the overall validity interval of an object at a specific time.
Parameters:
int i
Index into the ParamBlockDesc array of the parameter to retrieve.
TimeValue t
The time at which to retrieving a value.
float v
The value to store for the parameter at the time.
Interval &ivalid
The interval to update.
Return Value:
The return value is TRUE if a value was retrieved. Otherwise it is FALSE.
See Also: Parameter Blocksin the Advanced Topics section, Intervals.
Prototype:
virtual BOOL GetValue(int i, TimeValue t, int &v, Interval &ivalid)=0;
Remarks:
This is the integer version of above.
Prototype:
virtual BOOL GetValue(int i, TimeValue t, Point3 &v, Interval &ivalid)=0;
Remarks:
This is the Point3 version of above.
Prototype:
virtual BOOL GetValue(int i, TimeValue t, Color &v, Interval &ivalid)=0;
Remarks:
This is the Color version of above.
Prototype:
virtual SClass_ID GetAnimParamControlType(int anim)=0;
Remarks:
Implemented by the Plug-In.
Returns the super class ID of a parameters controller.
Parameters:
int anim
Specifies the parameter whose controller super class ID is returned.
Prototype:
virtual ParamType GetParameterType(int i)=0;
Remarks:
Returns the type of the 'i-th' parameter.
Parameters:
int i
The zero based index of the parameter to retrieve. See List of Parameter Types.
Prototype:
virtual DWORD GetVersion()=0;
Remarks:
Implemented by the System.
Returns the parameter block version.
Prototype:
virtual void RemoveController(int i)=0;
Remarks:
Implemented by the System.
Removes the 'i-th' controller.
Parameters:
int i
The parameter index of the controller to remove.
Prototype:
virtual Control* GetController(int i)=0;
Remarks:
Implemented by the System.
Returns the controller of the 'i-th' parameter.
Parameters:
int i
The parameter index of the controller to return.
Prototype:
virtual void SetController(int i, Control *c, BOOL preserveFrame0Value=TRUE)=0;
Remarks:
Implemented by the System.
Sets the 'i-th' parameter controller to c.
Parameters:
int i
The index of the parameter to set.
Control *c
The controller to set.
BOOL preserveFrame0Value=TRUE
If TRUE the controllers value at frame 0 is preserved.
Prototype:
virtual void SwapControllers(int j, int k )=0;
Remarks:
Implemented by the System.
Swaps the two controllers of the parameters whose indices are passed.
Parameters:
int j, int k
The parameter indices whose controllers should be swapped.
Prototype:
virtual int GetRefNum(int paramNum)=0;
Remarks:
Implemented by the System.
Given a parameter index this method will return the reference number of that parameter.
Parameters:
int paramNum
The parameter index.
Prototype:
virtual int GetAnimNum(int paramNum)=0;
Remarks:
Implemented by the System.
Given a parameter index this method will return the anim number.
Parameters:
int paramNum
The parameter index.
Prototype:
virtual int AnimNumToParamNum(int animNum)=0;
Remarks:
Implemented by the System.
Given an anim number this method will return the parameter index.
Parameters:
int animNum
The anim number.
Prototype:
virtual void RescaleParam(int paramNum, float f)=0;
Remarks:
This method is available in release 2.0 and later only.
This is only for use in a ReferenceMaker::RescaleWorldUnits() implementation: The parameter block implementation of RescaleWorldUnits() scales only tracks that have dimension type = stdWorldDim. If letting the parameter block handle the rescaling is not sufficient, call this on just the parameters you need to rescale. For additional details on this method see the sub-section called 'Scaling Parameter Values' in the section Updating MAX 1.0 Plug-Ins to work with MAX 2.0.
Parameters:
int paramNum
The index into the parmeter block of the parameter to rescale.
float f
The value to scale by.
Prototype:
virtual int LastNotifyParamNum()=0;
Remarks:
This method is available in release 2.0 and later only.
Returns the index into a parameter block of the parameter that generated a notification. You can call this method when you get a NotifyRefChanged() message from your parameter block to determine exactly which parameter it was that changed. When you have a very complicated dialog, for instance the Standard material, you can use this to selectively update controls in the dialog instead of updating all of them, which can feel pretty slow to the user. For smaller dialogs it's not worth the trouble.
Sample Code:
case REFMSG_CHANGE:
if (hTarget==pblock) {
int np =pblock->LastNotifyParamNum();
// ...
}
break;
The following methods are not part of class IParamBlock but are available for use:
Prototype:
IParamBlock *CreateParameterBlock(ParamBlockDesc *pdesc, int count);
Remarks:
Implemented by the System.
This method is used to create a parameter block.
Parameters:
ParamBlockDesc *pdesc
This is an array of parameter block descriptors.
int count
This is the number in the array.
Return Value:
A pointer to the created parameter block. On error NULL is returned.
Prototype:
IParamBlock *CreateParameterBlock(ParamBlockDescID *pdesc, int count,DWORD version);
Remarks:
Implemented by the System.
This method is used to create a parameter block with a version number to aide in backwards compatibility.
Parameters:
ParamBlockDesc *pdesc
This is an array of parameter block descriptors.
int count
This is the number in the array.
DWORD version
This is used to indicate a version of the parameter block. This is used for backwards compatibility when loading 3ds max files that were saved with a previous version of the parameter block structure. There is a mechanism which allows the older format to be converted to the newer format so the older files may still be loaded and used. See the Advanced Topics section on Parameter Maps for more information.
Return Value:
A pointer to the created parameter block. On error NULL is returned.
Prototype:
IParamBlock *UpdateParameterBlock(ParamBlockDescID *pdescOld, int oldCount, IParamBlock *oldPB,ParamBlockDescID *pdescNew, int newCount, DWORD newVersion);
Remarks:
Implemented by the System.
This creates a new parameter block, based on an existing parameter block of a later version. The new parameter block inherits any parameters from the old parameter block whose parameter IDs match.
Parameters:
ParamBlockDescID *pdescOld
The existing parameter block descriptor.
int oldCount
The number of old parameters.
IParamBlock *oldPB
The old parameter block.
ParamBlockDescID *pdescNew
The new parameter block descriptor.
int newCount
The number of new parameters.
DWORD newVersion
The version of the new parameter block.
Return Value:
The new parameter block.