@navaramap/three 0.0.3 → 0.0.5

package/src/mesh/sdfText/glyphBuffers.ts

@@ -0,0 +1,222 @@
+import {
+  BufferAttribute,
+  InstancedBufferAttribute,
+  InstancedBufferGeometry,
+} from "three";
+
+import type { GlyphQuad } from "./layout";
+
+/**
+ * The glyph-instance geometry of a batched text mesh: a shared unit quad plus
+ * one instance per glyph, drawn in a single call for every label in the batch.
+ *
+ * Instances are grouped into contiguous per-label runs handed out by
+ * `GlyphSlotAllocator`, so writing a label pushes only that run to the GPU via
+ * `addUpdateRange`. Growth doubles the buffers, which is the only path that
+ * re-uploads everything.
+ */
+
+/** Per-instance `glyphKind` values. Must match the `GLYPH_KIND_*` defines in
+ *  `shaders/glsl/sdfText.vert.glsl`. */
+export const GlyphKind = {
+  SDF: 0,
+  COLOR: 1,
+  BACKGROUND: 2,
+  /** A slot inside a label's run that its text doesn't use, or a hole left by
+   *  a freed run. Culled in the vertex shader. */
+  EMPTY: 3,
+} as const;
+
+/** Instance slots a freshly-created batch reserves. */
+const INITIAL_CAPACITY = 64;
+
+/** Attribute name and component count, in the order they are (re)created. */
+const INSTANCE_ATTRIBUTES = [
+  ["glyphOffset", 2],
+  ["glyphSize", 2],
+  ["glyphUvRect", 4],
+  ["glyphKind", 1],
+  ["labelIndex", 1],
+] as const;
+
+/** The backing arrays, one per instance attribute. */
+type InstanceArrays = {
+  glyphOffset: Float32Array;
+  glyphSize: Float32Array;
+  glyphUvRect: Float32Array;
+  glyphKind: Float32Array;
+  labelIndex: Float32Array;
+};
+
+export class GlyphBuffers {
+  readonly geometry: InstancedBufferGeometry;
+  private _capacity: number;
+  private _arrays: InstanceArrays;
+  /** The live instance attributes, paired with their component count.
+   *  Held directly so partial uploads don't go through `getAttribute`, whose
+   *  union return type doesn't expose `addUpdateRange`. */
+  private _attributes: [InstancedBufferAttribute, number][] = [];
+
+  constructor(initialCapacity = INITIAL_CAPACITY) {
+    this._capacity = Math.max(1, initialCapacity);
+    this.geometry = new InstancedBufferGeometry();
+
+    // Unit quad: 2 triangles, 6 vertices.
+    // prettier-ignore
+    const positions = new Float32Array([
+      -0.5, -0.5, 0, 0.5, -0.5, 0, 0.5, 0.5, 0,
+      -0.5, -0.5, 0, 0.5, 0.5, 0, -0.5, 0.5, 0,
+    ]);
+    // prettier-ignore
+    const uvs = new Float32Array([
+      0, 0, 1, 0, 1, 1,
+      0, 0, 1, 1, 0, 1,
+    ]);
+    this.geometry.setAttribute("position", new BufferAttribute(positions, 3));
+    this.geometry.setAttribute("uv", new BufferAttribute(uvs, 2));
+
+    this._arrays = this._allocate(this._capacity);
+    this.geometry.instanceCount = 0;
+  }
+
+  get capacity(): number {
+    return this._capacity;
+  }
+
+  /** Instances the draw call covers — the allocator's high-water mark. */
+  setInstanceCount(count: number): void {
+    this.geometry.instanceCount = count;
+  }
+
+  /**
+   * Grow to hold at least `slotCount` instances, preserving existing data.
+   * No-op when it already fits.
+   */
+  ensureCapacity(slotCount: number): void {
+    if (slotCount <= this._capacity) return;
+    let capacity = this._capacity;
+    while (capacity < slotCount) capacity *= 2;
+
+    const previousCapacity = this._capacity;
+    this._capacity = capacity;
+    this._arrays = this._allocate(capacity, this._arrays, previousCapacity);
+
+    // three caches the instance ceiling on the first VAO bind and only clears
+    // it when the geometry is disposed, then clamps every draw with
+    // `min(geometry.instanceCount, geometry._maxInstanceCount)`. Replacing the
+    // instance attributes with larger ones does NOT refresh it, so without this
+    // the batch stays pinned to whatever capacity it had when it was first
+    // rendered — labels added later silently never draw. Dropping the cached
+    // value makes three recompute it from the new attributes on the next bind.
+    delete (
+      this.geometry as InstancedBufferGeometry &
+        Partial<Record<"_maxInstanceCount", number>>
+    )._maxInstanceCount;
+  }
+
+  /**
+   * Write a label's glyph quads into its run and blank the rest of it, then
+   * queue a partial upload of exactly that range.
+   *
+   * `runCapacity` is the slots the label owns; anything past the quads becomes
+   * {@link GlyphKind.EMPTY}, so an over-allocated run — or a label whose text
+   * just got shorter — draws nothing in the leftover slots.
+   */
+  writeRun(
+    start: number,
+    runCapacity: number,
+    labelIndex: number,
+    quads: GlyphQuad[],
+    withBackground: boolean,
+  ): void {
+    const {
+      glyphOffset,
+      glyphSize,
+      glyphUvRect,
+      glyphKind,
+      labelIndex: label,
+    } = this._arrays;
+
+    // The background occupies the run's first slot so it is drawn before the
+    // label's glyphs — the fragment shader's outline-seam fix depends on that
+    // ordering (see sdfText.frag.glsl).
+    let slot = start;
+    if (withBackground) {
+      glyphKind[slot] = GlyphKind.BACKGROUND;
+      label[slot] = labelIndex;
+      // The background derives its quad from the label's box, not from these.
+      glyphOffset[slot * 2] = 0;
+      glyphOffset[slot * 2 + 1] = 0;
+      glyphSize[slot * 2] = 0;
+      glyphSize[slot * 2 + 1] = 0;
+      slot++;
+    }
+
+    for (const q of quads) {
+      glyphKind[slot] = q.isColor ? GlyphKind.COLOR : GlyphKind.SDF;
+      label[slot] = labelIndex;
+      glyphOffset[slot * 2] = q.offsetEmX;
+      glyphOffset[slot * 2 + 1] = q.offsetEmY;
+      glyphSize[slot * 2] = q.sizeEmX;
+      glyphSize[slot * 2 + 1] = q.sizeEmY;
+      glyphUvRect[slot * 4] = q.uvL;
+      glyphUvRect[slot * 4 + 1] = q.uvT;
+      glyphUvRect[slot * 4 + 2] = q.uvR;
+      glyphUvRect[slot * 4 + 3] = q.uvB;
+      slot++;
+    }
+
+    for (; slot < start + runCapacity; slot++) {
+      glyphKind[slot] = GlyphKind.EMPTY;
+      label[slot] = labelIndex;
+    }
+
+    this._queueUpload(start, runCapacity);
+  }
+
+  /** Blank a run so its slots draw nothing until reallocated. */
+  clearRun(start: number, runCapacity: number): void {
+    this._arrays.glyphKind.fill(GlyphKind.EMPTY, start, start + runCapacity);
+    this._queueUpload(start, runCapacity);
+  }
+
+  dispose(): void {
+    this.geometry.dispose();
+  }
+
+  /** Queue a `bufferSubData` covering `[start, start + count)` instances on
+   *  every instance attribute. */
+  private _queueUpload(start: number, count: number): void {
+    for (const [attr, itemSize] of this._attributes) {
+      // addUpdateRange takes array-element units, not instance units.
+      attr.addUpdateRange(start * itemSize, count * itemSize);
+      attr.needsUpdate = true;
+    }
+  }
+
+  /**
+   * (Re)create the instance attributes at `capacity`, copying `previous` in.
+   * Slots past the copied region start as EMPTY — a zero-filled array would
+   * otherwise read as `GlyphKind.SDF` and draw garbage quads.
+   */
+  private _allocate(
+    capacity: number,
+    previous?: InstanceArrays,
+    previousCapacity = 0,
+  ): InstanceArrays {
+    const arrays = {} as InstanceArrays;
+    this._attributes = [];
+    for (const [name, itemSize] of INSTANCE_ATTRIBUTES) {
+      const array = new Float32Array(capacity * itemSize);
+      if (previous) array.set(previous[name]);
+      if (name === "glyphKind") {
+        array.fill(GlyphKind.EMPTY, previousCapacity, capacity);
+      }
+      arrays[name] = array;
+      const attr = new InstancedBufferAttribute(array, itemSize);
+      this.geometry.setAttribute(name, attr);
+      this._attributes.push([attr, itemSize]);
+    }
+    return arrays;
+  }
+}

