ICENodeContext Class Reference
 
 
 
ICENodeContext Class Reference

#include <xsi_icenodecontext.h>


Class Description

ICENodeContext is used for accessing/handling custom node graph data. Instances of this object can pass information to the C++ API callbacks that implement the custom node plug-in item.

See also:
ICENode, PluginRegistrar::RegisterICENode, ICENode Callbacks
Since:
7.0
Inheritance diagram for ICENodeContext:
Context CBase

List of all members.

Public Member Functions

  ICENodeContext ()
  ~ICENodeContext ()
  ICENodeContext (const CRef &in_ref)
  ICENodeContext (const ICENodeContext &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
ICENodeContext operator= (const ICENodeContext &in_obj)
ICENodeContext operator= (const CRef &in_ref)
CStatus  GetGroupInstanceCount (ULONG in_grpUniqID, ULONG &out_inst_count) const
ULONG  GetEvaluationThreadCount () const
ULONG  GetCurrentThreadIndex () const
ULONG  GetNumberOfElementsToProcess () const
CStatus  PutNumberOfElementsToProcess (ULONG in_nElements)
CStatus  GetPortInfo (ULONG in_nPortID, siICENodeDataType &out_type, siICENodeStructureType &out_struct, siICENodeContextType &out_context) const
CStatus  GetPortInfo (ULONG in_nPortID, siICENodeDataType &out_type, siICENodeStructureType &out_struct, siICENodeContextType &out_context, CString &out_customDataType) const
ULONG  GetEvaluatedOutputPortID () const
CTime  GetTime () const
ULONG  GetEvaluationPhaseIndex () const
CStatus  SetLastEvaluationPhase ()
CStatus  AddEvaluationPhaseInputPort (ULONG in_portid, const XSI::CLongArray &in_portInstances=XSI::CLongArray())
CStatus  SetAsElementDataVarying ()
CStatus  SetAsTimeVarying ()

Constructor & Destructor Documentation

Default constructor.

Default destructor.

ICENodeContext ( const CRef in_ref )

Constructor.

Parameters:
in_ref constant reference object.
ICENodeContext ( const ICENodeContext 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.

ICENodeContext& operator= ( const ICENodeContext in_obj )

Creates an object from another object.

Parameters:
in_obj constant class object.
Returns:
The new ICENodeContext object.
ICENodeContext& 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 ICENodeContext object.

Reimplemented from Context.

CStatus GetGroupInstanceCount ( ULONG  in_grpUniqID,
ULONG &  out_inst_count 
) const

Returns the number of instances for a given group.

Parameters:
in_grpUniqID Group index to query
Return values:
out_inst_count Number of instances
Returns:
CStatus::OK success
ULONG GetEvaluationThreadCount ( ) const

Returns the number of threads used during the Evaluate callback.

Returns:
Thread count.
ULONG GetCurrentThreadIndex ( ) const

Returns the current evaluation thread index. If called from Evaluate, the index ranges between 0 and GetEvaluationThreadCount()-1. Returns 0 if called from either the BeginEvaluate or EndEvaluate callback.

Returns:
ULONG Thread index.
ULONG GetNumberOfElementsToProcess ( ) const

Returns the total number of elements to process during the evaluation of an ICENode. Returns 0 if the operation fails. The return value can be set by the custom ICENode if an output port is set with the siICENodeContextElementGenerator context type.

Returns:
ULONG Number of elements.
See also:
ICENodeContext::PutNumberOfElementsToProcess, ICENodeDef::AddOutputPort
CStatus PutNumberOfElementsToProcess ( ULONG  in_nElements )

Sets the number of elements to generate for an element generator node. The new value will affect the current output port being evaluated.

Parameters:
in_nElements Number of elements. The value is ignored if the current port has not been set with the siICENodeContextElementGenerator context type.
Returns:
CStatus::OK Success.
CStatus::Fail Operation failed.
See also:
ICENodeContext::GetNumberOfElementsToProcess, ICENodeDef::AddOutputPort
Example:
This example shows how to set the number of elements to generate for an element generator type of ICENode. The BeginEvaluate callback must be used for calling ICENodeContext::PutNumberOfElementsToProcess.
                XSIPLUGINCALLBACK CStatus MyICENodeGenerator_BeginEvaluate( ICENodeContext& in_ctxt )
                {
                        // Get some values from an input port
                        CDataArrayLong inSize( in_ctxt, ID_Size );

                        // Total number of elements to generate
                        ULONG nSize = inSize[ 0 ];
                        ULONG nElements = nSize * nSize;
                        in_ctxt.PutNumberOfElementsToProcess( nElements );

                        return CStatus::OK;
                }
CStatus GetPortInfo ( ULONG  in_nPortID,
siICENodeDataType out_type,
siICENodeStructureType out_struct,
siICENodeContextType out_context 
) const

Returns the resolved port types for the specified ICENodePort.

Parameters:
in_nPortID Index of the port to query
Return values:
out_type Data type for this port (see ICENodePort::GetDataType)
out_struct Structure for this port (see ICENodePort::GetStructureType)
out_context Context for this port (see ICENodePort::GetContextType)
Returns:
CStatus::OK success
CStatus GetPortInfo ( ULONG  in_nPortID,
siICENodeDataType out_type,
siICENodeStructureType out_struct,
siICENodeContextType out_context,
CString out_customDataType 
) const

Returns the resolved port types for the specified ICENodePort. The method also returns the resolved custom data type identifier if the port type is set with siICENodeDataCustomType, otherwise the string returned is empty.

Parameters:
in_nPortID Index of the port to query
Return values:
out_type Data type for this port (see ICENodePort::GetDataType)
out_struct Structure for this port (see ICENodePort::GetStructureType)
out_context Context for this port (see ICENodePort::GetContextType)
out_customDataType The custom data type identifier for this port.
Returns:
CStatus::OK success
ULONG GetEvaluatedOutputPortID ( ) const

Returns the unique identifier of the output port being evaluated.

Returns:
CStatus::OK success
CTime GetTime ( ) const

Returns the evaluation time. For a custom ICENode, the evaluation time is not necessarily the same as the current scene time or that it is evaluated just once per frame.

Returns:
CTime Evaluation time
ULONG GetEvaluationPhaseIndex ( ) const

Returns the current evaluation phase index when the ICENode is configured for multi-phase evaluation. This method returns UINT_MAX if the node threading mode is not set accordingly or the method is called during the last processing phase.

Returns:
Phase index.
See also:
ICENodeDef::PutThreadingModel, siICENodeMultiEvaluationPhase, ICENodeContext::AddEvaluationPhaseInputPorts, ICENodeContext::SetLastEvaluationPhase
Since:
8.0 (2010)
CStatus SetLastEvaluationPhase ( )

Sets the current evaluation phase as the last phase to process. This tells Softimage to pull the input port(s) data for the final processing phase. This method is enabled only when the node threading model is set to siICENodeMultiEvaluationPhase.

Returns:
CStatus::OK Operation succeeded.
See also:
ICENodeContext::GetEvaluationPhaseIndex, ICENodeContext::AddEvaluationPhaseInputPorts
Since:
8.0 (2010)
CStatus AddEvaluationPhaseInputPort ( ULONG  in_portid,
const XSI::CLongArray in_portInstances = XSI::CLongArray() 
)

Adds an input port to evaluate for the current evaluation phase. This method must be used in the context of a custom node with multi-evaluation processing and from the SubmitEvaluationPhaseInfo callback. The method is enabled only when the node threading model is set to siICENodeMultiEvaluationPhase.

AddEvaluationPhaseInputPort takes a port identifier, as specified with ICENodeDef::AddInputPort, and an optional array of port instance numbers. By default, all port instances are evaluated, but you can specify the port instance number(s) corrsponding to which port(s) you want to be evaluated in the in_portInstances array. You can call AddEvaluationPhaseInputPort multiple times to specify multiple ports to evaluate. Ports are evaluated in the same order in which they are specified.

Here are some important rules to follow when specifying the input ports to pull:

  • Except for singleton contexts, ports with similar context types should be prepared together in the same phase for better performance.
  • Unless input port contexts are specified as singletons, ports specified during the last phase must match the context of the output port(s).
Parameters:
in_portid A unique identifier describing the input port.
in_portInstances A CLongArray containing the instance(s) of the port(s) to evaluate.
Returns:
CStatus::OK Operation succeeded.
CStatus::InvalidArgument Input port or instances are invalid.
See also:
ICENodeContext::GetEvaluationPhaseIndex, ICENodeContext::SetLastEvaluationPhase, ICENodeDef::AddInputPort
Since:
8.0 (2010)
CStatus SetAsElementDataVarying ( )

In ICE, the data flowing in an ICETree is constant by default. For instance, the element data of a particle cloud do not vary at each evaluation when it's constant. In this case, the data array of an input port will always be set with one single value. SetAsElementDataVarying can be used to force the element data to vary independently of the input data state.

A typical use of SetAsElementDataVarying is when a custom node needs to output data randomly regardless of the input data state. The GridWalker example uses constants for all inputs and calling SetAsElementDataVarying will allow the GridWalker node to set the data for all particle elements.

Note:
Calling this method could lead to performance issues when it is not strictly required.
Returns:
CStatus::OK Operation succeeded.
Since:
8.0 (2010)
CStatus SetAsTimeVarying ( )

Forces the node to evaluate frame by frame regardless of the overall graph state. You can use this function instead of connecting the CurrentFrameNode as input to the custom node.

Returns:
CStatus::OK Operation succeeded.
Since:
8.0 (2010)

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