@jbrowse/render-core 4.3.0

package/src/shaders/rowRect.slang

@@ -0,0 +1,160 @@
+// 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.
+//
+// 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.
+//
+// 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
+//! 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 struct RowRectUniforms {
+  public float3 bpRangeX;      // [bpStartHi, bpStartLo, ±clippedLengthBp]
+  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.
+  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).
+  public float  minCellPx;
+  public float  zero;          // always 0.0 — prevents hp-split collapse
+  public float  rowHeight;     // CSS px per row
+  public float  rowProportion; // rect height = rowHeight * rowProportion
+  // Rows-area scroll offset in CSS px. The canvas is the viewport, not the
+  // content: a caller whose rows overflow it paints row i at
+  // `rowHeight*i - scrollTop` and lets the off-screen rows clip. Callers that
+  // size their canvas to the content (the multi-row painter) write 0.
+  public float  scrollTop;
+};
+
+public struct RowRectVsOut {
+  public float4 position : SV_Position;
+  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).
+//
+// 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;
+
+// What the multi-row painter ("chromosome painting") writes into `minCellPx`.
+//
+// Wider than a pixel because this display has no second channel to fall back
+// on. MAF's cells tile the row, so a sub-pixel cell sits in a run of its
+// neighbours and the run is what is read; a painting's features are sparse
+// intervals, and at chromosome zoom a RepeatMasker element is a single tick
+// against white paper with nothing beside it. At one pixel — anti-aliased
+// 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.
+static const float MULTI_ROW_MIN_CELL_PX = 2.0;
+
+public struct RowBand {
+  public float height;  // what the rect is painted at
+  public float offset;  // inset from the row's top, negative once floored
+};
+
+// The band a row's rects occupy, as two scalars so `//! js-export` can lift
+// them: rowBand.ts is the Canvas2D painter's, the indel glyphs' and the hover
+// box's definition of the same band, and a row drawn here but hit-tested there
+// has to land in the same place. The struct below is only packaging for the
+// vertex stage.
+//
+// Centered, so a floored band overhangs its row evenly on both sides rather
+// than pushing every row down.
+public float drawnRowHeightPx(float rowHeight, float rowProportion) {
+  return max(rowHeight * rowProportion, MIN_DRAWN_ROW_PX);
+}
+
+public float rowBandOffsetPx(float rowHeight, float rowProportion) {
+  return (rowHeight - drawnRowHeightPx(rowHeight, rowProportion)) * 0.5;
+}
+
+public RowBand rowBandPx(float rowHeight, float rowProportion) {
+  RowBand band;
+  band.height = drawnRowHeightPx(rowHeight, rowProportion);
+  band.offset = rowBandOffsetPx(rowHeight, rowProportion);
+  return band;
+}
+
+// The shape's geometry alone — row band, hp clip-x span, min-width widening —
+// so a consumer whose colour is not a per-instance packed value (wiggle
+// density: a per-instance score through a uniform scale) composes the same
+// rect without routing a resolved colour through the instance buffer.
+// `rowIndex` is float here because the row transform is float arithmetic;
+// each caller converts at its own boundary (`RowRectInstance` stores uint,
+// wiggle's fill record stores float).
+public float4 rowRectClipPos(
+  uint startBp, uint endBp, float rowIndex, uint vid, RowRectUniforms u
+) {
+  float2 local = quadLocal(vid);
+
+  RowBand band = rowBandPx(u.rowHeight, u.rowProportion);
+  float rowY   = band.offset + u.rowHeight * rowIndex - u.scrollTop;
+
+  float sx1 = hpToClipX(hpSplitUint(startBp), u.bpRangeX, u.zero);
+  float sx2 = hpToClipX(hpSplitUint(endBp), u.bpRangeX, u.zero);
+  sx2 = extendToMinWidthX(sx1, sx2, u.minCellPx, u.minCellDenomPx);
+
+  float yPx = lerp(rowY, rowY + band.height, local.y);
+
+  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/scoreScale.js.generated.ts

@@ -0,0 +1,51 @@
+// AUTO-GENERATED by packages/shader-tools/src/shader-codegen from scoreScale.slang.
+// Do not edit. Run `pnpm gen:shaders` to regenerate.
+
+// Scalar twins of scoreScale.slang, transliterated from slangc's WGSL so
+// the Canvas2D and SVG paths run the shader's own math. See adr-051.
+
+function _clamp(x: number, lo: number, hi: number) {
+  return _min(_max(x, lo), hi)
+}
+
+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
+}
+
+function symlogTransform(x: number, c: number): number {
+  return ((((Math.sign(x)) | 0)) * Math.log((1.0 + Math.abs((x / c)))))
+}
+
+export function normalizeScore(score: number, domainMin: number, domainMax: number, scaleType: number, symlogConstant: number): number {
+  if ((scaleType == 2)) {
+    let tMin = symlogTransform(domainMin, symlogConstant)
+    let tRange = (symlogTransform(domainMax, symlogConstant) - tMin)
+    if ((tRange <= 0.0)) {
+      return 0.0
+    }
+    return _clamp(((symlogTransform(score, symlogConstant) - tMin) / tRange), 0.0, 1.0)
+  }
+  if ((scaleType == 1)) {
+    let floorV: number
+    if ((domainMin > 0.0)) {
+      floorV = domainMin
+    } else {
+      floorV = 1.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 _clamp(((score - domainMin) / range), 0.0, 1.0)
+}

package/src/shaders/scoreScale.slang

@@ -0,0 +1,68 @@
+// The score → [0,1] normalizer every score-scaled track is placed by, and the
+// scale-type vocabulary its branches switch on.
+//
+// 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
+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.
+public static const int SCALE_TYPE_LOG = 1;
+public static const int SCALE_TYPE_SYMLOG = 2;
+
+public float symlogTransform(float x, float c) {
+  return sign(x) * log(1.0 + abs(x / c));
+}
+
+public float normalizeScore(float score, float domainMin, float domainMax, int scaleType, float symlogConstant) {
+  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.
+    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);
+  }
+  float range = domainMax - domainMin;
+  if (range <= 0.0) { return 0.0; }
+  return clamp((score - domainMin) / range, 0.0, 1.0);
+}