Class StdControl
See Also: Class Control, Class Interval, Class Matrix3, Class Point3, Class Quat, Class ScaleValue, List of Additional Control Related Functions
class StdControl : public Control
Description:
StdControl is a class from which you may derived controller objects. Controllers are the objects in 3ds max that control animation. Any controller that does not evaluate itself as a function of its input can subclass off this class.
The purpose of this class is to simplify some aspects of implementing controllers. The only restriction when using this class is that the controller can not evaluate itself as a function of its input. For example, position, rotation, and scale controllers are passed a TM when they are evaluated. They are supposed to calculate their value and apply it to the TM (pre-multiply). It is possible that the controller could calculate its value as some function of this input matrix. For example, a rotation controller could look at the position of the matrix and the position of some other node in the scene and calculate the rotation such that the object is looking at the other node. Most controllers don't do this so they can subclass off this class which handles processing ORTs (Out of Range Types), ease curves and multiplier curves.
This class implements GetValue() and SetValue() but requires the derived class to implement two new methods: GetValueLocalTime() and SetValueLocalTime().
The implementations of GetValue() and SetValue() handle processing the ORTs and ease and multiplier curves.
Plug-In Information:
Class Defined In CONTROL.H
Super Class ID CTRL_FLOAT_CLASS_ID - Used by float controllers.
CTRL_POINT3_CLASS_ID - Used by Point3 controllers.
CTRL_MATRIX3_CLASS_ID - Used by Matrix3 controllers.
CTRL_POSITION_CLASS_ID - Used by position controllers.
CTRL_ROTATION_CLASS_ID - Used by rotation controllers.
CTRL_SCALE_CLASS_ID - Used by scale controllers.
CTRL_MORPH_CLASS_ID - Used by morph controllers.
Standard File Name Extension DLC
Extra Include File Needed None
Methods:
Prototype:
virtual void GetValueLocalTime(TimeValue t, void *val,
Interval &valid, GetSetMethod method=CTRL_ABSOLUTE)=0;
Remarks:
Implemented by the Plug-In.
This method is called to have the controller evaluate itself at the given time. In this class the system implements the method GetValue(). GetValue() calls this method to retrieves the value of the controller at the specified time. The implementation of GetValue() then takes care of handling the ORTs, ease curves and multiplier curves. The plug-in must only return the value of the controller.
Parameters:
TimeValue t
The time to retrieve the value.
void *val
This points to a variable to hold the computed value of the controller at the specified time. What the plug-in needs to do to store the value of the controller depends on the controller type. There are six controller types: float, Point3, Position, Rotation, Scale, and Transform.
float
*val points to a float
Point3
*val points to a Point3
Position
*val points to a Point3
Rotation
*val points to a Quat
Scale
*val points to a ScaleValue
Transform
*val points to a Matrix3
Interval &valid
The interval to update. The controllers validity interval should be intersected with this interval. This updates the interval to reflect the interval of the controller.
GetSetMethod method=CTRL_ABSOLUTE
This will always be: CTRL_ABSOLUTE
This indicates the controller should simply store its value in *val.
Prototype:
virtual void SetValueLocalTime(TimeValue t, void *val,
int commit=1, GetSetMethod method=CTRL_ABSOLUTE)=0;
Remarks:
Implemented by the Plug-In.
In this class the system implements the method SetValue(). SetValue() calls this method to store the value of the controller at the specified time. The system takes care of handling the ORTs and multiplier curves. The plug-in must only store the value of the controller.
Parameters:
TimeValue t
The time to store the value.
void *val
Storage for the value to set. See *val in Control::SetValue() for the possible data types passed here.
int commit=1
If this parameter is zero, the controller should save the value at the given time before setting the value. If commit is nonzero, the controller doesn't need to actually update its keys or tangents. See Control methods CommitValue() and RestoreValue().
GetSetMethod method=CTRL_ABSOLUTE
One of the following values:
CTRL_RELATIVE
Indicates the plug-in should add the value to the existing value *val (i.e. Move/Rotate/Scale)
CTRL_ABSOLUTE
Indicates the plug-in should just set the value.
Prototype:
void GetValue(TimeValue t, void *val, Interval &valid,
GetSetMethod method=CTRL_ABSOLUTE);
Remarks:
This method is implemented by the system. Controller that subclass from StdControl only need to implement GetValueLocalTime(). See above.
Prototype:
void SetValue(TimeValue t, void *val, int commit=1,
GetSetMethod method=CTRL_ABSOLUTE);
Remarks:
This method is implemented by the system. Controller that subclass from StdControl only need to implement SetValueLocalTime(). See above.
Prototype:
virtual void Extrapolate(Interval range, TimeValue t,
void *val, Interval &valid, int type)=0;
Remarks:
Implemented by the Plug-In.
This method is used to calculate some of the Out of Range Types (ORTs). There are several kinds of extrapolations that need to be done based on the ORT type. There are template functions implemented in CONTROL.H to do them. See List of Miscellaneous Controller Functions for a description of those available.
Parameters:
Interval range
The range that must be extrapolated.
TimeValue t
The time outside the range to extrapolate.
void *val
Storage for the extrapolated value. See *val in GetValueLocalTime() for the possible data types passed here.
Interval &valid
The validity interval of the extrapolated value.
int type
See List of Out of Range Types.
Sample Code:
The following sample code shows the use of the template functions to implement this method to calculate the ORTs.
INTERP_CONT_TEMPLATE
void InterpControl<INTERP_CONT_PARAMS>::Extrapolate(Interval range,TimeValue t,void *val,
Interval &valid,int type)
{
T val0, val1, val2, res;
switch (type) {
case ORT_LINEAR:
if (t<range.Start()) {
GetValueLocalTime(range.Start(),&val0,valid);
GetValueLocalTime(range.Start()+1,&val1,valid);
res = LinearExtrapolate(range.Start(),t,val0,val1,val0);
} else {
GetValueLocalTime(range.End()-1,&val0,valid);
GetValueLocalTime(range.End(),&val1,valid);
res = LinearExtrapolate(range.End(),t,val0,val1,val1);
}
break;
case ORT_IDENTITY:
if (t<range.Start()) {
GetValueLocalTime(range.Start(),&val0,valid);
res = IdentityExtrapolate(range.Start(),t,val0);
} else {
GetValueLocalTime(range.End(),&val0,valid);
res = IdentityExtrapolate(range.End(),t,val0);
}
break;
case ORT_RELATIVE_REPEAT:
GetValueLocalTime(range.Start(),&val0,valid);
GetValueLocalTime(range.End(),&val1,valid);
GetValueLocalTime(CycleTime(range,t),&val2,valid);
res = RepeatExtrapolate(range,t,val0,val1,val2);
break;
}
valid.Set(t,t);
*((T*)val) = res;
}
Prototype:
virtual void *CreateTempValue()=0;
Remarks:
Implemented by the Plug-In.
When processing the ORTs the system might need a temporary variable to hold an intermediate value. Since the system doesn't know the type of the data that the controller is controlling it can't allocate the right amount of temporary storage. It calls this method to do so. The plug-in's implementation of this method should allocate storage to hold its type of data and return a pointer to it.
Prototype:
virtual void DeleteTempValue(void *val)=0;
Remarks:
Implemented by the Plug-In.
This method simply deletes the memory allocated by CreateTempValue().
Parameters:
void *val
Points to the memory allocated by CreateTempValue().
Prototype:
virtual void ApplyValue(void *val, void *delta)=0;
Remarks:
Implemented by the Plug-In.
Applies the given value to the given input value. For position, rotation, and scale controllers, the input value will be a matrix and the value being applied will be a Point3, Quaternion, or ScaleValue, respectively. For other controllers the input value is the same type as the value being applied.
Parameters:
void *val
The value to update.
void *delta
The value to apply.
Prototype:
virtual void MultiplyValue(void *val, float m)=0;
Remarks:
Implemented by the Plug-In.
If the controller has multiplier curves then the system will calculate the factor from all the multiplier curves and then ask the controller to multiply the scalar value to the particular data type.
Parameters:
void *val
The value to update.
float m
The scalar value to multiply *val by.