Grouped layers (isGrouped, groupTransform)

Pass CreateImageOptions as the third argument to createImage when you want multiple ImageProperties entries composited as one logical layer.

#Activation rules

1await painter.createImage(2  [3    { source: './bg.jpg', x: 0, y: 0, width: 600, height: 400 },4    { source: './fg.png', x: 120, y: 80, width: 320, height: 240, fit: 'contain' },5  ],6  buffer,7  {8    isGrouped: true,9    groupTransform: {10      rotation: -6,11      pivotX: 300,12      pivotY: 200,13      opacity: 0.95,14      shadow: { color: '#00000066', offsetY: 18, blur: 28 },15      filters: [{ type: 'gaussianBlur', intensity: 0.08 }],16      filterOrder: 'post',17    },18  }19);

Requirements:

1. images must be an array with more than one entry.
2. options.isGrouped must be true and you supply groupTransform — otherwise paintImageLayersOntoContext falls back to drawing items sequentially like unrelated layers.

#What groupTransform can do

Mirrors many ImageProperties fields:

Implementation notes worth remembering:

• filterOrder: 'pre' composites every child bitmap into an off-screen buffer clipped to the axis-aligned group bounding box, filters once, then blits — per-layer rotations are stripped (rotation: 0 clone). Early return skips transforms/effects/stroke pipeline besides what that branch draws.
• filterOrder: 'post' (default behaviour when unset or non-pre) rasterises transformed corners into a tighter rectangle estimate before filtering — heavily rotated groups might crop imperfectly near edges.
• Per-layer rotation values are intentionally forced to 0 inside the grouped loop — rotate with groupTransform.rotation instead.

#Stroke after grouping

After transforms restore, groupTransform.stroke outlines the original axis-aligned union rectangle (groupBox) optionally re-applying rotation/scale translation — handy for framing stickers.

#When not to group

• You need independent effects timings per bitmap with precise stroke ordering alongside meshWarp — split layers instead.
• Only one image is present — isGrouped adds no benefit.

#Related reading

• Paint order — contrasts grouped vs solo pipelines.