Instancer
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.
user
Container for user-defined plugs. Nodes should never make their own plugs here, so users are free to do as they wish.
out
The processed output scene.
enabled
The on/off state of the node. When it is off, the node outputs the input scene unchanged.
in
The input scene
filter
The filter used to control which parts of the scene are processed. A Filter node should be connected here.
parent
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.
name
The name of the location the instances will be generated below. This will be parented directly under the parent location.
prototypes
The scene containing the prototypes to be applied to
each vertex. Use the prototypeMode
and associated
plugs to control the mapping between prototypes and
instances.
Note that the prototypes are not limited to being a single object - they can have arbitrary child hierarchies.
prototypeMode
The method used to define how the prototypes map onto each instance.
In “Indexed (Roots List)” mode, the
prototypeIndex
primitive variable must be an integer per-vertex. Optionally, a path in the prototypes scene corresponding to each index can be specified via theprototypeRootsList
plug. 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
prototypeIndex
primitive variable must be an integer per-vertex, and theprototypeRoots
primitive 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
prototypeRoots
primitive variable must be a string per-vertex which will be used to specify a path in the prototypes scene for each instance.Note
it is advisable to provide an indexed string array in order to limit the number of unique prototypes.
prototypeIndex
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.
prototypeRoots
If prototypeMode
is set to “Indexed (Roots Variable)”,
then this should specify the name of a constant string
array primitive variable used to map between prototypeIndex
and paths in the prototypes scene.
If 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.
prototypeRootsList
An explicit list of paths used to map between prototypeIndex
and paths in the prototypes scene. This plug is only used in
“Indexed (Roots List)” mode.
id
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.
position
The name of the per-vertex primitive variable used to specify the position of each instance.
orientation
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.
scale
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.
attributes
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.
attributePrefix
A prefix added to all per-instance attributes specified via the “attributes” plug.
encapsulateInstanceGroups
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.
seedEnabled
Creates a seed context variable based on a hash of the instance ID, which could come
from the primitive varable specified in the id
plug or otherwise the point index.
This integer is available to the upstream prototypes network, and might typically
be used with a Random node to randomise properties of the prototype.
seedVariable
Name of the context variable to put the seed value in.
seeds
The number of possible seed values. Increasing this allows for more different variations to be driven by the seed, increasing the total number of variations required.
seedPermutation
Changing the seedPermutation changes the mapping of ids to seeds. This results in a different grouping of which instances end up with the same seed.
rawSeed
Enable this in rare cases when it is required to pass through every single id directly into the seed context variable. This is very expensive, because every single instance will need a separate context, but is sometimes useful, and may be an acceptable cost if there isn’t a huge number of total instances.
contextVariables
Specifies context variables to be created from primitive variables. These variables are available to upstream prototypes network, allowing the prototypes scene to be generated differently depending on the source point. Supports quantization to avoid re-evaluating the prototypes scene too many times.
timeOffset
Modify the current time when evaluating the prototypes network, by adding a primvar.
variations
This special output plug returns an CompoundData dictionary with counts about how many variations are being created. For each context variable variable being set ( including “frame” when using Time Offset ), there is an entry with the name of the context variable, with an IntData containing the number of unique values of that context variable. There is also an entry for “”, with an IntData for the total number of unique contexts, considering all the context variables being created.
Extracting the dictionary values and displaying them to users is handled by _VariationsPlugValueWidget.
This information is important to display to users because varying the context requires
extra evaluations of the prototypes
scene, and can dramatically increase the cost of the Instancer.
Note that variations are measured across all locations in the scene where the instancer is filtered.