#include <xsi_parameter.h>

Class Description

An array of Parameters.

See also:: ProjectItem::GetParameters, Parameter::GetParameters, CRefArray, Parameter

Example:

                using namespace XSI;
                Application app;
                Model root = app.GetActiveSceneRoot();

                X3DObject myCube;
                root.AddGeometry( L"Cube", L"MeshSurface", CString(L"MyCube"), myCube );

                CParameterRefArray params = myCube.GetParameters();

                Parameter posx(params.GetItem( L"posx" ));
                Parameter posy(params.GetItem( L"posy" ));
                Parameter posz(params.GetItem( L"posz" ));

                posx.PutValue(5.5);
                posy.PutValue(8.0);

                app.LogMessage( L"Cube's pos parameter: " +
                        CValue(posx.GetValue()).GetAsText() + L"," +
                        CValue(posy.GetValue()).GetAsText() + L"," +
                        CValue(posz.GetValue()).GetAsText() );

Inheritance diagram for CParameterRefArray:

List of all members.

Public Member Functions
	CParameterRefArray ()
	CParameterRefArray (const CParameterRefArray &)
	~CParameterRefArray ()
CParameterRefArray &	operator= (const CParameterRefArray &in_refArray)
CRef	GetItem (const CString &in_scriptname) const
void	Add (const CRef &in_item)
void	RemoveItem (const CString &in_scriptname)
CRefArray	PlotAnimation (double in_startFrame=DBL_MAX, double in_stopFrame=DBL_MAX, double in_stepFrame=1, siFCurveType in_fcurveTypeToPlot=siStandardFCurve, siFCurveInterpolation in_interpolation=siCubicInterpolation, bool in_bFitValues=false, double in_fitTolerance=0.01, bool in_bProcessRotation=false, bool in_bDisplayProgressBar=true)
CStatus	PlotAnimation (double in_startFrame, double in_stopFrame, double in_stepFrame, bool in_bProcessRotation, bool in_bDisplayProgressBar, CLongArray &out_startParamValuesIndicesArray, CDoubleArray &out_plottedFramesArray, CDoubleArray &out_plottedValuesArray)
CRefArray	PlotAnimation (double in_startFrame, double in_stepFrame, const CDoubleArray &in_frameset, siFCurveType in_fcurveTypeToPlot=siStandardFCurve, siFCurveInterpolation in_interpolation=siCubicInterpolation, bool in_bFitValues=false, double in_fitTolerance=0.01, bool in_bProcessRotation=false, bool in_bDisplayProgressBar=true)
CStatus	PlotAnimation (double in_startFrame, double in_stepFrame, const CDoubleArray &in_frameset, bool in_bProcessRotation, bool in_bDisplayProgressBar, CLongArray &out_startParamValuesIndicesArray, CDoubleArray &out_plottedFramesArray, CDoubleArray &out_plottedValuesArray)
CValue	GetValue (const CString &in_scriptname, double in_time=DBL_MAX) const
CValue	GetValue (LONG in_index, double in_time=DBL_MAX) const
CStatus	PutValue (const CString &in_scriptname, const CValue &in_val, double in_time=DBL_MAX)
CStatus	PutValue (LONG in_index, const CValue &in_val, double in_time=DBL_MAX)

Constructor & Destructor Documentation

CParameterRefArray ( )

Default constructor.

CParameterRefArray ( const CParameterRefArray & )

Copy constructor. Performs a shallow copy, so any change to one instance will appear in any of the copies.

~CParameterRefArray ( )

Default destructor.

Member Function Documentation

CParameterRefArray& operator= ( const CParameterRefArray & in_refArray )

Assign a CParameterRefArray object to this one.

Parameters:

in_refArray A constant CParameterRefArray object.

Returns:: A new reference object.

CRef GetItem ( const CString & in_scriptname ) const [virtual]

Search for all occurrences

Returns a CRef object contained in the list given an object scripting name. If the requested parameter does not exist in the array then an invalid CRef is returned.

Parameters:

in_scriptname The scripting name of a parameter to retrieve.

Returns:: A new CRef object.

See also:: Parameter::GetScriptName; CRef::IsValid

Reimplemented from CRefArray.

void Add ( const CRef & in_item ) [virtual]

Search for all occurrences

Adds a CRef object at the end of this array. The CRef must be Valid and refer to a Parameter, otherwise it is ignored. This operation does not actually add a parameter to any associated XSI object.

Parameters:

in_item CRef object.

See also:: CustomProperty::AddParameter

Reimplemented from CRefArray.

void RemoveItem ( const CString & in_scriptname )

Search for all occurrences

Removes a parameter from the CParameterRefArray. This does not actually remove the parameter from any associated XSI object. No action is performed if the requested parameter is not found in the CParameterRefArray.

