@navaramap/three 0.0.0

package/src/mesh/sprite/billboardAtlas.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  type AtlasImage,
+  type AtlasRect,
+  BillboardAtlas,
+} from "./billboardAtlas";
+
+/** Solid-color RGBA image where every pixel is (r, g, b, 255). */
+const solidImage = (
+  width: number,
+  height: number,
+  r: number,
+  g = 0,
+  b = 0,
+): AtlasImage => {
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    data[i * 4 + 0] = r;
+    data[i * 4 + 1] = g;
+    data[i * 4 + 2] = b;
+    data[i * 4 + 3] = 255;
+  }
+  return { width, height, data };
+};
+
+/** loadImage stub: url "WxH:r" resolves to a solid image of that size/color. */
+const stubLoader = () =>
+  vi.fn(async (url: string): Promise<AtlasImage> => {
+    const [size, r] = url.split(":");
+    const [w, h] = size.split("x").map(Number);
+    return solidImage(w, h, Number(r ?? 0));
+  });
+
+const overlaps = (a: AtlasRect, b: AtlasRect) =>
+  a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+
+/** pack() that fails the test instead of resolving undefined. */
+const mustPack = async (
+  atlas: BillboardAtlas,
+  url: string,
+): Promise<AtlasRect> => {
+  const rect = await atlas.pack(url);
+  if (!rect) throw new Error(`pack failed for ${url}`);
+  return rect;
+};
+
+describe("BillboardAtlas", () => {
+  it("packs an image and returns its pixel rect", async () => {
+    const atlas = new BillboardAtlas({
+      initialSize: 64,
+      loadImage: stubLoader(),
+    });
+    const rect = await mustPack(atlas, "16x8:255");
+
+    expect(rect.w).toBe(16);
+    expect(rect.h).toBe(8);
+    expect(rect.x + rect.w).toBeLessThanOrEqual(atlas.size);
+    expect(rect.y + rect.h).toBeLessThanOrEqual(atlas.size);
+  });
+
+  it("writes the image pixels at the rect position", async () => {
+    const atlas = new BillboardAtlas({
+      initialSize: 64,
+      loadImage: stubLoader(),
+    });
+    const rect = await mustPack(atlas, "4x4:200");
+
+    const data = atlas.texture.image.data as Uint8Array;
+    // Sample the rect's first and last pixels.
+    const first = (rect.y * atlas.size + rect.x) * 4;
+    const last = ((rect.y + rect.h - 1) * atlas.size + rect.x + rect.w - 1) * 4;
+    expect(data[first]).toBe(200);
+    expect(data[first + 3]).toBe(255);
+    expect(data[last]).toBe(200);
+    // One past the rect horizontally is gutter: untouched (transparent).
+    const gutter = (rect.y * atlas.size + rect.x + rect.w) * 4;
+    expect(data[gutter + 3]).toBe(0);
+  });
+
+  it("dedupes by URL, including in-flight loads", async () => {
+    const loadImage = stubLoader();
+    const atlas = new BillboardAtlas({ initialSize: 64, loadImage });
+
+    const [a, b] = await Promise.all([
+      atlas.pack("8x8:1"),
+      atlas.pack("8x8:1"),
+    ]);
+    const c = await atlas.pack("8x8:1");
+
+    expect(loadImage).toHaveBeenCalledTimes(1);
+    expect(a).toEqual(b);
+    expect(a).toEqual(c);
+  });
+
+  it("packs distinct images into non-overlapping rects", async () => {
+    const atlas = new BillboardAtlas({
+      initialSize: 64,
+      loadImage: stubLoader(),
+    });
+    const rects = await Promise.all([
+      mustPack(atlas, "16x16:1"),
+      mustPack(atlas, "8x4:2"),
+      mustPack(atlas, "20x12:3"),
+      mustPack(atlas, "3x30:4"),
+    ]);
+
+    for (let i = 0; i < rects.length; i++) {
+      for (let j = i + 1; j < rects.length; j++) {
+        expect(overlaps(rects[i], rects[j])).toBe(false);
+      }
+    }
+  });
+
+  it("grows when full and keeps existing rects and pixels valid", async () => {
+    const atlas = new BillboardAtlas({
+      initialSize: 16,
+      maxSize: 64,
+      loadImage: stubLoader(),
+    });
+
+    const small = await mustPack(atlas, "8x8:11");
+    const initialTexture = atlas.texture;
+    expect(atlas.size).toBe(16);
+
+    // Doesn't fit in the remaining 16x16 space: forces growth.
+    const big = await mustPack(atlas, "20x20:22");
+
+    expect(atlas.size).toBeGreaterThan(16);
+    expect(atlas.texture).not.toBe(initialTexture);
+    expect(overlaps(small, big)).toBe(false);
+
+    // The first image's pixels survived the copy into the larger buffer.
+    const data = atlas.texture.image.data as Uint8Array;
+    const first = (small.y * atlas.size + small.x) * 4;
+    expect(data[first]).toBe(11);
+  });
+
+  it("returns undefined when an image cannot fit even at maxSize", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const atlas = new BillboardAtlas({
+      initialSize: 16,
+      maxSize: 32,
+      loadImage: stubLoader(),
+    });
+
+    expect(await atlas.pack("64x64:0")).toBeUndefined();
+    warn.mockRestore();
+  });
+
+  it("reports its footprint as CPU buffer + GPU texture and tracks growth", async () => {
+    const atlas = new BillboardAtlas({
+      initialSize: 16,
+      maxSize: 64,
+      loadImage: stubLoader(),
+    });
+    // 16×16 RGBA, twice (CPU pixel buffer + GPU copy).
+    expect(atlas.byteLength).toBe(16 * 16 * 4 * 2);
+
+    // Forces growth to 32 (20+gutter doesn't fit in 16).
+    await mustPack(atlas, "20x20:0");
+    expect(atlas.byteLength).toBe(32 * 32 * 4 * 2);
+  });
+
+  it("caches failed loads and resolves them as undefined", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const loadImage = vi.fn(async (): Promise<AtlasImage> => {
+      throw new Error("404");
+    });
+    const atlas = new BillboardAtlas({ initialSize: 16, loadImage });
+
+    expect(await atlas.pack("bad")).toBeUndefined();
+    expect(await atlas.pack("bad")).toBeUndefined();
+    expect(loadImage).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+});

