@jbrowse/render-core 5.0.0-beta.1 → 5.0.0-beta.10

package/src/shaders/rowRect.slang

@@ -1,34 +1,34 @@
 // Shared "row of colored rects" primitive: one instance is a rectangle
-// spanning [startBp, endBp) in absolute genomic coords, drawn on the row given
-// by `rowIndex` and filled with a per-instance packed ABGR color.
+// spanning [x, x2) in absolute genomic coords, drawn on the row given by
+// `row` and filled with a per-instance packed ABGR color.
 //
-// Two renderers draw exactly this: the MAF alignment renderer (run-merged
-// per-base cells) and the multi-row feature painter / "chromosome painting"
-// (features are already intervals). They shipped as byte-identical copies of
-// one another joined only by a "probably belongs there too" comment; owning the
-// geometry here makes a change to the primitive land in both by construction.
+// The `span` mark draws exactly this for MAF (run-merged per-base cells) and
+// the multi-row feature painter (features are already intervals), and wiggle
+// density composes the same rect over a colour of its own.
 //
 // Row placement comes from uniforms rather than the instance data, so a
 // rowHeight / rowProportion change re-renders without a refetch.
 //
-// What the callers legitimately differ on is the min-width floor: both the
-// width they write into `minCellPx` and the *unit* they measure it in, via
-// `minCellDenomPx` (CSS px vs device px) — see GpuMafRenderer's note. Those are
-// uniform-write decisions, not a reason for two shaders. The unit is also
-// unsettled, and device px additionally makes MAF's floor depend on the
-// reader's monitor: `agent-docs/ideas/maf-subpixel-cells.md`.
-//! export-consts: MIN_DRAWN_ROW_PX, MIN_DRAWN_CELL_PX, MULTI_ROW_MIN_CELL_PX
+// What the callers legitimately differ on is the min-width floor they write
+// into `minCellPx` — a uniform-write decision, not a reason for two shaders.
+// Whether to floor at all turns on whether the caller's marks leave GAPS: a
+// floored quad grows off its start edge, so a neighbour abutting it covers the
+// growth and the floor paints nothing extra. The multi-row painter's features
+// are sparse intervals with nothing beside them, so it floors; MAF's cells
+// never gap and it passes 0; wiggle density tiles at most zooms and gaps where
+// its source does, so it floors and pays nothing for it on the tiling. Both
+// halves measured — `agent-docs/reference/MAF_SUBPIXEL_CELLS.md`.
+//! export-consts: MIN_DRAWN_ROW_PX, MULTI_ROW_MIN_CELL_PX
 //! js-export: drawnRowHeightPx, rowBandOffsetPx
 module rowRect;
 