package/src/mesh/sdfText/glyphSlots.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+
+import { GlyphSlotAllocator, capacityFor } from "./glyphSlots";
+
+describe("capacityFor", () => {
+  it("floors at the minimum run size", () => {
+    expect(capacityFor(0)).toBe(4);
+    expect(capacityFor(1)).toBe(4);
+    expect(capacityFor(4)).toBe(4);
+  });
+
+  it("rounds up to the next power of two", () => {
+    expect(capacityFor(5)).toBe(8);
+    expect(capacityFor(8)).toBe(8);
+    expect(capacityFor(9)).toBe(16);
+    expect(capacityFor(1000)).toBe(1024);
+    expect(capacityFor(1024)).toBe(1024);
+    expect(capacityFor(1025)).toBe(2048);
+  });
+});
+
+describe("GlyphSlotAllocator", () => {
+  it("hands out non-overlapping runs and tracks the high-water mark", () => {
+    const a = new GlyphSlotAllocator();
+    expect(a.highWater).toBe(0);
+
+    const first = a.alloc(3); // → capacity 4
+    const second = a.alloc(10); // → capacity 16
+
+    expect(first).toEqual({ start: 0, capacity: 4 });
+    expect(second).toEqual({ start: 4, capacity: 16 });
+    expect(a.highWater).toBe(20);
+  });
+
+  // The core of the design: a label whose text changes length must keep its
+  // slots so the update is an in-place write, not a buffer rebuild.
+  describe("realloc within a size class", () => {
+    it("keeps the same run when the glyph count stays in class", () => {
+      const a = new GlyphSlotAllocator();
+      const run = a.alloc(5); // capacity 8
+      const after = a.realloc(run, 7);
+
+      expect(after).toBe(run);
+      expect(a.highWater).toBe(8);
+    });
+
+    it("keeps the same run when the text gets shorter", () => {
+      const a = new GlyphSlotAllocator();
+      const run = a.alloc(8); // capacity 8
+      const after = a.realloc(run, 6);
+
+      expect(after).toBe(run);
+      expect(a.highWater).toBe(8);
+    });
+
+    it("does not shrink below the minimum class", () => {
+      const a = new GlyphSlotAllocator();
+      const run = a.alloc(4);
+      // "ab" → "a" stays in the floor class, so nothing moves.
+      expect(a.realloc(run, 1)).toBe(run);
+      expect(a.highWater).toBe(4);
+    });
+  });
+
+  describe("realloc across size classes", () => {
+    it("moves the run and recycles the old slots", () => {
+      const a = new GlyphSlotAllocator();
+      const run = a.alloc(4); // capacity 4 at 0
+      const grown = a.realloc(run, 9); // needs capacity 16
+
+      expect(grown.capacity).toBe(16);
+      expect(grown.start).not.toBe(run.start);
+      expect(a.highWater).toBe(20);
+
+      // The vacated capacity-4 run is reusable.
+      expect(a.alloc(4)).toEqual({ start: 0, capacity: 4 });
+      expect(a.highWater).toBe(20);
+    });
+
+    it("reuses a freed run of the matching class before growing", () => {
+      const a = new GlyphSlotAllocator();
+      const first = a.alloc(8);
+      a.alloc(8);
+      expect(a.highWater).toBe(16);
+
+      a.free(first);
+      expect(a.alloc(6)).toEqual({ start: first.start, capacity: 8 });
+      expect(a.highWater).toBe(16);
+    });
+
+    it("does not serve a request from a different class's free list", () => {
+      const a = new GlyphSlotAllocator();
+      a.free(a.alloc(4));
+      expect(a.highWater).toBe(4);
+
+      // A capacity-16 request can't use the freed capacity-4 run.
+      expect(a.alloc(16)).toEqual({ start: 4, capacity: 16 });
+      expect(a.highWater).toBe(20);
+    });
+  });
+
+  it("allocates a fresh run when reallocating from null", () => {
+    const a = new GlyphSlotAllocator();
+    expect(a.realloc(null, 2)).toEqual({ start: 0, capacity: 4 });
+  });
+
+  it("reset clears the free lists and the high-water mark", () => {
+    const a = new GlyphSlotAllocator();
+    a.free(a.alloc(8));
+    a.reset();
+
+    expect(a.highWater).toBe(0);
+    expect(a.alloc(8)).toEqual({ start: 0, capacity: 8 });
+  });
+
+  it("never overlaps runs across a churn of allocs, frees and reallocs", () => {
+    const a = new GlyphSlotAllocator();
+    const live = new Map<number, { start: number; capacity: number }>();
+
+    // Deterministic pseudo-random churn — a cheap stand-in for the real
+    // workload where labels appear, change text and disappear.
+    let seed = 42;
+    const next = (n: number) => {
+      seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+      return seed % n;
+    };
+
+    for (let step = 0; step < 500; step++) {
+      const id = next(40);
+      const existing = live.get(id);
+      const op = next(3);
+
+      if (op === 0 && existing) {
+        a.free(existing);
+        live.delete(id);
+      } else {
+        live.set(id, a.realloc(existing ?? null, 1 + next(30)));
+      }
+
+      // Every live run must stay inside the high-water mark and disjoint.
+      const occupied = new Set<number>();
+      for (const run of live.values()) {
+        expect(run.start + run.capacity).toBeLessThanOrEqual(a.highWater);
+        for (let s = run.start; s < run.start + run.capacity; s++) {
+          expect(occupied.has(s)).toBe(false);
+          occupied.add(s);
+        }
+      }
+    }
+  });
+});

