Parameter Class Reference
This reference page is linked to from the following overview topics: Using the Mental Ray Shader Wizard, Command Examples, Checking Return Values for Type.
#include <xsi_parameter.h>
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.
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() );
}
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 |
| 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.
| in_ClassID | Test if this object supports this class. |
Reimplemented from SIObject.
Reimplemented in ArrayParameter, KinematicState, ProxyParameter, ShaderArrayParameter, and ShaderParameter.
| siClassID GetClassID | ( | ) | const [virtual] |
Gets the class ID for this object.
Reimplemented from SIObject.
Reimplemented in ArrayParameter, KinematicState, ProxyParameter, ShaderArrayParameter, and ShaderParameter.
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.
| in_ref | A reference to an object that supports the Parameter class. |
Reimplemented from SIObject.
Reimplemented in ArrayParameter, KinematicState, ProxyParameter, ShaderArrayParameter, and ShaderParameter.
| LONG GetCapabilities | ( | ) | const |
Gets a mask of all the object's siCapabilities values.
| 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.
| in_flag | Specify the flag to change |
| in_bEnable | True to set the capability; false to remove it. |
| bool GetMarked | ( | ) | const |
Returns the object's marked state
| 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.
| in_bVal | Marked state flag |
| 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.
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.
| in_scriptname | The scripting name of the parameter (see Parameter::GetScriptName). |
| 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.
| in_time | Time in frame |
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.
| in_val | The parameter value to set. |
| in_time | Time in frame, defaults to the current frame (indicated by the
value of DBL_MAX). |
in_val cannot be converted to the parameter
type.| CString GetScriptName | ( | ) | const |
Returns the parameter's script name.
| CString GetDescription | ( | ) | const |
Returns the descriptive string of a Parameter. The description is a longer, more descriptive version of the parameter name.
| 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".
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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()
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.
| in_source | data source to connect. |
| CStatus AddFCurve | ( | siFCurveType | in_Type, |
| FCurve & | io_FCurve | ||
| ) |
Creates and connects an FCurve object to this parameter.
| in_Type | function curve type |
| io_FCurve | New FCurve object created |
| Expression AddExpression | ( | CString & | in_ExpressionDefinition | ) |
Creates and connects an Expression object to this parameter.
| in_ExpressionDefinition | The expression formula |
| 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.
| in_strName | Preset name |
| in_strFamily | Preset family name |
| io_prevSource | The CRef object that was previously connected. |
| io_source | The new CRef object. |
| 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.
| in_strName | Preset name |
| in_strSourceName | Source name |
| in_strFamily | Preset family name |
| io_prevSource | The CRef object that was previously connected. |
| io_source | The new CRef object. |
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.
| in_strName | Preset name |
| io_prevSource | The CRef data source object that was previously connected. |
| io_source | The new CRef to a data source object. |
| 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.
| in_strName | Preset name |
| in_strSourceName | Source name |
| io_prevSource | The CRef data source object that was previously connected. |
| io_source | The new CRef to a data source object. |
Creates a data source ( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object from a progid string and connects it to the parameter.
| in_strName | Preset name |
| io_prevSource | The CRef data source object that was previously connected. |
| io_source | The new CRef data source object. |
| 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.
| in_strName | Preset name |
| in_strSourceName | Source name |
| io_prevSource | The CRef data source object that was previously connected. |
| io_source | The new CRef data source object. |
Connects a data source ( e.g. ActionSource, Constraint FCurve, ImageClip, Operator, Shader, StaticSource.) object to the parameter.
| in_source | A reference to the data source object to connect. |
| io_prevSource | A reference to the data source object that was previously connected. |
| CStatus Disconnect | ( | ) |
Disconnects a source (e.g. FCurve, Expression, ImageClip, Operator, Shader) object from the parameter.
Disconnects a source (e.g. FCurve, Expression, ImageClip, Operator, Shader) object from the parameter.
| io_prevSource | A reference to the previously connected source object. |
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
| in_scriptname | The parameter scripting name (see Parameter::GetScriptName). |
| in_val | The parameter value to set. |
| in_time | Time in frame, defaults to the current frame (represented by
the value of DBL_MAX). |
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.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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.
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.
| in_name | Name of the parameter for which we want to get the value. |
| in_time | Time in frame defaults to the current frame (represented by the
value of DBL_MAX). |
| bool IsAnimated | ( | siSourceType | in_sourceType =
siAnySource |
) | const |
Returns true if the object is animated by a specific animation source type and false otherwise.
| in_sourceType | Animation source type,the default value is any source. |
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.
| in_sourceType | An object type. |
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.
| siLockLevel GetLockLevel | ( | ) |
Returns the lock level
| bool IsLocked | ( | ) |
Returns if an parameter is locked or not.
| CStatus SetLock | ( | siLockLevel | in_level =
siLockLevelAll |
) |
Locks a parameter
| in_level | The level to lock (use siLockLevelAll to lock it for all levels) |
| CStatus UnSetLock | ( | siLockLevel | in_level =
siLockLevelAll, |
| const CString & | in_password = CString() |
||
| ) |
Unlocks a parameter.
| in_level | The level to unlock (use siLockLevelAll to lock it for all levels) |
| in_password | The optional password to pass when the scene locks are password protected |
| 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.
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.
| in_eVal | The Tags to set |
| 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.
| in_code | The script code containing the implementation of the scripted operator. |
| in_inputs | Array of objects or parameters to be connected to input ports. |
| in_name | Name of the new scripted operator |
| in_language | The script language of the new scripted operator. If not specified the value current user preference for the scripting language will be used. |
| io_pst | Returned error status |
| 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.
| in_filename | The script filename containing the implementation of the scripted operator. |
| in_inputs | Array of objects or parameters to be connected to input ports. |
| in_name | Name of the new scripted operator |
| in_language | The script language of the new scripted operator. If not specified the value current user preference for the scripting language will be used. |
| io_pst | Returned error status |
| 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.
| in_type | The type of a operator. A PluginItem must be installed by this name. |
| in_inputs | Array of objects or parameters to be connected to input ports. |
| in_name | Name of the new custom operator. If not specified the type is used to determine a name for the operator. |
| io_pst | Returned error status |
| X3DObject GetParent3DObject | ( | ) | const |
| Model GetModel | ( | ) | const |
| 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 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.
| in_obj | The object to test the value |
| in_val | The value to test. |
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.
| in_obj | The object for which the instance value should be retrieved. |
| in_bindtobject | If 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. |
| 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.
| in_obj | The object to which the instance value should be assigned. |
| in_val | The 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_bindtovalidate | If 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. |
| 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.
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.
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:
| in_time | Frame at which to set or get the value. |