Copies from an input scene onto the vertices of a target object, making one copy per vertex. Additional primitive variables on the target object can be used to choose between multiple instances, and to specify their orientation and scale. Note the target object will be removed from the scene.
Container for user-defined plugs. Nodes should never make their own plugs here, so users are free to do as they wish.
The processed output scene.
The on/off state of the node. When it is off, the node outputs the input scene unchanged.
The input scene
The filter used to control which parts of the scene are processed. A Filter node should be connected here.
The object on which to make the instances. The position, orientation and scale of the instances are taken from per-vertex primitive variables on this object. This is ignored when a filter is connected, in which case the filter specifies multiple objects to make the instances from.
The name of the location the instances will be generated below. This will be parented directly under the parent location.
The scene containing the prototypes to be applied to
each vertex. Use the
prototypeMode and associated
plugs to control the mapping between prototypes and
Note that the prototypes are not limited to being a single object - they can have arbitrary child hierarchies.
The method used to define how the prototypes map onto each instance.
In “Indexed (Roots List)” mode, the
prototypeIndexprimitive variable must be an integer per-vertex. Optionally, a path in the prototypes scene corresponding to each index can be specified via the
prototypeRootsListplug. If no roots are specified, an index of 0 applies the first location from the prototypes scene, an index of 1 applies the second, and so on.
In “Indexed (Roots Variable)” mode, the
prototypeIndexprimitive variable must be an integer per-vertex, and the
prototypeRootsprimitive variable must be a separate constant string array specifying a path in the prototypes scene corresponding to each index.
In “Root per Vertex” mode, the
prototypeRootsprimitive variable must be a string per-vertex which will be used to specify a path in the prototypes scene for each instance.
it is advisable to provide an indexed string array in order to limit the number of unique prototypes.
The name of a per-vertex integer primitive variable used to determine which prototype is applied to the vertex. This plug is used in “Indexed (Roots List)” mode as well as “Indexed (Roots Variable)” mode.
prototypeMode is set to “Indexed (Roots Variable)”,
then this should specify the name of a constant string
array primitive variable used to map between
and paths in the prototypes scene.
prototypeMode is set to “Root per Vertex”, then this
should specify the name of a per-vertex string primitive
variable used to specify a path in the prototypes scene
for each instance.
This plug is not used in “Indexed (Roots List)” mode.
An explicit list of paths used to map between
and paths in the prototypes scene. This plug is only used in
“Indexed (Roots List)” mode.
The name of a per-vertex integer primitive variable used to give each instance a unique identity. This is useful when points are added and removed over time, as is often the case in a particle simulation. The id is used to name the instance in the output scene.
The name of the per-vertex primitive variable used to specify the position of each instance.
The name of the per-vertex primitive variable used to specify the orientation of each instance. This must be provided as a quaternion : use an upstream Orientation node to convert from other representations before instancing.
The name of the per-vertex primitive variable used to specify the scale of each instance. Scale can be provided as a float for uniform scaling, or as a vector to define different scaling in each axis.
The names of per-vertex primitive variables to be turned into per-instance attributes. Names should be separated by spaces and can use Gaffer’s standard wildcards.
A prefix added to all per-instance attributes specified via the “attributes” plug.
Converts each group of instances into a capsule, which won’t be expanded until you Unencapsulate or render. When keeping these locations encapsulated, downstream nodes can’t see the instance locations, which prevents editing but improves performance. This option should be preferred to a downstream Encapsulate node because it has the following benefits :
- Substantially improved performance when the prototypes define sets.
- Fewer unnecessary updates during interactive rendering.