package/src/mesh/sdfText/glyphSlots.ts

@@ -0,0 +1,98 @@
+/**
+ * Suballocator for the glyph-instance array of a batched text mesh.
+ *
+ * Every label owns one contiguous run of instance slots, so a text change
+ * rewrites only that run (one `addUpdateRange` on each instance attribute)
+ * instead of the whole buffer. Runs are rounded up to power-of-two size
+ * classes, which is what makes the common case free: re-shaping a label to a
+ * similar length ({@link realloc}) keeps the same `start`, so the caller
+ * overwrites in place and marks the leftover tail as empty slots.
+ *
+ * Freed runs go back to a per-class free list and are handed out again before
+ * the high-water mark advances. Worst-case internal fragmentation is 2x, which
+ * is the price of never having to relocate a run that merely changed length.
+ */
+
+/** Smallest run handed out: one background quad plus a few glyphs. Below this
+ *  the size classes churn without saving meaningful memory. */
+const MIN_RUN_CAPACITY = 4;
+
+/** A label's contiguous span of glyph-instance slots. */
+export type GlyphRun = {
+  /** First instance index owned by the label. */
+  readonly start: number;
+  /** Slots reserved — always >= the glyph count the run was sized for. */
+  readonly capacity: number;
+};
+
+/** Capacity class for `count` slots: the next power of two, floored at
+ *  {@link MIN_RUN_CAPACITY}. Exported for tests. */
+export function capacityFor(count: number): number {
+  if (count <= MIN_RUN_CAPACITY) return MIN_RUN_CAPACITY;
+  // 2^ceil(log2(count)), computed without floating-point log to stay exact for
+  // the large counts a pathological label could reach.
+  let capacity = MIN_RUN_CAPACITY;
+  while (capacity < count) capacity *= 2;
+  return capacity;
+}
+
+export class GlyphSlotAllocator {
+  /** Free run starts, keyed by capacity. Each list holds runs of exactly that
+   *  capacity, so a request is served without searching. */
+  private _free = new Map<number, number[]>();
+  private _highWater = 0;
+
+  /**
+   * One past the highest slot ever allocated — the value to assign to
+   * `geometry.instanceCount`. Slots below it that no label owns are holes and
+   * must be filled with empty-kind instances by the caller.
+   */
+  get highWater(): number {
+    return this._highWater;
+  }
+
+  /** Reserve a run large enough for `count` glyph instances. */
+  alloc(count: number): GlyphRun {
+    const capacity = capacityFor(count);
+
+    const pool = this._free.get(capacity);
+    const reused = pool?.pop();
+    if (reused !== undefined) {
+      return { start: reused, capacity };
+    }
+
+    const start = this._highWater;
+    this._highWater += capacity;
+    return { start, capacity };
+  }
+
+  /** Return a run to its size class's free list. */
+  free(run: GlyphRun): void {
+    let pool = this._free.get(run.capacity);
+    if (!pool) {
+      pool = [];
+      this._free.set(run.capacity, pool);
+    }
+    pool.push(run.start);
+  }
+
+  /**
+   * Resize a label's run to hold `count` glyphs.
+   *
+   * Returns the **same run** whenever `count` still fits its capacity class —
+   * the case that makes in-place text updates cheap. Otherwise the old run is
+   * freed and a new one allocated, and the caller must rewrite the run's
+   * attribute data at the new `start`.
+   */
+  realloc(run: GlyphRun | null, count: number): GlyphRun {
+    if (run && capacityFor(count) === run.capacity) return run;
+    if (run) this.free(run);
+    return this.alloc(count);
+  }
+
+  /** Drop all bookkeeping. The caller is responsible for the backing buffers. */
+  reset(): void {
+    this._free.clear();
+    this._highWater = 0;
+  }
+}