Parameters:

in_scriptname scriptname of parameter.

See also:: CustomProperty::RemoveParameter

CRefArray PlotAnimation	(	double	in_startFrame = `DBL_MAX`,
		double	in_stopFrame = `DBL_MAX`,
		double	in_stepFrame = `1`,
		siFCurveType	in_fcurveTypeToPlot = `siStandardFCurve`,
		siFCurveInterpolation	in_interpolation = `siCubicInterpolation`,
		bool	in_bFitValues = `false`,
		double	in_fitTolerance = `0.01`,
		bool	in_bProcessRotation = `false`,
		bool	in_bDisplayProgressBar = `true`
	)

Search for all occurrences

Creates and returns an array of FCurve objects by plotting the parameters values from consecutive frames of an animation. The resulting FCurve objects are transients and not connected to any XSI components. All resulting FCurve objects are parented to the Application object.

Parameters:

in_startFrame	First frame to plot. Use DBL_MAX to specify the first frame in the timeline. Defaults to DBL_MAX.
in_stopFrame	Last frame to plot. Use DBL_MAX to specify the last frame in the timeline. Defaults to DBL_MAX.
in_stepFrame	Step between frames. Defaults to 1.
in_fcurveTypeToPlot	Type of fcurve required for plotting. Defaults to siStandardFCurve.
in_interpolation	Type of interpolation required for the resulting fcurves. This argument is only relevant if in_fcurveTypeToPlot is siStandardFCurve. Defauts to siCubicInterpolation.
in_bFitValues	Fits the fcurves through the plotted values. Defaults to false.
in_fitTolerance	Tolerance value used for fitting the fcurves through the plotted values. Defaults to 0.01.
in_bProcessRotation	Processes the rotation curves to ensure their continuity. Defaults to false. For processing continuous rotations the rotation channels must be listed consecutively. e.g. cube.local.rotx, cube.local.roty, cube.local.rotz otherwise the rotation for that object will not be processed.
in_bDisplayProgressBar	Display a progress bar control to indicates the progress of the plot operation. Defaults to true.

Returns:: Array of FCurve objects. The returned array of FCurve objects matches the parameters in size. Parameters that are filtered out (e.g. invalid parameter to plot) have an invalid FCurve object in the returned array.

See also:: FCurve

Since:: 5.0

CStatus PlotAnimation	(	double	in_startFrame,
		double	in_stopFrame,
		double	in_stepFrame,
		bool	in_bProcessRotation,
		bool	in_bDisplayProgressBar,
		CLongArray &	out_startParamValuesIndicesArray,
		CDoubleArray &	out_plottedFramesArray,
		CDoubleArray &	out_plottedValuesArray
	)

Search for all occurrences

Returns an array of plotted values obtained by plotting the parameters values from consecutive frames of an animation.

Parameters:

in_startFrame	First frame to plot. Use DBL_MAX to specify the first frame in the timeline.
in_stopFrame	Last frame to plot. Use DBL_MAX to specify the last frame in the timeline.
in_stepFrame	Step between frames.
in_bProcessRotation	Processes the rotation curves to ensure their continuity. For processing continuous rotations the rotation channels must be listed consecutively. e.g. cube.local.rotx, cube.local.roty, cube.local.rotz otherwise the rotation for that object will not be processed.
in_bDisplayProgressBar	Display a progress bar control to indicates the progress of the plot operation.
out_startParamValuesIndicesArray	Output value. An array containing the index of the first plotted value in the output out_plottedValuesArray array of each plotted parameter. An index of -1 means the associated parameter has not been plotted.
out_plottedFramesArray	Output value. An array containing the frames that each parameter has been plotted with.
out_plottedValuesArray	Output value. An flat array containing the plotted values for all plotted parameters. The plotted values of each parameter are consecutive in the array, starting from the first frame up to the last frame been plotted.

Returns:: CStatus::OK success; CStatus::Fail other failure

See also:: CDoubleArray, CLongArray

