Port Data Indexing

The CIndexSet and CIndexSet::Iterator classes are recommended for accessing the input data of custom ICENodes. These classes encapsulate the indices required for accessing the custom ICENode input ports for a given evaluation thread. Conventional array indexing (direct access) is still possible for accessing the input port data but it is not as efficient as CIndexSet. This is particularly true in multi-threading mode since ICE breaks index subsets and run them on separate threads. If direct access is used instead, then all threads will iterate over the data with the same indices resulting with a loss of performance.

In the multi-threading operation mode, the CIndexSet objects are associated to the ICENode input and output ports that share the same evaluation context. In single-threading mode, CIndexSet objects are not associated to the input and output ports because their context can be different. Therefore, CIndexSet objects must be created for specific input ports in single-threading mode.

Using CIndexSet in single-threading mode for a specific port:

CIndexSet indexSet( in_ctxt, ID_IN_PointPosition );
for ( CIndexSet::Iterator it = indexSet.Begin(); it.HasNext(); it.Next() )
{
	CVector3f& v3f = posArray[ it ];

	if ( v3fMin.GetX() >= v3f.GetX() && v3fMin.GetY() >= v3f.GetY() && v3fMin.GetZ() >= v3f.GetZ() )
	{
		v3fMin = v3f;
	}

	if ( v3fMax.GetX() <= v3f.GetX() && v3fMax.GetY() <= v3f.GetY() && v3fMax.GetZ() <= v3f.GetZ() )
	{
		v3fMax = v3f;
	}
}

Using CIndexSet in multi-threading mode:

CIndexSet indexSet( in_ctxt );
for(CIndexSet::Iterator it = indexSet.Begin(); it.HasNext(); it.Next())
{
	outData[it] = inputData[it].GetX();
}

Note

When a custom ICENode is set up for the multi-phase mode (siICENodeMultiEvaluationPhase), CIndexSet objects must be created for specific ports. This is required only for the intermediate phases since they are always run in single-threading.

Unlike the input port data, the indices exposed by CIndexSet are not immutable and can be removed from the subset. This operation is called element filtering. Filtering out indices from a subset hides these indices from other ICENodes in the graph. Element filtering is an important concept which enables condition-based optimizations that could occur in an ICE graph. Removing indices from the subset doesn't alter the content of the input data which will always be set to the same size. The CIndexSet::Iterator class has been designed to automatically skip the filtered elements of a subset, that's why it is absolutely crucial to always iterate over the input data with the CIndexSet::Iterator class.

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License