@bloopjs/toodle 0.0.100

package/src/text/TextShader.ts

@@ -0,0 +1,223 @@
+import { WgslReflect } from "wgsl_reflect";
+import type { SceneNode } from "../scene/SceneNode";
+import type { EngineUniform } from "../shaders/EngineUniform";
+import type { IShader } from "../shaders/IShader";
+import type { FontPipeline } from "./FontPipeline";
+import type { MsdfFont } from "./MsdfFont";
+import { findLargestFontSize, measureText, shapeText } from "./shaping";
+import { DEFAULT_FONT_SIZE, TextNode } from "./TextNode";
+import msdfShader from "./text.wgsl";
+
+const deets = new WgslReflect(msdfShader);
+const struct = deets.structs.find((s) => s.name === "TextBlockDescriptor");
+if (!struct) {
+  throw new Error("FormattedText struct not found");
+}
+const textDescriptorInstanceSize = struct.size;
+
+export class TextShader implements IShader {
+  #device: GPUDevice;
+  #pipeline: GPURenderPipeline;
+  #bindGroups: GPUBindGroup[] = [];
+  #font: MsdfFont;
+  #maxCharCount: number;
+  #engineUniformsBuffer: GPUBuffer;
+  #descriptorBuffer: GPUBuffer;
+  #textBlockBuffer: GPUBuffer;
+  #cpuDescriptorBuffer: Float32Array;
+  #cpuTextBlockBuffer: Float32Array;
+  #instanceIndex = 0;
+  #textBlockOffset = 0;
+
+  constructor(
+    device: GPUDevice,
+    pipeline: FontPipeline,
+    font: MsdfFont,
+    colorFormat: GPUTextureFormat,
+    instanceCount: number,
+  ) {
+    this.#device = device;
+    this.#font = font;
+    this.#pipeline = pipeline.pipeline;
+    this.#maxCharCount = pipeline.maxCharCount;
+
+    this.#descriptorBuffer = device.createBuffer({
+      label: "msdf text descriptor buffer",
+      size: textDescriptorInstanceSize * instanceCount,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
+    this.#cpuDescriptorBuffer = new Float32Array(
+      (instanceCount * textDescriptorInstanceSize) /
+        Float32Array.BYTES_PER_ELEMENT,
+    );
+
+    this.#cpuTextBlockBuffer = new Float32Array(
+      instanceCount * this.maxCharCount * 4,
+    );
+
+    this.#engineUniformsBuffer = device.createBuffer({
+      label: "msdf view projection matrix",
+      size: Float32Array.BYTES_PER_ELEMENT * 12,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+
+    this.#textBlockBuffer = device.createBuffer({
+      label: "msdf text buffer",
+      size:
+        instanceCount * this.maxCharCount * 4 * Float32Array.BYTES_PER_ELEMENT,
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+    });
+
+    // create uniform bind groups
+    this.#bindGroups.push(pipeline.fontBindGroup);
+
+    this.#bindGroups.push(
+      device.createBindGroup({
+        label: "msdf text bind group",
+        layout: pipeline.pipeline.getBindGroupLayout(1),
+        entries: [
+          {
+            binding: 0,
+            resource: { buffer: this.#descriptorBuffer },
+          },
+          {
+            binding: 1,
+            resource: { buffer: this.#textBlockBuffer },
+          },
+        ],
+      }),
+    );
+
+    const engineUniformsBindGroup = device.createBindGroup({
+      label: "msdf text uniforms bind group",
+      layout: pipeline.pipeline.getBindGroupLayout(2),
+      entries: [
+        {
+          binding: 0,
+          resource: { buffer: this.#engineUniformsBuffer },
+        },
+      ],
+    });
+    this.#bindGroups.push(engineUniformsBindGroup);
+  }
+
+  startFrame(device: GPUDevice, uniform: EngineUniform): void {
+    device.queue.writeBuffer(
+      this.#engineUniformsBuffer,
+      0,
+      uniform.viewProjectionMatrix as Float32Array,
+    );
+    this.#instanceIndex = 0;
+    this.#textBlockOffset = 0;
+  }
+
+  processBatch(renderPass: GPURenderPassEncoder, nodes: SceneNode[]): number {
+    if (nodes.length === 0) return 0;
+
+    renderPass.setPipeline(this.#pipeline);
+    for (let i = 0; i < this.#bindGroups.length; i++) {
+      renderPass.setBindGroup(i, this.#bindGroups[i]);
+    }
+
+    for (const node of nodes) {
+      if (!(node instanceof TextNode)) {
+        console.error(node);
+        throw new Error(
+          `Tried to use TextShader on something that isn't a TextNode: ${node}`,
+        );
+      }
+      const text = node.text;
+      const formatting = node.formatting;
+      const measurements = measureText(this.#font, text, formatting.wordWrap);
+
+      const textBlockSize = 4 * text.length;
+
+      // Calculate the buffer offset to get the current TextBlockDescriptor
+      const textDescriptorOffset =
+        (this.#instanceIndex * textDescriptorInstanceSize) /
+        Float32Array.BYTES_PER_ELEMENT;
+
+      // Shape text and pack to the buffer...
+      this.#cpuDescriptorBuffer.set(node.matrix, textDescriptorOffset);
+
+      // Color
+      this.#cpuDescriptorBuffer.set(
+        [node.tint.r, node.tint.g, node.tint.b, node.tint.a],
+        textDescriptorOffset + 12,
+      );
+
+      // Font Size
+      const size = node.size ?? measurements;
+      const fontSize = formatting.shrinkToFit
+        ? findLargestFontSize(this.#font, text, size, formatting)
+        : formatting.fontSize;
+      const actualFontSize = fontSize || DEFAULT_FONT_SIZE;
+      this.#cpuDescriptorBuffer[textDescriptorOffset + 16] = actualFontSize;
+
+      // Alignment and dimensions
+      this.#cpuDescriptorBuffer[textDescriptorOffset + 17] =
+        formatting.align === "center" ? 0 : measurements.width;
+      this.#cpuDescriptorBuffer[textDescriptorOffset + 18] =
+        measurements.height;
+
+      // Text block buffer offset
+      // the shader at text.wgsl.ts is expecting an index into the text block buffer,
+      // which is an array<vec4f> hence the division by 4
+      this.#cpuDescriptorBuffer[textDescriptorOffset + 19] =
+        this.#textBlockOffset / 4;
+
+      shapeText(
+        this.#font,
+        text,
+        size,
+        actualFontSize,
+        formatting,
+        this.#cpuTextBlockBuffer,
+        this.#textBlockOffset,
+      );
+
+      // Write instance data
+      this.#device.queue.writeBuffer(
+        this.#descriptorBuffer,
+        textDescriptorOffset * Float32Array.BYTES_PER_ELEMENT,
+        this.#cpuDescriptorBuffer,
+        textDescriptorOffset,
+        textDescriptorInstanceSize / Float32Array.BYTES_PER_ELEMENT,
+      );
+
+      this.#device.queue.writeBuffer(
+        this.#textBlockBuffer,
+        this.#textBlockOffset * Float32Array.BYTES_PER_ELEMENT,
+        this.#cpuTextBlockBuffer,
+        this.#textBlockOffset,
+        textBlockSize,
+      );
+
+      this.#textBlockOffset += textBlockSize;
+
+      // Draw text
+      renderPass.draw(
+        4,
+        measurements.printedCharCount,
+        4 * this.#instanceIndex,
+        0,
+      );
+      this.#instanceIndex++;
+    }
+
+    return nodes.length;
+  }
+
+  endFrame(): void {
+    // No cleanup needed
+  }
+
+  get font() {
+    return this.#font;
+  }
+
+  get maxCharCount() {
+    return this.#maxCharCount;
+  }
+}

package/src/text/mod.ts

@@ -0,0 +1,8 @@
+// references:
+// https://tchayen.com/drawing-text-in-webgpu-using-just-the-font-file
+// https://github.com/Chlumsky/msdfgen/issues/22#issuecomment-234958005
+// https://github.com/pixijs/pixijs/blob/dev/src/scene/text-bitmap/utils/getBitmapTextLayout.ts#L20
+
+export type { TextOptions } from "./TextNode";
+export { TextNode } from "./TextNode";
+export { TextShader } from "./TextShader";

package/src/text/shaping.ts

@@ -0,0 +1,280 @@
+import type { Size } from "../coreTypes/Size";
+import { type MsdfChar, type MsdfFont, WhitespaceKeyCodes } from "./MsdfFont";
+import type { TextFormatting, WordWrapOptions } from "./TextFormatting";
+
+// shaping is responsible for cpu-side text shaping:
+// - measuring a text block
+// - calculating the glyph quads for the text block
+// - applying word wrap, shrink-to-fit, justification and other formatting options
+// - returning the text measurements and glyph quads
+const TAB_SPACES = 4;
+
+export interface MsdfTextMeasurements {
+  /** The width of the text block in em units. */
+  width: number;
+  /** The height of the text block in em units. */
+  height: number;
+  /** The width of each line in em units. */
+  lineWidths: number[];
+  /** The number of lines in the text block. */
+  lineCount: number;
+  /** The number of characters printed in the text block. */
+  printedCharCount: number;
+
+  /** All words in the text block */
+  words: Word[];
+}
+
+export type Glyph = {
+  char: MsdfChar;
+  offset: [number, number];
+  line: number;
+};
+
+export type Word = {
+  glyphs: Glyph[];
+  width: number;
+  startX: number;
+  startY: number;
+};
+
+export function shapeText(
+  font: MsdfFont,
+  text: string,
+  blockSize: Size,
+  fontSize: number,
+  formatting: TextFormatting,
+  textArray: Float32Array,
+  initialFloatOffset = 0,
+  debug = false,
+) {
+  let offset = initialFloatOffset;
+
+  const measurements = measureText(font, text, formatting.wordWrap);
+  const alignment = formatting.align || "left";
+  const em2px = fontSize / font.lineHeight;
+  // currently there is a code path that sets blockSize.width to measurements.width (em)
+  // if blockSize is not explicitly set (px)
+  const hackHasExplicitBlock = blockSize.width !== measurements.width;
+
+  let debugData: any[] | null = null;
+  if (debug) {
+    debugData = [];
+  }
+
+  for (const word of measurements.words) {
+    for (const glyph of word.glyphs) {
+      let lineOffset = 0;
+      if (alignment === "center") {
+        lineOffset =
+          measurements.width * -0.5 -
+          (measurements.width - measurements.lineWidths[glyph.line]) * -0.5;
+      } else if (alignment === "right") {
+        const blockSizeEm = blockSize.width / em2px;
+
+        const delta = measurements.width - measurements.lineWidths[glyph.line];
+
+        lineOffset =
+          (hackHasExplicitBlock ? blockSizeEm / 2 : measurements.width / 2) -
+          measurements.width +
+          delta;
+      } else if (alignment === "left") {
+        const blockSizeEm = blockSize.width / em2px;
+
+        lineOffset = hackHasExplicitBlock
+          ? -blockSizeEm / 2
+          : -measurements.width / 2;
+      }
+
+      if (debug && debugData) {
+        debugData.push({
+          line: glyph.line,
+          word: word.glyphs.map((g) => g.char.char).join(""),
+          glyph: glyph.char.char,
+          startX: word.startX,
+          glyphX: glyph.offset[0],
+          advance: glyph.char.xadvance,
+          lineOffset,
+          startY: word.startY,
+          glyphY: glyph.offset[1],
+        });
+      }
+      textArray[offset] = word.startX + glyph.offset[0] + lineOffset;
+      textArray[offset + 1] = word.startY + glyph.offset[1];
+      textArray[offset + 2] = glyph.char.charIndex;
+
+      offset += 4;
+    }
+  }
+
+  if (debug && debugData) {
+    console.table(debugData);
+  }
+}
+
+/**
+ * Measure the text and return measurements for block + each glyph.
+ * @param font - The font to use.
+ * @param text - The text to measure
+ * @param wordWrap - Maximum word length before word wrapping
+ * @returns The measurements of the text in em units.
+ */
+export function measureText(
+  font: MsdfFont,
+  text: string,
+  wordWrap?: WordWrapOptions,
+): MsdfTextMeasurements {
+  let maxWidth = 0;
+  const lineWidths: number[] = [];
+
+  let textOffsetX = 0;
+  let textOffsetY = 0;
+  let line = 0;
+  let printedCharCount = 0;
+  let nextCharCode = text.charCodeAt(0);
+  let word: Word = { glyphs: [], width: 0, startX: 0, startY: 0 };
+
+  const words: Word[] = [];
+
+  for (let i = 0; i < text.length; i++) {
+    const isLastLetter = i === text.length - 1;
+
+    const charCode = nextCharCode;
+    nextCharCode = i < text.length - 1 ? text.charCodeAt(i + 1) : -1;
+
+    switch (charCode) {
+      case WhitespaceKeyCodes.HorizontalTab:
+        insertSpaces(TAB_SPACES);
+        break;
+      case WhitespaceKeyCodes.Newline:
+        flushLine();
+        flushWord();
+        break;
+      case WhitespaceKeyCodes.CarriageReturn:
+        break;
+      case WhitespaceKeyCodes.Space:
+        insertSpaces(1);
+        break;
+      default: {
+        const advance = font.getXAdvance(charCode, nextCharCode);
+        if (
+          wordWrap &&
+          wordWrap.breakOn === "character" &&
+          textOffsetX + advance > wordWrap.emWidth
+        ) {
+          if (word.startX === 0) {
+            flushWord();
+          } else {
+            lineWidths.push(textOffsetX - word.width);
+            line++;
+            maxWidth = Math.max(maxWidth, textOffsetX);
+            textOffsetX = word.width;
+            textOffsetY -= font.lineHeight;
+            word.startX = 0;
+            word.startY = textOffsetY;
+            word.glyphs.forEach((g) => {
+              g.line = line;
+            });
+          }
+        }
+        word.glyphs.push({
+          char: font.getChar(charCode),
+          offset: [word.width, 0],
+          line,
+        });
+
+        if (isLastLetter) {
+          flushWord();
+        }
+
+        word.width += advance;
+        textOffsetX += advance;
+      }
+    }
+  }
+
+  lineWidths.push(textOffsetX);
+  maxWidth = Math.max(maxWidth, textOffsetX);
+
+  const lineCount = lineWidths.length;
+
+  return {
+    width: maxWidth,
+    height: lineCount * font.lineHeight,
+    lineWidths,
+    lineCount,
+    printedCharCount,
+    words,
+  };
+
+  function flushWord() {
+    printedCharCount += word.glyphs.length;
+    words.push(word);
+    word = {
+      glyphs: [],
+      width: 0,
+      startX: textOffsetX,
+      startY: textOffsetY,
+    };
+  }
+
+  function flushLine() {
+    lineWidths.push(textOffsetX);
+    line++;
+    maxWidth = Math.max(maxWidth, textOffsetX);
+    textOffsetX = 0;
+    textOffsetY -= font.lineHeight;
+  }
+
+  function insertSpaces(spaces: number) {
+    if (spaces < 1) spaces = 1;
+    textOffsetX += font.getXAdvance(WhitespaceKeyCodes.Space) * spaces;
+    if (wordWrap?.breakOn === "word" && textOffsetX >= wordWrap.emWidth) {
+      flushLine();
+    }
+    flushWord();
+  }
+}
+export function findLargestFontSize(
+  font: MsdfFont,
+  text: string,
+  size: Size,
+  formatting: TextFormatting,
+): number | undefined {
+  if (!formatting.fontSize) {
+    throw new Error("fontSize is required for shrinkToFit");
+  }
+  if (!formatting.shrinkToFit) {
+    throw new Error("shrinkToFit is required for findLargestFontSize");
+  }
+  // Binary search to find largest font size that fits
+  const minSize = formatting.shrinkToFit.minFontSize;
+  const maxSize = formatting.shrinkToFit.maxFontSize ?? formatting.fontSize;
+  const maxLines = formatting.shrinkToFit.maxLines ?? Number.POSITIVE_INFINITY;
+
+  const threshold = 0.5;
+  let low = minSize;
+  let high = maxSize;
+
+  while (high - low > threshold) {
+    // Stop when we get close enough
+    const testSize = (low + high) / 2;
+    const testMeasure = measureText(font, text, formatting.wordWrap);
+
+    const padding = formatting.shrinkToFit.padding ?? 0;
+
+    const scaledWidth = testMeasure.width * (testSize / font.lineHeight);
+    const scaledHeight = testMeasure.height * (testSize / font.lineHeight);
+    const fitsWidth = scaledWidth <= size.width - size.width * padding;
+    const fitsHeight = scaledHeight <= size.height - size.height * padding;
+    const fitsLines = testMeasure.lineCount <= maxLines;
+
+    if (fitsWidth && fitsHeight && fitsLines) {
+      low = testSize;
+    } else {
+      high = testSize;
+    }
+  }
+
+  return low;
+}

package/src/text/text.wgsl.ts

@@ -0,0 +1,149 @@
+export default /*wgsl*/ `
+// Adapted from: https://webgpu.github.io/webgpu-samples/?sample=textRenderingMsdf
+
+// Quad vertex positions for a character
+const pos = array(
+  vec2f(0, -1),
+  vec2f(1, -1),
+  vec2f(0,  0),
+  vec2f(1,  0),
+);
+
+// Debug colors for visualization
+const debugColors = array(
+  vec4f(1, 0, 0, 1),
+  vec4f(0, 1, 0, 1),
+  vec4f(0, 0, 1, 1),
+  vec4f(1, 1, 1, 1),
+);
+
+// Vertex input from GPU
+struct VertexInput {
+  @builtin(vertex_index) vertex: u32,
+  @builtin(instance_index) instance: u32,
+};
+
+// Output from vertex shader to fragment shader
+struct VertexOutput {
+  @builtin(position) position: vec4f,
+  @location(0) texcoord: vec2f,
+  @location(1) debugColor: vec4f,
+  @location(2) @interpolate(flat) instanceIndex: u32,
+};
+
+// Metadata for a single character glyph
+struct Char {
+  texOffset: vec2f, // Offset to top-left in MSDF texture (pixels)
+  texExtent: vec2f, // Size in texture (pixels)
+  size: vec2f,      // Glyph size in ems
+  offset: vec2f,    // Position offset in ems
+};
+
+// Metadata for a text block
+struct TextBlockDescriptor {
+  transform: mat3x3f,   // Text transform matrix (model matrix)
+  color: vec4f,         // Text color
+  fontSize: f32,        // Font size
+  blockWidth: f32,      // Total width of text block
+  blockHeight: f32,     // Total height of text block
+  bufferPosition: f32   // Index and length in textBuffer
+};
+
+// Font bindings
+@group(0) @binding(0) var fontTexture: texture_2d<f32>;
+@group(0) @binding(1) var fontSampler: sampler;
+@group(0) @binding(2) var<storage> chars: array<Char>;
+@group(0) @binding(3) var<uniform> fontData: vec4f; // Contains line height (x)
+
+// Text bindings
+@group(1) @binding(0) var<storage> texts: array<TextBlockDescriptor>;
+@group(1) @binding(1) var<storage> textBuffer: array<vec4f>; // Each vec4: xy = glyph pos, z = char index
+
+// Global uniforms
+@group(2) @binding(0) var<uniform> viewProjectionMatrix: mat3x3f;
+
+// Vertex shader
+@vertex
+fn vertexMain(input: VertexInput) -> VertexOutput {
+  // Because the instance index is used for character indexing, we are
+  // overloading the vertex index to store the instance of the text metadata.
+  //
+  // I.e...
+  // Vertex 0-4 = Instance 0, Vertex 0-4
+  // Vertex 4-8 = Instance 1, Vertex 0-4
+  // Vertex 8-12 = Instance 2, Vertex 0-4
+  let vertexIndex = input.vertex % 4;
+  let textIndex = input.vertex / 4;
+
+  let text = texts[textIndex];
+  let textElement = textBuffer[u32(text.bufferPosition) + input.instance];
+  let char = chars[u32(textElement.z)];
+
+  let lineHeight = fontData.x;
+  let textWidth = text.blockWidth;
+  let textHeight = text.blockHeight;
+
+  // Center text vertically; origin is mid-height
+  let offset = vec2f(0, -textHeight / 2);
+
+  // Glyph position in ems (quad pos * size + per-char offset)
+  let emPos = pos[vertexIndex] * char.size + char.offset + textElement.xy - offset;
+  let charPos = emPos * (text.fontSize / lineHeight);
+
+  var output: VertexOutput;
+  let transformedPosition = viewProjectionMatrix * text.transform * vec3f(charPos, 1);
+
+  output.position = vec4f(transformedPosition, 1);
+  output.texcoord = pos[vertexIndex] * vec2f(1, -1);
+  output.texcoord *= char.texExtent;
+  output.texcoord += char.texOffset;
+  output.debugColor = debugColors[vertexIndex];
+  output.instanceIndex = textIndex;
+  return output;
+
+  // To debug - hardcode quad in bottom right quarter of the screen:
+  // output.position = vec4f(pos[input.vertex], 0, 1);
+}
+
+// Signed distance function sampling for MSDF font rendering
+fn sampleMsdf(texcoord: vec2f) -> f32 {
+  let c = textureSample(fontTexture, fontSampler, texcoord);
+  return max(min(c.r, c.g), min(max(c.r, c.g), c.b));
+}
+
+// Fragment shader
+// Anti-aliasing technique by Paul Houx
+// more details here:
+// https://github.com/Chlumsky/msdfgen/issues/22#issuecomment-234958005
+@fragment
+fn fragmentMain(input: VertexOutput) -> @location(0) vec4f {
+  let text = texts[input.instanceIndex];
+
+  // pxRange (AKA distanceRange) comes from the msdfgen tool.
+  let pxRange = 4.0;
+  let texSize = vec2f(textureDimensions(fontTexture, 0));
+
+  let dx = texSize.x * length(vec2f(dpdxFine(input.texcoord.x), dpdyFine(input.texcoord.x)));
+  let dy = texSize.y * length(vec2f(dpdxFine(input.texcoord.y), dpdyFine(input.texcoord.y)));
+
+  let toPixels = pxRange * inverseSqrt(dx * dx + dy * dy);
+  let sigDist = sampleMsdf(input.texcoord) - 0.5;
+  let pxDist = sigDist * toPixels;
+
+  let edgeWidth = 0.5;
+  let alpha = smoothstep(-edgeWidth, edgeWidth, pxDist);
+
+  if (alpha < 0.001) {
+    discard;
+  }
+
+  let msdfColor = vec4f(text.color.rgb, text.color.a * alpha);
+  return msdfColor;
+
+  // Debug options:
+  // return text.color;
+  // return input.debugColor;
+  // return vec4f(1, 0, 1, 1); // hardcoded magenta
+  // return textureSample(fontTexture, fontSampler, input.texcoord);
+}
+`;