@weasel-js/renderer 0.0.0-stage → 1.10.0

package/dist/mesh.d.ts

@@ -0,0 +1,241 @@
+import { PaintUnits, ColorSpace, Paint, GradStop } from '@weasel-js/paint';
+import { c as PaintDrawKind } from './paintKinds-BmPAT51k.js';
+import '@weasel-js/registry';
+import '@weasel-js/geom';
+
+/**
+ * Coons and tensor-product patch surfaces — PDF's shading types 6 and 7, as
+ * pure geometry.
+ *
+ * A patch is a curved quadrilateral: four cubic Bézier edges and a color at
+ * each corner. A Coons patch reads its interior off the boundary alone; a
+ * tensor patch adds four interior control points that pull it around.
+ */
+/** A point in the patch's own space. */
+interface MeshPoint {
+    x: number;
+    y: number;
+}
+/**
+ * One patch.
+ *
+ * `points` walks the boundary: corner 0, the two control points of the edge
+ * leaving it, corner 1, its two, and so on — twelve points, ending with the
+ * two controls that return to corner 0. A tensor patch appends its four
+ * interior points, in the order `(1,1)`, `(1,2)`, `(2,2)`, `(2,1)` of the
+ * bicubic control net, which is PDF's own order. Twelve points is a Coons
+ * patch and sixteen is a tensor patch.
+ *
+ * `colors` are the corner colors in the same walk order.
+ */
+interface MeshPatch<TColor = string> {
+    points: readonly MeshPoint[];
+    colors: readonly [TColor, TColor, TColor, TColor];
+}
+/** Corner `i` of the boundary walk. */
+declare function patchCorner(patch: MeshPatch<unknown>, i: number): MeshPoint;
+/** `true` when the patch carries the four interior points a tensor patch adds. */
+declare function isTensorPatch(patch: MeshPatch<unknown>): boolean;
+/** A patch is twelve boundary points, or sixteen with the interior. Anything
+ *  else cannot be evaluated, and saying so here beats painting nonsense. */
+declare function isValidPatch(patch: MeshPatch<unknown>): boolean;
+/**
+ * The patch surface at `(u, v)`, both in `0..1`.
+ *
+ * `u` runs along the edge leaving corner 0 and `v` along the edge leaving
+ * corner 1, so `(0,0)` is corner 0, `(1,0)` corner 1, `(1,1)` corner 2 and
+ * `(0,1)` corner 3 — the same walk `colors` is in.
+ */
+declare function evalPatch(patch: MeshPatch<unknown>, u: number, v: number): MeshPoint;
+/**
+ * The four corner weights at `(u, v)` — bilinear, in the corner walk order.
+ */
+declare function cornerWeights(u: number, v: number): [number, number, number, number];
+/** Axis-aligned bounds of a patch, sampled on a grid: control points alone
+ *  bound a Bézier but not tightly. */
+declare function patchBounds(patch: MeshPatch<unknown>, steps?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+/**
+ * The `mesh-gradient` paint kind — PDF's shading types 6 and 7 as a registered
+ * paint: a set of curved quadrilateral patches, each with a color at every
+ * corner.
+ *
+ * It uses only the slots `registerPaintKind` gives a consumer, so whatever it
+ * can do, a consumer's own kind can do too.
+ */
+
+/**
+ * A mesh gradient paint.
+ *
+ * `patches` are in the space `units` names, the same way a gradient's
+ * geometry is — under `'bounds'` every point is a fraction of the painted
+ * node's box, which is what lets the paint survive a resize.
+ *
+ * `interpolate` is the space corner colors blend through, matching the three
+ * gradients.
+ */
+interface MeshGradientPaint {
+    kind: 'mesh-gradient';
+    patches: MeshPatch[];
+    units?: PaintUnits;
+    interpolate?: ColorSpace;
+    opacity?: number;
+}
+/** The kind's id, as `Paint['fill']` carries it. */
+declare const MESH_GRADIENT_KIND = "mesh-gradient";
+/** A mesh paint, narrowed. */
+declare function isMeshGradientPaint(fill: Paint | null | undefined): fill is Paint & MeshGradientPaint;
+/** A one-patch square covering the unit box, its four corners four readings of
+ *  `color` — a mesh seeded from a solid has to show *something* curved, or
+ *  switching kind looks like nothing happened. */
+declare function seedMeshPatch(color: string): MeshGradientPaint;
+/**
+ * A stop list as a mesh: one full-height band per gap between neighboring
+ * stops, colored left to right. The bands blend exactly the way the ramp
+ * does, so a horizontal gradient survives the switch unchanged. A zero-width
+ * gap is a hard break and gets no band.
+ */
+declare function meshFromStops(stops: readonly GradStop[]): MeshGradientPaint;
+/**
+ * A mesh read as a stop list: every patch's top edge — corner 0 to corner 1 —
+ * placed by its `x` across the mesh's horizontal extent. The inverse of
+ * `meshFromStops`, and for any other mesh the ramp across its top.
+ */
+declare function meshStops(mesh: MeshGradientPaint): GradStop[];
+/** The kind's draw half, shader program included. Core adds the editor's
+ *  slots and registers the whole entry. */
+declare const meshDrawKind: PaintDrawKind;
+/**
+ * The `<defs>` entry for a mesh paint, in weasel's own namespace.
+ *
+ * Not SVG's abandoned `<meshgradient>`: that vocabulary only reaches Coons
+ * patches, shares patch edges implicitly — a reader that gets the sharing
+ * wrong tears the surface rather than failing outright — and has exactly one
+ * implementation in the world. Ours writes every patch's points in full.
+ * `@weasel-js/svg` puts the paint fallback color beside the reference, so a
+ * foreign renderer paints flat instead of nothing.
+ */
+declare function meshGradientXml(id: string, mesh: MeshGradientPaint): string;
+
+/**
+ * A mesh paint baked into one RGBA bitmap: each patch is subdivided into small
+ * quads and rasterized forward, once per paint, into a texture the shader then
+ * samples. Inverting a bicubic per fragment would be Newton iteration.
+ *
+ * The bitmap is straight (non-premultiplied) RGBA; the fragment shader
+ * premultiplies.
+ */
+
+/** Texels on a side of a bake when the caller names no size. The renderer
+ *  sizes each bake from how large the paint draws — see `meshBakeSize`. */
+declare const MESH_BAKE_SIZE = 256;
+/** The box a bake covers, in the paint's own space. */
+interface MeshBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The bitmap `bakeMesh` produces, and the paint-space box it covers. */
+interface BakedMesh {
+    /** `size` × `size` texels, straight RGBA. */
+    pixels: Uint8ClampedArray;
+    /** Texels on a side; `MESH_BAKE_SIZE` unless the caller asked otherwise. */
+    size: number;
+    /** Where the bitmap sits in paint space, which is what the shader maps a
+     *  fragment through. */
+    box: MeshBox;
+}
+/** The union of every patch's bounds, or `null` when nothing is drawable. */
+declare function meshBounds(patches: readonly MeshPatch[]): MeshBox | null;
+/**
+ * Rasterize `patches` into a square bitmap covering their union, or `null`
+ * when no patch is drawable.
+ */
+declare function bakeMesh(patches: readonly MeshPatch[], space?: ColorSpace, size?: number): BakedMesh | null;
+
+/**
+ * How large a mesh bake is, and the bounded cache the bakes live in.
+ *
+ * A gradient's ramp is one-dimensional, so 256 texels cover it at any size. A
+ * mesh's bake is two-dimensional and is stretched over whatever the paint
+ * covers, so a fixed size shows its texels once the paint draws large. The
+ * bake is sized from the device pixels it covers instead, in power-of-two
+ * buckets so a zoom inside one bucket reuses the bake it already has.
+ */
+/** The smallest bake: below this a texture costs more in bookkeeping than in
+ *  bytes. */
+declare const MESH_BAKE_MIN = 32;
+/** The largest bake, whatever the context allows: 16 MiB of RGBA, and a bake
+ *  that already takes a noticeable moment on the CPU. */
+declare const MESH_BAKE_MAX = 2048;
+/**
+ * The bake side for a paint drawn `devicePx` device pixels across, on a
+ * context accepting `maxTextureSize`: the next power of two at or above it,
+ * clamped to `[MESH_BAKE_MIN, MESH_BAKE_MAX]` and to the context. A size that
+ * cannot be measured gets `MESH_BAKE_SIZE`.
+ */
+declare function meshBakeSize(devicePx: number, maxTextureSize: number): number;
+
+/**
+ * The draggable points of a mesh paint, as pure geometry — what an on-canvas
+ * editor lists, and what moving one of them does to the paint.
+ *
+ * Nothing here knows a frame: the handles are in whatever space the mesh's
+ * points are, so a caller resolves a `'bounds'` mesh onto its box first
+ * (`fillInPoseFrame`) and normalizes the result back (`fillToBoundsFrame`).
+ */
+
+/** What a handle moves: a patch corner, one of the two controls of an edge,
+ *  or one of a tensor patch's four interior points. */
+type MeshHandleKind = 'corner' | 'control' | 'interior';
+/** One stored point: `patches[patch].points[index]`. */
+interface MeshPointRef {
+    patch: number;
+    index: number;
+}
+/**
+ * One draggable point.
+ *
+ * Patches store their points in full rather than sharing edges, so two
+ * patches that meet each carry a copy of the corner and controls they meet
+ * at. Those copies are one handle, with a `ref` per copy — dragging one of
+ * them alone would tear the surface open along the seam.
+ */
+interface MeshHandle {
+    /** Stable while the handle moves: its first ref, as `"patch:index"`. */
+    id: string;
+    kind: MeshHandleKind;
+    at: MeshPoint;
+    refs: readonly MeshPointRef[];
+}
+/**
+ * Every draggable point of `mesh`, in walk order: each patch's corners and
+ * edge controls, then a tensor patch's interior. Coincident points of one
+ * kind merge into one handle. A patch that cannot be evaluated has none.
+ */
+declare function meshHandles(mesh: MeshGradientPaint): MeshHandle[];
+/**
+ * `mesh` with `handle` moved to `to`. A corner carries its edge controls
+ * and interior neighbor along by the same offset, the way a path editor's
+ * anchor carries its handles; a control or interior point moves alone.
+ * Returns a new paint; `mesh` is not modified.
+ */
+declare function moveMeshHandle(mesh: MeshGradientPaint, handle: MeshHandle, to: MeshPoint): MeshGradientPaint;
+/** The lines an editor draws under the handles, as control polygons. */
+interface MeshGuides {
+    /** Every patch edge as its four cubic control points, from the corner it
+     *  leaves to the corner it reaches. */
+    edges: [MeshPoint, MeshPoint, MeshPoint, MeshPoint][];
+    /** Corner to each point it carries — an edge control or interior point. */
+    arms: [MeshPoint, MeshPoint][];
+}
+/** The guides for `mesh`'s valid patches. Shared edges appear once per patch. */
+declare function meshGuides(mesh: MeshGradientPaint): MeshGuides;
+
+export { type BakedMesh, MESH_BAKE_MAX, MESH_BAKE_MIN, MESH_BAKE_SIZE, MESH_GRADIENT_KIND, type MeshBox, type MeshGradientPaint, type MeshGuides, type MeshHandle, type MeshHandleKind, type MeshPatch, type MeshPoint, type MeshPointRef, bakeMesh, cornerWeights, evalPatch, isMeshGradientPaint, isTensorPatch, isValidPatch, meshBakeSize, meshBounds, meshDrawKind, meshFromStops, meshGradientXml, meshGuides, meshHandles, meshStops, moveMeshHandle, patchBounds, patchCorner, seedMeshPatch };