@weasel-js/renderer 0.0.0-stage → 1.9.4

package/dist/imageCache-oJVgxhkr.d.ts

@@ -0,0 +1,372 @@
+import { TextureHandle, TilePatternSpec, PosedFill, CommandFill, FillStyle } 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-B2vEy9A4.js';
+
+/**
+ * registerTexture — accepts an image source, assigns an opaque id, stores in
+ * a module-level registry. Actual GL upload happens lazily at draw time in
+ * drawShader() via GLTextureCache.upload (which is idempotent).
+ *
+ * Lifecycle: a texture lives until `unregisterTexture`. Each renderer frees
+ * its own GL copy at the top of its next frame.
+ *
+ * Convention §9: this registry stores image data only — no per-renderer state.
+ * Each WeaselRenderer's GLTextureCache does its own dedup by id and source.
+ */
+
+/** 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 handle is valid for the lifetime of the renderer it will be used with.
+ *
+ * @param image  The image to register. HTMLImageElement must be fully loaded.
+ * @returns      Opaque TextureHandle.
+ */
+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, and every clipped group paid a flush on the way in and
+ * another on the way out. 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: `draw.ts` owns when a run starts, what breaks it, and the
+ * uniforms the flush draws under.
+ *
+ * **One batch for all three, because a page interleaves them.** A grid of
+ * thumbnails is a ground rect under an atlas quad under a caption, per cell,
+ * and while each kind staged separately every one had to drain the others
+ * before it could stage — so a shape that batches perfectly in any one half
+ * alone paid a flush per command. 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 join as a fourth off the ramp
+ * atlas — a linear one without a mode of its own, since (ramp position, row) is
+ * what the plain mode already samples, and a radial or conic one with a mode
+ * that says its UV is a gradient-space coordinate to take a `length` or an
+ * `atan` of. See `shaders/batchFill.ts`.
+ *
+ * Colors ride the vertices because shapes in a run differ in color and a merged
+ * draw has one set of uniforms — and so does the model transform, applied here
+ * rather than uploaded, so shapes under different transforms still share a
+ * draw. The texture rides them too, as a slot index into the units the flush
+ * binds: slot 0 is the white texel every solid samples, and `draw.ts` hands out
+ * the rest per bitmap. A run holds as many bitmaps as there are slots, so an
+ * atlas is what makes a wall of one sheet coalesce and a handful of loose
+ * bitmaps no longer breaks a run per command.
+ */
+
+/** vec2 a_position + vec4 a_vertexColor + vec2 a_uv + float a_post + float
+ *  a_texSlot. Exported so the buffer-replay tests read fields by name rather
+ *  than by a stride they repeat — a hard-coded one silently reads a different
+ *  field when the vertex grows, instead of failing. */
+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`.
+ *
+ * One shape for all three gradients. A linear one'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 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`. `draw.ts` sets it as rect
+     *  clips enter and leave — see `batchClip.ts`. 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). An affine maps a rect to a parallelogram, so two triangles still
+     * cover it and the batch draws at `u_model` identity.
+     */
+    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.
+     *
+     * Corners wind top-left, top-right, bottom-right, bottom-left with UVs
+     * following — the same winding `pushRect` uses, which is what lets a run of
+     * mixed rects and quads keep the canonical index pattern. The flips a command
+     * asks for are already in the `u` / `v` the caller passes.
+     *
+     * `slot` is the texture unit the corners sample, which `draw.ts` assigns per
+     * bitmap within the run.
+     */
+    pushQuad(x: number, y: number, w: number, h: number, m: GlMat3, u0: number, v0: number, u1: number, v1: number, post: number, slot: 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 — so a run off a baked MSDF atlas
+     * and one off the runtime canvas bake still share a draw. The synthetic-bold
+     * threshold does not: it is `u_synthBold`, and `draw.ts` breaks the run when
+     * it changes.
+     *
+     * **A synthetic oblique is sheared here rather than in the shader.** The old
+     * text program carried the baseline per vertex and skewed against
+     * `u_synthItalic`; the batch places its own corners, so the shear is one
+     * multiply while they are being placed, and `tanItalic` is 0 for an upright
+     * face. It has to happen before `m`, which is where the shader had it too.
+     *
+     * Corners wind top-left, top-right, bottom-right, bottom-left — `pushQuad`'s
+     * winding, which is what lets a run of mixed rects, image quads and glyphs
+     * keep the canonical index pattern.
+     */
+    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, which is what lets a gradient ride the vertices at
+     * all: a linear one's ramp position is affine in position outright, and a
+     * radial or conic one's gradient-space *coordinate* is, even though the ramp
+     * position it yields is not. Either way the rasterizer's interpolation across
+     * a triangle is exact. `mode` says which of the two the fragment shader is
+     * looking at, and `post` carries the atlas row for the modes that read it —
+     * see `shaders/batchFill.ts`.
+     *
+     * Values outside 0..1 are the sampler's business; the atlas clamps to the
+     * edge texel, which is what the gradient shader's own `clamp` did.
+     */
+    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 `draw.ts` to clip through the stencil instead.
+     *
+     * A cut axis-aligned quad is still four corners, so the run stays pure.
+     */
+    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 the serializable
+ * half of a pattern 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;
+/** Whether a pattern payload is a spec rather than an already-built handle. */
+declare function isPatternSpec(payload: TextureHandle | TilePatternSpec): payload is TilePatternSpec;
+/**
+ * Swap a pattern paint's spec payload for the texture that paints it,
+ * 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 spec that can't rasterize drops the fill rather than painting garbage.
+ */
+declare function resolveFillPattern(fill: PosedFill): CommandFill | null;
+declare function resolveFillPattern(fill: FillStyle): FillStyle | null;
+
+/**
+ * imageCache — the kit's per-`src` image loader + cache.
+ *
+ * The shape-painter chain (`kit:image` in `NodeShape.ts`) is synchronous, but
+ * decoding an image is async. This module bridges the two: `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
+ * — `<SceneCanvas>` subscribes and calls `requestRedraw()`, so the painter
+ * re-runs and emits the now-ready bitmap.
+ *
+ * `src` is any browser-loadable image string: a remote URL, a `blob:` URL, or
+ * a `data:image/…;base64,…` URI (the embedded-bytes path). The decoded bitmap
+ * lives only here, keyed by `src` — never in node `data` — so `scene.toJSON()`
+ * round-trips the (serializable) `src` string untouched.
+ */
+/** 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;
+/** 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, isPatternSpec as c, isVectorImageSrc as d, releaseImage as e, resolveFillPattern as f, getImageBitmap as g, resolvePatternSpec as h, imageStatus as i, retryImage as j, _resetImageCacheForTests as k, _resetPatternSpecCacheForTests as l, _resetTextureRegistryForTests as m, registerTexture as r, subscribeImageReady as s, textureRegistry as t, unregisterTexture as u };