Example:

                using namespace XSI;
                Application app;
                Model root = app.GetActiveSceneRoot();

                X3DObject myGrid;
                root.AddGeometry( L"Grid", L"MeshSurface", CString( L"MyGrid" ), myGrid );

                Parameter posxParam = myGrid.GetParameters().GetItem( L"posx" );

                FCurve fcrv;
                posxParam.AddFCurve( siStandardFCurve, fcrv );
                fcrv.AddKey( 1.0, 0.0 );
                fcrv.AddKey( 5.0, 5.0 );

                CParameterRefArray paramArray = myGrid.GetKinematics().GetLocal().GetParameters();
                CParameterRefArray paramToPlot;
                paramToPlot.Add( paramArray.GetItem( "posx" ) );
                paramToPlot.Add( paramArray.GetItem( "posy" ) );
                paramToPlot.Add( paramArray.GetItem( "siscaling" ) );

                CLongArray startParamValuesIndicesArray;
                CDoubleArray plottedFramesArray;
                CDoubleArray plottedValuesArray;
                paramToPlot.PlotAnimation(
                        1.0, 5.0, 1.0, false, true,
                        startParamValuesIndicesArray,
                        plottedFramesArray,
                        plottedValuesArray );

                // Log values
                app.LogMessage( L"* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *" );
                for( LONG i = 0; i < paramToPlot.GetCount(); i++ )
                {
                        Parameter param = paramToPlot[ i ];

                        LONG offsetInArray = startParamValuesIndicesArray[ i ];
                        if( offsetInArray != -1 )
                        {
                                app.LogMessage( param.GetFullName() + L" has plotted values: " );

                                for( LONG frameIndex = 0; frameIndex < plottedFramesArray.GetCount(); frameIndex++ )
                                {
                                        app.LogMessage( 
                                                L"    Frame: " + 
                                                CValue( plottedFramesArray[ frameIndex ] ).GetAsText() +
                                                L",   Value: " + 
                                                CValue( plottedValuesArray[ frameIndex + offsetInArray ] ).GetAsText() );
                                }
                        }
                        else
                        {
                                app.LogMessage( param.GetFullName() + L" has not been plotted." );
                        }
                }

                // INFO : * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
                // INFO : MyGrid.kine.local.posx has plotted values: 
                // INFO :     Frame: 1,   Value: 0
                // INFO :     Frame: 2,   Value: 0.78125
                // INFO :     Frame: 3,   Value: 2.5
                // INFO :     Frame: 4,   Value: 4.21875
                // INFO :     Frame: 5,   Value: 5
                // INFO : MyGrid.kine.local.posy has plotted values: 
                // INFO :     Frame: 1,   Value: 0
                // INFO :     Frame: 2,   Value: 0
                // INFO :     Frame: 3,   Value: 0
                // INFO :     Frame: 4,   Value: 0
                // INFO :     Frame: 5,   Value: 0
                // INFO : MyGrid.kine.local.siscaling has not been plotted.

Since:: 12.0 (2014)

CRefArray PlotAnimation	(	double	in_startFrame,
		double	in_stepFrame,
		const CDoubleArray &	in_frameset,
		siFCurveType	in_fcurveTypeToPlot = `siStandardFCurve`,
		siFCurveInterpolation	in_interpolation = `siCubicInterpolation`,
		bool	in_bFitValues = `false`,
		double	in_fitTolerance = `0.01`,
		bool	in_bProcessRotation = `false`,
		bool	in_bDisplayProgressBar = `true`
	)

Search for all occurrences

Creates and returns an array of FCurve objects by plotting the parameters values from consecutive frames of an animation. The resulting FCurve objects are transients and not connected to any XSI components. All resulting FCurve objects are parented to the Application object.

Parameters:

in_startFrame	First frame of plot, usually set to 1.
in_stepFrame	Step between frames, usually set to 1.
in_frameset	Array of non-sequential, non-integer frames. Assumes frames are defined using the current frame rate.
in_fcurveTypeToPlot	Type of fcurve required for plotting. Defaults to siStandardFCurve.
in_interpolation	Type of interpolation required for the resulting fcurves. This argument is only relevant if in_fcurveTypeToPlot is siStandardFCurve. Defauts to siCubicInterpolation.
in_bFitValues	Fits the fcurves through the plotted values. Defaults to false.
in_fitTolerance	Tolerance value used for fitting the fcurves through the plotted values. Defaults to 0.01.
in_bProcessRotation	Processes the rotation curves to ensure their continuity. Defaults to false. For processing continuous rotations the rotation channels must be listed consecutively. e.g. cube.local.rotx, cube.local.roty, cube.local.rotz otherwise the rotation for that object will not be processed.
in_bDisplayProgressBar	Display a progress bar control to indicates the progress of the plot operation. Defaults to true.

Returns:: Array of FCurve objects. The returned array of FCurve objects matches the parameters in size. Parameters that are filtered out (e.g. invalid parameter to plot) have an invalid FCurve object in the returned array.

See also:: FCurve

Since:: 12.0 (2014)

CStatus PlotAnimation	(	double	in_startFrame,
		double	in_stepFrame,
		const CDoubleArray &	in_frameset,
		bool	in_bProcessRotation,
		bool	in_bDisplayProgressBar,
		CLongArray &	out_startParamValuesIndicesArray,
		CDoubleArray &	out_plottedFramesArray,
		CDoubleArray &	out_plottedValuesArray
	)

