Public Member Functions
Parameter Class Reference

Detailed Description

Represents a parameter value within the ProjectItem, for example, the angle parameter of the twist operator. It is possible to create custom defined parameters on the CustomProperty object.

Besides representing a regular parameter in Softimage, this class is the base class for a number of specializations, including the ArrayParameter, ShaderParameter, ProxyParameter, etc. See the class inheritance diagram at the top of the page for more information.

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

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

        // print the names of all parameter exposed by the cube object
        CRefArray params = myCube.GetParameters();

        for (LONG i = 0 ; i < params.GetCount(); ++i )
        {
            Parameter param(params[i]);
            app.LogMessage( param.GetScriptName() + L" = " +
                param.GetValue().GetAsText() );
        }

#include <xsi_parameter.h>

Inheritance diagram for Parameter:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 Parameter ()
 ~Parameter ()
 Parameter (const CRef &in_ref)
 Parameter (const Parameter &in_obj)
bool IsA (siClassID in_ClassID) const
siClassID GetClassID () const
Parameter & operator= (const Parameter &in_obj)
Parameter & operator= (const CRef &in_ref)
LONG GetCapabilities () const
CStatus PutCapabilityFlag (siCapabilities in_flag, bool in_bEnable)
bool GetMarked () const
CStatus PutMarked (bool in_bVal)
CParameterRefArray & GetParameters () const
Parameter GetParameter (const CString &in_scriptname) const
CValue GetValue (double in_time=DBL_MAX) const
CStatus PutValue (const CValue &in_val, double in_time=DBL_MAX)
CString GetScriptName () const
CString GetDescription () const
CValue::DataType GetValueType () const
CValue GetMin () const
CValue GetMax () const
CValue GetSuggestedMin () const
CValue GetSuggestedMax () const
CValue GetDefault () const
CRef GetSource () const
CRefArray GetSources () const
CStatus PutSource (const CRef &in_source)
CStatus AddFCurve (siFCurveType in_Type, FCurve &io_FCurve)
Expression AddExpression (CString &in_ExpressionDefinition)
CStatus ConnectFromPreset (const CString &in_strName, const CString &in_strFamily, CRef &io_prevSource, CRef &io_source)
CStatus ConnectFromPreset (const CString &in_strName, const CString &in_strFamily, const CString &in_strSourceName, CRef &io_prevSource, CRef &io_source)
CStatus ConnectFromFile (const CString &in_strName, CRef &io_prevSource, CRef &io_source)
CStatus ConnectFromFile (const CString &in_strName, const CString &in_strSourceName, CRef &io_prevSource, CRef &io_source)
CStatus ConnectFromProgID (const CString &in_strName, CRef &io_prevSource, CRef &io_source)
CStatus ConnectFromProgID (const CString &in_strName, const CString &in_strSourceName, CRef &io_prevSource, CRef &io_source)
CStatus Connect (const CRef &in_source, CRef &io_prevSource)
CStatus Disconnect ()
CStatus Disconnect (CRef &io_prevSource)
CStatus PutParameterValue (const CString &in_scriptname, bool in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, double in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, float in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, short in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, LONG in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, LLONG in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, const CValue &in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, const CRef &in_val, double in_time=DBL_MAX)
CStatus PutParameterValue (const CString &in_scriptname, const CString &in_val, double in_time=DBL_MAX)
CValue GetParameterValue (const CString &in_name, double in_time=DBL_MAX) const
bool IsAnimated (siSourceType in_sourceType=siAnySource) const
CRefArray GetAnimatedParameters (siSourceType in_sourceType=siAnySource) const
siLockType GetLockType ()
siLockLevel GetLockLevel ()
bool IsLocked ()
CStatus SetLock (siLockLevel in_level=siLockLevelAll)
CStatus UnSetLock (siLockLevel in_level=siLockLevelAll, const CString &in_password=CString())
siTags GetTags ()
CStatus PutTags (siTags in_eVal)
CRef AddScriptedOp (const CString &in_code=L"", const CRefArray &in_inputs=CRefArray(), const CString &in_name=L"", const CString &in_language=L"", CStatus *io_pst=0)
CRef AddScriptedOpFromFile (const CString &in_filename=L"", const CRefArray &in_inputs=CRefArray(), const CString &in_name=L"", const CString &in_language=L"", CStatus *io_pst=0)
CRef AddCustomOp (const CString &in_type, const CRefArray &in_inputs=CRefArray(), const CString &in_name=L"", CStatus *io_pst=0)
X3DObject GetParent3DObject () const
Model GetModel () const
bool HasInstanceValue () const
bool IsSupportedInstanceValue (const CRef &in_obj, const CValue &in_val) const
CValue GetInstanceValue (const CRef &in_obj, bool in_bindtobject=false) const
CStatus PutInstanceValue (const CRef &in_obj, const CValue &in_val, bool in_bindtovalidate=false)
Parameter GetOverridingObject () const
Parameter GetOverridenObject () const
CValue GetOriginalValue (double in_time=DBL_MAX) const