-import colorPack;
 import hpmath;
 
 public struct RowRectInstance {
-  public uint startBp  : ATTR0;
-  public uint endBp    : ATTR1;
-  public uint rowIndex : ATTR2;
-  public uint color    : ATTR3;  // packed ABGR
+  public uint x     : ATTR0;
+  public uint x2    : ATTR1;
+  public uint row   : ATTR2;
+  public uint color : ATTR3;  // packed ABGR
 };
 
 public struct RowRectUniforms {
@@ -36,16 +36,15 @@ public struct RowRectUniforms {
   public float  canvasHeight;  // CSS px
   // The width `minCellPx` is measured against, and so the thing that decides
   // what unit `minCellPx` IS. Named for that rather than for the viewport
-  // because the three callers do not agree: multi-row and wiggle density pass
-  // a CSS width (a 1 CSS px floor), MAF passes a device one (1 device px, so
-  // half a CSS px on a retina screen and a floor that moves with the monitor).
-  // That disagreement is live and parked, not settled —
-  // agent-docs/ideas/maf-subpixel-cells.md — so the name carries it to every
-  // call site instead of a comment forty lines away.
+  // because the callers that floor pass a CSS width. Pass a DEVICE width and
+  // the floor moves with the reader's monitor — MAF did, and rendered
+  // measurably differently on a retina screen until it stopped flooring.
   public float  minCellDenomPx;
-  // Narrowest a cell is painted, in whatever unit `minCellDenomPx` is in.
-  // MIN_DRAWN_CELL_PX is the floor a caller takes when it has no reason to
-  // widen further; the multi-row painter does (see MULTI_ROW_MIN_CELL_PX).
+  // Narrowest a cell is painted, in whatever unit `minCellDenomPx` is in. Zero
+  // is a no-op, and over marks that tile so is every other value; what a floor
+  // decides is what a GAP next to a sub-pixel mark looks like. MAF writes 0,
+  // the multi-row painter MULTI_ROW_MIN_CELL_PX, wiggle density
+  // MIN_FILL_WIDTH_PX.
   public float  minCellPx;
   public float  zero;          // always 0.0 — prevents hp-split collapse
   public float  rowHeight;     // CSS px per row
@@ -62,24 +61,16 @@ public struct RowRectVsOut {
   public float4 color    : COLOR0;
 };
 
-// Thinnest a row is ever painted. Vertical twin of MIN_DRAWN_CELL_PX below: a
-// row thinner than a pixel can miss every pixel center and disappear, so
-// without this rows drop out as they get denser instead of just getting
-// thinner. Floored, neighbours overlap instead.
-static const float MIN_DRAWN_ROW_PX = 1.0;
-
-// Thinnest a cell can be painted and still be drawable at all, for the same
-// reason as the row floor above on the other axis. A caller writes this into
-// `minCellPx` when a cell being *visible* is not its problem, only a cell
-// existing; one whose whole encoding is carried by sub-pixel cells asks for
-// more (MULTI_ROW_MIN_CELL_PX).
+// Thinnest a row is ever painted: a row thinner than a pixel can miss every
+// pixel center and disappear, so without this rows drop out as they get denser
+// instead of just getting thinner. Floored, neighbours overlap instead.
 //
-// One caller mirrors it on the Canvas2D side and one deliberately does not: the
-// multi-row painter floors, MAF draws cells at their natural sub-pixel width.
-// That asymmetry is real and parked in `agent-docs/ideas/maf-subpixel-cells.md`;
-// sharing the constant does not decide it, it just stops the value being
-// anonymous in the places that DO agree.
-static const float MIN_DRAWN_CELL_PX = 1.0;
+// There is no X-axis twin. A row is a container the reader is counting, so
+// losing one loses a species; a cell is a sample of a tiling, so losing one to
+// the blend is the honest answer and flooring it invents ink
+// (`agent-docs/reference/MAF_SUBPIXEL_CELLS.md`). The caller that does want an X
+// floor names its own width, below.
+static const float MIN_DRAWN_ROW_PX = 1.0;
 
 // What the multi-row painter ("chromosome painting") writes into `minCellPx`.
 //
@@ -91,9 +82,9 @@ static const float MIN_DRAWN_CELL_PX = 1.0;
 // across two, so neither reaches full opacity — the tick reads as a smudge, and
 // the eye scanning for structure across the rows finds none.
 //
-// Both floors distort width; that is what a floor is. This one distorts more,
-// and only where the alternative was showing nothing legible: a feature wide
-// enough to matter is already past it.
+// A floor distorts width; that is what a floor is. This is the only caller that
+// takes the trade, and only where the alternative was showing nothing legible:
+// a feature wide enough to matter is already past it.
 static const float MULTI_ROW_MIN_CELL_PX = 2.0;
 
 public struct RowBand {
@@ -148,13 +139,3 @@ public float4 rowRectClipPos(
   return float4(
     lerp(sx1, sx2, local.x), yPxToClipY(yPx, u.canvasHeight), 0.0, 1.0);
 }
-
-public RowRectVsOut rowRectVertex(
-  RowRectInstance inst, uint vid, RowRectUniforms u
-) {
-  RowRectVsOut o;
-  o.position = rowRectClipPos(
-    inst.startBp, inst.endBp, float(inst.rowIndex), vid, u);
-  o.color = unpackRGBA(inst.color);
-  return o;
-}

package/src/shaders/rowTable.generated.ts

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from rowTable.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+export const ROW_TABLE_MAX_WIDTH = 2048

package/src/shaders/rowTable.js.generated.ts

@@ -0,0 +1,37 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from rowTable.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+// Scalar twins of rowTable.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+
+function _max(a: number, b: number) {
+  return b > a || Number.isNaN(a) ? b : a
+}
+
+function _min(a: number, b: number) {
+  return b < a || Number.isNaN(a) ? b : a
+}
+
+export function rowTableWidth(keys: number): number {
+  return _max(_min(keys, 2048), 1)
+}
+
+export function rowTablePlaneHeight(keys: number): number {
+  let w = rowTableWidth(keys)
+  let _t0 = Math.trunc(((((keys + w) >>> 0) - 1) >>> 0) / w)
+  return _max(_t0, 1)
+}
+
+export function rowTableTexelX(key: number, keys: number): number {
+  let _t0 = (key % rowTableWidth(keys))
+  return _t0
+}
+
+export function rowTableTexelY(key: number, keys: number): number {
+  let _t0 = Math.trunc(key / rowTableWidth(keys))
+  return _t0
+}
+
+export function rowBandTopPx(rowOffsetPx: number, rowHeight: number, slot: number): number {
+  return (rowOffsetPx + (rowHeight * (slot)))
+}

package/src/shaders/rowTable.slang

@@ -0,0 +1,98 @@
+// The row axis resolved on the GPU. An instance carries a stable row KEY in its
+// `row` lane, and the pass binds a table mapping each key to the slot it is
+// drawn on, or to hidden, with an optional colour override — so a reorder, a
+// focus, a hide or a recolour uploads this table and no instance bytes, the
+// property a y domain already has as a uniform (GRAMMAR_OF_GRAPHICS.md, rule 3).
+//
+// The table is an RGBA8 texture of two planes, one texel per key, keys wrapped
+// onto rows of ROW_TABLE_MAX_WIDTH past it (the WebGL2 floor on a texture
+// dimension). The slot plane holds the slot's low 24 bits in rgb and 255 in
+// alpha where the key is drawn, 0 where it is hidden; the colour plane below it
+// holds the override, straight alpha, and alpha 0 where the instance keeps its
+// own colour. `marks/rowTable.ts` writes it through the texel twins exported
+// here, and is the painter's and hit test's reading of the same bytes.
+//
+// Sampled at texel centres with `SampleLevel`, never `Load`: this slangc emits
+// `textureLoad` on the sampler variable for `Load`, which is invalid WGSL. The
+// texel index arithmetic is unsigned and the filter below is `nearest`, so the
+// read-back is the byte the builder wrote — `rowTableWidth` is the key count
+// itself below the cap, and `(x + 0.5) / w` at a non-power-of-two width does
+// not round-trip through the sampler's fixed point, so a linear tap would blend
+// two keys' slot bytes into a slot belonging to neither. A module can take a
+// sampler as a parameter but not declare the binding for its importer, so each
+// pass reading a table declares its own `Sampler2D<float4> rowTable` and
+// inherits the filter from here.
+//! texture-filter: rowTable nearest
+//! export-consts: ROW_TABLE_MAX_WIDTH
+//! js-export: rowTableWidth, rowTablePlaneHeight, rowTableTexelX, rowTableTexelY, rowBandTopPx
+//! js-skip: byteOf — recovers a byte from a sampled texel; the TS side reads the table's bytes directly
+module rowTable;
+
+public static const uint ROW_TABLE_MAX_WIDTH = 2048u;
+
+public struct RowPlacement {
+  public bool hidden;
+  public uint slot;
+  public float4 color;
+};
+
+public uint rowTableWidth(uint keys) {
+  return max(min(keys, ROW_TABLE_MAX_WIDTH), 1u);
+}
+
+public uint rowTablePlaneHeight(uint keys) {
+  uint w = rowTableWidth(keys);
+  return max((keys + w - 1u) / w, 1u);
+}
+
+public uint rowTableTexelX(uint key, uint keys) {
+  return key % rowTableWidth(keys);
+}
+
+// The key's row in the slot plane; the colour plane's is one plane height on.
+public uint rowTableTexelY(uint key, uint keys) {
+  return key / rowTableWidth(keys);
+}
+
+// Where the band of `slot` starts, in CSS px below the canvas top: every
+// mark placing an instance through the table stacks its bands this way.
+public float rowBandTopPx(float rowOffsetPx, float rowHeight, uint slot) {
+  return rowOffsetPx + rowHeight * float(slot);
+}
+
+uint byteOf(float channel) {
+  return uint(channel * 255.0 + 0.5);
+}
+
+// The key's placement: its slot and colour through the table of `keys` keys,
+// or the identity — its `row` as the slot, its own colour — where `keys` is
+// negative, which is what a pass with no table binds.
+public RowPlacement rowTableLookup(
+  Sampler2D<float4> table, uint key, int keys, float4 own
+) {
+  RowPlacement p;
+  p.hidden = false;
+  p.slot = key;
+  p.color = own;
+  if (keys < 0) {
+    return p;
+  }
+  uint n = uint(keys);
+  if (key >= n) {
+    p.hidden = true;
+    return p;
+  }
+  uint h = rowTablePlaneHeight(n);
+  float u = (float(rowTableTexelX(key, n)) + 0.5) / float(rowTableWidth(n));
+  float rows = float(2u * h);
+  uint y = rowTableTexelY(key, n);
+  float4 s = table.SampleLevel(float2(u, (float(y) + 0.5) / rows), 0.0);
+  if (s.a < 0.5) {
+    p.hidden = true;
+    return p;
+  }
+  p.slot = byteOf(s.r) | (byteOf(s.g) << 8) | (byteOf(s.b) << 16);
+  float4 c = table.SampleLevel(float2(u, (float(y + h) + 0.5) / rows), 0.0);
+  p.color = c.a > 0.0 ? c : own;
+  return p;
+}

package/src/shaders/scoreScale.generated.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from scoreScale.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+export const SCALE_TYPE_LOG = 1
+
+export const SCALE_TYPE_SYMLOG = 2

package/src/shaders/scoreScale.js.generated.ts

@@ -16,36 +16,61 @@ function _min(a: number, b: number) {
   return b < a || Number.isNaN(a) ? b : a
 }
 
+function log1pf(x: number): number {
+  let u = (1.0 + x)
+  let _t0: number
+  if ((u == 1.0)) {
+    _t0 = x
+  } else {
+    _t0 = (Math.log(u) * (x / (u - 1.0)))
+  }
+  return _t0
+}
+
 function symlogTransform(x: number, c: number): number {
-  return ((((Math.sign(x)) | 0)) * Math.log((1.0 + Math.abs((x / c)))))
+  return ((((Math.sign(x)) | 0)) * log1pf(Math.abs((x / c))))
 }
 
-export function normalizeScore(score: number, domainMin: number, domainMax: number, scaleType: number, symlogConstant: number): number {
+export function normalizeScoreUnclamped(score: number, domainMin: number, domainMax: number, scaleType: number, symlogConstant: number): number {
+  let tMax: number
+  let tMin: number
+  let t: number
   if ((scaleType == 2)) {
-    let tMin = symlogTransform(domainMin, symlogConstant)
-    let tRange = (symlogTransform(domainMax, symlogConstant) - tMin)
-    if ((tRange <= 0.0)) {
-      return 0.0
+    let _t0 = symlogTransform(score, symlogConstant)
+    let _t1 = symlogTransform(domainMin, symlogConstant)
+    tMax = symlogTransform(domainMax, symlogConstant)
+    tMin = _t1
+    t = _t0
+  } else {
+    if ((scaleType == 1)) {
+      if ((domainMin > 0.0)) {
+        tMax = domainMin
+      } else {
+        tMax = 1.0
+      }
+      let _t2 = Math.log2(_max(score, tMax))
+      let _t3 = Math.log2(tMax)
+      tMax = Math.log2(_max(domainMax, tMax))
+      tMin = _t3
+      t = _t2
+    } else {
+      tMax = domainMax
+      tMin = domainMin
+      t = score
     }
-    return _clamp(((symlogTransform(score, symlogConstant) - tMin) / tRange), 0.0, 1.0)
   }
-  if ((scaleType == 1)) {
-    let floorV: number
-    if ((domainMin > 0.0)) {
-      floorV = domainMin
+  let tRange = (tMax - tMin)
+  if ((tRange <= 0.0)) {
+    if ((t > tMin)) {
+      tMax = 1.0
     } else {
-      floorV = 1.0
+      tMax = 0.0
     }
-    let logMin = Math.log2(floorV)
-    let logRange = (Math.log2(_max(domainMax, floorV)) - logMin)
-    if ((logRange <= 0.0)) {
-      return 0.0
-    }
-    return _clamp(((Math.log2(_max(score, floorV)) - logMin) / logRange), 0.0, 1.0)
-  }
-  let range = (domainMax - domainMin)
-  if ((range <= 0.0)) {
-    return 0.0
+    return tMax
   }
-  return _clamp(((score - domainMin) / range), 0.0, 1.0)
+  return ((t - tMin) / tRange)
+}
+
+export function normalizeScore(score: number, domainMin: number, domainMax: number, scaleType: number, symlogConstant: number): number {
+  return _clamp(normalizeScoreUnclamped(score, domainMin, domainMax, scaleType, symlogConstant), 0.0, 1.0)
 }

package/src/shaders/scoreScale.slang

@@ -1,68 +1,62 @@
-// The score → [0,1] normalizer every score-scaled track is placed by, and the
-// scale-type vocabulary its branches switch on.
+// The score → [0,1] normalizer every score-scaled mark is placed and coloured
+// by — wiggle, the coverage band, the bar and point shapes, their ramps — and
+// the scale-type vocabulary its branches switch on. `makeScoreNormalizer`
+// (render-core's scoreScale.ts) is its loop-hoisted twin.
 //
-// Two real consumers with non-obvious math, which is ADR-040's bar: the wiggle
-// renderer's four modes (`wiggleCommon.slang`, via `scoreToY`) and the coverage
-// band's depth axis (`coverageBand.slang`, via `normalizeDepthScalar`). They
-// carried a branch-for-branch copy each, and the copies did not agree: the
-// coverage one compared `scaleType` against bare 2 and 1 rather than the
-// constants below, and answered 0 on a degenerate domain where wiggle's divided
-// by a 1e-6 floor and saturated. This module is one answer to both.
-//
-// The degenerate domain answers 0, which is what the JS twin
-// (`makeScoreNormalizer`, packages/wiggle-core/src/normalize.ts) has always
-// answered. Returning 0 avoids the NaN the 1e-6 floor was there for just as
-// well, so the divergence bought nothing and cost a documented exception.
-//
-// `SCALE_TYPE_LINEAR` is deliberately absent: it is "neither of these", and a
-// third constant would be a value nothing compares against.
-//! js-export: normalizeScore
-//! js-skip: symlogTransform — the JS twin (wiggle-core normalize.ts) spells it Math.log1p, which is accurate near zero where the shader's log(1.0 + x) is not; a generated twin would be a faithful copy of the worse of the two. What both backends must agree on is normalizeScore, which is exported and swept by normalizeScoreParity.test.ts
+// A domain with no range is a step: a score above its min maps to 1 and any
+// other to 0, so a score above a pinned domain sits off the top everywhere.
+//! export-consts: SCALE_TYPE_LOG, SCALE_TYPE_SYMLOG
+//! js-export: normalizeScore, normalizeScoreUnclamped
+//! js-skip: log1pf — JS has Math.log1p, so a twin of this would be the float32 workaround spelled out where the language already answers it
+//! js-skip: symlogTransform — render-core scoreScale.ts reaches Math.log1p directly, one call inside a normalizer it hoists the whole log domain out of, so a per-call twin of this would have no caller. What both backends must agree on is normalizeScore, which is exported and swept by normalizeScoreParity.test.ts
 module scoreScale;
 
-// The values the `scaleType` uniform is compared against. Emitted into
-// @jbrowse/wiggle-core through `wiggleCommon.slang`'s `export-consts` — the
-// constant evaluator resolves through imports, and wiggle-core is where
-// `WiggleScaleType` is declared, so the numbers stay next to the type they
-// name rather than next to the module that happens to author them.
+// `ScaleTypeCode` in scoreScale.ts is these two and 0, for linear.
 public static const int SCALE_TYPE_LOG = 1;
 public static const int SCALE_TYPE_SYMLOG = 2;
 
+// log(1 + x) for x that `1.0 + x` rounds away: a symlog domain narrower than
+// its constant lands entirely in that region, and in float32 the rounding
+// survives the normalize's divide by a tiny domain range — 0.2px of a 40px row
+// on domain [-1, 0.75] with constant 100.5, against the Canvas2D twin's
+// Math.log1p. Kahan's identity: `u - 1.0` is exact where `u` is near 1, so the
+// ratio is the correction the sum lost.
+float log1pf(float x) {
+  float u = 1.0 + x;
+  return u == 1.0 ? x : log(u) * (x / (u - 1.0));
+}
+
 public float symlogTransform(float x, float c) {
-  return sign(x) * log(1.0 + abs(x / c));
+  return sign(x) * log1pf(abs(x / c));
 }
 
-public float normalizeScore(float score, float domainMin, float domainMax, int scaleType, float symlogConstant) {
+// The fraction a score sits at, extrapolated past either end rather than
+// clamped, so a value outside the domain keeps its order against every other
+// one. A threshold cut is placed through this: a cut the domain excludes then
+// lands off the plot, instead of tying with the scores clamped to the edge it
+// would sit on and reading as crossed.
+public float normalizeScoreUnclamped(float score, float domainMin, float domainMax, int scaleType, float symlogConstant) {
+  float t = score;
+  float tMin = domainMin;
+  float tMax = domainMax;
   if (scaleType == SCALE_TYPE_SYMLOG) {
-    // Defined at and either side of zero, so unlike the log branch there is
-    // nothing to floor: the domain arrives as-is and 0 lands where it belongs
-    // instead of on the baseline with everything else below the floor. On a
-    // coverage band that is the whole reason symlog is offered — a depth of 0
-    // is real, common, and what log cannot separate from a depth of 1.
-    float tMin = symlogTransform(domainMin, symlogConstant);
-    float tMax = symlogTransform(domainMax, symlogConstant);
-    float tRange = tMax - tMin;
-    if (tRange <= 0.0) { return 0.0; }
-    float t = symlogTransform(score, symlogConstant);
-    return clamp((t - tMin) / tRange, 0.0, 1.0);
-  }
-  if (scaleType == SCALE_TYPE_LOG) {
-    // Floor at the domain's own min, not at 1, so a domain sitting entirely
-    // below 1 (mappability, a methylation fraction, any normalized ratio) still
-    // has a range to spread over instead of collapsing to a flat baseline. Same
-    // rule and same reasoning as JS `makeScoreNormalizer`, which keeps its own
-    // hand-written copy because it hoists this arithmetic out of a per-feature
-    // loop — so this one is `//! js-export`ed as the ORACLE the two are swept
-    // against (`normalizeScoreParity.test.ts`), not to retire it.
+    t = symlogTransform(score, symlogConstant);
+    tMin = symlogTransform(domainMin, symlogConstant);
+    tMax = symlogTransform(domainMax, symlogConstant);
+  } else if (scaleType == SCALE_TYPE_LOG) {
+    // The domain's own min, so a domain entirely below 1 still spreads.
     float floorV = domainMin > 0.0 ? domainMin : 1.0;
-    float logMin = log2(floorV);
-    float logMax = log2(max(domainMax, floorV));
-    float logRange = logMax - logMin;
-    if (logRange <= 0.0) { return 0.0; }
-    float logScore = log2(max(score, floorV));
-    return clamp((logScore - logMin) / logRange, 0.0, 1.0);
+    t = log2(max(score, floorV));
+    tMin = log2(floorV);
+    tMax = log2(max(domainMax, floorV));
+  }
+  float tRange = tMax - tMin;
+  if (tRange <= 0.0) {
+    return t > tMin ? 1.0 : 0.0;
   }
-  float range = domainMax - domainMin;
-  if (range <= 0.0) { return 0.0; }
-  return clamp((score - domainMin) / range, 0.0, 1.0);
+  return (t - tMin) / tRange;
+}
+
+public float normalizeScore(float score, float domainMin, float domainMax, int scaleType, float symlogConstant) {
+  return clamp(normalizeScoreUnclamped(score, domainMin, domainMax, scaleType, symlogConstant), 0.0, 1.0);
 }