This reference page is linked to from the following overview topics: Lesson 6: Parameter Blocks, Major New Features, General Best Practices, Getting and Setting Parameter Block Values, Creating a Parameter Block 1, Intervals, Supporting Save to Previous.

Detailed Description

See also:: Class ReferenceTarget, Class IParamArray, Parameter Maps, Class ParamBlockDescID, Class Control.

Description:: This class provides methods to work with parameter blocks. For more details on parameter blocks see Parameter Blocks.

#include <iparamb.h>

Inheritance diagram for IParamBlock:

[legend]

List of all members.

Public Member Functions
virtual SClass_ID	GetAnimParamControlType (int anim)=0
virtual ParamType	GetParameterType (int i)=0
virtual BOOL	SetValue (int i, TimeValue t, float v)=0
virtual BOOL	SetValue (int i, TimeValue t, int v)=0
virtual BOOL	SetValue (int i, TimeValue t, Point3 &v)=0
virtual BOOL	SetValue (int i, TimeValue t, Color &v)=0
virtual BOOL	GetValue (int i, TimeValue t, float &v, Interval &ivalid)=0
virtual BOOL	GetValue (int i, TimeValue t, int &v, Interval &ivalid)=0
virtual BOOL	GetValue (int i, TimeValue t, Point3 &v, Interval &ivalid)=0
virtual BOOL	GetValue (int i, TimeValue t, Color &v, Interval &ivalid)=0
virtual Color	GetColor (int i, TimeValue t=0)=0
virtual Point3	GetPoint3 (int i, TimeValue t=0)=0
virtual int	GetInt (int i, TimeValue t=0)=0
virtual float	GetFloat (int i, TimeValue t=0)=0
virtual DWORD	GetVersion ()=0
virtual int	NumParams ()=0
virtual void	RemoveController (int i)=0
virtual Control *	GetController (int i)=0
virtual void	SetController (int i, Control *c, BOOL preserveFrame0Value=TRUE)=0
virtual void	SwapControllers (int j, int k)=0
virtual int	GetRefNum (int paramNum)=0
virtual int	GetAnimNum (int paramNum)=0
virtual int	AnimNumToParamNum (int animNum)=0
IParamBlock *	GetParamBlock ()
virtual void	RescaleParam (int paramNum, float f)=0
virtual int	LastNotifyParamNum ()=0

Member Function Documentation

virtual SClass_ID GetAnimParamControlType ( int anim ) [pure virtual]

Search for all occurrences

Remarks:: Returns the super class ID of a parameters controller.

Parameters:: int anim

Specifies the parameter whose controller super class ID is returned.

virtual ParamType GetParameterType ( int i ) [pure virtual]

Search for all occurrences

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.

virtual BOOL SetValue	(	int	i,
		TimeValue	t,
		float	v
	)		`[pure virtual]`

Search for all occurrences

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.

Returns:: If the value was set TRUE is returned; otherwise FALSE is returned.

Reimplemented from IParamArray.

virtual BOOL SetValue	(	int	i,
		TimeValue	t,
		int	v
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the integer version of above.

Reimplemented from IParamArray.

virtual BOOL SetValue	(	int	i,
		TimeValue	t,
		Point3 &	v
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the Point3 version of above.

Reimplemented from IParamArray.

virtual BOOL SetValue	(	int	i,
		TimeValue	t,
		Color &	v
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the Color version of above.

virtual BOOL GetValue	(	int	i,
		TimeValue	t,
		float &	v,
		Interval &	ivalid
	)		`[pure virtual]`

Search for all occurrences

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.

Returns:: The return value is TRUE if a value was retrieved. Otherwise it is FALSE.

See also:: Parameter Blocksin the Advanced Topics section, Intervals.

Reimplemented from IParamArray.

virtual BOOL GetValue	(	int	i,
		TimeValue	t,
		int &	v,
		Interval &	ivalid
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the integer version of above.

Reimplemented from IParamArray.

virtual BOOL GetValue	(	int	i,
		TimeValue	t,
		Point3 &	v,
		Interval &	ivalid
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the Point3 version of above.

Reimplemented from IParamArray.

virtual BOOL GetValue	(	int	i,
		TimeValue	t,
		Color &	v,
		Interval &	ivalid
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the Color version of above.

virtual Color GetColor	(	int	i,
		TimeValue	t = `0`
	)		`[pure virtual]`

Search for all occurrences

virtual Point3 GetPoint3	(	int	i,
		TimeValue	t = `0`
	)		`[pure virtual]`

Search for all occurrences

virtual int GetInt	(	int	i,
		TimeValue	t = `0`
	)		`[pure virtual]`

Search for all occurrences

virtual float GetFloat	(	int	i,
		TimeValue	t = `0`
	)		`[pure virtual]`

Search for all occurrences

virtual DWORD GetVersion ( ) [pure virtual]

Search for all occurrences

Remarks:: Implemented by the System.

Returns the parameter block version.

virtual int NumParams ( ) [pure virtual]

Search for all occurrences

virtual void RemoveController ( int i ) [pure virtual]

Search for all occurrences

Remarks:: Implemented by the System.

Removes the 'i-th' controller.

Parameters:: int i

The parameter index of the controller to remove.

virtual Control* GetController ( int i ) [pure virtual]

Search for all occurrences

Remarks:: Implemented by the System.

Returns the controller of the 'i-th' parameter.

Parameters:: int i

The parameter index of the controller to return.

virtual void SetController	(	int	i,
		Control *	c,
		BOOL	preserveFrame0Value = `TRUE`
	)		`[pure virtual]`

Search for all occurrences

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.

virtual void SwapControllers	(	int	j,
		int	k
	)		`[pure virtual]`

Search for all occurrences

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.

virtual int GetRefNum ( int paramNum ) [pure virtual]

Search for all occurrences

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.

virtual int GetAnimNum ( int paramNum ) [pure virtual]

Search for all occurrences

Remarks:: Implemented by the System.

Given a parameter index this method will return the anim number.

Parameters:: int paramNum

The parameter index.

virtual int AnimNumToParamNum ( int animNum ) [pure virtual]

Search for all occurrences

Remarks:: Implemented by the System.

Given an anim number this method will return the parameter index.

Parameters:: int animNum

The anim number.

IParamBlock* GetParamBlock ( ) [inline, virtual]

Search for all occurrences

Remarks:: Implemented by the System.

If the array uses a parameter block, this method will return a pointer to it, otherwise it will return NULL. Note that casting won't work because of multiple inheritance.

Returns:: Returns a pointer to the parameter block if one is used; NULL otherwise.

Reimplemented from IParamArray.

{return this;}

virtual void RescaleParam	(	int	paramNum,
		float	f
	)		`[pure virtual]`

Search for all occurrences

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.

Parameters:: int paramNum

The index into the parmeter block of the parameter to rescale.

float f

The value to scale by.

virtual int LastNotifyParamNum ( ) [pure virtual]

Search for all occurrences

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;

IParamBlock Class Reference

Detailed Description

Public Member Functions

Member Function Documentation