@navaramap/three 0.0.4 → 0.0.5

package/src/mesh/sdfText/labelData.ts

@@ -0,0 +1,187 @@
+import {
+  ClampToEdgeWrapping,
+  DataTexture,
+  FloatType,
+  NearestFilter,
+  RGBAFormat,
+  Vector2,
+} from "three";
+
+import {
+  LABEL_ROWS,
+  LabelRow,
+} from "../../material/enhancer/sdfText/sdfTextBaseEnhancer/types";
+
+export { LABEL_ROWS, LabelRow };
+
+/**
+ * Texels per texture row. Fixed so a capacity grow never changes an existing
+ * label's address — only the height grows, and previously written data stays
+ * valid after the copy.
+ */
+const TEXTURE_WIDTH = 64;
+
+/** Labels a freshly-created store is sized for, before row padding. */
+const INITIAL_CAPACITY = 16;
+
+/** Floats needed to hold `capacity` labels, padded out to whole texture rows. */
+function floatsFor(capacity: number): number {
+  const rows = Math.ceil((capacity * LABEL_ROWS) / TEXTURE_WIDTH);
+  return rows * TEXTURE_WIDTH * 4;
+}
+
+/**
+ * Labels an allocation can actually address — the row padding {@link floatsFor}
+ * adds is usable space, not slack. Deriving capacity from the buffer instead of
+ * from the requested count is what stops `ensureCapacity` from growing while
+ * there are still free slots inside the current allocation.
+ */
+function labelsIn(floats: number): number {
+  return Math.max(1, Math.floor(floats / 4 / LABEL_ROWS));
+}
+
+/**
+ * Per-label state for a batched text mesh, stored in a float texture that the
+ * vertex shader reads with `texelFetch`.
+ *
+ * A batched mesh's instances are *glyphs*, not labels, so anything that varies
+ * per label can't be an instance attribute without replicating it onto every
+ * glyph. Indirecting through this texture (via the `labelIndex` attribute)
+ * keeps a per-label change — colour, size, the declutter fade running every
+ * frame — at a handful of float writes regardless of how many glyphs the label
+ * has, and leaves label state untouched when a text change relocates the
+ * label's glyph run.
+ *
+ * Addressing mirrors `fogLight.frag.glsl`: a linear texel index split over a
+ * fixed-width texture, sampled unfiltered. The row layout itself
+ * ({@link LabelRow} / {@link LABEL_ROWS}) is the shader contract and lives with
+ * the enhancer that owns the shader; `LABEL_ROWS` is injected there as a GLSL
+ * define so the two addressing schemes can't drift.
+ */
+export class LabelDataTexture {
+  private _capacity = 0;
+  private _data: Float32Array;
+  private _texture: DataTexture;
+  private readonly _size = new Vector2();
+
+  constructor(initialCapacity = INITIAL_CAPACITY) {
+    this._data = new Float32Array(floatsFor(Math.max(1, initialCapacity)));
+    this._capacity = labelsIn(this._data.length);
+    this._texture = this._createTexture();
+  }
+
+  /** The texture to bind to `uLabelData`. Replaced by {@link ensureCapacity}. */
+  get texture(): DataTexture {
+    return this._texture;
+  }
+
+  /** Dimensions in texels, for the `uLabelTexSize` uniform. */
+  get size(): Vector2 {
+    return this._size;
+  }
+
+  /**
+   * Labels addressable without a grow. Derived from the allocation, so it
+   * includes the row padding and is generally larger than the count the store
+   * was constructed or grown for.
+   */
+  get capacity(): number {
+    return this._capacity;
+  }
+
+  /**
+   * Make room for `slotCount` labels.
+   *
+   * Returns `true` when the backing `DataTexture` was replaced, in which case
+   * the caller must re-point the `uLabelData` uniform and refresh
+   * `uLabelTexSize`. Existing label data survives unchanged.
+   */
+  ensureCapacity(slotCount: number): boolean {
+    if (slotCount <= this._capacity) return false;
+
+    let target = this._capacity;
+    while (target < slotCount) target *= 2;
+
+    const data = new Float32Array(floatsFor(target));
+    data.set(this._data);
+
+    this._data = data;
+    this._capacity = labelsIn(data.length);
+    this._texture.dispose();
+    this._texture = this._createTexture();
+    return true;
+  }
+
+  /** Write a whole texel. */
+  setRow(
+    slot: number,
+    row: number,
+    x: number,
+    y: number,
+    z: number,
+    w: number,
+  ): void {
+    const i = (slot * LABEL_ROWS + row) * 4;
+    const data = this._data;
+    data[i] = x;
+    data[i + 1] = y;
+    data[i + 2] = z;
+    data[i + 3] = w;
+    this._texture.needsUpdate = true;
+  }
+
+  /** Write one channel of a texel, leaving the other three alone. */
+  setComponent(
+    slot: number,
+    row: number,
+    component: number,
+    value: number,
+  ): void {
+    this._data[(slot * LABEL_ROWS + row) * 4 + component] = value;
+    this._texture.needsUpdate = true;
+  }
+
+  /** Read one channel back — used by the declutter fade's read/modify/write. */
+  getComponent(slot: number, row: number, component: number): number {
+    return this._data[(slot * LABEL_ROWS + row) * 4 + component];
+  }
+
+  /** Zero a label's rows so a recycled slot can't inherit stale state. */
+  clearSlot(slot: number): void {
+    const start = slot * LABEL_ROWS * 4;
+    this._data.fill(0, start, start + LABEL_ROWS * 4);
+    this._texture.needsUpdate = true;
+  }
+
+  /** Mark the texture for re-upload without writing anything. */
+  markDirty(): void {
+    this._texture.needsUpdate = true;
+  }
+
+  dispose(): void {
+    this._texture.dispose();
+  }
+
+  private _createTexture(): DataTexture {
+    // Derived from the buffer rather than recomputed from `_capacity`: the
+    // texture must describe exactly the memory it is backed by.
+    const height = this._data.length / (TEXTURE_WIDTH * 4);
+    const tex = new DataTexture(
+      this._data,
+      TEXTURE_WIDTH,
+      height,
+      RGBAFormat,
+      FloatType,
+    );
+    // texelFetch is unfiltered by definition, but the sampler state still has
+    // to be complete for the texture to be bindable.
+    tex.magFilter = NearestFilter;
+    tex.minFilter = NearestFilter;
+    tex.wrapS = ClampToEdgeWrapping;
+    tex.wrapT = ClampToEdgeWrapping;
+    tex.generateMipmaps = false;
+    tex.needsUpdate = true;
+    this._size.set(TEXTURE_WIDTH, height);
+    return tex;
+  }
+}