package/src/mesh/sprite/billboardAtlas.ts

@@ -0,0 +1,210 @@
+import { DataTexture, LinearFilter, RGBAFormat, UnsignedByteType } from "three";
+
+/**
+ * Sub-rectangle of the atlas in pixels. Row 0 is the bottom of the texture
+ * (v = 0), matching the flipY applied at decode time. Rects are stored in
+ * pixel space and normalized by `uAtlasSize` in the shader, so they stay
+ * valid when the atlas grows.
+ */
+export type AtlasRect = {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+};
+
+export type AtlasImage = {
+  width: number;
+  height: number;
+  /** RGBA, tightly packed, row 0 = bottom of the image (flipY at decode). */
+  data: Uint8Array;
+};
+
+export type LoadAtlasImage = (url: string) => Promise<AtlasImage>;
+
+export type BillboardAtlasOptions = {
+  initialSize?: number;
+  maxSize?: number;
+  /**
+   * How to fetch and decode a URL into RGBA pixels. Kept injectable (and out
+   * of this module) so the atlas has no browser/worker dependencies — use
+   * `loadAtlasImageFromUrl` from `billboardAtlasImageLoader` in the app.
+   */
+  loadImage: LoadAtlasImage;
+};
+
+/** Spacing between entries so LinearFilter sampling never bleeds neighbors. */
+const GUTTER = 1;
+const DEFAULT_INITIAL_SIZE = 256;
+// Conservative floor of WebGL2 MAX_TEXTURE_SIZE across devices.
+const DEFAULT_MAX_SIZE = 4096;
+
+type Shelf = {
+  y: number;
+  height: number;
+  /** Horizontal cursor: next free x within this shelf. */
+  x: number;
+};
+
+/**
+ * A texture atlas for billboard images: packs arbitrarily sized images into a
+ * single square RGBA `DataTexture` with a shelf allocator, deduplicating loads
+ * by URL (including in-flight ones — the promise itself is cached).
+ *
+ * The atlas grows by doubling up to `maxSize`. Growth preserves the layout, so
+ * previously returned rects remain valid; only the texture object is replaced
+ * (a `DataTexture` cannot be resized in place). Callers must re-read `texture`
+ * and `size` after every `pack()` and re-sync their uniforms.
+ *
+ * Failed loads are cached as `undefined` so a bad URL shared by many features
+ * is fetched once, not once per feature.
+ */
+export class BillboardAtlas {
+  private _size: number;
+  private readonly _maxSize: number;
+  private _data: Uint8Array;
+  private _texture: DataTexture;
+  private _shelves: Shelf[] = [];
+  private _nextShelfY = 0;
+  private readonly _rects = new Map<string, Promise<AtlasRect | undefined>>();
+  private readonly _loadImage: LoadAtlasImage;
+
+  constructor(options: BillboardAtlasOptions) {
+    this._size = options.initialSize ?? DEFAULT_INITIAL_SIZE;
+    this._maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+    this._loadImage = options.loadImage;
+    this._data = new Uint8Array(this._size * this._size * 4);
+    this._texture = this._createTexture();
+  }
+
+  get texture(): DataTexture {
+    return this._texture;
+  }
+
+  /** Current atlas edge length in pixels (the atlas is always square). */
+  get size(): number {
+    return this._size;
+  }
+
+  /**
+   * Memory footprint of the atlas in bytes: the CPU pixel buffer (kept
+   * resident for growth re-blits and `needsUpdate` re-uploads) plus the
+   * equal-sized GPU copy held by the `DataTexture` (RGBA8, no mipmaps).
+   */
+  get byteLength(): number {
+    return this._data.byteLength * 2;
+  }
+
+  /**
+   * Load `url` (once) and pack it into the atlas.
+   * Resolves to the entry's pixel rect, or `undefined` when the image fails
+   * to load or the atlas is full even at `maxSize`.
+   */
+  pack(url: string): Promise<AtlasRect | undefined> {
+    const cached = this._rects.get(url);
+    if (cached) return cached;
+
+    const pending = this._loadAndPack(url).catch((error) => {
+      console.warn(`BillboardAtlas: failed to load image "${url}"`, error);
+      return undefined;
+    });
+    this._rects.set(url, pending);
+    return pending;
+  }
+
+  dispose(): void {
+    this._texture.dispose();
+    this._rects.clear();
+    this._shelves = [];
+  }
+
+  private async _loadAndPack(url: string): Promise<AtlasRect | undefined> {
+    const image = await this._loadImage(url);
+    const rect = this._allocate(image.width, image.height);
+    if (!rect) {
+      console.warn(
+        `BillboardAtlas: no space for "${url}" (${image.width}x${image.height}) at max atlas size ${this._maxSize}`,
+      );
+      return undefined;
+    }
+    this._blit(image, rect);
+    return rect;
+  }
+
+  private _allocate(w: number, h: number): AtlasRect | undefined {
+    for (;;) {
+      const rect = this._tryAllocate(w, h);
+      if (rect) return rect;
+      if (!this._grow()) return undefined;
+    }
+  }
+
+  private _tryAllocate(w: number, h: number): AtlasRect | undefined {
+    const needW = w + GUTTER;
+    const needH = h + GUTTER;
+    if (needW > this._size) return undefined;
+
+    // Best-fit shelf: the shortest existing shelf that still fits the entry.
+    let best: Shelf | undefined;
+    for (const shelf of this._shelves) {
+      if (needH > shelf.height || shelf.x + needW > this._size) continue;
+      if (!best || shelf.height < best.height) best = shelf;
+    }
+
+    if (!best && this._nextShelfY + needH <= this._size) {
+      best = { y: this._nextShelfY, height: needH, x: 0 };
+      this._shelves.push(best);
+      this._nextShelfY += needH;
+    }
+    if (!best) return undefined;
+
+    const rect = { x: best.x, y: best.y, w, h };
+    best.x += needW;
+    return rect;
+  }
+
+  /**
+   * Double the atlas edge, preserving the existing layout: old pixel rows are
+   * copied into the wider buffer, shelves keep their y/height and simply gain
+   * free space to the right, and new shelves can open below `_nextShelfY`.
+   */
+  private _grow(): boolean {
+    const newSize = this._size * 2;
+    if (newSize > this._maxSize) return false;
+
+    const newData = new Uint8Array(newSize * newSize * 4);
+    for (let row = 0; row < this._size; row++) {
+      newData.set(
+        this._data.subarray(row * this._size * 4, (row + 1) * this._size * 4),
+        row * newSize * 4,
+      );
+    }
+
+    this._size = newSize;
+    this._data = newData;
+    this._texture.dispose();
+    this._texture = this._createTexture();
+    return true;
+  }
+
+  private _blit(image: AtlasImage, rect: AtlasRect): void {
+    for (let row = 0; row < rect.h; row++) {
+      this._data.set(
+        image.data.subarray(row * rect.w * 4, (row + 1) * rect.w * 4),
+        ((rect.y + row) * this._size + rect.x) * 4,
+      );
+    }
+    this._texture.needsUpdate = true;
+  }
+
+  private _createTexture(): DataTexture {
+    const texture = new DataTexture(this._data, this._size, this._size);
+    texture.format = RGBAFormat;
+    texture.type = UnsignedByteType;
+    texture.minFilter = LinearFilter;
+    texture.magFilter = LinearFilter;
+    texture.generateMipmaps = false;
+    texture.needsUpdate = true;
+    return texture;
+  }
+}

