DrawInstances
Stamp a rendered texture — an image, a whole effect chain, or another layer's output — at every point in a Points set, with per-point rotation, scale, opacity, and color tint.
Category: Render Menu path: Render > Draw Instances
Ports
| Port | Type | Direction | Description |
|---|---|---|---|
in | imageRgba16f | input (multi) | Source palette: connect one or more textures. Per-point selection cycles/randomizes across them (like CloneToPoints' Shapes input, but in the texture domain) |
points_in | points | input | Points to stamp at. Also accepts a Shape (its vertices are used) |
out | imageRgba16f | output | All instances composited in point order |
Parameters
| Param | Type | Default | Description |
|---|---|---|---|
scale | scalar | 1.0 | Uniform scale multiplier on top of per-point scale attributes |
rotation | scalar | 0 | Extra rotation in degrees on top of per-point rotation attributes |
opacity | scalar | 1.0 | Uniform opacity multiplier on top of per-point opacity attributes |
anchor | vec2 | 0.5, 0.5 | Which point of the stamp rect lands on the target point. (0.5, 0.5) = center, (0, 0) = top-left |
fitMode | enum | None | None stamps content at natural size. Fit scales content to fit inside the cell (contain). Fill crops content to the cell's aspect and fills it exactly (cover) |
cellSize | vec2 | 200, 200 | Cell dimensions in comp px (when fitMode ≠ None) — or per point, from a cellSize column; Layout writes one on every cell it emits. The param is the fallback for points that carry none |
cornerRadius | scalar | 0 | Rounded-rect mask radius in px, applied in stamp-local space so it rotates/scales with each instance |
selectionMode | enum | Sequential | How each point picks its variant — palette source in palette mode, clone render in per-clone mode: Sequential (in point order, i mod N), Random (seeded hash of the point's id, so a point keeps its variant for life), Point Index (reads a shapeIndex column written on the point — write it with PointAttributes' Custom target; with no such column it falls back to the same stable id-hash Random uses) |
seed | scalar | 0 | Seed for Random selection / Random time offsets |
group | string | "" | Column-name filter — only points whose named column (attribute or intrinsic) exceeds the threshold receive an instance. Empty = all points |
groupThreshold | scalar | 0.5 | Threshold for the group filter |
timeOffsetMode | enum | Off | Per-instance time offsets: Sequential (i × offsetFrames cascade), Random (shuffled over the same span, drawn from the point's id so an instance keeps its source frame for life), Attribute (per-point scalar × offsetFrames) |
offsetFrames | scalar | 2 | Frames of offset per step |
offsetAttribute | string | index | Per-point value driving offsets in Attribute mode — any attribute or intrinsic (@indexnorm cascades evenly with no tagging). Vec values reduce (magnitude / luma). A missing or typo'd name reads as 0 = no offset; it used to fall back to the point index, which turned a typo into a plausible sequential cascade |
maxTimeSamples | scalar | 8 | Offsets are quantized into this many distinct sample frames (max 32) |
perClone | enum | Auto | Auto re-evaluates the source chain once per instance when a CloneIndex node is upstream. Off disables per-clone evaluation |
maxClones | scalar | 32 | Cap on per-clone re-evaluations; excess clones share renders round-robin |
Expose Channels
When enabled (E button on node header), adds input ports that override params via edge connections:
| Port | Type | Overrides |
|---|---|---|
scale_in | scalar | scale |
rotation_in | scalar | rotation |
opacity_in | scalar | opacity |
How It Works
DrawInstances is CloneToPoints for pixels. Each source input is captured as a stamp (its content rect — an image's actual dimensions, or the comp area for effect chains and generators) and drawn once per point as a GPU-instanced textured quad, reading the same per-point attributes CloneToPoints reads: rotation (radians), scale (scalar or per-axis vec2), opacity, and color (RGB tint). All instances render in a single MSAA draw call; point order is paint order, so later points stack on top.
Fitting. fitMode decides how a source meets its cell: Fit scales the whole picture to sit inside the box, Fill crops it to the box's aspect and fills it edge to edge, None ignores the box and stamps the picture at its natural size. The box is normally the cellSize param, the same for every instance — but a point carrying its own cellSize fits to that instead, so a grid of differently sized cells gets differently sized content, each cropped against its own aspect. Layout writes that column on every cell, which is what makes a bento of mixed tiles work. A point with no cellSize (or a zero on either axis, which reads as "none") falls back to the param, so nothing about a Grid or a scatter changes. When the incoming points do carry one, the Cell Size row in Properties says so — unused when every point has its own box, partly unused when only some do (a merged stream), which is why the row stays put instead of disappearing. Per-point scale still multiplies on top: cellSize chooses the box, scale scales the stamp that fitted into it. cornerRadius is an absolute px radius clamped to each instance's own box, so it rounds a small cell proportionally more than a large one.
Colour rule: DrawInstances tints — a per-point color multiplies the source pixels (white = unchanged). DrawPoints overrides — its per-point color replaces the node colour outright. Same attribute, two renderers, two documented behaviours.
With time offsets, each instance samples its source chain at frame − offset, re-evaluating the chain live at the offset frames (quantized to maxTimeSamples buckets). The result is a pure function of the timeline — scrubbing anywhere always renders the same picture.
With a CloneIndex node in the source chain, the chain is re-evaluated once per instance with a distinct index — each copy can drive any parameter from its own index (see CloneIndex). selectionMode then controls which clone render each point shows: Sequential assigns in point order, Random shuffles (seeded, keyed on the point), and Point Index reads the shapeIndex column written on each point — so a field written through PointAttributes' Custom target (named shapeIndex) can assign clone variants spatially.
Variation on a particle stream
Random hashes the point's id, which never changes once a point is born, so an instance keeps the same palette source, the same clone render and the same time offset for its whole life while neighbours are born and die around it. Point Index behaves the same way when nothing wrote a shapeIndex column.
Sequential is positional by definition — it reads a point's place in the stream, and that place is renumbered whenever membership changes. On a static cloud (a Grid, a scatter) that is exactly what you want; on a particle system it means a stamp changes every time another particle expires.
The same caution applies to the builtin index: it is an order, not an identity, so anything selecting on it reshuffles when points die. That is why variant selection reads shapeIndex (a column you wrote on purpose) and never index. In Attribute time-offset mode, offsetAttribute defaults to index for the same reason — on a particle stream point at @rand01 or your own column instead.
Intrinsic Names
Any attribute-name field here also accepts an intrinsic — a property every element has by virtue of existing, computed on read and never stored. The leading @ is a reserved namespace: no attribute may be named with one, so a name starting with @ never hits the attribute map.
| Name | Value |
|---|---|
@index | Position in the list, starting at 0 |
@id | Stable PointId — survives filtering and reordering |
@x / @y | Position, in local geometry space |
@n | Total number of elements |
@indexnorm | @index / (@n - 1), normalized 0–1 |
@rand01 | Deterministic 0–1 per element, keyed on @id (stable as neighbours come and go) |
@speed | Speed in pixels per second, from the velocity attribute (0 where there is none) |
Names are case-insensitive (@Y = @y). A misspelled intrinsic (@bogus) resolves to nothing rather than falling through to an attribute lookup.
Non-scalar attributes reduce to a scalar by one rule everywhere: Vec2/Vec3 → magnitude, Vec4 → Rec.709 luma of RGB.
So group = "@rand01" with groupThreshold = 0.8 draws a stable random 20% of the instances.
Usage Examples
Basic: Clone an effect chain to points
Build Circle → DrawShape → Glow, connect its output into DrawInstances in, and a Grid into points_in. Every grid point gets the full glowing-circle render. Drive per-point variation with PointAttributes (scale, rotation, opacity, color — including Index-mode ramps).
Image grid: photos in animated cells
Connect several images into in (they cycle per point), set fitMode to Fill with a square cellSize and a cornerRadius — mixed-aspect photos become uniform rounded tiles. Animate the points (keyframed Transform2D in geometry mode, PointDeform, PointsAlongPath) and the tiles travel in formation.
Bento: a grid of unequal tiles
Wire Layout.cells → points_in, put your media in the palette, and set fitMode to Fill. Each cell fits its own box, so a 1 2 1 column split gives you a wide middle tile with the picture cropped to its aspect, not the grid's. Animate the track sizes and the content re-crops as the cells resize. Add a cornerRadius for rounded tiles. See Layout.
Cell’s Selected / Remaining outputs also carry their original boxes. Split selected cells into separate Layout branches, then recombine only the leaves with MergePoints. That merge uses slot order and assigns sequential ids; count changes may change random source picks downstream.
Clone another layer
Add a LayerSource, pick the layer, wire it into in. The layer's rendered output — animation, effects and all — stamps at every point.
Staggered copies
Set timeOffsetMode to Sequential with offsetFrames 3: each instance plays the source animation 3 frames behind the previous one — a cascading wave from a single animated source.
Tips
- The stamp for a shape/effect chain is the whole comp picture, re-anchored at each point — content offset from comp center stays offset from the point. Center your source content for predictable stamping.
- Point order = paint order.
PointDelete/sorting upstream controls stacking. - Time offsets re-run the source chain per sample frame. For expensive chains, put a FileCache upstream — offset frames then read from disk (the same guidance as Echo/Slitscan). The node shows a "may be slow" chip when this applies.
- Per-clone evaluation costs one full chain eval per instance per frame — keep the chain light or
maxClonesmodest. - Sources are capped at 16; total render layers (sources × time samples) at 32.
Related Nodes
- CloneToPoints — the vector-domain counterpart (instances live geometry instead of rendered pixels)
- CloneIndex — per-instance iteration variable for per-clone evaluation
- PointAttributes — write the per-point rotation/scale/opacity/color this node reads
- LayerSource — bring another layer's render in as a stamp source
- DrawPoints — simple colored dots when you don't need a texture per point