@aethervtt/shard-text 0.0.1

package/dist/opentype.d.ts

@@ -0,0 +1,36 @@
+// The subset of opentype.js (which ships no types) that @aethervtt/shard-text uses.
+declare module 'opentype.js' {
+  export type PathCommand =
+    | { type: 'M'; x: number; y: number }
+    | { type: 'L'; x: number; y: number }
+    | { type: 'Q'; x1: number; y1: number; x: number; y: number }
+    | { type: 'C'; x1: number; y1: number; x2: number; y2: number; x: number; y: number }
+    | { type: 'Z' }
+
+  export interface Glyph {
+    index: number
+    name: string | null
+    advanceWidth: number | undefined
+    leftSideBearing: number | undefined
+    path: { commands: PathCommand[] }
+  }
+
+  export interface Font {
+    unitsPerEm: number
+    ascender: number
+    descender: number
+    numGlyphs: number
+    outlinesFormat: 'truetype' | 'cff'
+    names: Record<string, Record<string, string> | undefined>
+    glyphs: { get(index: number): Glyph }
+    kerningPairs: Record<string, number>
+    tables: {
+      cmap: { glyphIndexMap: Record<number, number> }
+      hhea: { ascender: number; descender: number; lineGap: number }
+      os2?: { sTypoAscender: number; sTypoDescender: number; sTypoLineGap: number }
+      [name: string]: unknown
+    }
+  }
+
+  export function parse(buffer: ArrayBuffer, options?: { lowMemory?: boolean }): Font
+}

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+/** Text and ScreenText: MSDF glyphs in the world (after transparent 3D) and over the image. */
+export declare const textPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/plugin.js

@@ -0,0 +1,43 @@
+import { Last } from "@aethervtt/shard-core";
+import { Gpu, Graph, RenderDescribers, RenderSet, Shaders } from "@aethervtt/shard-render";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import * as componentsModule from "./components.js";
+import * as importerModule from "./importer.js";
+import { Fonts } from "./importer.js";
+import * as localeModule from "./locale.js";
+import { installLocalization } from "./locale.js";
+import * as previewModule from "./preview.js";
+import * as renderModule from "./render.js";
+import {
+  describeText,
+  prepareTexts,
+  screenTextNode,
+  TextRenderer,
+  TextStore,
+  textNode
+} from "./render.js";
+import { TEXT_SHADERS } from "./shaders.js";
+const textPlugin = definePlugin({
+  name: "text",
+  provides: [componentsModule, importerModule, localeModule, previewModule, renderModule],
+  dependencies: ["render/forward"],
+  build(app) {
+    app.world.initResource(Fonts);
+    installLocalization(app);
+    app.addSystems(Last, prepareTexts.inSet(RenderSet.Prepare));
+  },
+  ready(app) {
+    const world = app.world;
+    app.insertResource(TextRenderer, new TextStore(world.resource(Gpu)));
+    const shaders = world.resource(Shaders);
+    for (const [path, source] of Object.entries(TEXT_SHADERS))
+      shaders.register(path, source, `engine:${path}`);
+    const graph = world.resource(Graph);
+    graph.addNode("text", textNode(world));
+    graph.addNode("text/screen", screenTextNode(world));
+    world.initResource(RenderDescribers).set("text", (w) => describeText(w));
+  }
+});
+export {
+  textPlugin
+};

package/dist/preview.d.ts

@@ -0,0 +1,2 @@
+/** A font specimen: sample lines at 16, 32, and 64 px, rendered from the distance field on the CPU. */
+export declare const fontPreview: import("@aethervtt/shard-assets").AssetPreview;

package/dist/preview.js

