@weasel-js/renderer 1.10.0 → 1.11.0

package/dist/index.d.ts

@@ -2,13 +2,14 @@ import { S as ShaderProgramHandle, a as ShaderUniform, b as ShaderProgram, F as
 export { P as PaintBindContext, c as PaintDrawKind, d as PaintDrawKindLoader, e as PaintProgram, f as PaintResources, g as ProgramSource, h as ShaderCompileError, i as ShaderStage, U as UniformArray, j as fillInPoseFrame, k as fillToBoundsFrame, l as getPaintDrawKind, m as getProgramSource, n as isPaintKindKnown, p as paintDrawKindRegistry, o as programSourceRegistry, r as registerPaintDrawKind, q as registerPaintDrawKindLoader, s as registerProgram, w as warmPaintKinds } from './paintKinds-BmPAT51k.js';
 import { Mesh } from '@weasel-js/geom/tessellate';
 export { Mesh, TessellateOptions, tessellate } from '@weasel-js/geom/tessellate';
-import { GradStop, ColorSpace, CommandFill, CommandStroke, Stroke, Fill, Paint, CommandPaint, TextureHandle } from '@weasel-js/paint';
+import { GradStop, ColorSpace, CommandFill, CommandStroke, Stroke, CommandPaint, Fill, Paint, TextureHandle } from '@weasel-js/paint';
 export { CommandFill, CommandPaint, CommandPaintUnits, CommandStroke, PosedPaint, SolidPaint, TextureHandle } from '@weasel-js/paint';
 import { GlMat3, Path } from '@weasel-js/geom';
 export { GlMat3, View as ViewLike, mat3, viewToMat3 } from '@weasel-js/geom';
 import { ResolvedRun, TextAlign, TextDirection, TextStyle, TextVerticalAlign, TextPaint, TextPose, StyledRun } from '@weasel-js/text';
-import { D as DrawBatch } from './imageCache-DYcWftY8.js';
-export { I as ImageNodeData, a as ImageRasterSize, b as ImageStatus, T as TextureEntry, g as getImageBitmap, i as imageStatus, c as isVectorImageSrc, r as registerTexture, d as releaseImage, e as resolveFillPattern, f as resolvePatternSpec, h as retryImage, s as setImageCacheBudget, j as subscribeImageReady, t as textureRegistry, u as unregisterTexture } from './imageCache-DYcWftY8.js';
+import { D as DrawBatch } from './imageCache-CDm3qgsg.js';
+export { I as ImageNodeData, a as ImageRasterSize, b as ImageStatus, T as TextureEntry, c as bitmapSrc, g as getImageBitmap, i as imageStatus, d as isVectorImageSrc, r as registerTexture, e as releaseImage, f as resolveFillPattern, h as resolvePatternSpec, j as retryImage, s as setImageCacheBudget, k as subscribeImageReady, t as textureRegistry, u as unregisterTexture } from './imageCache-CDm3qgsg.js';
+import { StrokeSpaces } from '@weasel-js/stroke';
 export { StrokeOptions, tessellateStroke } from '@weasel-js/stroke';
 export { RegisterFontOptions, canQueryLocalFonts, cssFontFamily, cssFontFamilyLoading, enableLocalFontOutlines, fontOutlineRegistry, fontRegistry, hasFontOutlines, isCanvasFont, listFontOutlines, loadFontOutlines, outlineStatus, registerCanvasFont, registerFont, registerFontOutlines, subscribeGlyphReady, unregisterCanvasFont, unregisterFontOutlines } from '@weasel-js/font';
 import '@weasel-js/registry';
@@ -378,8 +379,6 @@ interface Effect {
  *
  * The fragment shader reads `v_uv` and `u_source`, may declare `u_resolution` /
  * `u_texel`, and must write premultiplied alpha. See `effectPrelude.ts`.
- *
- * @experimental
  */
 declare function registerEffect(id: string, frag: string): ShaderProgramHandle;
 
@@ -476,6 +475,36 @@ interface GroupDrawCommand {
      * that has one: a context created with `alpha: false` reads as opaque.
      */
     composite?: CompositeOp | BlendFactors;
+    /**
+     * Keep this group's pixels in a texture of its own, named by this id, and
+     * composite that texture as one quad on later frames instead of drawing the
+     * children again. They are drawn again when `children` is a different
+     * array, or when anything else they were drawn under moves: the enclosing
+     * transform, alpha, color matrix or clips, the frame's view matrix, the
+     * drawing size, or a font, texture, paint kind or program the renderer serves.
+     * So `children` must not be mutated once drawn, the rule a layer's cached
+     * commands already follow.
+     *
+     * The composite matches drawing the group to within 8-bit rounding, except
+     * at a pixel where an edge of the group crosses an edge drawn beneath it: the
+     * surface is resolved from its samples before it meets the canvas, so the
+     * two edges' coverage no longer pairs up, and such a pixel can land a few
+     * levels off.
+     *
+     * Worth it for a group of a few hundred commands or more that holds still
+     * across frames; below that, drawing it is cheaper than the composite. A
+     * surface covers the device pixels the children can paint, clamped to the
+     * drawing buffer — all of it under text, a custom shader or `effects`, which
+     * are bounded only by the clips around them — and is freed at the end of any
+     * frame that does not draw its id. The renderer's `retainBudget` caps what
+     * they hold together.
+     *
+     * Ignored, and the children drawn straight through, on a group that owns a
+     * surface anyway (`effects`, `isolate`, `composite`), inside another such
+     * surface, or over a tree holding a `composite` other than `source-over`,
+     * which reads pixels a retained surface does not have.
+     */
+    retain?: string;
     children: DrawCommand[];
 }
 /**
@@ -599,6 +628,17 @@ interface ShaderDrawCommand {
     };
 }
 
+/**
+ * How far a flattened curve may stray from the true one: a length in the
+ * path's own units, or `{ px }` on screen, which follows the transform the
+ * path draws under.
+ */
+type FlattenTolerance = number | {
+    px: number;
+};
+/** The default, in device pixels: the world default at scale 1 and dpr 1. */
+declare const DEFAULT_FLATTEN_TOLERANCE_PX = 0.5;
+
 /** A run of top-level commands, `[start, end)` by index, that
  *  {@link WeaselRenderer.lastFrameStats} accounts for separately — one render
  *  layer's commands, say. Spans are in order and do not overlap. */
@@ -623,6 +663,21 @@ interface RenderStats {
     drawCalls: number;
     ms: number;
     spans: RenderSpanStats[];
+    /** What the frame did with groups carrying `retain`. */
+    retained: RetainedStats;
+}
+/** How a frame's retained groups were drawn. See `GroupDrawCommand.retain`. */
+interface RetainedStats {
+    /** Composited from pixels kept from an earlier frame. */
+    composited: number;
+    /** Drawn into their surface this frame, then composited. */
+    redrawn: number;
+    /** Drawn straight through, as if they carried no `retain`: over the budget,
+     *  or somewhere a surface cannot stand in for them. */
+    declined: number;
+    /** GPU memory held for retained surfaces once the frame ended, scratch
+     *  buffer included. */
+    bytes: number;
 }
 /** Construction options for {@link WeaselRenderer}. Pass `gl` or `canvas`;
  *  a context passed in must have a stencil buffer. */
@@ -643,14 +698,19 @@ interface WeaselRendererOptions {
      *  the headless `renderSceneToPixels` path does; `'auto'` builds them
      *  for an image the first time a frame draws it at half size or smaller. */
     imageMinification?: ImageMinification;
-    /** Flatness tolerance for curve tessellation, in WORLD units (see
-     *  `TessellateOptions.flattenTolerance`). When set, path fills are
-     *  tessellated fresh at this tolerance per frame (transient pool) instead
-     *  of served from the Path-identity mesh cache — the cache key does not
-     *  include tolerance. Default: unset — the existing cached behavior at
-     *  `DEFAULT_FLATTEN_TOLERANCE`. The headless path derives this from the
-     *  requested output scale; screen callers normally leave it unset. */
-    flattenTolerance?: number;
+    /** How far a flattened curve may stray: in world units, or `{ px }` in
+     *  device pixels, which follows each path's transform so a zoom keeps
+     *  curves smooth. Default `{ px: DEFAULT_FLATTEN_TOLERANCE_PX }`. */
+    flattenTolerance?: FlattenTolerance;
+    /** GPU memory, in bytes, that retained groups may hold between frames — see
+     *  `GroupDrawCommand.retain`. A group that would take the total past it is
+     *  drawn straight through instead. Counts each surface, 4 bytes a device
+     *  pixel. Not counted: the multisampled buffer surfaces are drawn in, 8
+     *  bytes a sample at the size of the largest surface drawn, held across
+     *  frames that redraw one and freed after the first that does not; on a
+     *  frame that redraws, GPU memory can reach the budget plus that buffer.
+     *  Default {@link DEFAULT_RETAIN_BUDGET}; 0 retains nothing. */
+    retainBudget?: number;
     /** Per-render synchronous bake budget for dynamic canvas-SDF glyphs.
      *  Default DEFAULT_BAKE_BUDGET (16). The headless renderSceneToPixels
      *  path passes Infinity so print never defers a glyph. */
@@ -683,6 +743,9 @@ interface RenderTarget {
      *  stencil bits, and even-odd fills then fill their holes. */
     clear?: boolean;
 }
+/** 256 MiB: at 1280x800 and dpr 2, the 4x scratch buffer and seven surfaces. */
+declare const DEFAULT_RETAIN_BUDGET: number;
+
 /**
  * The WebGL2 renderer: takes a list of draw commands and paints them.
  *
@@ -694,11 +757,14 @@ interface RenderTarget {
 declare class WeaselRenderer {
     private readonly gl;
     private stats;
-    private pathFill;
-    private pathFillVColor;
+    /** Built on the first frame that draws with each, so a one-shot render of
+     *  plain shapes builds the batch program alone. */
+    private readonly pathFill;
+    private readonly pathFillVColor;
     private batchFill;
-    private gradFill;
-    private patternFill;
+    private readonly batchFillMatrices;
+    private readonly gradFill;
+    private readonly patternFill;
     /** Compiled on first use: only atlas text under a texture paint needs one. */
     private glyphPaintPrograms;
     private meshCache;
@@ -727,6 +793,10 @@ declare class WeaselRenderer {
     /** Offscreen buffers for group effects. Allocates nothing until a group
      *  with effects asks, so a canvas without them pays no memory. */
     private readonly effectTargets;
+    private readonly retained;
+    /** Advanced when a program is compiled again over one already drawn with,
+     *  which leaves every retained surface drawn by the old one stale. */
+    private programEpoch;
     private readonly paintScratch;
     private readonly imageMinification;
     private flattenTolerance?;
@@ -742,6 +812,7 @@ declare class WeaselRenderer {
      *  generation: a restore releases it and opens the next. */
     private paintResources;
     constructor(opts: WeaselRendererOptions);
+    private lazyPrograms;
     private uploadQuadGeometry;
     /**
      * Compile a consumer-registered shader program against this renderer's GL context.
@@ -776,6 +847,8 @@ declare class WeaselRenderer {
     /** Viewport and scissor for this frame. Re-applied inside `render()` because
      *  a co-tenant on the same context moves both between our frames. */
     private applyTarget;
+    /** This renderer's rect as GL addresses it, from the buffer's bottom left. */
+    private glRect;
     /** Confine this renderer to a rect of its drawing buffer, or pass null to
      *  give it the whole buffer back. Takes effect from the next `render()`. */
     setTarget(target: RenderTarget | null): void;
@@ -804,9 +877,10 @@ declare class WeaselRenderer {
      *  spent issuing them, in total and per requested span. GPU time is not
      *  measured; the GPU runs asynchronously. */
     lastFrameStats(): RenderStats;
-    /** Change the curve-flattening tolerance after construction. `undefined`
-     *  restores the cached `DEFAULT_FLATTEN_TOLERANCE` route. */
-    setFlattenTolerance(tolerance: number | undefined): void;
+    /** Change `flattenTolerance` after construction; `undefined` restores the default. */
+    setFlattenTolerance(tolerance: FlattenTolerance | undefined): void;
+    /** Change `retainBudget` after construction; `undefined` restores the default. */
+    setRetainBudget(bytes: number | undefined): void;
     resize(dims: {
         width: number;
         height: number;
@@ -817,6 +891,7 @@ declare class WeaselRenderer {
     /** @internal */ _pathFillVColor(): ShaderProgram;
     /** @internal */ _drawBatch(): DrawBatch;
     /** @internal */ _batchFill(): ShaderProgram;
+    /** @internal */ _batchFillMatrices(): ShaderProgram;
     /** @internal */ _gradFill(): ShaderProgram;
     /** @internal */ _patternFill(): ShaderProgram;
     /** @internal */ _meshCache(): GLMeshCache;
@@ -977,6 +1052,32 @@ declare const EFFECT_VERT_SRC = "#version 300 es\nin vec2 a_position;\nin vec2 a
  *  redeclare them with different meanings; it may leave any of them out. */
 declare const EFFECT_KIT_UNIFORMS: readonly ["u_source", "u_resolution", "u_texel"];
 
+/** A path command whose stroke paints. */
+type StrokedPathCommand = PathDrawCommand & {
+    stroke: CommandStroke & {
+        paint: CommandPaint;
+    };
+};
+/** A stroke command ready to tessellate, and the spaces to tessellate it in. */
+interface ResolvedStrokeCommand {
+    cmd: StrokedPathCommand;
+    /** Where the ribbon and each head are built; every length in `cmd` is
+     *  measured in the space of the part it belongs to. */
+    spaces: StrokeSpaces;
+}
+/**
+ * `cmd` with its `{ px }` lengths — the stroke width, any marker size, and on a
+ * `{ px }` stroke its dashes — resolved against the accumulated transform's
+ * quantized scale, so everything downstream (the ribbon cache key, the insets,
+ * the heads) sees plain numbers.
+ *
+ * Under a transform that stretches one direction more than another, each
+ * screen-sized part is also built in the transform's stretch, where lengths
+ * measure as they do on screen, so it is exact across, down and on every
+ * diagonal rather than right only on average. World-sized parts stay in world.
+ */
+declare function resolveStrokeLengths(transform: GlMat3, cmd: StrokedPathCommand): ResolvedStrokeCommand;
+
 /**
  * A node's paint, resolved into what a draw command takes. One place composes
  * the two resolutions so every painter and layer applies both.
@@ -1059,4 +1160,4 @@ declare function textCommand(x: number, y: number, text: string, style?: TextSty
  */
 declare function textCommandFromPose(pose: TextPose, scale?: number): TextDrawCommand;
 
-export { type BlendFactor, type BlendFactors, type CompositeOp, type CullRect, type DrawCommand, EFFECT_KIT_UNIFORMS, EFFECT_VERT_SRC, type Effect, FillPoseBox, type GroupDrawCommand, IDENTITY_COLOR_MATRIX, type ImageDrawCommand, type ImageMinification, OUTLINE_MIN_SCREEN_PX, type PathDrawCommand, type RenderOptions, type RenderSpan, type RenderSpanStats, type RenderStats, type RenderTarget, SPRITE_STRIDE, type ShaderDrawCommand, ShaderProgram, ShaderProgramHandle, ShaderUniform, type SpriteSheet, type SpritesDrawCommand, type TextDrawCommand, type TilePatternOpts, WeaselRenderer, type WeaselRendererOptions, blur, boundsMissRect, buildGradientRamp, commandFill, commandPaint, commandStroke, createTilePattern, cullDrawCommands, frameRect, registerEffect, releaseImageSource, strokeReachAt, textCommand, textCommandFromPose, textCommandFromRuns, vignette };
+export { type BlendFactor, type BlendFactors, type CompositeOp, type CullRect, DEFAULT_FLATTEN_TOLERANCE_PX, DEFAULT_RETAIN_BUDGET, type DrawCommand, EFFECT_KIT_UNIFORMS, EFFECT_VERT_SRC, type Effect, FillPoseBox, type FlattenTolerance, type GroupDrawCommand, IDENTITY_COLOR_MATRIX, type ImageDrawCommand, type ImageMinification, OUTLINE_MIN_SCREEN_PX, type PathDrawCommand, type RenderOptions, type RenderSpan, type RenderSpanStats, type RenderStats, type RenderTarget, type ResolvedStrokeCommand, type RetainedStats, SPRITE_STRIDE, type ShaderDrawCommand, ShaderProgram, ShaderProgramHandle, ShaderUniform, type SpriteSheet, type SpritesDrawCommand, type StrokedPathCommand, type TextDrawCommand, type TilePatternOpts, WeaselRenderer, type WeaselRendererOptions, blur, boundsMissRect, buildGradientRamp, commandFill, commandPaint, commandStroke, createTilePattern, cullDrawCommands, frameRect, registerEffect, releaseImageSource, resolveStrokeLengths, strokeReachAt, textCommand, textCommandFromPose, textCommandFromRuns, vignette };