Masking, distortion & mesh warp

These options apply only when source is a bitmap (string / Buffer). Shape layers use drawShape — use clipPath / borderRadius on the layer instead.

#Mask compositing — mask

1mask?: {2  source: string | Buffer;3  mode?: 'alpha' | 'luminance' | 'inverse';4};

The masked bitmap still honours fit / align into the layout box before masking runs.

1await painter.createImage(2  {3    source: './subject.png',4    x: 40,5    y: 40,6    width: 280,7    height: 280,8    fit: 'cover',9    mask: {10      source: './mask-soft.png',11      mode: 'luminance',12    },13  },14  buffer15);

#Distortion — distortion

1distortion?: {2  type: 'perspective' | 'warp' | 'bulge' | 'pinch';3  points?: Array<{ x: number; y: number }>;4  intensity?: number;5};

##Implemented today

##Not wired on the bitmap path

The union includes warp, but ImageCreator.drawImageBitmap currently handles perspective, bulge, and pinch only. warp falls through — leave meshWarp for grid deformation instead.

Distortion branches return immediately after drawing — stroke, effects, and filterOrder: 'post' filters do not run afterward for that layer (see Paint order).

1await painter.createImage(2  {3    source: './poster.jpg',4    x: 60,5    y: 80,6    width: 320,7    height: 220,8    fit: 'cover',9    distortion: {10      type: 'perspective',11      points: [12        { x: 40, y: 40 },13        { x: 380, y: 20 },14        { x: 360, y: 260 },15        { x: 20, y: 240 },16      ],17    },18  },19  buffer20);

#Mesh warp — meshWarp

1meshWarp?: {2  gridX?: number;3  gridY?: number;4  controlPoints?: Array<Array<{ x: number; y: number }>>;5};

Like distortion, meshWarp ends the bitmap pipeline early — combine stroke/effects only if you redesign ordering or split layers.

#Interaction summary

Use either mask or the straight drawImage path — mesh/distortion branches skip masks.

Do not combine meshWarp + distortion expecting automatic chaining — whichever branch triggers first wins (distortion is evaluated before meshWarp).