@pixerate/editor 0.240.0 → 0.241.0

package/dist/image-editor/index.js

@@ -8,7 +8,7 @@ import {
   parseOpenTypeFont,
   removeAnchorsKeepingShape,
   traceField
-} from "../chunk-UUBO6RB5.js";
+} from "../chunk-UDBDYZET.js";
 import {
   ColorGmm,
   GAMMA,
@@ -410,7 +410,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-3E36VDMJ.js";
+} from "../chunk-NE6OOKWJ.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -729,8 +729,8 @@ import {
   warpMeshParamAt,
   warpMeshRows,
   warpPresetMesh
-} from "../chunk-7YGBSFC6.js";
-import "../chunk-PJYG6FCF.js";
+} from "../chunk-ILM6GYAX.js";
+import "../chunk-XBZK47LV.js";
 import "../chunk-M6DNZNVY.js";
 import {
   bezierPathToSvg,

package/dist/paint-editor/controller.d.cts

@@ -112,6 +112,12 @@ export interface PaintEditorState {
     mixerLoad: MixerLoad;
     view: PaintView;
     hand: Hand;
+    /** Live effect paint: whether strokes on stroke layers play their effect, the frame rate cap and the time (ms) the view shows. Editor state. */
+    effectPlayback: {
+        playing: boolean;
+        fps: number;
+        time: number;
+    };
     /** The stroke picked on a stroke layer, on the canvas or in the stroke panel (editor state, not an undo step). */
     selectedStroke: string | null;
     /** The sticker picked on the canvas or in the sticker panel (editor state, not an undo step). */
@@ -308,6 +314,15 @@ export declare class PaintEditorController {
     private dirty;
     private seedCounter;
     private strokeCounter;
+    /** Live effect paint: playing and the frame rate cap (editor state), and the time the view shows. */
+    private effectPlaybackState;
+    private effectTime;
+    /** While a frame is drawn: the time live effect strokes are drawn at (else their own time). */
+    private liveEffectAt;
+    /** The view's stroke layers at `effectTime`, each with the document surface it was drawn from (stale once that changes). */
+    private animatedLayers;
+    /** `renderAnimationFrame` / `withEffectTime`: layer surfaces at another time, for one render. */
+    private frameOverride;
     /** The area each stroke painted (document pixels; `null`: nothing), learnt as it is painted or drawn, so a stroke layer edit redraws only where it changes (see `drawLiveStrokes`). */
     private paintedBounds;
     private guides;
@@ -559,11 +574,15 @@ export declare class PaintEditorController {
      * size, and brushes then take each pixel's colour (and alpha) from it, fixed to the canvas, as if
      * painting a hidden picture into view. `setColor` and `setPaint` go back to colour. Editor state,
      * not an undo step. Strokes that would paint with it throw while it renders. Returns the paint.
+     * With `map: { by: 'stroke' }` the effect lies along each stroke instead of the canvas; with
+     * `live`, strokes on a stroke layer keep playing it (see `setEffectPlayback`).
      */
     setEffectPaint(source: {
         effect: string;
         values?: Record<string, EffectValue | null>;
         time?: number;
+        map?: unknown;
+        live?: boolean;
     }): Promise<PaintEffectPaint>;
     /** The rendered pixels of an effect paint at the current canvas size, or `null` when it has not been rendered. */
     private effectPaintImage;
@@ -1090,6 +1109,52 @@ export declare class PaintEditorController {
      * strokes over it); the other tiles are kept. Without it, or with `null`, every stroke is drawn.
      */
     private drawLiveStrokes;
+    /** The view's layers: stroke layers playing live effects at `effectTime`, the rest as they are. */
+    private animatedView;
+    /** Stroke layers with live effect strokes, and the distinct live sources (frame 0). */
+    private liveEffects;
+    /** What plays: the live effect strokes and their layers, or `null` when nothing does. */
+    getAnimation(): {
+        layerIds: string[];
+        strokes: number;
+        sources: number;
+    } | null;
+    /** Plays or pauses live effect paint, and caps its frame rate (1..60). Editor state, not an undo step. */
+    setEffectPlayback(update: {
+        playing?: boolean;
+        fps?: number;
+    }): {
+        playing: boolean;
+        fps: number;
+        time: number;
+    };
+    /** The surfaces of every stroke layer with live effects at `time` ms, drawn in full (frames rendered first). */
+    private liveSurfacesAt;
+    /**
+     * Shows the live effects at `time` ms (each live stroke's effect at its own time plus `time`):
+     * renders their frames, then redraws only where live effect strokes paint. Nothing in the
+     * document changes. Resolves `false` when the document changed while frames rendered (the next
+     * frame catches up).
+     */
+    showEffectTime(time: number): Promise<boolean>;
+    /**
+     * Plays live effect paint in the view until `stop`: a frame per tick of `clock` (default
+     * animation frames) at most `fps` a second, one render in flight. Idle while paused, while a
+     * stroke is painted, or when nothing is live. The bindings start it while the editor is shown.
+     */
+    playEffects(clock?: {
+        now(): number;
+        frame(cb: () => void): () => void;
+    }): {
+        stop(): void;
+    };
+    /**
+     * Runs `fn` with the painting as it is `time` ms into its live effects (see `getAnimation`): for
+     * exports at a moment. Nothing in the document changes.
+     */
+    withEffectTime<T>(time: number, fn: () => T | Promise<T>): Promise<T>;
+    /** The painting composited `time` ms into its live effects, like `compositePixels`. Nothing in the document changes. */
+    renderAnimationFrame(time: number, options?: RenderOptions): Promise<PixelImage>;
     private stencilCache;
     private nextStencilId;
     /** The mask stencils' coverage over the canvas (cached), or `null` when none masks. */
@@ -1164,3 +1229,5 @@ export declare class PaintEditorController {
 export type { Tile };
 /** Largest tracing or reference image side, in pixels. */
 export declare const MAX_IMAGE_SIDE = 8192;
+/** The most live effects (distinct sources) a document plays at once: each needs a renderer. */
+export declare const MAX_LIVE_EFFECT_SOURCES = 8;

package/dist/paint-editor/controller.d.ts

@@ -112,6 +112,12 @@ export interface PaintEditorState {
     mixerLoad: MixerLoad;
     view: PaintView;
     hand: Hand;
+    /** Live effect paint: whether strokes on stroke layers play their effect, the frame rate cap and the time (ms) the view shows. Editor state. */
+    effectPlayback: {
+        playing: boolean;
+        fps: number;
+        time: number;
+    };
     /** The stroke picked on a stroke layer, on the canvas or in the stroke panel (editor state, not an undo step). */
     selectedStroke: string | null;
     /** The sticker picked on the canvas or in the sticker panel (editor state, not an undo step). */
@@ -308,6 +314,15 @@ export declare class PaintEditorController {
     private dirty;
     private seedCounter;
     private strokeCounter;
+    /** Live effect paint: playing and the frame rate cap (editor state), and the time the view shows. */
+    private effectPlaybackState;
+    private effectTime;
+    /** While a frame is drawn: the time live effect strokes are drawn at (else their own time). */
+    private liveEffectAt;
+    /** The view's stroke layers at `effectTime`, each with the document surface it was drawn from (stale once that changes). */
+    private animatedLayers;
+    /** `renderAnimationFrame` / `withEffectTime`: layer surfaces at another time, for one render. */
+    private frameOverride;
     /** The area each stroke painted (document pixels; `null`: nothing), learnt as it is painted or drawn, so a stroke layer edit redraws only where it changes (see `drawLiveStrokes`). */
     private paintedBounds;
     private guides;
@@ -559,11 +574,15 @@ export declare class PaintEditorController {
      * size, and brushes then take each pixel's colour (and alpha) from it, fixed to the canvas, as if
      * painting a hidden picture into view. `setColor` and `setPaint` go back to colour. Editor state,
      * not an undo step. Strokes that would paint with it throw while it renders. Returns the paint.
+     * With `map: { by: 'stroke' }` the effect lies along each stroke instead of the canvas; with
+     * `live`, strokes on a stroke layer keep playing it (see `setEffectPlayback`).
      */
     setEffectPaint(source: {
         effect: string;
         values?: Record<string, EffectValue | null>;
         time?: number;
+        map?: unknown;
+        live?: boolean;
     }): Promise<PaintEffectPaint>;
     /** The rendered pixels of an effect paint at the current canvas size, or `null` when it has not been rendered. */
     private effectPaintImage;
@@ -1090,6 +1109,52 @@ export declare class PaintEditorController {
      * strokes over it); the other tiles are kept. Without it, or with `null`, every stroke is drawn.
      */
     private drawLiveStrokes;
+    /** The view's layers: stroke layers playing live effects at `effectTime`, the rest as they are. */
+    private animatedView;
+    /** Stroke layers with live effect strokes, and the distinct live sources (frame 0). */
+    private liveEffects;
+    /** What plays: the live effect strokes and their layers, or `null` when nothing does. */
+    getAnimation(): {
+        layerIds: string[];
+        strokes: number;
+        sources: number;
+    } | null;
+    /** Plays or pauses live effect paint, and caps its frame rate (1..60). Editor state, not an undo step. */
+    setEffectPlayback(update: {
+        playing?: boolean;
+        fps?: number;
+    }): {
+        playing: boolean;
+        fps: number;
+        time: number;
+    };
+    /** The surfaces of every stroke layer with live effects at `time` ms, drawn in full (frames rendered first). */
+    private liveSurfacesAt;
+    /**
+     * Shows the live effects at `time` ms (each live stroke's effect at its own time plus `time`):
+     * renders their frames, then redraws only where live effect strokes paint. Nothing in the
+     * document changes. Resolves `false` when the document changed while frames rendered (the next
+     * frame catches up).
+     */
+    showEffectTime(time: number): Promise<boolean>;
+    /**
+     * Plays live effect paint in the view until `stop`: a frame per tick of `clock` (default
+     * animation frames) at most `fps` a second, one render in flight. Idle while paused, while a
+     * stroke is painted, or when nothing is live. The bindings start it while the editor is shown.
+     */
+    playEffects(clock?: {
+        now(): number;
+        frame(cb: () => void): () => void;
+    }): {
+        stop(): void;
+    };
+    /**
+     * Runs `fn` with the painting as it is `time` ms into its live effects (see `getAnimation`): for
+     * exports at a moment. Nothing in the document changes.
+     */
+    withEffectTime<T>(time: number, fn: () => T | Promise<T>): Promise<T>;
+    /** The painting composited `time` ms into its live effects, like `compositePixels`. Nothing in the document changes. */
+    renderAnimationFrame(time: number, options?: RenderOptions): Promise<PixelImage>;
     private stencilCache;
     private nextStencilId;
     /** The mask stencils' coverage over the canvas (cached), or `null` when none masks. */
@@ -1164,3 +1229,5 @@ export declare class PaintEditorController {
 export type { Tile };
 /** Largest tracing or reference image side, in pixels. */
 export declare const MAX_IMAGE_SIDE = 8192;
+/** The most live effects (distinct sources) a document plays at once: each needs a renderer. */
+export declare const MAX_LIVE_EFFECT_SOURCES = 8;

package/dist/paint-editor/effect-paint.d.cts

@@ -24,12 +24,59 @@ export interface PaintEffectPaint {
     values: Record<string, EffectValue>;
     /** Which moment of an animated effect, in ms. */
     time: number;
+    /**
+     * How the effect lies on the paint: fixed to the canvas (missing, the default), or along each
+     * stroke (`by: 'stroke'`): the effect is rendered as a strip `length` px long and 256 px across,
+     * and each pixel takes the colour at (distance along the stroke, position across the tip).
+     */
+    map?: PaintEffectStrokeMap;
+    /**
+     * Live: on a stroke layer the stroke keeps playing the effect (each frame drawn at the editor's
+     * effect time); elsewhere it bakes the frame at `time` like any effect paint.
+     */
+    live?: boolean;
 }
-/** Canvas-sized straight-alpha RGBA an effect paint was rendered to. */
+/** Effect paint laid along the stroke. */
+export interface PaintEffectStrokeMap {
+    by: 'stroke';
+    /** Strip length: px of stroke per repeat of the effect, 16..4096. */
+    length: number;
+    /** Past the strip's end: start again, run back (mirror), or hold the last colour (clamp). */
+    repeat: 'repeat' | 'mirror' | 'clamp';
+}
+/** How tall a stroke-mapped effect strip is rendered (the position across the tip maps onto it). */
+export declare const EFFECT_STRIP_HEIGHT = 256;
+export declare const EFFECT_MAP_REPEATS: readonly ["repeat", "mirror", "clamp"];
+/** The size an effect paint renders at: the canvas, or its strip. */
+export declare function effectPaintSize(p: PaintEffectPaint, canvas: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+};
+/** A stroke map checked and rounded; throws a sentence naming the bad field. */
+export declare function readEffectStrokeMap(raw: unknown): PaintEffectStrokeMap | undefined;
+/**
+ * Straight-alpha RGBA an effect paint was rendered to: canvas-sized, or (with `map`) the strip
+ * laid along each stroke.
+ */
 export interface EffectPaintPixels {
     width: number;
     height: number;
     data: ArrayLike<number>;
+    map?: PaintEffectStrokeMap;
+}
+/** Where a dab is on its stroke, for effect paint laid along the stroke. */
+export interface EffectDabPlace {
+    x: number;
+    y: number;
+    /** Direction of travel, radians counter-clockwise with y up. */
+    direction: number;
+    /** The tip's radius (px): the position across the tip maps onto the strip's height. */
+    radius: number;
+    /** Path length (px) travelled to the dab. */
+    travel: number;
 }
 /** The cache key of an effect paint (the same source renders the same pixels). */
 export declare function effectPaintKey(p: PaintEffectPaint): string;
@@ -42,6 +89,16 @@ export declare function readPaintEffectPaint(raw: unknown): PaintEffectPaint | n
  * document rectangle) with the effect's colour at each pixel and multiplies `vals` by its alpha.
  * Pixels off the canvas paint nothing.
  */
-export declare function sampleEffectField(img: EffectPaintPixels, rect: RasterRect, vals: Float32Array, field: Float32Array): void;
+export declare function sampleEffectField(img: EffectPaintPixels, rect: RasterRect, vals: Float32Array, field: Float32Array, dab?: EffectDabPlace | null): void;
 /** The effect's colour (sRGB 0..1 into `out`) at a document point; returns its alpha 0..1 (0 off the canvas). */
-export declare function sampleEffectAt(img: EffectPaintPixels, x: number, y: number, out: [number, number, number]): number;
+export declare function sampleEffectAt(img: EffectPaintPixels, x: number, y: number, out: [number, number, number], dab?: EffectDabPlace | null): number;
+/**
+ * Effect colours for one dab of a brush that mixes paint (wet and impasto brushes): fills `field`
+ * (sRGB 0..1, 3 per pixel of `rect`) with the effect's colour at each pixel, shifted by how far the
+ * brush's mixed paint (`mixed`) moved from the effect's colour at the dab's centre (`centre`, which
+ * the brush was loaded with), so paint the brush picked up still drags through the pattern. A clean
+ * brush paints the effect's colours exactly. `cov` is multiplied by the effect's alpha, rounded to
+ * `steps` levels when given (wet paint keeps its coverage on fixed steps so replays are exact).
+ * `dab` places it on its stroke, for effect paint laid along the stroke.
+ */
+export declare function effectDabField(img: EffectPaintPixels, rect: RasterRect, cov: Float32Array, centre: readonly [number, number, number], mixed: readonly [number, number, number], field: Float32Array, steps?: number, dab?: EffectDabPlace | null): void;

package/dist/paint-editor/effect-paint.d.ts

@@ -24,12 +24,59 @@ export interface PaintEffectPaint {
     values: Record<string, EffectValue>;
     /** Which moment of an animated effect, in ms. */
     time: number;
+    /**
+     * How the effect lies on the paint: fixed to the canvas (missing, the default), or along each
+     * stroke (`by: 'stroke'`): the effect is rendered as a strip `length` px long and 256 px across,
+     * and each pixel takes the colour at (distance along the stroke, position across the tip).
+     */
+    map?: PaintEffectStrokeMap;
+    /**
+     * Live: on a stroke layer the stroke keeps playing the effect (each frame drawn at the editor's
+     * effect time); elsewhere it bakes the frame at `time` like any effect paint.
+     */
+    live?: boolean;
 }
-/** Canvas-sized straight-alpha RGBA an effect paint was rendered to. */
+/** Effect paint laid along the stroke. */
+export interface PaintEffectStrokeMap {
+    by: 'stroke';
+    /** Strip length: px of stroke per repeat of the effect, 16..4096. */
+    length: number;
+    /** Past the strip's end: start again, run back (mirror), or hold the last colour (clamp). */
+    repeat: 'repeat' | 'mirror' | 'clamp';
+}
+/** How tall a stroke-mapped effect strip is rendered (the position across the tip maps onto it). */
+export declare const EFFECT_STRIP_HEIGHT = 256;
+export declare const EFFECT_MAP_REPEATS: readonly ["repeat", "mirror", "clamp"];
+/** The size an effect paint renders at: the canvas, or its strip. */
+export declare function effectPaintSize(p: PaintEffectPaint, canvas: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+};
+/** A stroke map checked and rounded; throws a sentence naming the bad field. */
+export declare function readEffectStrokeMap(raw: unknown): PaintEffectStrokeMap | undefined;
+/**
+ * Straight-alpha RGBA an effect paint was rendered to: canvas-sized, or (with `map`) the strip
+ * laid along each stroke.
+ */
 export interface EffectPaintPixels {
     width: number;
     height: number;
     data: ArrayLike<number>;
+    map?: PaintEffectStrokeMap;
+}
+/** Where a dab is on its stroke, for effect paint laid along the stroke. */
+export interface EffectDabPlace {
+    x: number;
+    y: number;
+    /** Direction of travel, radians counter-clockwise with y up. */
+    direction: number;
+    /** The tip's radius (px): the position across the tip maps onto the strip's height. */
+    radius: number;
+    /** Path length (px) travelled to the dab. */
+    travel: number;
 }
 /** The cache key of an effect paint (the same source renders the same pixels). */
 export declare function effectPaintKey(p: PaintEffectPaint): string;
@@ -42,6 +89,16 @@ export declare function readPaintEffectPaint(raw: unknown): PaintEffectPaint | n
  * document rectangle) with the effect's colour at each pixel and multiplies `vals` by its alpha.
  * Pixels off the canvas paint nothing.
  */
-export declare function sampleEffectField(img: EffectPaintPixels, rect: RasterRect, vals: Float32Array, field: Float32Array): void;
+export declare function sampleEffectField(img: EffectPaintPixels, rect: RasterRect, vals: Float32Array, field: Float32Array, dab?: EffectDabPlace | null): void;
 /** The effect's colour (sRGB 0..1 into `out`) at a document point; returns its alpha 0..1 (0 off the canvas). */
-export declare function sampleEffectAt(img: EffectPaintPixels, x: number, y: number, out: [number, number, number]): number;
+export declare function sampleEffectAt(img: EffectPaintPixels, x: number, y: number, out: [number, number, number], dab?: EffectDabPlace | null): number;
+/**
+ * Effect colours for one dab of a brush that mixes paint (wet and impasto brushes): fills `field`
+ * (sRGB 0..1, 3 per pixel of `rect`) with the effect's colour at each pixel, shifted by how far the
+ * brush's mixed paint (`mixed`) moved from the effect's colour at the dab's centre (`centre`, which
+ * the brush was loaded with), so paint the brush picked up still drags through the pattern. A clean
+ * brush paints the effect's colours exactly. `cov` is multiplied by the effect's alpha, rounded to
+ * `steps` levels when given (wet paint keeps its coverage on fixed steps so replays are exact).
+ * `dab` places it on its stroke, for effect paint laid along the stroke.
+ */
+export declare function effectDabField(img: EffectPaintPixels, rect: RasterRect, cov: Float32Array, centre: readonly [number, number, number], mixed: readonly [number, number, number], field: Float32Array, steps?: number, dab?: EffectDabPlace | null): void;