package/src/mesh/sdfText/index.ts

@@ -0,0 +1,10 @@
+export { BatchedSdfTextMesh } from "./batchedSdfText";
+export { GlyphKind } from "./glyphBuffers";
+export {
+  breakLines,
+  isRtlText,
+  lineWidthFu,
+  buildLabelLayout,
+  type GlyphQuad,
+  type LabelLayout,
+} from "./layout";

package/src/mesh/sdfText/labelData.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+
+import { LABEL_ROWS, LabelDataTexture, LabelRow } from "./labelData";
+
+/** The texel index the shader's `readLabel(slot, row)` resolves to. */
+const texelIndex = (slot: number, row: number) => slot * LABEL_ROWS + row;
+
+const dataOf = (store: LabelDataTexture) =>
+  store.texture.image.data as unknown as Float32Array;
+
+describe("LabelDataTexture", () => {
+  it("creates a float RGBA texture sized to hold the initial capacity", () => {
+    const store = new LabelDataTexture(16);
+    const { width, height } = store.texture.image;
+
+    expect(width * height).toBeGreaterThanOrEqual(16 * LABEL_ROWS);
+    expect(store.size.x).toBe(width);
+    expect(store.size.y).toBe(height);
+    expect(dataOf(store).length).toBe(width * height * 4);
+  });
+
+  it("writes a row at the address the shader reads", () => {
+    const store = new LabelDataTexture(8);
+    store.setRow(3, LabelRow.COLOR_OPACITY, 0.25, 0.5, 0.75, 0.5);
+
+    const base = texelIndex(3, LabelRow.COLOR_OPACITY) * 4;
+    expect(Array.from(dataOf(store).slice(base, base + 4))).toEqual([
+      0.25, 0.5, 0.75, 0.5,
+    ]);
+  });
+
+  it("keeps rows of the same label independent", () => {
+    const store = new LabelDataTexture(4);
+    store.setRow(2, LabelRow.BOX, 1, 2, 3, 4);
+    store.setRow(2, LabelRow.STATE, 5, 6, 7, 8);
+
+    const box = texelIndex(2, LabelRow.BOX) * 4;
+    const state = texelIndex(2, LabelRow.STATE) * 4;
+    expect(Array.from(dataOf(store).slice(box, box + 4))).toEqual([1, 2, 3, 4]);
+    expect(Array.from(dataOf(store).slice(state, state + 4))).toEqual([
+      5, 6, 7, 8,
+    ]);
+  });
+
+  it("setComponent touches only its channel", () => {
+    const store = new LabelDataTexture(4);
+    store.setRow(1, LabelRow.STATE, 1, 2, 3, 4);
+    store.setComponent(1, LabelRow.STATE, 0, 0.5);
+
+    const base = texelIndex(1, LabelRow.STATE) * 4;
+    expect(Array.from(dataOf(store).slice(base, base + 4))).toEqual([
+      0.5, 2, 3, 4,
+    ]);
+    expect(store.getComponent(1, LabelRow.STATE, 0)).toBe(0.5);
+    expect(store.getComponent(1, LabelRow.STATE, 2)).toBe(3);
+  });
+
+  it("clearSlot zeroes exactly one label's rows", () => {
+    const store = new LabelDataTexture(4);
+    store.setRow(0, LabelRow.BOX, 9, 9, 9, 9);
+    store.setRow(1, LabelRow.BOX, 7, 7, 7, 7);
+    store.setRow(2, LabelRow.BOX, 5, 5, 5, 5);
+
+    store.clearSlot(1);
+
+    expect(store.getComponent(0, LabelRow.BOX, 0)).toBe(9);
+    expect(store.getComponent(1, LabelRow.BOX, 0)).toBe(0);
+    expect(store.getComponent(2, LabelRow.BOX, 0)).toBe(5);
+  });
+
+  describe("ensureCapacity", () => {
+    it("is a no-op while the request fits", () => {
+      const store = new LabelDataTexture(16);
+      const before = store.texture;
+
+      expect(store.ensureCapacity(16)).toBe(false);
+      expect(store.texture).toBe(before);
+    });
+
+    // The allocation is padded out to whole texture rows, and that padding is
+    // usable space — 16 labels round up to 2 rows, which address 25. Growing
+    // at 17 would mean an allocate + copy + texture recreate (and a full GPU
+    // re-upload) while free slots were still sitting in the buffer.
+    it("uses the row padding before growing", () => {
+      const store = new LabelDataTexture(16);
+      const before = store.texture;
+
+      expect(store.capacity).toBeGreaterThan(16);
+      expect(store.ensureCapacity(17)).toBe(false);
+      expect(store.ensureCapacity(store.capacity)).toBe(false);
+      expect(store.texture).toBe(before);
+
+      // ...and the padded slots are genuinely addressable.
+      const last = store.capacity - 1;
+      store.setRow(last, LabelRow.BOX, 1, 2, 3, 4);
+      expect(store.getComponent(last, LabelRow.BOX, 3)).toBe(4);
+      expect(texelIndex(last, LABEL_ROWS - 1) * 4 + 3).toBeLessThan(
+        dataOf(store).length,
+      );
+
+      // One past the padded capacity is what actually triggers the grow.
+      expect(store.ensureCapacity(store.capacity + 1)).toBe(true);
+    });
+
+    it("reports a capacity the texture can really back", () => {
+      for (const requested of [1, 2, 16, 32, 40, 64, 128]) {
+        const store = new LabelDataTexture(requested);
+        const { width, height } = store.texture.image;
+        expect(store.capacity).toBeGreaterThanOrEqual(requested);
+        // Every row of every label must land inside the texture.
+        expect(store.capacity * LABEL_ROWS).toBeLessThanOrEqual(width * height);
+        expect(dataOf(store).length).toBe(width * height * 4);
+      }
+    });
+
+    it("grows, replaces the texture, and preserves existing data", () => {
+      const store = new LabelDataTexture(2);
+      store.setRow(0, LabelRow.BOX, 1, 2, 3, 4);
+      store.setRow(1, LabelRow.STATE, 5, 6, 7, 8);
+      const before = store.texture;
+
+      expect(store.ensureCapacity(40)).toBe(true);
+      expect(store.texture).not.toBe(before);
+      expect(store.capacity).toBeGreaterThanOrEqual(40);
+
+      // Addresses are stable across a grow: the width is fixed, so only the
+      // height changes and previously written texels keep their index.
+      expect(store.getComponent(0, LabelRow.BOX, 1)).toBe(2);
+      expect(store.getComponent(1, LabelRow.STATE, 3)).toBe(8);
+
+      // ...and the new tail is addressable.
+      store.setRow(39, LabelRow.BOX, 11, 12, 13, 14);
+      expect(store.getComponent(39, LabelRow.BOX, 0)).toBe(11);
+    });
+
+    it("reports the grown dimensions through size", () => {
+      const store = new LabelDataTexture(2);
+      const heightBefore = store.size.y;
+
+      store.ensureCapacity(500);
+
+      expect(store.size.y).toBeGreaterThan(heightBefore);
+      expect(store.size.x).toBe(store.texture.image.width);
+      expect(store.size.y).toBe(store.texture.image.height);
+      expect(dataOf(store).length).toBe(store.size.x * store.size.y * 4);
+    });
+
+    it("keeps the highest addressable slot inside the buffer", () => {
+      const store = new LabelDataTexture(3);
+      store.ensureCapacity(100);
+
+      const last = texelIndex(store.capacity - 1, LABEL_ROWS - 1) * 4 + 3;
+      expect(last).toBeLessThan(dataOf(store).length);
+    });
+  });
+
+  // `needsUpdate` is a write-only setter that bumps `version`, so the upload
+  // request is only observable through the version counter.
+  it("flags the texture for upload on every write", () => {
+    const store = new LabelDataTexture(4);
+
+    let version = store.texture.version;
+    store.setRow(0, LabelRow.BOX, 1, 1, 1, 1);
+    expect(store.texture.version).toBeGreaterThan(version);
+
+    version = store.texture.version;
+    store.setComponent(0, LabelRow.STATE, 0, 1);
+    expect(store.texture.version).toBeGreaterThan(version);
+
+    version = store.texture.version;
+    store.clearSlot(0);
+    expect(store.texture.version).toBeGreaterThan(version);
+
+    version = store.texture.version;
+    store.markDirty();
+    expect(store.texture.version).toBeGreaterThan(version);
+  });
+});