ICENodeContext Class Reference

Search for all occurrences

#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:

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]

Search for all occurrences

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]

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

Returns the number of threads used during the Evaluate callback.

Returns:

Thread count.

ULONG GetCurrentThreadIndex

(

)

const

Search for all occurrences

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

Search for all occurrences

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

)

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

Returns the unique identifier of the output port being evaluated.

Returns:

CStatus::OK success

CTime GetTime

(

)

const

Search for all occurrences

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

Search for all occurrences

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

(

)

Search for all occurrences

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()
	)

Search for all occurrences

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

(

)

Search for all occurrences

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

(

)

Search for all occurrences

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