Constructor & Destructor Documentation

Parameter ( )

Constructs a Parameter object.

~Parameter ( )

Destroys a Parameter object.

Parameter ( const CRef &  in_ref)

Constructs a Parameter object from a CRef object.

Parameters:
in_refA reference to a group.
Parameter ( const Parameter &  in_obj)

Constructs a new Parameter object from an existing Parameter object.

Parameters:
in_objAn existing Parameter object to copy into this Parameter object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID) const [virtual]

Returns True if this object supports the functionality of a specified class. For example, a Parameter is a type of SIObject, so a Parameter object supports SIObject functionality.

Parameters:
in_ClassIDTest if this object supports this class.
Returns:
True if this object supports the specified class, and false otherwise.

Reimplemented from SIObject.

Reimplemented in ArrayParameter, KinematicState, ProxyParameter, ShaderArrayParameter, and ShaderParameter.

siClassID GetClassID ( ) const [virtual]

Gets the class ID for this object.

Returns:
The class ID.

Reimplemented from SIObject.

Reimplemented in ArrayParameter, KinematicState, ProxyParameter, ShaderArrayParameter, and ShaderParameter.

Parameter& operator= ( const Parameter &  in_obj)

Assigns a Parameter object to an existing Parameter object.

Parameters:
in_objA Parameter object to be copied into this object.
Returns:
The reinitialized Parameter object.
Parameter& operator= ( const CRef &  in_ref)

Assigns a CRef to this Parameter object. The Parameter object is cleared if the CRef is not a reference to an object that supports the Parameter class.

Parameters:
in_refA reference to an object that supports the Parameter class.
Returns:
The reinitialized Parameter object.

Reimplemented from SIObject.

Reimplemented in ArrayParameter, KinematicState, ProxyParameter, ShaderArrayParameter, and ShaderParameter.

LONG GetCapabilities ( ) const

Gets a mask of all the object's siCapabilities values.

Returns:
The capability value.
CStatus PutCapabilityFlag ( siCapabilities  in_flag,
bool  in_bEnable 
)

Disables or enables any Capability flag set on the Parameter. For example a parameter can be set to "read-only" or "animatable". Changing the capability flags only affects one particular instance of the parameter.

Parameters:
in_flagSpecify the flag to change
in_bEnableTrue to set the capability; false to remove it.
See also:
Parameter::GetCapabilities
Since:
4.0
bool GetMarked ( ) const

Returns the object's marked state

Returns:
true if object is marked, false otherwise.
CStatus PutMarked ( bool  in_bVal)

Sets the object's marked state. Marking is consider an subset of selection and can only be set if the object parent of the parameter is first selected. A parameter can only be successfully marked if it has a value type that is not equal to siEmpty.

Marking parameters is a way of selecting which parameters you want to use for a specific animation task. For example, you can mark parameters so that only their animation is copied or removed, or you mark the parameters you want to store in an action to be used in the animation mixer. You can also mark parameters to be used when scaling or offsetting an animation, or with linked parameters or scripted operators.

Marking parameters is also one of the most common and useful tools for setting keys. By marking only the parameters you need, you can keep the animation information small.

The marking will be set relative to the first group type object ( X3DObject, Model, Group ) in the parameter's path. If there is no group type object in the path then the marking will be set relative to the parameter's immediate parent.

Parameters:
in_bValMarked state flag
Returns:
CStatus::OK success
CStatus::Fail failure parameter could not be marked
CParameterRefArray& GetParameters ( ) const

Returns an array of all parameters nested within the parameter object. In XSI parameters are often organized into a hierarchy, with parameters like Visibility and Kinematics representing entire groups of parameters rather than a single value. This function provides access to the parameters nested within such a parameter. For normal parameters that do not have any children the returned parameter array will be empty.