@@ -0,0 +1,76 @@
+import { assetServer, defineAssetPreview } from "@aethervtt/shard-assets";
+import { ShardError } from "@aethervtt/shard-core";
+import { readKtx2 } from "@aethervtt/shard-texture";
+import { Fonts } from "./importer.js";
+import { layoutText } from "./layout.js";
+const SPECIMEN = [
+  "AaBbCcDdEeFfGg 0123456789",
+  "The quick brown fox jumps over the lazy dog.",
+  "Sharp at any size \u2014 \xC0\xC9\xCE\xF5\xFC ?!&@"
+];
+const fontPreview = defineAssetPreview("Font", async (world, path, width, height) => {
+  const server = assetServer(world);
+  await server.whenSettled([path]);
+  const font = world.resource(Fonts).get(server.resolve(path));
+  if (!font) throw new ShardError("text/not-loaded", `${path} isn't loaded`, { path });
+  const pages = await Promise.all(
+    font.pages.map(async (page, i) => {
+      if (page.texture?.levels)
+        return { w: page.width, h: page.height, data: page.texture.levels[0] };
+      const ktx = readKtx2(
+        (await server.artifact(`${path}#${i === 0 ? "Atlas" : `Atlas/${i}`}`)).bytes
+      );
+      return { w: ktx.width, h: ktx.height, data: ktx.levels[0] };
+    })
+  );
+  const out = new Uint8Array(width * height * 4);
+  for (let p = 0; p < width * height; p++) out.set([24, 26, 32, 255], p * 4);
+  let baseline = 8;
+  for (const px of [16, 32, 64]) {
+    for (const line of SPECIMEN) {
+      baseline += px * 1.25;
+      if (baseline > height) break;
+      const layout = layoutText(font, line, { size: px, anchor: [0, 0] });
+      for (let q = 0; q < layout.count; q++) {
+        const page = pages[layout.pages[layout.page[q]].index];
+        if (!page) continue;
+        const gFont = layout.glyphs[q].font;
+        const screenRange = gFont.range * (px / gFont.size);
+        const [x, y, w, h] = layout.quads.subarray(q * 4, q * 4 + 4);
+        const [u0, v0, u1, v1] = layout.uvs.subarray(q * 4, q * 4 + 4);
+        for (let j = Math.floor(baseline - y - h); j < Math.ceil(baseline - y); j++) {
+          if (j < 0 || j >= height) continue;
+          for (let i = Math.floor(8 + x); i < Math.ceil(8 + x + w); i++) {
+            if (i < 0 || i >= width) continue;
+            const fu = (i + 0.5 - 8 - x) / w;
+            const fv = (j + 0.5 - (baseline - y - h)) / h;
+            const sd = sample(page, u0 + (u1 - u0) * fu, v0 + (v1 - v0) * fv);
+            const a = Math.min(1, Math.max(0, screenRange * (sd - 0.5) + 0.5));
+            const o = (j * width + i) * 4;
+            for (let k = 0; k < 3; k++) out[o + k] = Math.round(out[o + k] * (1 - a) + 240 * a);
+          }
+        }
+      }
+    }
+  }
+  return { width, height, data: out };
+});
+function sample(page, u, v) {
+  const x = Math.min(page.w - 1, Math.max(0, u * page.w - 0.5));
+  const y = Math.min(page.h - 1, Math.max(0, v * page.h - 0.5));
+  const x0 = Math.floor(x);
+  const y0 = Math.floor(y);
+  const x1 = Math.min(page.w - 1, x0 + 1);
+  const y1 = Math.min(page.h - 1, y0 + 1);
+  const fx = x - x0;
+  const fy = y - y0;
+  const c = [0, 0, 0];
+  for (let k = 0; k < 3; k++) {
+    const at = (px, py) => page.data[(py * page.w + px) * 4 + k] / 255;
+    c[k] = (at(x0, y0) * (1 - fx) + at(x1, y0) * fx) * (1 - fy) + (at(x0, y1) * (1 - fx) + at(x1, y1) * fx) * fy;
+  }
+  return Math.max(Math.min(c[0], c[1]), Math.min(Math.max(c[0], c[1]), c[2]));
+}
+export {
+  fontPreview
+};

package/dist/render.d.ts

