@jbrowse/render-core 4.3.0

package/esm/canvas2dUtils.d.ts

@@ -0,0 +1,372 @@
+import type { BpRegionBounds } from './renderBlock.ts';
+export interface BlockClip {
+    scissorX: number;
+    scissorW: number;
+    fullBlockWidth: number;
+    bpLength: number;
+}
+export declare const MAX_DPR = 2;
+/**
+ * The ratio every canvas in the app renders at, capped at {@link MAX_DPR}.
+ *
+ * Use this, never a bare `devicePixelRatio` read — the value has to agree
+ * across the backing-store sizing (`syncCanvasSize` / `prepareCanvas`), the
+ * scissor/viewport rects derived from it (`clipBlock`, alignments'
+ * `computeBlockGeom`), and any shader uniform that reconstructs backing-store
+ * dimensions from CSS ones. A call site that reads the global directly renders
+ * geometry at a different scale than the canvas it lands on.
+ *
+ * Two places legitimately want something other than this and should keep saying
+ * so explicitly: `createSvgRasterCanvas` pins 2x because export goes to a file
+ * rather than a screen, and the analytics / error-report paths read the raw
+ * global because they are reporting the device, not drawing on it.
+ */
+export declare function getDpr(): number;
+export declare const MAX_CANVAS_DIM_PX = 8192;
+/**
+ * The largest CSS-px extent a canvas may take on one axis before its backing
+ * store (`× dpr`) crosses the ceiling above.
+ *
+ * For displays that size a canvas to their **content** rather than to a
+ * viewport — a row stack that grows with the row count, so nothing downstream
+ * bounds it. Past this the backing store stops tracking the CSS size
+ * (`syncCanvasSize` clamps it) while scissor/viewport rects are still derived
+ * as `cssPx * dpr`, so WebGPU rejects an out-of-bounds rect and blanks the
+ * frame, WebGL clamps and paints at the wrong scale, and the Canvas2D fallback
+ * stretches its top slice over the whole track.
+ *
+ * A function, not a constant: `getDpr()` follows the window, so a display
+ * reading this into a computed re-derives it when the window moves to another
+ * screen. Where the cap lands is the caller's — MAF scrolls its overflow into a
+ * viewport, the multi-row painting divides the cap across its rows so they thin
+ * out and all stay on screen.
+ */
+export declare function maxCanvasCssPx(): number;
+/**
+ * The ratio a canvas's backing store ACTUALLY has to its CSS box, per axis.
+ *
+ * Equal to `getDpr()` on both axes until `backingPx` clamps, and below it after
+ * — which is the whole point: every device-px rect a renderer hands the GPU has
+ * to be derived from this rather than from the true dpr, or a clamped canvas
+ * gets a viewport taller than the target it draws into and the frame is
+ * rejected outright. See ARCHITECTURAL_LIMITS.md §"A canvas past
+ * MAX_CANVAS_DIM_PX renders wrong, not smaller".
+ */
+export interface CanvasScale {
+    x: number;
+    y: number;
+}
+export declare function syncCanvasSize(canvas: HTMLCanvasElement, width: number, height: number): {
+    changed: boolean;
+    scale: CanvasScale;
+};
+export declare function prepareCanvas(canvas: HTMLCanvasElement, ctx: CanvasRenderingContext2D, canvasWidth: number, canvasHeight: number): void;
+export declare function getPreparedCanvas2D(canvas: HTMLCanvasElement | null, width: number, height: number): CanvasRenderingContext2D | null;
+export declare function devicePxSpan(cssStart: number, cssEnd: number, dpr: number): {
+    start: number;
+    width: number;
+};
+/**
+ * One horizontal band of a stacked canvas as a device-px scissor rect, clamped
+ * to the backing store: `top`/`height` in CSS px, `bufH` the backing store's
+ * height in device px.
+ *
+ * The clamp is the part that matters. A band scrolled past either edge — a
+ * grouped alignments section, a MAF rows viewport under a resized band — yields
+ * a rect the backing store does not contain, and WebGPU REJECTS an
+ * out-of-bounds scissor and blanks the whole frame rather than clipping it. A
+ * band clamped to zero height is the caller's cue to skip its passes.
+ *
+ * `dpr` is the scale the canvas ACTUALLY got (`hal.resize`'s return), not
+ * `getDpr()`: the two part company once the backing store clamps at
+ * `MAX_CANVAS_DIM_PX`, and past that a band built from the true ratio is taller
+ * than the target.
+ */
+export declare function devicePxBand(top: number, height: number, dpr: number, bufH: number): {
+    top: number;
+    height: number;
+};
+export declare function clampBlockScissor(screenStartPx: number, screenEndPx: number, canvasWidth: number): {
+    scissorX: number;
+    scissorEnd: number;
+    scissorW: number;
+} | null;
+export declare function clipBlockForCanvas(block: BpRegionBounds, canvasWidth: number): BlockClip | null;
+/**
+ * The 2D-context subset the block scaffold below needs. Structural on purpose:
+ * render-core must not depend on `@jbrowse/core`, where the real `Ctx2D =
+ * CanvasRenderingContext2D | SvgCanvas` union lives. Both members satisfy it,
+ * so a plugin passes its `Ctx2D` straight in.
+ */
+export interface ClipContext2D {
+    save(): void;
+    restore(): void;
+    beginPath(): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    clip(): void;
+}
+/**
+ * Clip to one rect, paint, unclip — the `save`/`clip`/`restore` triple with the
+ * `restore` in a `finally`.
+ *
+ * The `finally` is the whole point, and the cost of missing it is not local: an
+ * on-screen ctx outlives the frame and `prepareCanvas`'s setTransform/clearRect
+ * do **not** reset clip state, so one painter throwing once leaves every later
+ * frame drawing through a stale clip. A transient error becomes permanent
+ * corruption, and the visible symptom (content missing from a band that has no
+ * reason to be clipped) points nowhere near the painter that threw.
+ *
+ * `forEachClippedBlock` is the per-block form and covers the common case on its
+ * own. Reach for this one for the clips *nested inside* a block — a display
+ * whose bands each own a horizontal strip of the canvas (alignments clips its
+ * coverage, pileup and arc bands separately within one block clip), where the
+ * nesting is what makes a hand-rolled pairing easy to get wrong: an early
+ * `return` inside the band body unbalances the block's `save` too.
+ */
+export declare function withClip(ctx: ClipContext2D, x: number, y: number, w: number, h: number, paint: () => void): void;
+/**
+ * The Canvas2D twin of `GpuPerRegionRenderingBackend.renderBlocks`' per-block
+ * scissor: skip blocks with nothing to draw or no on-screen span, clip to the
+ * block's columns, paint, unclip. Owning it here means a painter can't pair
+ * `save()` with a missed `restore()` (leaking the clip onto every later block),
+ * clip to a span other than `clipBlockForCanvas`', or forget the null check.
+ *
+ * `select` resolves a block to what it paints, or `undefined` to skip it — the
+ * one gate covering all three reasons a painter skips: no region in the map, a
+ * region with zero features, and a region whose relevant sub-field is absent
+ * (MAF's `?.coverage`). It runs *before* the clip so an empty block costs
+ * neither the path-and-clip round trip on a real context nor the queued group
+ * on `SvgCanvas` — that class now drops a clip nothing was drawn inside, so a
+ * skipped-late block no longer leaves dead `<clipPath>` markup in the export,
+ * but relying on it to clean up after the gate is backwards. Resolving here
+ * also lets `paint` take a non-optional value instead of re-narrowing inside
+ * the callback.
+ *
+ * `clipHeight` is a parameter rather than read off a render state because
+ * painters that own a sub-band of the canvas clip to that band, not the full
+ * height (MAF's coverage row).
+ *
+ * `paint` receives the block, so callers needing bp→px build their own mapper
+ * (`makeBpMapper` / `makeCellLeftMapper` — which one is a per-painter choice).
+ * Two closures per draw call, not per feature: per-feature loops live inside the
+ * `paint` body and stay allocation-free.
+ */
+export declare function forEachClippedBlock<T, B extends BpRegionBounds>(ctx: ClipContext2D, blocks: readonly B[], canvasWidth: number, clipHeight: number, select: (block: B) => T | undefined, paint: (data: T, block: B, clip: BlockClip) => void): void;
+/**
+ * Stroke the outline of `[x, y, w, h]` so the line lands **inside** the rect
+ * rather than straddling its edge.
+ *
+ * Canvas2D centres a stroke on its path, so `strokeRect(x, y, w, h)` puts half
+ * the line width outside the rectangle you named. Every GPU pass in this repo
+ * draws an outline as an inner band — a fragment test on distance-to-edge, which
+ * has no way to paint outside the glyph — so the straddling spelling is a
+ * guaranteed half-pixel disagreement with the shader, and it eats whatever gap
+ * separates the glyph from its neighbour.
+ *
+ * **It matters more in the SVG export than on screen**, which is the reason this
+ * is a helper and not a house style. On a canvas the difference is half a pixel;
+ * in SVG a centred stroke means the emitted element's *declared geometry* and
+ * its painted extent differ by half the stroke width, so a 10px-tall read
+ * exports as an 11px-tall mark. Anything that measures the file, or opens it in
+ * a vector editor and snaps to the shape's bounds, is then reading a rectangle
+ * whose coordinates do not describe what is drawn.
+ *
+ * Degenerate rects are left to the caller: below `lineWidth` on an axis the
+ * inset would invert it, and what to do instead (skip the outline, or fill
+ * solid) is a per-glyph decision. The alignments read painter and the canvas
+ * feature painter both gate on a minimum size first.
+ */
+export declare function strokeRectInside(ctx: {
+    strokeRect: (x: number, y: number, w: number, h: number) => void;
+}, x: number, y: number, w: number, h: number, lineWidth?: number): void;
+/**
+ * `fillRect` x for a mark that spans `x1`→`x2` but is painted at `width` — the
+ * Canvas2D pivot for every painter that widens a too-narrow span to a floor (a
+ * 1bp feature, a zoomed-out coverage bin), and the twin of the pivot baked into
+ * the shaders' `extendToMinWidthX`.
+ *
+ * The mark is anchored at `x1` and grows *away* from it. That's the whole point:
+ * on a reversed block `makeBpMapper` flips, so `x2 < x1`, `x1` is the feature's
+ * **start** — its right edge — and the mark must grow leftward from it. Spelling
+ * the fill as `min(x1, x2)` + `max(floor, |dx|)` instead anchors whichever edge
+ * happens to be leftmost, which reversed is the feature's *end*, sliding the
+ * mark by up to the floor. Forward blocks are identical either way, so the error
+ * only ever shows on flipped regions and survives review. The canvas rect
+ * painter (2px floor), the multi-row painter (1px), and wiggle (1.5px) each had
+ * it independently.
+ *
+ * Callers own the *width*, like `makeCellLeftMapper` below — it's a per-plugin
+ * rule (canvas/multi-row take `max(floor, |dx|)`, matching `extendToMinWidthX`
+ * exactly; wiggle adds a seam-closing fudge the shader deliberately omits).
+ * Only the pivot is shared, and it's the part that keeps being got wrong.
+ *
+ * Scalar in, scalar out: runs per feature per frame, so it must not allocate.
+ */
+export declare function spanLeft(x1: number, x2: number, width: number): number;
+export declare function makeRampFillStyleLut(ramp: Uint8Array): (t: number) => string;
+export declare function bpToScreenPx(absBp: number, regionStart: number, regionEnd: number, screenStartPx: number, screenEndPx: number, reversed?: boolean): number;
+export declare function makeBpMapper(bounds: BpRegionBounds): (bp: number) => number;
+/**
+ * Left edge of the **1bp cell** covering `bp` — for painters that fill a rect
+ * per base (MAF alignment cells, the alignments pileup's mismatch /
+ * modification / per-base quality+letter / soft-clip base layers).
+ *
+ * Use this, not `makeBpMapper`, whenever the mark is a cell rather than a point
+ * or a two-edge span. `makeBpMapper(bp)` is the cell's left edge only on a
+ * forward block: a reversed block runs bp leftward, so it lands on the cell's
+ * *right* edge, and `fillRect(x, y, +w, h)` from there covers bp-1 instead. The
+ * error is one base wide — invisible zoomed out (cells floor to ~1px), a whole
+ * base off zoomed in, and it only reproduces on flipped regions, so it survives
+ * casual review. Every plugin that hand-rolled the pivot had to rediscover it;
+ * the alignments pileup got it wrong across all five of its cell layers.
+ *
+ * Two-edge spans (`min(toX(start), toX(end))`) and boundary marks (insertions,
+ * clip bars, centered on a bp edge) are orientation-safe already and don't need
+ * this. The GPU side has no equivalent bug — shaders span
+ * `bpToClipX(pos)`→`bpToClipX(pos+1)` unflipped and mirror via `flipX` — and
+ * gets its own pivot from `writeBpRangeUniforms`.
+ *
+ * Callers own the cell *width*: it's a per-plugin rule (MAF uses the raw
+ * bp-scale; the pileup floors at 1px and adds a seam fudge). Only the pivot is
+ * shared.
+ */
+/**
+ * Screen px one base occupies in this region — the scale factor, unsigned, with
+ * the block's direction deliberately left out (that lives in `makeBpMapper` and
+ * `spanLeft`, and folding it in here would make a *scale* carry an orientation).
+ *
+ * Shared because it is usually an input to something a second painter has to
+ * reproduce exactly: a mark sized against it in a draw pass and hit-tested
+ * against it in a component is two spellings of one number, and the hit target
+ * silently stops covering the mark if they ever drift. Trivial arithmetic, but
+ * the drift is not.
+ */
+export declare function pxPerBpOf(bounds: BpRegionBounds): number;
+export declare function makeCellLeftMapper(bounds: BpRegionBounds): (bp: number) => number;
+/**
+ * Fill the rect covering genomic `[startBp, endBp)`, given a bare
+ * `makeBpMapper`. Maps **both** edges and takes the leftmost, which is
+ * orientation-safe by construction: on a reversed block bp runs leftward, so
+ * the span's left edge is its *end*, and there is no pivot to get backwards.
+ *
+ * Prefer this to `makeCellLeftMapper` + a caller-computed width for anything
+ * wider than one base. The pivot in `makeCellLeftMapper` is exactly one base,
+ * which is right for a 1bp cell and silently wrong for an N-bp span — it
+ * anchors the rect one base from the correct edge and then grows it the wrong
+ * way. `fillBpSpan(bp, bp + 1)` is *identical* to the cell-mapper spelling, so
+ * a per-base painter can use this too and never think about orientation again.
+ *
+ * `seam` is the caller's sub-pixel overlap (MAF's `GAP_STROKE_OFFSET`), added
+ * to the width so adjacent cells don't show hairlines at ~1px/bp. Widening a
+ * sub-pixel *feature* to a visible floor is a different job — that's
+ * `spanLeft`, which must anchor the feature's start edge.
+ */
+export declare function fillBpSpan(ctx: {
+    fillRect: (x: number, y: number, w: number, h: number) => void;
+}, toX: (bp: number) => number, startBp: number, endBp: number, top: number, height: number, seam?: number): void;
+/**
+ * The **integer base** whose 1bp cell covers screen pixel `px` — the inverse of
+ * `makeCellLeftMapper`, for hit-testing (which base did the cursor land on) as
+ * opposed to painting.
+ *
+ * Rounding is not `Math.floor` on both orientations, which is the trap. The
+ * un-rounded inverse of `makeBpMapper` lands in `[b, b+1)` on a forward block
+ * but in `(b, b+1]` on a reversed one, because bp runs leftward there — so
+ * flooring reversed names `b+1` on base `b`'s leftmost pixel column, and names
+ * `end` (outside the block) on the block's first column. It is the same
+ * one-base pivot `makeCellLeftMapper` exists to get right, seen from the other
+ * direction, and it fails the same way: invisible zoomed out, a whole base off
+ * at base zoom, and only on flipped regions.
+ *
+ * Callers own the *range* check: a `px` outside `[screenStartPx, screenEndPx)`
+ * extrapolates rather than clamping, since which block owns a pixel is the
+ * caller's decision (adjacent blocks share an edge pixel).
+ *
+ * **Multiply before dividing, and never form the fraction.** That is the whole
+ * of the arithmetic below and it is load-bearing: `(px - screenStartPx) * span`
+ * is *exact* — both operands are dyadic and the product tops out around 3e12
+ * against a 2^53 budget — so the one division that follows is the only rounding
+ * in the expression, and its true quotient is either an exact integer (the
+ * division is then exact too) or at least `1 / blockWidth` from one, which is
+ * ~1e-3 against a relative error of 2^-53. So the floor cannot land on the
+ * wrong base. Spelling it `frac = (px - s) / w` and then `frac * span` rounds
+ * twice, and the second product can land arbitrarily close to an integer from
+ * either side.
+ *
+ * Not a micro-optimization — a correctness one, and measured. Against an exact
+ * rational oracle over 11.6M realistic samples (integer through eighth-pixel
+ * cursor positions, chr1-scale starts, spans from 1bp to 3Mb, both
+ * orientations, fractional block offsets) this form is exact on every one,
+ * where the `frac` spelling it replaces named the wrong base 4202 times and
+ * wiggle's independent `baseAtFraction` — which this now backs — 10992 times.
+ * Those are all boundary pixels, which is exactly where a per-base tooltip is
+ * read.
+ *
+ * **The anchor splits, because `bounds.start` is usually not a whole base.** A
+ * block's edges are laid out in PIXELS, so its bp edges land wherever that
+ * projection puts them — `visibleRegions` hands every hit test a start like
+ * `14468.9936` — and rounding the *offset* and then adding such an anchor
+ * returns the anchor's fraction untouched. The result is then not a base at
+ * all, and every caller that indexes one by equality (a mismatch column, a
+ * coverage bin, the sort-at-this-column anchor) misses silently: the pileup
+ * offered no SNP submenu over a mismatch it was drawing. Rounding
+ * `whole + fraction + offset` in one step instead fixes that and hands back the
+ * genome-scale addend the paragraph above exists to keep out, so the whole base
+ * comes off first and only the sub-base remainder enters the rounded
+ * expression. On a whole-base anchor that remainder is zero and the arithmetic
+ * is identical to what an integer start has always done.
+ *
+ * The same oracle, re-run over 3.7M samples on fractional anchors: this spelling
+ * misses 696 and the shipped one missed every single fractional-anchor sample,
+ * 3,076,480 of them. `Math.floor(start + offset)` misses 2,524. The residue is
+ * the boundary pixel itself, which no double-precision spelling resolves both
+ * ways once base boundaries stop landing on whole pixels.
+ */
+export declare function bpAtPx(px: number, bounds: BpRegionBounds): number;
+/**
+ * The **fractional bp** at screen pixel `px` — the un-rounded inverse of
+ * `makeBpMapper`, for hit tests that measure a distance or open a search window
+ * rather than index a base (the alignments interbase triangles and modification
+ * centers, the variant cell's bp padding, the Manhattan point's ±radius query).
+ *
+ * Ask `bpAtPx` instead the moment the answer indexes per-base data, and **do
+ * not floor this** — flooring an already-divided fraction is the double
+ * rounding `bpAtPx`'s JSDoc argues against at length, and reversed it names the
+ * neighbouring base as well. `end - offset` reversed, not `start + offset`: bp
+ * runs leftward there, and each of the three plugins that spelled this out
+ * locally had to rediscover that.
+ *
+ * **Neither function is the other's implementation.** This multiplies before
+ * dividing for the same reason `bpAtPx` does — `(px - screenStartPx) * span` is
+ * exact, so the division is the only rounding — but it does not split the
+ * anchor into whole and remainder the way `bpAtPx` does. That split keeps the
+ * genome-scale addend out of a *rounded* expression, and there is no rounding
+ * here to protect; the caller wants the anchor's fraction kept, not floored
+ * away.
+ *
+ * Adopting it moved no consumer's answer, which is the point rather than a
+ * caveat. Over 300000 fractional-anchor samples against the exact-rational
+ * oracle `bpAtPx` was measured on, it and all three spellings it replaced land
+ * within 1 ulp of the exactly-rounded value; it returns a different double from
+ * the `frac` spelling on 114 and from gwas' `bpPerPx` spelling on 289, by at
+ * most 7.5e-9 bp against hit radii measured in whole pixels.
+ */
+export declare function bpAtPxExact(px: number, bounds: BpRegionBounds): number;
+/**
+ * The region owning screen pixel `px`, or undefined past the last one — the
+ * range check `bpAtPx` and `bpAtPxExact` leave to their callers, answered once.
+ *
+ * **The exclusive upper bound is the whole content of this.** Adjacent regions
+ * share a pixel (`regionA.screenEndPx === regionB.screenStartPx`), so an
+ * inclusive bound matches both and `find` hands back the earlier one — which
+ * then steals every click meant for the later region's first column. Half-open,
+ * exactly one region can match, so this answers with a region rather than a
+ * list.
+ *
+ * Generic so a caller gets its own region type back, since what it wants from
+ * the match is a `displayedRegionIndex` or the bp/px edges for a mapper.
+ */
+export declare function regionAtPixel<R extends {
+    screenStartPx: number;
+    screenEndPx: number;
+}>(regions: readonly R[], px: number): R | undefined;