package/src/mesh/sprite/billboardAtlasImageLoader.ts

@@ -0,0 +1,29 @@
+import { TEXTURE_LOADER } from "../../event/loaders";
+import { getImageDataFromImageBitmap } from "../../tasks/getImageDataFromImageBitmap";
+
+import type { LoadAtlasImage } from "./billboardAtlas";
+
+/**
+ * Browser decode pipeline for `BillboardAtlas`: fetch via the shared texture
+ * loader, rasterize to RGBA off the main thread. Lives outside billboardAtlas
+ * so the atlas itself stays importable in worker-free environments (tests).
+ *
+ * flipY at decode matches the previous DataArrayTexture path: row 0 of the
+ * pixel data is the bottom of the image, i.e. v = 0 in the atlas texture.
+ */
+export const loadAtlasImageFromUrl: LoadAtlasImage = async (url) => {
+  const texture = await TEXTURE_LOADER.loadAsync(url);
+  try {
+    const img = texture.image as HTMLImageElement | ImageBitmap;
+    const width = img.width;
+    const height = img.height;
+
+    const data = await getImageDataFromImageBitmap(
+      await createImageBitmap(img, { imageOrientation: "flipY" }),
+      new OffscreenCanvas(width, height),
+    );
+    return { width, height, data: new Uint8Array(data) };
+  } finally {
+    texture.dispose();
+  }
+};

package/src/mesh/sprite/index.ts

@@ -0,0 +1 @@
+export * from "./instancedSprite";