Public Member Functions
ICENodeContext Class Reference

## Detailed 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, cb_icenodes ICENode Callbacks

Since:
  7.0

`#include <xsi_icenodecontext.h>`

Inheritance diagram for ICENodeContext:
[legend]

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

ICENodeContext | ( |  | ) |

Default constructor.

~ICENodeContext | ( |  | ) |

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 cb_ICENode_Evaluate Evaluate callback.

Returns:
  Thread count.

ULONG GetCurrentThreadIndex | ( |  | ) | const

Returns the current evaluation thread index. If called from cb_ICENode_Evaluate Evaluate , the index ranges between 0 and GetEvaluationThreadCount()-1. Returns 0 if called from either the cb_ICENode_BeginEvaluate BeginEvaluate or cb_ICENode_EndEvaluate 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 cb_ICENode_BeginEvaluate 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 cb_ICENode_SubmitEvaluationPhaseInfo 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 CustomICENodes/netview_CustomICENodes 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:

- xsi_icenodecontext.h