Note:
This function builds a cache of all nested parameters. Building the cache can be costly performance-wise. Use this function in cases where the object has many parameters and you need to access many of them. It is more suitable to use Parameter::GetParameter or ProjectItem::GetParameter if you only need to access a few of them.
Returns:
Array of references to Parameter objects
See also:
Parameter::GetParameter, ProjectItem::GetParameters, ProjectItem::GetParameter
Since:
5.1
Parameter GetParameter ( const CString &  in_scriptname) const

Returns a particular parameter nested within this parameter object. If the parameter scripting name does not exist the Parameter will be invalid and all functions will return default values.

Parameters:
in_scriptnameThe scripting name of the parameter (see Parameter::GetScriptName).
Returns:
A Parameter object
Since:
3.5.1
CValue GetValue ( double  in_time = DBL_MAX) const

Returns the parameter value. If the parameter is unable to retrieve the value, it will return an empty CValue. If the parameter value is a string and it has not been set then it will return an empty string.

Parameters:
in_timeTime in frame
Returns:
The parameter value.
CStatus PutValue ( const CValue &  in_val,
double  in_time = DBL_MAX 
)

Sets the parameter value. 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. Note that you can set a custom property parameter even if it is created with the readonly capability.

Note:
Prior to the v5.0 the time argument had the default value 0, this was incorrect and would have give the incorrect value if the parameter was animated and the current time was not set to frame 0.
Parameters:
in_valThe parameter value to set.
in_timeTime in frame, defaults to the current frame (indicated by the value of 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.
CString GetScriptName ( ) const

Returns the parameter's script name.

Returns:
The parameter's scripting name.
CString GetDescription ( ) const

Returns the descriptive string of a Parameter. The description is a longer, more descriptive version of the parameter name.

Returns:
The parameter's description string.
CValue::DataType GetValueType ( ) const

Returns the type of the parameter. For example a check box parameter would return siBool and a text based parameter would return siString. This is different from the SIObject::GetType property, which refers to the type of the parameter object, in other words "Parameter".

Returns:
The parameter's value type.
CValue GetMin ( ) const

Returns the minimum value that the parameter could possibly have. This property is only valid for numeric parameters. Other value types, for example siString do not have concept of Minimum or Maximum.

Returns:
The minimum value.
CValue GetMax ( ) const

Returns the maximum value that the parameter could possibly have. This property is only valid for numeric parameters. Other value types, for example siString do not have concept of Minimum or Maximum.

Returns:
The maximum value.
CValue GetSuggestedMin ( ) const

Returns the suggested minimum value for the parameter. A parameter can have two separate ranges - the Min/Max which defines the entire range of legal values and the Suggested Minimum/Suggested Maximum which defines a sub-range of the Min/Max that makes the most sense. For example an enormous number of subdivisions may theoretically be possible on a geometry, but for performance reasons a smaller range can be suggested to the user. The suggested Min/Max values are used when determining the slider ranges for controls when parameters are inspected. This property is only valid for numeric parameters. Other value types, for example siString do not have concept of Minimum or Maximum.

Returns:
The suggested minimum value.
CValue GetSuggestedMax ( ) const

Returns the suggested minimum value for the parameter. A parameter can have two separate ranges - the Min/Max which defines the entire range of legal values and the Suggested Minimum/Suggested Maximum which defines a sub-range of the Min/Max that makes the most sense. For example an enormous number of subdivisions may theoretically be possible on a geometry, but for performance reasons a smaller range can be suggested to the user. The Suggested Min/Max values are used when determining the slider ranges for controls when parameters are inspected. This property is only valid for numeric parameters. Other value types, for example siString do not have concept of Minimum or Maximum.

Returns:
The suggested maximum value.
CValue GetDefault ( ) const

Returns the default value of the parameter. Some parameters have a default value, which defines what the initial value of the parameter is.

Returns:
The default value.
CRef GetSource ( ) const

Returns a parameter's DataSource. If no source is connected then an empty CRef object is returned. If a parameter is animated and connected to a source (eg., a Shader), then the connected source is returned.

Returns:
A reference to the data source connected to this parameter.
CRefArray GetSources ( ) const

Returns the list of all DataSource items for the parameter. If no source is connected then an empty CRefArray object is returned. If a parameter is animated and connected to many sources (eg., a Mixer and an FCurve), then the sources are returned in the order from most significant to the least significant, so that: 

 GetSources()[0] == GetSource()
Returns:
An array of references to the data sources connected to this parameter.
Since:
7.5
CStatus PutSource ( const CRef &  in_source)

Sets a parameter's data source e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource, Mixer. You can remove the data source by assigning an empty CRef object. This function is only supported for shader parameters.

Parameters:
in_sourcedata source to connect.
Returns:
CStatus::OK success
CStatus::Fail Operation failed or operation performed on a non-shader parameter.
CStatus AddFCurve ( siFCurveType  in_Type,
FCurve &  io_FCurve 
)

Creates and connects an FCurve object to this parameter.

Parameters:
in_Typefunction curve type
io_FCurveNew FCurve object created
Returns:
CStatus::OK success
CStatus::Fail failure
Expression AddExpression ( CString &  in_ExpressionDefinition)

Creates and connects an Expression object to this parameter.

Parameters:
in_ExpressionDefinitionThe expression formula
Returns:
Newly created Expression. Use the CBase::IsValid() function on the returned object to test whether this function has failed.
Since:
5.0
CStatus ConnectFromPreset ( const CString &  in_strName,
const CString &  in_strFamily,
CRef &  io_prevSource,
CRef &  io_source 
)

Creates a data source( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object from a preset name and connects it to the Parameter. This method can be used to connect a shader to a parameter from the shader preset.

Parameters:
in_strNamePreset name
in_strFamilyPreset family name
io_prevSourceThe CRef object that was previously connected.
io_sourceThe new CRef object.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus ConnectFromPreset ( const CString &  in_strName,
const CString &  in_strFamily,
const CString &  in_strSourceName,
CRef &  io_prevSource,
CRef &  io_source 
)

Creates a data source( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object from a preset name and connects it to the Parameter. This method can be used to connect a shader to a parameter from the shader preset. This method also allows a source name to be specified in order to select from which source the connection will made when source has multiple output ports.

Parameters:
in_strNamePreset name
in_strSourceNameSource name
in_strFamilyPreset family name
io_prevSourceThe CRef object that was previously connected.
io_sourceThe new CRef object.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus ConnectFromFile ( const CString &  in_strName,
CRef &  io_prevSource,
CRef &  io_source 
)

Creates a data source ( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object from file and connects it to the parameter. This method can be used to connect a shader to a parameter from the shader preset file name.

Parameters:
in_strNamePreset name
io_prevSourceThe CRef data source object that was previously connected.
io_sourceThe new CRef to a data source object.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus ConnectFromFile ( const CString &  in_strName,
const CString &  in_strSourceName,
CRef &  io_prevSource,
CRef &  io_source 
)

Creates a data source ( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object from file and connects it to the parameter. This method can be used to connect a shader to a parameter from the shader preset file name. This method also allows a source name to be specified in order to select from which source the connection will made when source has multiple output ports.

Parameters:
in_strNamePreset name
in_strSourceNameSource name
io_prevSourceThe CRef data source object that was previously connected.
io_sourceThe new CRef to a data source object.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus ConnectFromProgID ( const CString &  in_strName,
CRef &  io_prevSource,
CRef &  io_source 
)

Creates a data source ( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object from a progid string and connects it to the parameter.

Parameters:
in_strNamePreset name
io_prevSourceThe CRef data source object that was previously connected.
io_sourceThe new CRef data source object.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus ConnectFromProgID ( const CString &  in_strName,
const CString &  in_strSourceName,
CRef &  io_prevSource,
CRef &  io_source 
)

Creates a data source ( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object from a progid string and connects it to the parameter. This method also allows a source name to be specified in order to select from which source the connection will made when source has multiple output ports.

Parameters:
in_strNamePreset name
in_strSourceNameSource name
io_prevSourceThe CRef data source object that was previously connected.
io_sourceThe new CRef data source object.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus Connect ( const CRef &  in_source,
CRef &  io_prevSource 
)

Connects a data source ( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object to the parameter.

Parameters:
in_sourceA reference to the data source object to connect.
io_prevSourceA reference to the data source object that was previously connected.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus Disconnect ( )

Disconnects a source (e.g. FCurve, Expression, ImageClip, Operator, Shader) object from the parameter.

Returns:
CStatus::OK success
CStatus::Fail failure
Since:
5.0
CStatus Disconnect ( CRef &  io_prevSource)

Disconnects a source (e.g. FCurve, Expression, ImageClip, Operator, Shader) object from the parameter.

Parameters:
io_prevSourceA reference to the previously connected source object.
Returns:
CStatus::OK success
CStatus::Fail failure
CStatus PutParameterValue ( const CString &  in_scriptname,
bool  in_val,
double  in_time = DBL_MAX 
)

Sets the parameter value for a parameter which is nested under the current parameter. 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 does not build a cache of all parameter values. Use this function in cases where the object has many parameters but you only need to set the value on a few of them.
Parameters:
in_scriptnameThe parameter scripting name (see Parameter::GetScriptName).
in_valThe parameter value to set.
in_timeTime in frame, defaults to the current frame (represented by the value of DBL_MAX).
Returns:
CStatus::OK success
CStatus::Unexpected Trying to set a read-only parameter.
CStatus::Fail other failure
CStatus::BadVarType Invalid input value type. Usually happens if in_val cannot be converted to the parameter type.
CStatus PutParameterValue ( const CString &  in_scriptname,
double  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CStatus PutParameterValue ( const CString &  in_scriptname,
float  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CStatus PutParameterValue ( const CString &  in_scriptname,
short  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CStatus PutParameterValue ( const CString &  in_scriptname,
LONG  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CStatus PutParameterValue ( const CString &  in_scriptname,
LLONG  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Note:
LLONG types are not supported as a native parameter value type, so the input value will be converted to the parameter type specified by in_scriptname.
CStatus PutParameterValue ( const CString &  in_scriptname,
const CValue &  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CStatus PutParameterValue ( const CString &  in_scriptname,
const CRef &  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CStatus PutParameterValue ( const CString &  in_scriptname,
const CString &  in_val,
double  in_time = DBL_MAX 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CValue GetParameterValue ( const CString &  in_name,
double  in_time = DBL_MAX 
) const

Returns the parameter value for a parameter which is nested under the current parameter. If the parameter is unable to retrieve the value, it will return an empty CValue. If the parameter value is a string and it has not been set then it will return an empty string.

Note:
This function does not build a cache of all parameter values. Use this function in cases where the object has many parameters but you only need to get the value on a few of them.
Parameters:
in_nameName of the parameter for which we want to get the value.
in_timeTime in frame defaults to the current frame (represented by the value of DBL_MAX).
Returns:
The parameter value.
bool IsAnimated ( siSourceType  in_sourceType = siAnySource) const

Returns true if the object is animated by a specific animation source type and false otherwise.

Parameters:
in_sourceTypeAnimation source type,the default value is any source.
Returns:
true if the object is animated, false otherwise.
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 );

        CRefArray paramArray = myGrid.GetParameters();

        for (LONG i=0; i<paramArray.GetCount(); i++ )
        {
            Parameter param = paramArray[i];
            app.LogMessage( param.GetFullName() + L" is node animated: "
                + CValue(param.IsAnimated()).GetAsText() );
        }
CRefArray GetAnimatedParameters ( siSourceType  in_sourceType = siAnySource) const

Returns an array of references to parameters animated by a specific animation source type. Only Compound parameters can return an array of animated parameters.

Parameters:
in_sourceTypeAn object type.
Returns:
Array of references to the parameters.
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 );

        CRefArray paramArray = myGrid.GetAnimatedParameters();

        for (LONG i=0; i<paramArray.GetCount(); i++ )
        {
            Parameter param = paramArray[i];
            app.LogMessage( param.GetFullName() + L" is node animated" );
        }
siLockType GetLockType ( )

Returns the lock type if the parameter is locked.

Returns:
The type of owner
siLockTypeNone if not locked
Since:
4.0
siLockLevel GetLockLevel ( )

Returns the lock level

Returns:
The level of lock for this parameter
siLockLevelNone if not locked
Since:
4.0
bool IsLocked ( )

Returns if an parameter is locked or not.

Returns:
true if it is locked
false otherwise
Since:
4.0
CStatus SetLock ( siLockLevel  in_level = siLockLevelAll)

Locks a parameter

Parameters:
in_levelThe level to lock (use siLockLevelAll to lock it for all levels)
Returns:
CStatus
Since:
4.0
CStatus UnSetLock ( siLockLevel  in_level = siLockLevelAll,
const CString &  in_password = CString() 
)

Unlocks a parameter.

Parameters:
in_levelThe level to unlock (use siLockLevelAll to lock it for all levels)
in_passwordThe optional password to pass when the scene locks are password protected
Returns:
CStatus
Since:
4.0
siTags GetTags ( )

Returns the tags (siTags) on this parameter. Tags are similar to marked parameters except that you can use tags to flag a parameter for further processing by a script or custom command. Also, tags are saved with the scene, unlike marked parameters.

Tags are easy to query and organize, and you can key, plot, store, and transfer tags to another program using the object model or C++ API. You can set one tag on a parameter or up to 10 tags named Tag1, Tag2, etc. Many parameters can be tagged with the same Tag value, which allows you to easily get the list of all parameters for a specific tag.

Returns:
The tags on this parameter.
Since:
4.0
CStatus PutTags ( siTags  in_eVal)

Sets the tags on this parameter. Tags are similar to marked parameters except that you can use tags to flag a parameter for further processing by a script or custom command. Also, tags are saved with the scene, unlike marked parameters.

Tags are easy to query and organize, and you can key, plot, store, and transfer tags to another program using the object model or C++ API. You can set one tag on a parameter or up to 10 tags named Tag1, Tag2, etc. Many parameters can be tagged with the same Tag value, which allows you to easily get the list of all parameters for a specific tag.

Parameters:
in_eValThe Tags to set
Returns:
CStatus::OK success
CStatus::Fail failure
Since:
4.0
CRef AddScriptedOp ( const CString &  in_code = L"",
const CRefArray &  in_inputs = CRefArray(),
const CString &  in_name = L"",
const CString &  in_language = L"",
CStatus *  io_pst = 0 
)

Creates a new runtime scripted operator and connects its output to this object. If the script code is not specified then a default implementation will be used. For parameter connections a simple assignment of the current value be use created for example 'out.value = 0.00'.

Specifying the scripting language is optional. If not specified then current scripting language user preference will used.

Tip:
This is the C++ API version of the AddScriptedOp command, which also creates a runtime scripted operator. To create a Self-Installed Custom Operator, use the Parameter::AddCustomOp instead.
Parameters:
in_codeThe script code containing the implementation of the scripted operator.
in_inputsArray of objects or parameters to be connected to input ports.
in_nameName of the new scripted operator
in_languageThe script language of the new scripted operator. If not specified the value current user preference for the scripting language will be used.
io_pstReturned error status
Returns:
A reference to the new runtime scripted operator
Empty CRef() on failure
Since:
4.0
CRef AddScriptedOpFromFile ( const CString &  in_filename = L"",
const CRefArray &  in_inputs = CRefArray(),
const CString &  in_name = L"",
const CString &  in_language = L"",
CStatus *  io_pst = 0 
)

Creates a new scripted operator and connects its output to this object. If the scripting file is not specified then a default implementation will be used. For parameter connections a simple assignment of the current value be use created for example 'out.value = 0.00'.

Specifying the scripting language is optional. If not specified then the language associated with the file extension will be used. If this cannot be determined then the current scripting language user preference will used.

Tip:
This is the C++ API version of the AddScriptedOpFromFile command, which also creates a runtime scripted operator. To create a Self-Installed Custom Operator, use the Parameter::AddCustomOp instead.
Parameters:
in_filenameThe script filename containing the implementation of the scripted operator.
in_inputsArray of objects or parameters to be connected to input ports.
in_nameName of the new scripted operator
in_languageThe script language of the new scripted operator. If not specified the value current user preference for the scripting language will be used.
io_pstReturned error status
Returns:
A reference to the new scripted operator
Empty CRef() on failure
Since:
4.0
CRef AddCustomOp ( const CString &  in_type,
const CRefArray &  in_inputs = CRefArray(),
const CString &  in_name = L"",
CStatus *  io_pst = 0 
)

Creates a new Self-Installed Custom Operator and connects its output to this object.

Tip:
This is the C++ API version of the AddCustomOp command, which also creates a Self-Installed Custom Operator. To create a runtime scripted operator, use the Parameter::AddScriptedOp function.
Parameters:
in_typeThe type of a operator. A PluginItem must be installed by this name.
in_inputsArray of objects or parameters to be connected to input ports.
in_nameName of the new custom operator. If not specified the type is used to determine a name for the operator.
io_pstReturned error status
Returns:
A reference to the new CustomOperator
Empty CRef() on failure
Since:
5.1
X3DObject GetParent3DObject ( ) const

Returns the X3DObject to which the parameter belongs. /note If this method is called from the Update() context of a custom operator it will return an invalid X3DObject.

Returns:
The X3DObject to which this object belongs.
Since:
5.0
Model GetModel ( ) const

Returns the Model to which the parameter belongs. /note If this method is called from the Update() context of a custom operator it will return an invalid Model.

Returns:
The Model to which this object belongs.
Since:
5.0
bool HasInstanceValue ( ) const

Returns true if the parameter has instance values. A parameter has instance values if the parameter belongs to a shared object, such as a shared property or a shader connected to a shared material. Note, however, that not all shader parameters support instance values.

Parameters with instance values include ImageShader.tspace_id, Material.ImageClipName, Material.UV, and Material.CAV. For example, a material is owned by the Material Library but may be used by many objects. Different objects can have different values for the ImageShader.tspace_id parameter.

See the MaterialLibrary object for an example of the usage.

Returns:
True if the parameter has instance values
See also:
Material::GetShaderInputType, Shader::GetShaderInputType
Since:
5.0
bool IsSupportedInstanceValue ( const CRef &  in_obj,
const CValue &  in_val 
) const

Returns true if the parameter instance value supports this type of value. This is useful for Shaders that need to determine what types of object a texturespace parameter supports. Some texturespace parameters may support vertex color (CAV) properties only, while others may support a more extensive list of properties.

Texturespace parameters are instance values that support object binding. This allows an instance value to be a string value that references an object that may already exist or one that is yet to be created. The parameter is 'bound' to the object when the parameter is used.

If in_val is a string, IsSupportedInstanceValue tries to bind to the referenced object, and tests if it is supported. If the object doesn't exist, IsSupportedInstanceValue returns true, because the object may be created later.

See the MaterialLibrary object for an example usage.

See also:
Material::GetShaderInputType, Shader::GetShaderInputType
Parameters:
in_objThe object to test the value
in_valThe value to test.
Returns:
True if the parameter instance value supports this type of value
Since:
5.0
CValue GetInstanceValue ( const CRef &  in_obj,
bool  in_bindtobject = false 
) const

Returns an instance value for the specified object. Instance values apply only to shared Property objects or Shader objects connected to a shared Material object. For example, a Shader texturespace parameter is an instance value and so is a rendermap tspace_id parameter.

Instance values cannot be animated, so this function does not need a time argument.

See the MaterialLibrary object for an example of the usage.

See also:
Parameter::HasInstanceValue, Material::GetShaderInputType, sa Shader::GetShaderInputType
Parameters:
in_objThe object for which the instance value should be retrieved.
in_bindtobjectIf the instance value supports object binding then GetInstanceValue attempts to retrieve and return that object as the instance value. If the object doesn't exist, GetInstanceValue fails.
Returns:
Instance value
Since:
5.0
CStatus PutInstanceValue ( const CRef &  in_obj,
const CValue &  in_val,
bool  in_bindtovalidate = false 
)

Sets an instance value for a specified object. Instance values apply only to shared Property objects or Shader objects connected to a shared Material object. For example, the texturespace parameter is an instance value.

Instance values cannot be animated, so this function does not need a time argument.

For parameters supporting object binding (such as texturespace), PutInstanceValue accepts a valid CRef as an instance value. It checks that the object is supported and sets the instance value to the name of the object. If the object is not supported, PutInstanceValue returns CStatus::Fail.

If the object does not exist, you can set the instance value to the name of the object by setting in_bindtovalidate to false.

See the MaterialLibrary object for an example of the usage.

See also:
Parameter::HasInstanceValue, Parameter::IsSupportedInstanceValue, Material::GetShaderInputType, Shader::GetShaderInputType
Parameters:
in_objThe object to which the instance value should be assigned.
in_valThe instance value for the object. If the parameter supports object binding then this may be a CString containing the name of the object. The value may also be a CRef, in which case, if the object is supported then the object name is used as the instance value.
in_bindtovalidateIf the instance value supports object binding and the in_val is a string, then PutInstanceValue tests if the object specified by the string exists and is supported. If the object does not exist, PutInstanceValue returns CStatus::Fail.
Returns:
CStatus::OK success
CStatus::Fail failure
Since:
5.0
Parameter GetOverridingObject ( ) const

Returns the parameter overriding this parameter. Returns itself unless Parameter::GetOverridenObject is empty. Returns an empty object if the parameter is not overridden.

Tip:
See Override::AddParameterEntry for information about adding an overriding parameter.
Returns:
Parameter The overriding parameter.
This parameter if Parameter::GetOverridenObject is not empty.
An empty object if the overriding parameter hasn't been set yet. You must first set the overriding parameter value with the SetValue command to activate the overridden parameter. Parameter::PutValue will not activate the override parameter.
See also:
Override, Parameter::GetOriginalValue, Parameter::GetOverridenObject
Since:
7.0
Example:
This example demonstrates how to access an overriding parameter 
        Application app;
        Model root = app.GetActiveSceneRoot();

        // Create a light object
        Light pointLight;
        root.AddLight( L"Point", false, L"PointLight", pointLight );

        // Override the light posx parameter
        Override overrideProp = pointLight.AddProperty( L"Override", false, L"PointOverride" );
        Parameter posx = pointLight.GetKinematics().GetLocal().GetParameters().GetItem(L"posx");

        // Set the original value
        posx.PutValue( 5.0 );

        // Set the overriding value
        Parameter overridingPosx = overrideProp.AddParameterEntry( posx );
        SetValue( overridingPosx.GetFullName(), -4.0, 0 );

        // Log values
        app.LogMessage( L"* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *" );
        app.LogMessage( L"Overriding posx: " + overridingPosx.GetFullName() );
        app.LogMessage( L"Overriding posx value: " + CString( overridingPosx.GetValue() ) );
        app.LogMessage( L"Overriding posx original value: " + CString( overridingPosx.GetOriginalValue() ) );

        // INFO : * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
        // INFO : Overriding posx: PointLight.PointOverride.posx
        // INFO : Overriding posx value: -4
        // INFO : Overriding posx original value: 5
Parameter GetOverridenObject ( ) const

Returns the parameter overridden by this parameter. Returns itself unless Parameter::GetOverridingObject is empty. Returns an empty object if the parameter is not an overriding parameter.

Tip:
See Override::AddParameterEntry for information about adding an overriding parameter.
Returns:
The overridden parameter.
This parameter if Parameter::GetOverridingObject is not empty.
An empty object if the overriding parameter hasn't been set yet. You must first set the overriding parameter value with the SetValue command to activate the overridden parameter. Parameter::PutValue will not activate the override parameter.
See also:
Override, Parameter::GetOriginalValue, Parameter::GetOverridingObject
Since:
7.0
Example:
This example demonstrates how to access an overridden parameter 
        Application app;
        Model root = app.GetActiveSceneRoot();

        // Create a light object
        Light pointLight;
        root.AddLight( L"Point", false, L"PointLight", pointLight );

        // Override the light posx parameter
        Override overrideProp = pointLight.AddProperty( L"Override", false, L"PointOverride" );
        Parameter posx = pointLight.GetKinematics().GetLocal().GetParameters().GetItem(L"posx");

        // Set the original value
        posx.PutValue( 5.0 );

        // Set the overriding value
        Parameter overridingPosx = overrideProp.AddParameterEntry( posx );
        SetValue( overridingPosx.GetFullName(), -4.0, 0 );

        // Log overriding values
        app.LogMessage( L"* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *" );
        app.LogMessage( L"Overriding posx: " + overridingPosx.GetFullName() );
        app.LogMessage( L"Overriding posx value: " + CString( overridingPosx.GetValue() ) );
        app.LogMessage( L"Overriding posx original value: " + CString( overridingPosx.GetOriginalValue() ) );

        // Log overridden values
        Parameter overridenPosx = overridingPosx.GetOverridenObject( );
        app.LogMessage( L"* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *" );
        app.LogMessage( L"Overriden posx: " + overridenPosx.GetFullName() );
        app.LogMessage( L"Overriden posx value: " + CString( overridenPosx.GetValue() ) );
        app.LogMessage( L"Overriden posx original value: " + CString( overridenPosx.GetOriginalValue() ) );

        // INFO : * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
        // INFO : Overriding posx: PointLight.PointOverride.posx
        // INFO : Overriding posx value: -4
        // INFO : Overriding posx original value: 5
        // INFO : * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
        // INFO : Overriden posx: PointLight.kine.local.posx
        // INFO : Overriden posx value: -4
        // INFO : Overriden posx original value: 5
CValue GetOriginalValue ( double  in_time = DBL_MAX) const

Returns the original value of a parameter according to the following:

  • If this parameter is an overridden parameter, its original value is returned (equivalent to what Parameter::GetValue returns on this parameter).
  • If this parameter is an overriding parameter, the overridden parameter's original value is returned. If the overriding parameter value has not yet been set, an empty value is returned.
  • If the parameter is neither overriding nor overridden, this function returns the same as Parameter::GetValue.
Tip:
You must first set the overriding parameter value with the SetValue command to activate the overridden parameter. Parameter::PutValue does not activate the override parameter.
Note:
This property is read-only. You cannot explicitly set the original value.
Parameters:
in_timeFrame at which to set or get the value.
Returns:
The original value of an overridden parameter.
See also:
Override, Parameter::GetOverridenObject
Since:
7.0
The documentation for this class was generated from the following file:
Generated on Mon Jul 9 2012 13:43:12 by doxygen 1.7.4
Please send us your comment about this page