This reference page is linked to from the following overview topics: Controller API Elements, Hit Testing.

Detailed Description

See also:: Class Control, Class Interval, Class Matrix3, Class Point3, Class Quat, Class ScaleValue, List of Additional Control Related Functions

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

#include <control.h>

Inheritance diagram for StdControl:

[legend]

List of all members.

Public Member Functions
virtual void	GetValueLocalTime (TimeValue t, void *val, Interval &valid, GetSetMethod method=CTRL_ABSOLUTE)=0
virtual void	SetValueLocalTime (TimeValue t, void *val, int commit=1, GetSetMethod method=CTRL_ABSOLUTE)=0
CoreExport void	GetValue (TimeValue t, void *val, Interval &valid, GetSetMethod method=CTRL_ABSOLUTE)
CoreExport void	SetValue (TimeValue t, void *val, int commit=1, GetSetMethod method=CTRL_ABSOLUTE)
CoreExport bool	GetLocalTMComponents (TimeValue t, TMComponentsArg &cmpts, Matrix3Indirect &parentMatrix)
virtual void	Extrapolate (Interval range, TimeValue t, void *val, Interval &valid, int type)=0
virtual void *	CreateTempValue ()=0
virtual void	DeleteTempValue (void *val)=0
virtual void	ApplyValue (void val, void delta)=0
virtual void	MultiplyValue (void *val, float m)=0

Member Function Documentation

virtual void GetValueLocalTime	(	TimeValue	t,
		void *	val,
		Interval &	valid,
		GetSetMethod	method = `CTRL_ABSOLUTE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: 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:

t	The time to retrieve the value.
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 as follows: 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
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.
method	This will always be: CTRL_ABSOLUTE . It indicates the controller should simply store its value in *val.

virtual void SetValueLocalTime	(	TimeValue	t,
		void *	val,
		int	commit = `1`,
		GetSetMethod	method = `CTRL_ABSOLUTE`
	)		`[pure virtual]`

Search for all occurrences

Remarks:: 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:

t	The time to store the value.
val	Storage for the value to set. See val in Control::SetValue()* for the possible data types passed here.
commit	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().
method	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.

CoreExport void GetValue	(	TimeValue	t,
		void *	val,
		Interval &	valid,
		GetSetMethod	method = `CTRL_ABSOLUTE`
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is implemented by the system. Controller that subclass from StdControl only need to implement GetValueLocalTime(). See above.

Implements Control.

CoreExport void SetValue	(	TimeValue	t,
		void *	val,
		int	commit = `1`,
		GetSetMethod	method = `CTRL_ABSOLUTE`
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is implemented by the system. Controller that subclass from StdControl only need to implement SetValueLocalTime(). See above.

Implements Control.

CoreExport bool GetLocalTMComponents	(	TimeValue	t,
		TMComponentsArg &	cmpts,
		Matrix3Indirect &	parentMatrix
	)		`[virtual]`

Search for all occurrences

Remarks:: This method returns the PRS components of the local matrix. In general, controller cannot decide on the local matrix without knowing the parent matrix. However, many controllers, such as default controllers, are well defined without the parent matrix. In these cases, it is more efficient to compute the local components directly without going through the world matrix.

Therefore, the argument parentMatrix is a reference to Matrix3Indirect. This would allow clients to supply a "delayed parent matrix," which will be computed only if it is necessary. It returns true for Matrix3, Position, Rotation, or Scale controllers, and return false otherwise.

The PRS components will be put in argument cmpts in the respective fields with corresponding validity intervals. NULL pointer, of TMComponentsArg::position for example, indicates that the client is not concerned about the component. When it is not NULL, the corresponding pointer to the validity interval MUST NOT be NULL. When it is not NULL, TMComponentsArg::rotation is a float[4]. rotRep tells what the numbers mean.

Position, Rotation, or Scale, controllers will put results at the respective component when the corresponding pointer is not NULL.

Upon entry, parentMatrix should represent the parent matrix up to the first requested components. For Matrix3 controllers, for example, if cmpts.position==NULL && cmpts.rotation!=NULL, then parentMatrix should be matrix that includes the parent node matrix plus the position of this node. Upon return, this matrix may be modified.

Parameters:

t	The time at which to get the local TM components.
cmpts	See Structure TMComponentsArgs.
parentMatrix	The parent matrix. Note the definition: LocalMatrix = WorldMatrix * ParentWorldMatrix^(-1)

Reimplemented from Control.

virtual void Extrapolate	(	Interval	range,
		TimeValue	t,
		void *	val,
		Interval &	valid,
		int	type
	)		`[pure virtual]`

Search for all occurrences

Remarks:: 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:

range	The range that must be extrapolated.
t	The time outside the range to extrapolate.
val	Storage for the extrapolated value. See val in GetValueLocalTime()* for the possible data types passed here.
valid	The validity interval of the extrapolated value.
type	See 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;
        }

virtual void* CreateTempValue ( ) [pure virtual]

Search for all occurrences

Remarks:: 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.

virtual void DeleteTempValue ( void * val ) [pure virtual]

Search for all occurrences

Remarks:: This method simply deletes the memory allocated by CreateTempValue().

Parameters:

val	Points to the memory allocated by CreateTempValue().

virtual void ApplyValue	(	void *	val,
		void *	delta
	)		`[pure virtual]`

Search for all occurrences

Remarks:: 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:

val	The value to update.
delta	The value to apply.

virtual void MultiplyValue	(	void *	val,
		float	m
	)		`[pure virtual]`

Search for all occurrences

Remarks:: 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:

val	The value to update.
m	The scalar value to multiply *val by.

StdControl Class Reference

Detailed Description

Public Member Functions

Member Function Documentation