ICENodes are configured with an ICENodeDef object which provides the API with definitions for the input and output ports (ICENodeDef::AddInputPort, ICENodeDef::AddOutputPort), groups (ICENodeDef::AddPortGroup) and to specify the threading model (ICENodeDef::PutThreadingModel, ICENodeDef::GetThreadingModel).
Each custom ICENode has at least one output and zero or more input ports. Each port must be configured for the specific data it needs to read or write to. ICENodePorts need to be defined with a group, which can contain an unlimited number of ports. You usually want to regroup ports in the same logical group but nothing prevents you from defining one port per group. Input and output ports cannot be mixed in the same group.
Input and output ports use a strong typing system defined with a 3-category type set:
Type of data the port can support. See siICENodeDataType for a list of available data types.
The way the data is stored when passed to the Evaluate callback. See siICENodeStructureType for a list of available structure types.
Specifies the elements on which the data is evaluated. See siICENodeContextType for a list of available context types.
The type of a port is specified with a triple value set, one for each category.For example:
// single array of vector3 elements evaluated for each mesh vertex siICENodeDataVector3 + siICENodePortStructureSingle + siICENodeEvaluationContextComponent0D: // single array of booleans evaluated per object siICENodePortDataBool + siICENodePortStructureSingle + siICENodeContextSingleton: // 2D array of long values evaluated per mesh polygons siICENodePortDataLong + siICENodePortStructureArray + siICENodeEvaluationContextComponent2D:
You can create user-defined types which can be used like any regular data type for defining a custom node port. Custom types are typically used in ICE for propagating user-defined data (such as binary data) through the graph. Custom types can be defined with the ICENodeDef object and are identified with a global identifier (string name), a fundamental data type (siICENodeDataCustomType) and a port connection handle color.
In general, port types of a same category can be combined together to allow port polymorphism. Polymorphism refers to a ICENode port's ability to support multiple types. This is helpful if you need to define general-purpose nodes where the input data is used generically (see Polymorphism handling section for details.). You can assign multiple types to ports by using the bitwise OR operator with AddInputPort and AddOutputPort methods.
Constraint maps force multiple input and output ports to use the same data, structure or context types. For instance, mapping can be used to enforce the context of input port A and output port B to siICENodeContextSingleton. In some scenarios, input ports can also be constrained between each other, as can output ports. You can set up a mapping by linking the port types or structures with an integer: use the same integer for ports that need to match or ULONG_MAX if no constraints are required. Port constraints are specified when defining ports with AddInputPort and AddOutputPort.
Ports and groups must be defined with unique identifiers. ICENodeDef will issue an error if duplicate identifiers are used. A simple way to ensure your identifiers are unique is to use an enum. Using unique IDs also ensures full backward compatibility on ports in case ICENode ports or groups are removed or new ones added. Ports can be added or removed without affecting the loading of old scenes saved with a previous version of a specific ICENode.
You must not change the enum identifiers in order to maintain backward compatibility. Once an identifier is used, it must remain intact for the entire life of the ICENode and must not be reused by another port or group. You can only add new identifiers at the end of the enum when new ports are required.
Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License
