@driftengine/core 4.1.2 → 4.1.4

package/src/render/textLayout.ts

@@ -70,6 +70,94 @@ export function textHeightPx(cellSize: number): number {
   return GLYPH_HEIGHT * cellSize;
 }
 
+/**
+ * The cell size to draw at, so every cell of a bitmap glyph covers whole device pixels.
+ *
+ * **A 5x7 face draws every stroke exactly one cell wide, so a fractional cell is not a slightly
+ * softer glyph — it is a glyph whose strokes are different widths.** The rasteriser gives one
+ * column of cells four pixels and the next three, and a face carrying its legibility entirely in
+ * uniform strokes comes apart. Reported three times as text "eaten away" in a checkerboard while
+ * larger text in the same frame stayed solid, which is the size dependence this explains: a whole
+ * cell is uniform and a fractional one is not, and nothing about it is a dropped pixel.
+ *
+ * Two doors reach a fractional cell, which is why it was reported as unrelated faults. A caller
+ * asks for one outright, sizing a second line at a fraction of its headline; or asks for a whole
+ * one that the device ratio makes fractional, a 3-pixel cell at a 1.25 ratio being 3.75 on the
+ * grid. `viewportWidth` is whatever units the caller lays out in — CSS pixels for an overlay
+ * sized from `cssWidth`, device pixels for one sized from the canvas — and `bufferWidth` is the
+ * drawing buffer, so the ratio between them is exactly what turns one into the other.
+ *
+ * **What it gives up is the asked size.** The cell drawn is the largest whole number of device
+ * pixels that is not larger than the one asked for, so a string is drawn up to one device pixel
+ * per cell narrower than `textWidthPx` measures it. Down rather than to nearest, because a caller
+ * that fitted a line to a box measured it first: rounding up would draw a line wider than the box
+ * it was fitted to, and rounding down can only leave a gap.
+ *
+ * **`textWidthPx` and `RendererApi.textWidth` are deliberately left unsnapped**, and that is the
+ * cost rather than an oversight. Neither is handed a viewport, so neither can know whether the
+ * caller lays out in CSS pixels or device ones — and this ratio is exactly that question. A width
+ * is therefore an upper bound on what is drawn: a centred line sits up to half the shortfall off
+ * centre, at most half a device pixel per cell. Handing the measurement a viewport would fix it
+ * and is a change to the public surface rather than to a patch.
+ *
+ * **What would make it wrong** is a face whose strokes are not cell-aligned — an SDF atlas, where
+ * the glyph is a distance field and a fractional size is exactly what it is built to serve.
+ * `sdfTextLayout.ts` is that path and does not come through here.
+ */
+export function deviceSnappedCellSize(
+  cellSize: number,
+  viewportWidth: number,
+  bufferWidth: number,
+): number {
+  const ratio = bufferWidth / viewportWidth;
+  if (!Number.isFinite(ratio) || ratio <= 0) return cellSize;
+  const device = cellSize * ratio;
+  if (!Number.isFinite(device)) return cellSize;
+  /*
+   * The tolerance is against float error rather than a fudge: a ratio of 1 turns an asked 4 into
+   * 3.9999999999999996 often enough, and flooring that would shrink every whole cell on every
+   * ordinary display by a pixel — the change doing most harm where there was nothing to fix.
+   */
+  const whole = Math.floor(device + 1e-6);
+  /* Below one device pixel there is no whole size to snap to, and flooring would draw nothing. */
+  if (whole < 1) return cellSize;
+  return whole / ratio;
+}
+
+/**
+ * The same grid's **phase**, which is the other half of the same defect.
+ *
+ * **A whole pitch on a fractional origin still draws strokes of two widths.** Snapping the cell to
+ * four device pixels puts the boundaries four apart, and starting them at 10.4 puts every boundary
+ * at `.4` — so each stroke covers three whole pixels and two halves, and the rasteriser resolves
+ * that the same ragged way it resolved a fractional cell. The pitch decides how far apart the
+ * boundaries are; this decides where the first one is, and a face of uniform strokes needs both.
+ *
+ * It was found the way the first half was: the cell snap shipped, and the reporter said the text was
+ * still wrong.
+ *
+ * **To nearest rather than down**, which is the opposite of the cell above and for the opposite
+ * reason: this is a position, not a size. Moving a label up to half a device pixel is the smallest
+ * change that puts its grid on the display's, while flooring would shift every label the same way
+ * and bias a centred one off centre.
+ *
+ * **What would make it wrong** is a caller animating an origin sub-pixel on purpose — a label that
+ * slides smoothly now steps by a device pixel. For a face whose strokes are one pixel wide that is
+ * the trade this whole function exists to make, and `sdfTextLayout.ts`, which does not come through
+ * here, is the path for anything that wants the other answer.
+ */
+export function deviceSnappedOrigin(
+  value: number,
+  viewportWidth: number,
+  bufferWidth: number,
+): number {
+  const ratio = bufferWidth / viewportWidth;
+  if (!Number.isFinite(ratio) || ratio <= 0) return value;
+  const device = value * ratio;
+  if (!Number.isFinite(device)) return value;
+  return Math.round(device) / ratio;
+}
+
 export class TextLayout {
   /** Reused every upload; text changes far too often to allocate per change. */
   readonly cells = new Float32Array(MAX_CELLS * 2);

package/src/render/textRenderer.ts

@@ -1,5 +1,11 @@
 import type { TextStyle } from './textLayout.ts';
-import { MAX_CELLS, TEXT_CUBE, TextLayout } from './textLayout.ts';
+import {
+  MAX_CELLS,
+  TEXT_CUBE,
+  TextLayout,
+  deviceSnappedCellSize,
+  deviceSnappedOrigin,
+} from './textLayout.ts';
 import { compileProgram, uniformLocations } from './shader.ts';
 import { TEXT_FRAG, TEXT_VERT } from './shaders/text.ts';
 
@@ -115,8 +121,21 @@ export class TextRenderer {
     gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
 
     setVec2(gl, this.uniforms['uViewport'], viewportWidth, viewportHeight);
-    setVec2(gl, this.uniforms['uOrigin'], originX, originY);
-    setFloat(gl, this.uniforms['uCellSize'], style.cellSize);
+    /* Snapped with the cell below: a whole pitch on a fractional origin still splits a stroke.
+       See `deviceSnappedOrigin`. */
+    setVec2(
+      gl,
+      this.uniforms['uOrigin'],
+      deviceSnappedOrigin(originX, viewportWidth, gl.drawingBufferWidth),
+      deviceSnappedOrigin(originY, viewportHeight, gl.drawingBufferHeight),
+    );
+    /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
+       decision is shared with WebGPU; only this binding is per-backend. See `textLayout.ts`. */
+    setFloat(
+      gl,
+      this.uniforms['uCellSize'],
+      deviceSnappedCellSize(style.cellSize, viewportWidth, gl.drawingBufferWidth),
+    );
     // Far enough that a whole line barely converges, near enough that a rotating character
     // reads as turning rather than shearing.
     setFloat(gl, this.uniforms['uDepth'], Math.max(viewportWidth, 600) * 1.4);