Search for all occurrences

Returns an array of plotted values obtained by plotting the parameters values from non-linear set of non-discrete frames of an animation.

Parameters:

in_startFrame	First frame of plot, usually set to 1.
in_stepFrame	Step between frames, usually set to 1.
in_frameset	Array of non-sequential, non-integer frames. Assumes frames are defined using the current frame rate.
in_bProcessRotation	Processes the rotation curves to ensure their continuity. Defaults to false. For processing continuous rotations the rotation channels must be listed consecutively. e.g. cube.local.rotx, cube.local.roty, cube.local.rotz otherwise the rotation for that object will not be processed.
in_bDisplayProgressBar	Display a progress bar control to indicates the progress of the plot operation. Defaults to true.
out_startParamValuesIndicesArray	Output value. An array containing the index of the first plotted value in the output out_plottedValuesArray array of each plotted parameter. An index of -1 means the associated parameter has not been plotted.
out_plottedFramesArray	Output value. An array containing the frames that each parameter has been plotted with.
out_plottedValuesArray	Output value. An flat array containing the plotted values for all plotted parameters. The plotted values of each parameter are consecutive in the array, starting from the first frame up to the last frame been plotted.

Returns:: CStatus::OK success; CStatus::Fail other failure

See also:: CDoubleArray, CLongArray

Since:: 12.0 (2014)

CValue GetValue	(	const CString &	in_scriptname,
		double	in_time = `DBL_MAX`
	)		const

Search for all occurrences

Returns the value of a parameter identified with a scripting name. The value returned is empty if the input name is invalid.

Note:: This function can be more efficient than getting a Parameter object and then calling Parameter::GetValue to get the value. Use this function in cases where you only need to get the value on a parameter.

Parameters:

in_scriptname	The parameter scripting name (see Parameter::GetScriptName).
in_time	Time in frame defaults to the current frame if in_time is set with DBL_MAX.

Returns:: The parameter value.

Since:: 5.1

CValue GetValue	(	LONG	in_index,
		double	in_time = `DBL_MAX`
	)		const

Search for all occurrences

Returns the value of a parameter at a specific position in the array. The value returned is empty if the index is out of bounds.

Note:: This function can be more efficient than getting a Parameter object and then calling Parameter::GetValue to get the value. Use this function in cases where you only need to get the value on a parameter.

Parameters:

in_index	The position of the parameter in the array.
in_time	Time in frames. Defaults to the current frame if `in_time` is set with `DBL_MAX`.

Returns:: The parameter value.

Since:: 6.0

CStatus PutValue	(	const CString &	in_scriptname,
		const CValue &	in_val,
		double	in_time = `DBL_MAX`
	)

Search for all occurrences

Sets a parameter value by scripting name. If you try to set a read-only parameter, an error (CStatus::Unexpected) occurs. You can check if a parameter is read-only by checking the condition:

 Parameter::GetCapabilities && siReadOnly == siReadOnly

Tip:: You can set a custom property parameter even if it is created with the read-only capability.

Note:: This function can be more efficient than getting a Parameter object and then calling Parameter::PutValue to set the value. Use this function in cases where you only need to set the value on a parameter.

Parameters:

in_scriptname	The parameter scripting name.
in_val	The parameter value to set.
in_time	Time in frame defaults to the current frame if `in_time` is set with `DBL_MAX`.

Returns:: CStatus::OK success; CStatus::Fail other failure; CStatus::Unexpected Trying to set a read-only parameter.; CStatus::BadVarType Invalid input value type. Usually happens if in_val cannot be converted to the parameter type.

Since:: 5.1

CStatus PutValue	(	LONG	in_index,
		const CValue &	in_val,
		double	in_time = `DBL_MAX`
	)

Search for all occurrences

Sets the value of the parameter at a given position in the array. If you try to set a read-only parameter, an error (CStatus::Unexpected) occurs. You can check if a parameter is read-only by checking the condition:

 Parameter::GetCapabilities && siReadOnly == siReadOnly

Tip:: You can set a custom property parameter even if it is created with the read-only capability.

Note:: This function can be more efficient than getting a Parameter object and then calling Parameter::PutValue to set the value. Use this function in cases where you only need to set the value on a parameter.

Parameters:

in_index	The position of the parameter in the array.
in_val	The parameter value to set.
in_time	Time in frame defaults to the current frame if `in_time` is set with `DBL_MAX`.

Returns:: CStatus::OK success; CStatus::Fail other failure; CStatus::Unexpected Trying to set a read-only parameter.; CStatus::BadVarType Invalid input value type. Usually happens if in_val cannot get converted to the parameter type.

Since:: 6.0

The documentation for this class was generated from the following file:

xsi_parameter.h

Class Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation