Watermark & text overlay

Overlays are applied after the frame raster is drawn onto the GIF output canvas and before encoder.addFrame.

#Watermarks

Global and per-frame watermarks use the same GIFWatermarkSpec:

1interface GIFWatermarkSpec {2  enable?: boolean;3  url: string | Buffer | Uint8Array | URL;4  x?: number;5  y?: number;6  opacity?: number; // 0..17  width?: number;8  height?: number;9  scale?: number;10  margin?: number;11  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';12}

url is a GIFFrameSource, despite the historical field name. It can therefore be local bytes, a path/data image, or a permitted remote URL. Remote watermark sources use Apexify's central network policy and byte limits.

##Global watermark

1const gif = await painter.createGIF(frames, {2  outputFormat: 'buffer',3  width: 640,4  height: 360,5  watermark: {6    url: './brand/logo.png',7    position: 'bottom-right',8    margin: 16,9    opacity: 0.8,10    scale: 0.6,11  },12});

The global image is resolved once for the operation and reused through a bounded cache rather than being decoded independently for every frame.

##Per-frame watermark

A frame-level watermark replaces the global watermark specification for that frame. enable: false suppresses watermarking for the frame even when a global watermark exists.

1const frames = [2  { buffer: frameA },3  {4    buffer: frameB,5    watermark: {6      url: './brand/alternate.png',7      position: 'top-left',8      opacity: 0.5,9    },10  },11  { buffer: frameC, watermark: { enable: false, url: './brand/logo.png' } },12];

##Sizing and placement

• scale scales both native dimensions and cannot be combined with explicit width/height.
• width only preserves native aspect ratio while deriving height.
• height only preserves native aspect ratio while deriving width.
• both width and height use the explicit dimensions.
• position defaults to bottom-left.
• margin defaults to 10 pixels for position-based placement.
• explicit x / y override the derived position coordinate independently.
• opacity defaults to 1.

#textOverlay uses the main text renderer

Phase 7 no longer uses a hard-coded ${fontSize}px Arial fillText shortcut. GIFOptions.textOverlay is based on the normal TextProperties model and is rendered through EnhancedTextRenderer.

That means GIF text overlays support the same core styling model used by createText, including nested font/fill/layout/placement/effects/decorations, custom font paths, gradients, strokes, shadows/glow, wrapping, rotation, and curved text where the underlying TextProperties feature supports it.

x and y are optional only for the GIF overlay convenience API and default to 10 and 30. fontColor remains a compatibility alias for the text color.

1await painter.createGIF(frames, {2  outputFormat: 'file',3  outputFile: './out/branded.gif',4  width: 640,5  height: 360,6  textOverlay: {7    text: 'Apexify.js',8    x: 24,9    y: 48,10    font: { family: 'Arial', size: 28 },11    decorations: { bold: true },12    fill: { color: '#ffffff' },13    effects: {14      shadow: { color: '#000000', blur: 4, offsetX: 2, offsetY: 2, opacity: 0.7 },15    },16  },17});

Text-overlay validation uses the same authoritative text-property validation path as other Apexify rendering surfaces.