@@ -0,0 +1,114 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import { type NodeDescriptor } from '@aethervtt/shard-render';
+import type { Font, FontPage } from './font.js';
+import { TextLayout } from './layout.js';
+interface TextState {
+    entity: Entity;
+    space: number;
+    layout: TextLayout;
+    /** What the layout was made from: re-lay out when any of these change. */
+    value: string;
+    font: Font | undefined;
+    fontVersion: number;
+    size: number;
+    align: number;
+    anchorX: number;
+    anchorY: number;
+    maxWidth: number;
+    lineHeight: number;
+    /** Record index in the text buffer. */
+    index: number;
+    seen: number;
+}
+/** Glyphs of one atlas page in one space: one draw. */
+interface GlyphGroup {
+    page: FontPage;
+    space: number;
+    first: number;
+    count: number;
+}
+/**
+ * Laid-out text on the GPU. Each Text or ScreenText keeps its layout and relays out only when its
+ * value, font, size, or layout options change (or its font gains glyphs). Glyph records are
+ * rebuilt, grouped by atlas page, only on frames where some layout changed; transforms and colors
+ * update the small per-text records.
+ */
+export declare class TextStore {
+    readonly states: Map<number, TextState>;
+    glyphs: Float32Array<ArrayBuffer>;
+    glyphU32: Uint32Array<ArrayBuffer>;
+    glyphCount: number;
+    texts: Float32Array<ArrayBuffer>;
+    textU32: Uint32Array<ArrayBuffer>;
+    textCount: number;
+    readonly groups: GlyphGroup[];
+    groupCount: number;
+    readonly glyphBuffer: GpuBuffer;
+    readonly textBuffer: GpuBuffer;
+    /** Layouts redone this frame, and characters nothing could draw. */
+    relayouts: number;
+    missing: number;
+    uploadedBytes: number;
+    private frame;
+    private freeIndices;
+    private nextIndex;
+    dirtyGlyphs: boolean;
+    constructor(gpu: GpuContext);
+    beginFrame(): void;
+    state(entity: Entity, space: number): TextState;
+    /** Forgets texts not seen this frame (despawned, hidden, or their component removed). */
+    sweep(): void;
+    /** Group per (page, space) while rebuilding: [world, screen], -1 for none yet. */
+    private readonly groupOf;
+    private groupFor;
+    /** Rebuilds the glyph records, grouped by (page, space), from every layout. */
+    rebuild(): void;
+}
+export declare const TextRenderer: import("@aethervtt/shard-core").ResourceDef<TextStore>;
+/**
+ * Lays out changed text (Text in the world, ScreenText on screen), writes per-text style and
+ * placement records, and rebuilds glyph records on frames where a layout changed.
+ */
+export declare const prepareTexts: import("@aethervtt/shard-core").SystemDef<{
+    worldQ: import("@aethervtt/shard-core").Query;
+    screenQ: import("@aethervtt/shard-core").Query;
+    screen: {
+        corner: number;
+        x: number;
+        y: number;
+    };
+}>;
+interface TextCaches {
+    generation: number;
+    layouts?: {
+        view: GPUBindGroupLayout;
+        data: GPUBindGroupLayout;
+        page: GPUBindGroupLayout;
+    };
+    pipelines: Map<string, GPURenderPipeline>;
+    groups: Map<string, {
+        key: string;
+        group: GPUBindGroup;
+    }>;
+    views: Map<string, GpuBuffer>;
+    sampler?: GPUSampler;
+}
+export declare const TextCachesResource: import("@aethervtt/shard-core").ResourceDef<TextCaches>;
+/** World text: after transparent 3D, depth-tested against the scene. */
+export declare function textNode(world: World): NodeDescriptor;
+/** Screen text: over the finished image, after screen sprites. */
+export declare function screenTextNode(world: World): NodeDescriptor;
+/** The text section of `render.describe`. */
+export declare function describeText(world: World): {
+    texts: number;
+    glyphs: number;
+    drawCalls: number;
+    atlasPages: number;
+    runtimePages: number;
+    runtimeGlyphs: number;
+    missing: string[];
+    relayouts: number;
+    uploadedBytes: number;
+} | undefined;
+export {};