Apps submit mutli-plane images with glyphs, rather than mere images

This commit is contained in:
James Babcock committed 2026-08-16 21:01:20 -07:00
1 parent df85fb4072
commit fdf683761e
22 files changed
+348 -101

No files matched your search

+8
View File
@@ -11,7 +11,15 @@ export type Glyph = {
bitmapRows: number[];
};
let nextFontFingerprintId = 1;
export class BdfFont {
/**
* Process-local identity for content fingerprints (fonts are cached
* singletons, so two draws with the same id + encoding are the same glyph
* bitmap). Only meaningful within one JS context; never persist it.
*/
readonly fingerprintId = nextFontFingerprintId++;
readonly ascent: number;
readonly descent: number;
readonly lineHeight: number;
+120 -18
View File
@@ -21,10 +21,31 @@ export function imageFromAsciiArt(lines: readonly string[], value = 255): GrayIm
return image;
}
/**
* One deferred glyph draw. Text drawn through drawGlyph/drawText/
* drawTextWrapped is retained here rather than baked into the pixel buffer,
* so the compositor can later ship glyphs as display-list references instead
* of pixels. (x, y) and value are the drawGlyph arguments (y is the top of
* the line; the baseline is y + font.ascent).
*/
export type PlacedGlyph = {
font: BdfFont;
glyph: Glyph;
x: number;
y: number;
value: number;
};
export class GrayImage {
readonly width: number;
readonly height: number;
readonly pixels: Uint8Array;
/**
* Deferred glyph draws, always rendered on top of the raster pixels
* regardless of draw order. An overlay that must cover text below it needs
* its own plane (see plane.ts) or must suppress the covered draws.
*/
private readonly glyphList: PlacedGlyph[] = [];
constructor(width: number, height: number, fill = 0) {
this.width = width;
@@ -33,14 +54,24 @@ export class GrayImage {
this.clear(fill);
}
get glyphs(): readonly PlacedGlyph[] {
return this.glyphList;
}
hasGlyphs(): boolean {
return this.glyphList.length > 0;
}
clone(): GrayImage {
const clone = new GrayImage(this.width, this.height, 0);
clone.pixels.set(this.pixels);
clone.glyphList.push(...this.glyphList);
return clone;
}
clear(value = 0): void {
this.pixels.fill(clampByte(value));
this.glyphList.length = 0;
}
setPixel(x: number, y: number, value: number): void {
@@ -107,7 +138,6 @@ export class GrayImage {
drawText(font: BdfFont, x: number, y: number, text: string, value: number): void {
let cursorX = x;
const fill = clampByte(value);
for (const char of text) {
if (char === "\n") {
cursorX = x;
@@ -116,7 +146,7 @@ export class GrayImage {
}
const glyph = font.getGlyph(char.codePointAt(0) ?? 32);
if (!glyph) continue;
this.drawGlyph(font, glyph, cursorX, y, fill);
this.drawGlyph(font, glyph, cursorX, y, value);
cursorX += glyph.dwidthX;
}
}
@@ -168,6 +198,23 @@ export class GrayImage {
this.pixels[ty * this.width + tx] = value;
}
}
// Carry the source's deferred glyphs along, translated into destination
// space. Membership in the copied rect is judged by the glyph's anchor
// (fine for the whole-image blits this is used for; a sub-rect blit can
// clip a glyph's overhang imperfectly).
if (source.glyphList.length) {
const offsetX = destX - srcX;
const offsetY = destY - srcY;
for (const placed of source.glyphList) {
if (
placed.x >= srcX && placed.x < srcX + copyWidth &&
placed.y >= srcY && placed.y < srcY + copyHeight
) {
this.glyphList.push({ ...placed, x: placed.x + offsetX, y: placed.y + offsetY });
}
}
}
}
fillRoundedRect(
@@ -251,31 +298,80 @@ export class GrayImage {
hash ^= this.pixels[i]!;
hash = Math.imul(hash, 16777619);
}
for (const placed of this.glyphList) {
hash = mixInt(hash, placed.font.fingerprintId);
hash = mixInt(hash, placed.glyph.encoding);
hash = mixInt(hash, placed.x);
hash = mixInt(hash, placed.y);
hash = mixInt(hash, placed.value);
}
return `fnv:${(hash >>> 0).toString(16)}`;
}
/**
* Snapshot of the full image as a single 8-bit-per-pixel grayscale buffer,
* row-major and top-to-bottom. The Java side turns this into whatever wire
* format the firmware currently expects (today: a 4bpp BMP), so all framing
* concerns stay on one side of the bridge.
* row-major and top-to-bottom, with any deferred glyphs baked in. The Java
* side turns this into whatever wire format the firmware currently expects
* (today: a 4bpp BMP), so all framing concerns stay on one side of the
* bridge.
*/
to8bppBuffer(): Uint8Array {
return Uint8Array.from(this.pixels);
if (!this.glyphList.length) {
return Uint8Array.from(this.pixels);
}
// withGlyphsBaked's buffer is a private temporary, safe to hand out.
return this.withGlyphsBaked().pixels;
}
private drawGlyph(font: BdfFont, glyph: Glyph, x: number, y: number, value: number): void {
const baselineY = y + font.ascent;
const top = baselineY - (glyph.bbxHeight + glyph.bbxY);
const left = x + glyph.bbxX;
const rowBitWidth = ((glyph.bbxWidth + 7) >> 3) << 3;
for (let row = 0; row < glyph.bbxHeight; row++) {
const bits = glyph.bitmapRows[row] ?? 0;
for (let col = 0; col < glyph.bbxWidth; col++) {
const shift = rowBitWidth - 1 - col;
if (((bits >> shift) & 1) !== 0) {
this.setPixelUnchecked(left + col, top + row, value);
}
/**
* Record a glyph draw. Deferred: the glyph joins the image's glyph list
* (rendered above all raster pixels) instead of being baked into the
* buffer.
*/
drawGlyph(font: BdfFont, glyph: Glyph, x: number, y: number, value: number): void {
this.glyphList.push({ font, glyph, x, y, value: clampByte(value) });
}
/**
* This image with its glyph list rasterized into the pixel buffer. Returns
* this image unchanged when there are no glyphs, otherwise a baked copy
* with an empty glyph list.
*/
withGlyphsBaked(): GrayImage {
if (!this.glyphList.length) return this;
const baked = new GrayImage(this.width, this.height, 0);
baked.pixels.set(this.pixels);
this.bakeGlyphsInto(baked, 0, 0);
return baked;
}
/** Rasterize this image's glyph list into target, translated by (dx, dy). */
bakeGlyphsInto(target: GrayImage, dx: number, dy: number): void {
for (const placed of this.glyphList) {
rasterizeGlyph(target, placed.font, placed.glyph, placed.x + dx, placed.y + dy, placed.value);
}
}
}
/** Bake one BDF glyph into an image's pixel buffer (y is the top of the line). */
function rasterizeGlyph(
target: GrayImage,
font: BdfFont,
glyph: Glyph,
x: number,
y: number,
value: number,
): void {
const baselineY = y + font.ascent;
const top = baselineY - (glyph.bbxHeight + glyph.bbxY);
const left = x + glyph.bbxX;
const rowBitWidth = ((glyph.bbxWidth + 7) >> 3) << 3;
for (let row = 0; row < glyph.bbxHeight; row++) {
const bits = glyph.bitmapRows[row] ?? 0;
for (let col = 0; col < glyph.bbxWidth; col++) {
const shift = rowBitWidth - 1 - col;
if (((bits >> shift) & 1) !== 0) {
target.setPixel(left + col, top + row, value);
}
}
}
@@ -285,6 +381,12 @@ function clampByte(value: number): number {
return Math.max(0, Math.min(255, Math.round(value)));
}
/** Fold a 32-bit int into an FNV-style running hash. */
function mixInt(hash: number, value: number): number {
hash ^= value | 0;
return Math.imul(hash, 16777619);
}
function roundedRectRowSpan(
row: number,
x: number,
+74
View File
@@ -0,0 +1,74 @@
import { GrayImage } from "./image";
/**
* The unit apps (and the shell) submit to the compositor: instead of one
* flattened image, a frame is an ordered array of planes, each an image plus
* placement metadata. Planes composite in array order, first at the bottom,
* with the shell's transparency convention: an 8-bit value of 0 is
* transparent, 1 is black (the two quantize to the same 4bpp shade, so
* reserving 0 costs nothing visible).
*
* This representation exists to carry structure the wire pipeline will later
* exploit: a plane's glyph list can become on-glasses display-list references
* (texture cache), and the offset can diverge per lens for stereo depth. For
* now the compositor boundary just flattens (flattenPlanes) and feeds the
* existing incremental-update and screen-preview pipeline.
*/
export type Plane = {
image: GrayImage;
/**
* Offset of the plane's top-left within the submitted frame. Applied
* identically to both lenses for now; a per-lens divergence (stereo depth
* for floating overlays) is the planned extension.
*/
x: number;
y: number;
};
/** Wrap a single full-frame image as a one-plane submission. */
export function singlePlane(image: GrayImage): Plane[] {
return [{ image, x: 0, y: 0 }];
}
/**
* Flatten planes into one image: for each plane in order, blend its raster
* (0 = transparent) and then its glyphs on top. A later plane's raster covers
* an earlier plane's glyphs — this is what lets an overlay plane occlude text
* beneath it, which raster drawn into the *same* image cannot do (glyphs
* always render above their own image's raster).
*
* The output size defaults to the planes' joint extent (in practice the base
* plane's size, since overlays share its dimensions).
*/
export function flattenPlanes(
planes: readonly Plane[],
size?: { width: number; height: number },
): GrayImage {
const width = size?.width ?? Math.max(1, ...planes.map((plane) => plane.x + plane.image.width));
const height = size?.height ?? Math.max(1, ...planes.map((plane) => plane.y + plane.image.height));
const only = planes.length === 1 ? planes[0]! : undefined;
if (only && only.x === 0 && only.y === 0 && only.image.width === width && only.image.height === height) {
return only.image.withGlyphsBaked();
}
const target = new GrayImage(width, height, 0);
for (const plane of planes) {
// Baking first (rather than bitBlt's glyph carry-over) is what enforces
// the plane ordering: the next plane's raster must be able to cover this
// plane's glyphs.
target.bitBlt(plane.image.withGlyphsBaked(), plane.x, plane.y, { transparentZero: true });
}
return target;
}
/**
* Stable identifier for a plane stack's composited content: equal
* fingerprints mean an equal flattened frame. Feeds the same dedupe paths
* that single-image fingerprints did.
*/
export function planesFingerprint(planes: readonly Plane[]): string {
return planes
.map((plane) => `${plane.x},${plane.y}+${plane.image.width}x${plane.image.height}:${plane.image.fingerprint()}`)
.join("|");
}