XSI::OperatorContext

OperatorContext Class Reference



Your Ad Here

Related Scripting Object: OperatorContext

This class is provided as the context object in the Operator update callback for a Self-Installed CustomOperator object (see PluginRegistrar::RegisterOperator). More...

#include <xsi_operatorcontext.h>

Inheritance diagram for OperatorContext:

Context CBase List of all members.

Public Member Functions
  OperatorContext ()
  ~OperatorContext ()
  OperatorContext (const CRef &in_ref)
  OperatorContext (const OperatorContext &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
OperatorContext &  operator= (const OperatorContext &in_obj)
OperatorContext &  operator= (const CRef &in_ref)
CRef  GetOutputTarget () const
CRef  GetOutputPort () const
CTime  GetTime () const
CValue  GetInputValue (LONG in_port, LONG in_group=0, LONG in_instance=0) const
CValue  GetInputValue (const CString &in_port, const CString &in_group=CString(), LONG in_instance=0) const
CValue  GetParameterValue (const CString &in_name) const

Detailed Description

This class is provided as the context object in the Operator update callback for a Self-Installed CustomOperator object (see PluginRegistrar::RegisterOperator).

This object is offers all the context information necessary to implement a normal operator. However for advanced operators it is possible to retrieve more information via the CustomOperator object, which is available through Context::GetSource.

Note:
The UpdateContext object continues to be used for legacy C++ Custom Operators based on a Preset and SPDL.
The Context::GetUserData and Context::PutUserData functions provide a convenient way to store non-persisted, per-instance state information for the operator. A common pattern is to use user data to store a pointer to C++ objects that actually implement the operator algorithm and store the operator's state.

See also:
UpdateContext, CustomOperator, Operator, PluginRegistrar
Since:
5.1

Constructor & Destructor Documentation

OperatorContext (  ) 

Default constructor.

~OperatorContext (  ) 

Default destructor.

OperatorContext ( const CRef &  in_ref  ) 

Constructor.

Parameters:
in_ref  Constant reference object.

OperatorContext ( const OperatorContext &  in_obj  ) 

Copy constructor.

Parameters:
in_obj  Constant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID  )  const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassID  Class type.
Returns:
True if the class is compatible, false otherwise.

Reimplemented from Context.

siClassID GetClassID (  )  const [virtual]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from Context.

OperatorContext& operator= ( const OperatorContext &  in_obj  ) 

Creates an object from another object.

Parameters:
in_obj  Constant class object.
Returns:
The new OperatorContext object.

OperatorContext& operator= ( const CRef &  in_ref  ) 

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_ref  Constant class object.
Returns:
The new OperatorContext object.

Reimplemented from Context.

CRef GetOutputTarget (  )  const

Returns the target object connected to the OutputPort. The only state of the XSI scene that an operator should modify during its evaluation is via the functions available on the object returned by this function. For example, if an operator writes to a ClusterProperty (for example, a Weight Map) then this function will return the ClusterProperty and the operator code can set the values of the property via CClusterPropertyElementArray::PutArray.

In the case of a multi-output operator the operator is called once per output, and this function will return the currently evaluating target. In this case it may be necessary to also call OperatorContext::GetOutputPort to determine the name of the current output port, in order to know which output is being evaluated.

Note:
If the operator is writing to a Parameter then use OperatorContext::GetOutputPort instead of this function.
Returns:
A reference to the XSI object being written
See also:
CustomOperator::AddOutputPort, OperatorContext::GetOutputPort

CRef GetOutputPort (  )  const

Returns the OutputPort that represents the connection to the currently evaluating output target. In the case of a multi-output operator this object can be used to determine which output is currently being evaluated.

When the operator is writing to a Parameter use the OutputPort::PutValue function on the returned OutputPort to set a new value on the parameter.

Returns:
OutputPort

CTime GetTime (  )  const

Returns the evaluation time. An operator should not assume that the evaluation time is the same as the current scene time or that it is evaluated just once per frame.

Returns:
CTime Evaluation time

CValue GetInputValue ( LONG  in_port,
LONG  in_group = 0,
LONG  in_instance = 0  
) const

Returns the value of a given InputPort on the CustomOperator by index. If the connected object is a Parameter this will return the actual value of the Parameter value, not the Parameter object. Otherwise it will return the object that represents the input object, and this object can be used to retrieve information about the state of the input object. For example if the operator is connected to a Parameter of type double this will return a double. And if the operator is connected to a Primitive this will return a Primitive.

Note:
This function is a convenient and fast approach that hides the existence of InputPort objects.
Parameters:
in_port  Port index. If the operator was created by a function like Parameter::AddCustomOp then the index is easy to determine based on the order of the inputs in the input argument. If the operator was built manually then the index can be determined based on the order of calls to CustomOperator::AddInputPort or CustomOperator::AddIOPort
in_group  PortGroup index. Use this parameter for advanced operators that have more than one PortGroup. Otherwise it can be assumed that the input is on the first group (group 0)
in_instance  PortGroup instance index. Use this parameter for advanced operators that support having more than one object connecting to a particular PortGroup. Otherwise it is assumed that the input is on the first group instance.
Returns:
A CValue containing a reference to an XSI Object or the value of a Parameter.
See also:
Operator::GetInputValue, Parameter::GetValue

CValue GetInputValue ( const CString &  in_port,
const CString &  in_group = CString(),
LONG  in_instance = 0  
) const

Returns the value of a given input port by name. This variation works based on the string names of the InputPort and PortGroup objects.

Warning:
This function is slower the other signature, which works based on numeric index.
Parameters:
in_port  Port name.
in_group  PortGroup name.
in_instance  PortGroup instance index.
Returns:
A CValue containing a reference to an XSI Object or the value of a Parameter.
See also:
Operator::GetInputValue, Parameter::GetValue

CValue GetParameterValue ( const CString &  in_name  )  const

Returns the current value of the specified Parameter, if any, of the CustomOperator. This function provides access only to parameters defined for the CustomOperator. For example, an Operator often has parameters that allow the user or the plug-in to configure the operator's behavior, such as "RecursionDepth", "UDivisions", "Height" or "CenterX".

Note:
This function cannot be used to retrieve the value of Parameters on any other object in the scene. For that scenario the operator should connect to the Parameter (or object that owns the parameter) and use OperatorContext::GetInputValue to retrieve the Parameter value.
Parameters:
in_name  scripting name of the parameter for which we want to get the value.
Returns:
The current value of the Parameter (boolean, double, string or other supported type)

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.

See also:
ProjectItem::GetParameterValue, Parameter::GetValue

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

Return to Softimage XSI Index


Your Ad Here