@weasel-js/renderer 0.0.0-stage → 1.10.0

package/dist/imageCache-DYcWftY8.d.ts

@@ -0,0 +1,329 @@
+import { TextureHandle, PosedPaint, CommandPaint, Paint, TilePatternSpec } from '@weasel-js/paint';
+import { Reflection } from '@weasel-js/registry';
+import { Mesh } from '@weasel-js/geom/tessellate';
+import { GlMat3 } from '@weasel-js/geom';
+import { b as ShaderProgram } from './paintKinds-BmPAT51k.js';
+
+/**
+ * A module-level registry of image sources by opaque id. It stores image data
+ * only — no per-renderer state; each renderer uploads to GL lazily at draw
+ * time. A texture lives until `unregisterTexture`.
+ */
+
+/** A registered texture's image source, uploaded to GL lazily at first draw. */
+interface TextureEntry {
+    source: HTMLImageElement | ImageBitmap;
+}
+/** Every registered texture, keyed by its handle id. */
+declare const textureRegistry: Reflection<TextureEntry>;
+/** @internal Test helper — do not call from product code. */
+declare function _resetTextureRegistryForTests(): void;
+/**
+ * Register an image for use as a shader texture uniform. Returns a
+ * TextureHandle whose `id` can be passed as a ShaderUniform value.
+ *
+ * The texture holds premultiplied texels whichever source it came from, so a
+ * shader sampling one reads `vec4(rgb * a, a)`, the form its own output takes.
+ *
+ * @param image  HTMLImageElement must be fully loaded. An ImageBitmap must
+ *               hold premultiplied pixels, the `createImageBitmap` default.
+ */
+declare function registerTexture(image: HTMLImageElement | ImageBitmap): TextureHandle;
+/**
+ * Drop a registered texture. Every renderer that uploaded it frees its GL
+ * copy at the top of its next frame; a draw command still holding the handle
+ * then draws nothing and warns. The image itself is the caller's to release.
+ *
+ * @returns Whether the handle was registered.
+ */
+declare function unregisterTexture(handle: TextureHandle): boolean;
+
+/**
+ * Clipping staged geometry to an axis-aligned rect on the CPU, so a rect clip
+ * needs no stencil and does not break the run.
+ *
+ * A stencil clip is GL state, so content inside one cannot share a draw with
+ * content outside it. A rect under a transform that keeps it axis-aligned
+ * is the common clip, and for that one the clip can ride the geometry instead:
+ * cut each staged polygon to the rect before it joins the run.
+ *
+ * Exact, not approximate: every attribute a batch vertex carries is affine
+ * across the polygon it belongs to, so interpolating along a cut edge gives
+ * the value the rasterizer would have produced there, and the cut polygon
+ * covers the same pixel centers the stencil would have passed.
+ */
+
+/** In the space batch vertices are staged in: after the model transform,
+ *  before the projection. */
+interface ClipRect {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+
+/**
+ * Growable vertex staging for a run of solid-fill geometry, image quads and
+ * glyphs. Geometry only: the caller owns when a run starts, what breaks it, and
+ * the uniforms the flush draws under.
+ *
+ * One batch for all of them, because a page interleaves them. Everything a
+ * vertex needs to say which it is fits in the same vertex: solids carry the UV
+ * of a 1x1 white texel and are their own color, quads carry their atlas UV and
+ * a white color, glyphs carry a font atlas UV, their text color, and a paint
+ * mode saying the texel is a distance field rather than a color. Gradients
+ * sample the ramp atlas. See `shaders/batchFill.ts`.
+ *
+ * The model transform is applied here rather than uploaded, so shapes under
+ * different transforms still share a draw. The texture rides the vertices as a
+ * slot index into the units the flush binds: slot 0 is the white texel every
+ * solid samples.
+ */
+
+/** vec2 a_position + vec4 a_vertexColor + vec2 a_uv + float a_post + float
+ *  a_texSlot. */
+declare const FLOATS_PER_VERTEX = 10;
+/**
+ * A gradient vertex's `a_uv`, each channel affine in the coordinates the
+ * geometry arrives in: `u = ux*x + uy*y + u0`, and the same for `v`.
+ *
+ * A linear gradient's `v` row is the constant atlas row and its `u` row is the
+ * ramp position; a radial or conic one's two rows are the gradient-space
+ * coordinate, and the atlas row rides `a_post` instead.
+ */
+interface GradientUV {
+    ux: number;
+    uy: number;
+    u0: number;
+    vx: number;
+    vy: number;
+    v0: number;
+}
+declare class DrawBatch {
+    private readonly gl;
+    private readonly aPos;
+    private readonly aColor;
+    private readonly aUv;
+    private readonly aPost;
+    private readonly aSlot;
+    /** One ring per tier, cycled per flush. Slots are created on first use, so a
+     *  renderer that flushes rarely allocates as few as it flushes. */
+    private readonly rings;
+    private readonly nextInRing;
+    /** The same, for flushes past the largest tier; these sets grow to fit. */
+    private readonly largeRing;
+    private nextLarge;
+    private verts;
+    private idx;
+    private nVerts;
+    private nIdx;
+    /** Whether the staged run is quads alone, so its indices are the canonical
+     *  pattern and a slot already holding that pattern needs no upload. */
+    private pureRects;
+    /** The rect every push is cut to, or `null`. A push returns `false`, having
+     *  staged nothing, for geometry it cannot cut exactly; see `clipQuad`. */
+    clip: ClipRect | null;
+    /** Polygon scratch for `clip`: a quad cut by four edges has at most eight
+     *  corners. */
+    private readonly polyIn;
+    private readonly polyOut;
+    private readonly polyTmp;
+    constructor(gl: WebGL2RenderingContext, prog: ShaderProgram);
+    get length(): number;
+    /** Whether staging `vertices` more would put the run past the per-flush cap. */
+    wouldOverflow(vertices: number): boolean;
+    /**
+     * Append one rect's four corners through `m`, all carrying `rgba` (straight
+     * alpha).
+     */
+    pushRect(x: number, y: number, w: number, h: number, m: GlMat3, r: number, g: number, b: number, a: number): boolean;
+    /**
+     * Append one image quad: the destination rect `(x, y, w, h)` mapped through
+     * `m`, sampling `(u0, v0)`-`(u1, v1)`, every corner carrying `post` as the
+     * after-the-color-matrix alpha factor and `rgb` as the scale on its texel.
+     * `slot` is the texture unit the corners sample.
+     *
+     * Corners wind top-left, top-right, bottom-right, bottom-left — the same
+     * winding `pushRect` uses, which is what lets a run of mixed rects and quads
+     * keep the canonical index pattern.
+     */
+    pushQuad(x: number, y: number, w: number, h: number, m: GlMat3, u0: number, v0: number, u1: number, v1: number, post: number, slot: number, r?: number, g?: number, b?: number): boolean;
+    /**
+     * Append one glyph quad: the box `(x0, y0)`-`(x1, y1)` mapped through `m`,
+     * sampling `(u0, v0)`-`(u1, v1)` of the font atlas at `slot`, painted in
+     * `rgba`.
+     *
+     * `mode` says which channels of that atlas carry the distance field, and
+     * rides the vertices packed into the slot. The synthetic-bold threshold does
+     * not: it is `u_synthBold`, and the caller breaks the run when it changes.
+     *
+     * A synthetic oblique is sheared here, before `m`; `tanItalic` is 0 for an
+     * upright face. Corners wind as `pushQuad`'s do.
+     */
+    pushGlyph(x0: number, y0: number, x1: number, y1: number, baselineY: number, tanItalic: number, m: GlMat3, u0: number, v0: number, u1: number, v1: number, r: number, g: number, b: number, a: number, slot: number, mode: number): boolean;
+    /**
+     * Append one rect filled by a gradient: the corners of `(x, y, w, h)` mapped
+     * through `m`, sampling the ramp atlas at `slot`.
+     *
+     * `uv` gives each channel of `a_uv` as an affine function of the coordinates
+     * the corners arrive in. `mode` says whether that is a ramp position or a
+     * gradient-space coordinate, and `post` carries the atlas row for the modes
+     * that read it — see `shaders/batchFill.ts`. Values outside 0..1 clamp to
+     * the atlas's edge texel.
+     */
+    pushGradientRect(x: number, y: number, w: number, h: number, m: GlMat3, uv: GradientUV, post: number, slot: number, mode: number, r: number, g: number, b: number, a: number): boolean;
+    /** `pushMesh` for a mesh filled by a gradient — see `pushGradientRect` for
+     *  what `uv`, `post` and `mode` carry. */
+    pushGradientMesh(mesh: Mesh, m: GlMat3, uv: GradientUV, post: number, slot: number, mode: number, r: number, g: number, b: number, a: number): boolean;
+    /**
+     * Append a tessellated mesh through `m`, all vertices carrying `rgba`. The
+     * mesh's own indices are rebased onto the staged vertices, which is why the
+     * index buffer is uploaded per flush rather than written once.
+     */
+    pushMesh(mesh: Mesh, m: GlMat3, r: number, g: number, b: number, a: number): boolean;
+    /** Upload the staged geometry into the next set of buffers and bind its VAO.
+     *  Returns the index count for the caller's `drawElements`. */
+    uploadAndBind(): number;
+    reset(): void;
+    dispose(): void;
+    private writeVertex;
+    /**
+     * Fit the quad just written at `v0` to `rect`: keep it if it lies inside,
+     * drop it if it misses, and cut it if it crosses — but only if its edges
+     * run along the axes. Cutting a slanted edge moves its endpoint off the
+     * subpixel grid the rasterizer snaps to, and the shortened edge then covers
+     * different samples than the whole one did; along an axis the cut edge is
+     * the same line exactly. So a slanted quad that crosses is rolled back and
+     * refused, for the caller to clip through the stencil instead.
+     */
+    private clipQuad;
+    /** `clipQuad` for a mesh staged from `v0`. A mesh's edges are slanted in
+     *  general, so one that crosses is refused rather than cut. */
+    private clipMesh;
+    /** Append the `n`-corner convex polygon in `poly` as a triangle fan. */
+    private appendFan;
+    /** Two triangles over the four corners just written. */
+    private pushQuadIndices;
+    /** Grow the CPU arrays so `vertices` / `indices` more fit. */
+    private reserve;
+    private nextRingSlot;
+    private nextLargeSlot;
+    private createSet;
+    private deleteSet;
+}
+
+/**
+ * `TilePatternSpec` → `TextureHandle`. The bridge between a tile paint and the
+ * GL texture that paints it.
+ *
+ * Memoized on the spec's field values, so identical specs across nodes share
+ * one texture and a re-render never re-rasterizes. The memo keeps the
+ * `PATTERN_TILE_CACHE_LIMIT` tiles most recently resolved or drawn and
+ * unregisters the rest. A handle outliving its tile still draws: its id is
+ * the spec, and the texture registry asks this module to rebuild it.
+ */
+
+/** @internal Test helper — do not call from product code. */
+declare function _resetPatternSpecCacheForTests(): void;
+/**
+ * Build (or fetch) the texture for a spec. Returns `null` when the tile
+ * can't be rasterized — no `OffscreenCanvas`, same as `createTilePattern`.
+ */
+declare function resolvePatternSpec(spec: TilePatternSpec): TextureHandle | null;
+/**
+ * Swap a tile paint for the `texture` paint that draws it, placement kept,
+ * leaving every other fill untouched. The built-in painters run this
+ * alongside `fillInPoseFrame`; a consumer emitting its own draw commands
+ * runs it at the same place it runs that one.
+ *
+ * A tile that can't rasterize drops the fill rather than painting garbage.
+ */
+declare function resolveFillPattern(fill: PosedPaint): CommandPaint | null;
+declare function resolveFillPattern(fill: Paint): Paint | null;
+
+/**
+ * The kit's per-`src` image loader + cache. Shape painters are synchronous
+ * and decoding an image is async, so `getImageBitmap` is a synchronous read
+ * that returns the decoded `ImageBitmap` when ready, and otherwise returns
+ * `undefined` and lazily kicks off a de-duped async load. When a load
+ * resolves (or errors), every `subscribeImageReady` listener fires.
+ *
+ * `src` is any browser-loadable image string: a remote URL, a `blob:` URL, or
+ * a `data:image/…;base64,…` URI. The decoded bitmap lives only here, keyed by
+ * `src` — never in node `data`.
+ */
+/** Public shape of an image node's `data`. `src` round-trips through
+ *  serialization; the decoded bitmap is held in this cache, not on the node. */
+interface ImageNodeData {
+    image: {
+        src: string;
+        opacity?: number;
+        /** The part of the bitmap drawn into the pose rect, as fractions of the
+         *  bitmap's width and height from its top-left. Omitted draws the whole
+         *  bitmap. Fractions, so the data means the same thing before the bitmap
+         *  has decoded and after `src` is swapped for another resolution. */
+        source?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        /** Mirror the drawn region within the pose rect. The rect does not move. */
+        flipX?: boolean;
+        flipY?: boolean;
+    };
+}
+/** Where an image is in its load: never requested, in flight, decoded, or
+ *  failed. Renderers paint a placeholder for anything but `'ready'`. */
+type ImageStatus = 'idle' | 'loading' | 'ready' | 'error';
+/** A size in device pixels. */
+interface ImageRasterSize {
+    width: number;
+    height: number;
+}
+/** `size` is absent for the first load, which decodes at natural size. */
+type Loader = (src: string, size?: ImageRasterSize) => Promise<ImageBitmap>;
+/** True when `src` names SVG — a `data:image/svg+xml` URI, or a URL whose path
+ *  ends in `.svg`/`.svgz`. Such sources re-rasterize at the size they are drawn
+ *  at; everything else decodes once. A `blob:` URL carries no type and counts
+ *  as raster. */
+declare function isVectorImageSrc(src: string): boolean;
+/**
+ * Set how many bytes of decoded RGBA the cache may hold, and return the
+ * previous value. Default 256MB; `Infinity` never drops anything. Takes
+ * effect when the next image lands. A dropped image loads again on its next
+ * {@link getImageBitmap}, as one never requested does.
+ */
+declare function setImageCacheBudget(bytes: number): number;
+/** Synchronous read. Returns the decoded bitmap when ready; otherwise returns
+ *  `undefined` and lazily starts a de-duped async load for `src`.
+ *
+ *  `drawnAt` is the size in device pixels the image is about to cover. A
+ *  vector source ({@link isVectorImageSrc}) uses it to re-rasterize in
+ *  power-of-two steps — the current raster is returned until the sharper one
+ *  is ready. Raster sources ignore it. */
+declare function getImageBitmap(src: string, drawnAt?: ImageRasterSize): ImageBitmap | undefined;
+/** Current load status for `src` (`'idle'` if never requested). */
+declare function imageStatus(src: string): ImageStatus;
+/**
+ * Forget `src`: drop its decoded bitmap, its decoded SVG, and the texture every
+ * live renderer holds for it, and abandon a load in flight. The cache is keyed
+ * by `src` across every scene on the page, so it cannot know when the last use
+ * is gone; whoever does know calls this. A later {@link getImageBitmap} for the
+ * same `src` loads it again.
+ */
+declare function releaseImage(src: string): void;
+/** Load a `src` whose last load failed again. Does nothing for a `src` in any
+ *  other state; one that failed otherwise stays `'error'` for the page's life. */
+declare function retryImage(src: string): void;
+/** Subscribe to load-resolution events (fires after any `src` resolves or
+ *  errors). Returns an unsubscribe. */
+declare function subscribeImageReady(cb: () => void): () => void;
+/** @internal test seam — override the async loader so unit tests don't need
+ *  a real DOM image. Not part of the public barrel. */
+declare function __setImageLoaderForTests(fn: Loader): void;
+/** @internal test seam — clear cache + subscribers and restore the default
+ *  loader. Not part of the public barrel. */
+declare function _resetImageCacheForTests(): void;
+
+export { DrawBatch as D, FLOATS_PER_VERTEX as F, type ImageNodeData as I, type TextureEntry as T, __setImageLoaderForTests as _, type ImageRasterSize as a, type ImageStatus as b, isVectorImageSrc as c, releaseImage as d, resolveFillPattern as e, resolvePatternSpec as f, getImageBitmap as g, retryImage as h, imageStatus as i, subscribeImageReady as j, _resetImageCacheForTests as k, _resetPatternSpecCacheForTests as l, _resetTextureRegistryForTests as m, registerTexture as r, setImageCacheBudget as s, textureRegistry as t, unregisterTexture as u };