package/src/mesh/{sdfText.test.ts → sdfText/layout.test.ts}

@@ -1,7 +1,7 @@
 import { GlyphCharClass, type ShapedGlyph } from "@navaramap/font";
 import { describe, expect, it } from "vitest";
 
-import { breakLines, isRtlText, lineWidthFu } from "./sdfText";
+import { breakLines, isRtlText, lineWidthFu } from "./layout";
 
 /** Build a glyph run from a compact spec: one entry per glyph. */
 function glyphs(

package/src/mesh/sdfText/layout.ts

@@ -0,0 +1,306 @@
+import {
+  COLOR_GLYPH_PX_SIZE,
+  GlyphCharClass,
+  type GlyphMetrics,
+  type ShapedGlyph,
+  type ShapeTextResult,
+} from "@navaramap/font";
+
+/**
+ * Pure text-layout helpers: line breaking, paragraph direction, and turning a
+ * shaping result into positioned glyph quads in em space.
+ *
+ * Nothing here touches three.js or WASM, which is what makes the layout rules
+ * — the part with all the edge cases — unit-testable without a GL context.
+ */
+
+/** Must match Rust `SDF_PX_SIZE` in `crates/navara_wasm_font_worker/src/atlas.rs`. */
+export const SDF_PX_SIZE = 64.0;
+
+/** Horizontal alignment of lines within a multi-line block, as the fraction
+ *  of leftover width placed before each line. */
+export const ALIGN_FACTORS: Record<string, number> = {
+  left: 0,
+  center: 0.5,
+  right: 1,
+};
+
+/** Line width in font units: advances summed, trailing whitespace ignored so
+ *  it never affects alignment or the block width. */
+export function lineWidthFu(line: ShapedGlyph[]): number {
+  let end = line.length;
+  while (end > 0 && line[end - 1].charClass === GlyphCharClass.Whitespace) {
+    end--;
+  }
+  let width = 0;
+  for (let i = 0; i < end; i++) width += line[i].xAdvance;
+  return width;
+}
+
+/** Strong RTL code points (Hebrew through Arabic Extended, presentation
+ *  forms, and the supplementary-plane RTL blocks). Used for first-strong
+ *  paragraph direction detection, mirroring the shaper's own direction guess.
+ */
+const STRONG_RTL_RE =
+  /[\u0591-\u08FF\uFB1D-\uFDFD\uFE70-\uFEFC\u{10800}-\u{10FFF}\u{1E800}-\u{1EFFF}]/u;
+
+/** Paragraph direction from the first strong directional character (UAX #9
+ *  P2/P3 approximation): the first letter decides, RTL ranges win over other
+ *  letters. */
+export function isRtlText(text: string): boolean {
+  for (const ch of text) {
+    if (STRONG_RTL_RE.test(ch)) return true;
+    if (/\p{L}/u.test(ch)) return false;
+  }
+  return false;
+}
+
+/**
+ * Split a shaped glyph run into lines: hard breaks at newline markers, greedy
+ * soft breaks at the last whitespace/ideographic glyph when a line would
+ * exceed `maxWidthFu` (font units; 0 disables wrapping). A word longer than
+ * the wrap width overflows rather than breaking mid-word.
+ *
+ * When `rtl` is set, glyphs are assumed to arrive in visual order (leftmost
+ * first — how the shaper emits RTL runs), i.e. reversed logical order. Each
+ * hard-break segment is wrapped in logical order so the greedy fill starts at
+ * the sentence start and lines stack top-to-bottom in reading order, then
+ * every line is flipped back to visual order for rendering. Mixed-direction
+ * lines may still break sub-optimally — same trade other map renderers make.
+ */
+export function breakLines(
+  glyphs: ShapedGlyph[],
+  maxWidthFu: number,
+  rtl = false,
+): ShapedGlyph[][] {
+  const lines: ShapedGlyph[][] = [];
+
+  const pushSegment = (segment: ShapedGlyph[]) => {
+    if (!rtl) {
+      lines.push(...wrapSegment(segment, maxWidthFu));
+      return;
+    }
+    segment.reverse();
+    for (const line of wrapSegment(segment, maxWidthFu)) {
+      lines.push(line.reverse());
+    }
+  };
+
+  let segment: ShapedGlyph[] = [];
+  for (const g of glyphs) {
+    if (g.charClass === GlyphCharClass.Newline) {
+      pushSegment(segment);
+      segment = [];
+    } else {
+      segment.push(g);
+    }
+  }
+  pushSegment(segment);
+  return lines;
+}
+
+/** Greedy soft-wrap of a single hard-break-free segment in logical order. */
+function wrapSegment(
+  glyphs: ShapedGlyph[],
+  maxWidthFu: number,
+): ShapedGlyph[][] {
+  const lines: ShapedGlyph[][] = [];
+  let line: ShapedGlyph[] = [];
+  let width = 0;
+  let breakIdx = -1; // index in `line` of the last break opportunity
+
+  for (const g of glyphs) {
+    // Trailing whitespace is invisible at a line end, so it never triggers a
+    // wrap itself — it just gets trimmed if a later glyph wraps.
+    if (
+      maxWidthFu > 0 &&
+      g.charClass !== GlyphCharClass.Whitespace &&
+      line.length > 0 &&
+      breakIdx >= 0 &&
+      width + g.xAdvance > maxWidthFu
+    ) {
+      const head = line.slice(0, breakIdx + 1);
+      while (
+        head.length > 0 &&
+        head[head.length - 1].charClass === GlyphCharClass.Whitespace
+      ) {
+        head.pop();
+      }
+      lines.push(head);
+
+      const tail = line.slice(breakIdx + 1);
+      const start = tail.findIndex(
+        (gg) => gg.charClass !== GlyphCharClass.Whitespace,
+      );
+      line = start === -1 ? [] : tail.slice(start);
+
+      width = 0;
+      for (const rest of line) width += rest.xAdvance;
+      breakIdx = -1;
+    }
+
+    line.push(g);
+    width += g.xAdvance;
+    if (
+      g.charClass === GlyphCharClass.Whitespace ||
+      g.charClass === GlyphCharClass.Ideographic
+    ) {
+      breakIdx = line.length - 1;
+    }
+  }
+
+  lines.push(line);
+  return lines;
+}
+
+/** One positioned glyph quad in em space, ready to become an instance. */
+export type GlyphQuad = {
+  offsetEmX: number;
+  offsetEmY: number;
+  sizeEmX: number;
+  sizeEmY: number;
+  /** Atlas sub-rect in PIXEL space; the shader divides by the live atlas size
+   *  uniform so an atlas resize doesn't invalidate the instance data. */
+  uvL: number;
+  uvT: number;
+  uvR: number;
+  uvB: number;
+  /** Sample the COLRv1 colour atlas rather than the SDF atlas. */
+  isColor: boolean;
+};
+
+/** A laid-out label: its glyph quads plus the block metrics the shader and the
+ *  declutter pass need. All measurements are in ems. */
+export type LabelLayout = {
+  quads: GlyphQuad[];
+  /** Unique atlas glyphs referenced, for retain/release against the atlas. */
+  glyphKeys: bigint[];
+  widthEm: number;
+  heightEm: number;
+  /** Y bounds of the actual rendered glyph bboxes, for the background quad. */
+  minYEm: number;
+  maxYEm: number;
+};
+
+export type LayoutOptions = {
+  /** The source string — only used to detect paragraph direction. */
+  text: string;
+  /** Wrap width in ems (multiples of font size); 0 disables soft wrapping. */
+  maxWidth: number;
+  /** Multiplier on the font's natural line height. */
+  lineHeight: number;
+  /** 0 left, 0.5 center, 1 right. */
+  textAlign: number;
+};
+
+const EMPTY_LAYOUT: LabelLayout = {
+  quads: [],
+  glyphKeys: [],
+  widthEm: 0,
+  heightEm: 0,
+  minYEm: 0,
+  maxYEm: 1,
+};
+
+/**
+ * Turn a shaping result into positioned glyph quads.
+ *
+ * Lines lay out top-down: line 0 keeps its baseline at y=0, later baselines
+ * step down by the line height, and alignment shifts each line within the
+ * widest line's width. Each glyph carries its own normalization scale so SDF
+ * and colour glyphs share one em-space coordinate system downstream — the two
+ * paths rasterize at different sizes (`SDF_PX_SIZE` vs `COLOR_GLYPH_PX_SIZE`)
+ * but both end up in ems after dividing by their respective pixel size.
+ */
+export function buildLabelLayout(
+  shapeResult: ShapeTextResult,
+  options: LayoutOptions,
+): LabelLayout {
+  const { glyphs, metrics, unitsPerEm, ascender, descender, lineGap } =
+    shapeResult;
+
+  // Keys are pre-computed by the WASM font worker (composite_key in Rust) so
+  // the key layout stays in sync between Rust and TypeScript.
+  const metricsMap = new Map<bigint, GlyphMetrics>();
+  for (const m of metrics) metricsMap.set(m.compositeKey, m);
+
+  const fontUnitToSdfPx = SDF_PX_SIZE / unitsPerEm;
+  const fontUnitToColorPx = COLOR_GLYPH_PX_SIZE / unitsPerEm;
+
+  // Baseline-to-baseline distance in font units. Older cached results may
+  // predate line metrics; fall back to one em.
+  const naturalLineHeight = ascender - descender + lineGap;
+  const lineHeightFu =
+    (naturalLineHeight > 0 ? naturalLineHeight : unitsPerEm) *
+    options.lineHeight;
+
+  // `maxWidth` is in ems so the wrap width tracks the font size in both
+  // sizeInMeters modes; font units are ems × unitsPerEm.
+  const lines = breakLines(
+    glyphs,
+    options.maxWidth * unitsPerEm,
+    isRtlText(options.text),
+  );
+  const widths = lines.map(lineWidthFu);
+  const blockWidthFu = Math.max(...widths);
+
+  const quads: GlyphQuad[] = [];
+  const glyphKeys = new Set<bigint>();
+  let minYEm = Infinity;
+  let maxYEm = -Infinity;
+
+  for (let li = 0; li < lines.length; li++) {
+    let cursorX = (blockWidthFu - widths[li]) * options.textAlign;
+    let cursorY = -li * lineHeightFu;
+
+    for (const glyph of lines[li]) {
+      const m = metricsMap.get(glyph.compositeKey);
+      if (m && m.atlasW > 0 && m.atlasH > 0) {
+        glyphKeys.add(glyph.compositeKey);
+        const px = m.isColor ? COLOR_GLYPH_PX_SIZE : SDF_PX_SIZE;
+        const fuToPx = m.isColor ? fontUnitToColorPx : fontUnitToSdfPx;
+        const offsetEmX =
+          ((cursorX + glyph.xOffset) * fuToPx + m.bearingX) / px;
+        const offsetEmY =
+          ((cursorY + glyph.yOffset) * fuToPx + m.bearingY) / px;
+        const sizeEmY = m.atlasH / px;
+
+        minYEm = Math.min(minYEm, offsetEmY);
+        maxYEm = Math.max(maxYEm, offsetEmY + sizeEmY);
+
+        quads.push({
+          offsetEmX,
+          offsetEmY,
+          sizeEmX: m.atlasW / px,
+          sizeEmY,
+          uvL: m.atlasX,
+          uvT: m.atlasY,
+          uvR: m.atlasX + m.atlasW,
+          uvB: m.atlasY + m.atlasH,
+          isColor: m.isColor,
+        });
+      }
+      cursorX += glyph.xAdvance;
+      cursorY += glyph.yAdvance;
+    }
+  }
+
+  if (quads.length === 0) {
+    // Glyphs may have shaped but all been blank (whitespace only) — the label
+    // still has no collision box and nothing to draw.
+    return { ...EMPTY_LAYOUT, glyphKeys: [...glyphKeys] };
+  }
+
+  // The block is as wide as its widest line and grows downward by one line
+  // height per extra line (a single line stays exactly one em tall).
+  return {
+    quads,
+    glyphKeys: [...glyphKeys],
+    widthEm: (blockWidthFu * fontUnitToSdfPx) / SDF_PX_SIZE,
+    heightEm:
+      (SDF_PX_SIZE + (lines.length - 1) * lineHeightFu * fontUnitToSdfPx) /
+      SDF_PX_SIZE,
+    minYEm,
+    maxYEm,
+  };
+}

package/src/mesh/sprite/instancedSprite.ts

@@ -26,14 +26,21 @@ import {
 import type { EventContext } from "../../event/context";
 import { createInstancedSpriteMaterialEnhancer } from "../../material/enhancer";
 import type { CustomObject3DEventMap } from "../../object3DEvent";
+import { GEOMETRY_TYPES, type GeometryType } from "../constants";
 import { PickableMesh } from "../pickableMesh";
 
 import { BillboardAtlas, type AtlasRect } from "./billboardAtlas";
 import { loadAtlasImageFromUrl } from "./billboardAtlasImageLoader";
 
+type SpriteGeometryType = Extract<
+  GeometryType,
+  typeof GEOMETRY_TYPES.Point | typeof GEOMETRY_TYPES.Billboard
+>;
+
 export type InstancedSpriteOptions = {
   renderOrder?: number;
   ctx: EventContext;
+  geometryType: SpriteGeometryType;
 };
 
 type PositionsInfo = {
@@ -58,6 +65,7 @@ export class InstancedSpriteMesh
   extends Mesh<BufferGeometry, Material | Material[], CustomObject3DEventMap>
   implements PickableMesh, DeclutterParticipant
 {
+  private _geometryType: SpriteGeometryType = GEOMETRY_TYPES.Point;
   private _batchIdToInstance = new Map<number, number>();
   private _initialColor: Color = new Color(0xffffff);
   private _initialHeight = 0.0;
@@ -103,6 +111,7 @@ export class InstancedSpriteMesh
     super();
     this.renderOrder = options.renderOrder ?? this.renderOrder;
     this.ctx = options.ctx;
+    this._geometryType = options.geometryType;
     this.ctx.declutter?.register(this);
     // `processObjectRemoved` dispatches this for every removed mesh; it is the
     // reliable teardown signal (this class's dispose() is not called there).
@@ -117,6 +126,29 @@ export class InstancedSpriteMesh
     this.ctx.declutter?.markDirty();
   }
 
+  /**
+   * Set the geometry type for this mesh.
+   *
+   * This affects how FeatureEvaluator provides meshGeomType to evaluators,
+   * which is used by MapLibreStylePlugin to determine which properties to apply
+   * (e.g., billboard vs text rendering for symbol layers).
+   *
+   * Changing this after initialization is supported and will affect subsequent
+   * feature evaluations, but does NOT automatically trigger re-evaluation.
+   * Call layer.forceUpdate() if you need to re-evaluate existing features.
+   */
+  setGeometryType(type: SpriteGeometryType): void {
+    this._geometryType = type;
+  }
+
+  /**
+   * Get the geometry type of this mesh.
+   * Defaults to GEOMETRY_TYPES.Point if not explicitly set.
+   */
+  get geometryType(): SpriteGeometryType {
+    return this._geometryType;
+  }
+
   // --- DeclutterParticipant ---
 
   collectDeclutterCandidates(out: DeclutterCandidate[]): void {