vgpu-render 0.1.0 → 0.2.0

package/dist/text-font.js

@@ -15,6 +15,7 @@
  */
 import { FIRA_MONO_MEDIUM_SUBSET_BASE64, FIRA_MONO_MEDIUM_SUBSET_TTF_BASE64 } from "./assets/fira-mono-medium-subset.js";
 import { coverageToSdf, DEFAULT_SDF_RANGE } from "./text-sdf.js";
+import { fontFaceKey } from "./text-layout.js";
 /**
  * Family name the bundled font is registered under. It is deliberately not `"Fira Mono"` so
  * a locally installed face can never shadow the inlined one.
@@ -36,6 +37,38 @@ export function decodeBase64Bytes(base64) {
         bytes[index] = binary.charCodeAt(index);
     return bytes;
 }
+const registeredFamilies = new Map();
+/**
+ * Registers a family whose weights are separate faces, each carrying its own `weight` descriptor.
+ *
+ * This is the only way to get more than one drawn weight out of Canvas2D: the font shorthand carries a
+ * single synthesised bold step, and `font-variation-settings` does not exist there, but the browser
+ * does select a face by the weight it was registered with. Registering the same family once per
+ * weight therefore turns `weight: 700` into a real bold face instead of an emboldened regular one.
+ *
+ * Idempotent per family, like `loadDefaultFont`, and browser-only.
+ */
+export function loadFontFaces(family, faces) {
+    const existing = registeredFamilies.get(family);
+    if (existing !== undefined)
+        return existing;
+    const registration = registerFontFaces(family, faces);
+    registeredFamilies.set(family, registration);
+    return registration;
+}
+async function registerFontFaces(family, faces) {
+    const fonts = typeof document === "undefined" ? undefined : document.fonts;
+    if (fonts === undefined || typeof FontFace === "undefined") {
+        throw new Error("registering a font family requires a browser environment");
+    }
+    const loaded = faces.map(async (face) => {
+        const definition = new FontFace(family, decodeBase64Bytes(face.woff2Base64), { weight: String(face.weight) });
+        await definition.load();
+        return definition;
+    });
+    for (const definition of await Promise.all(loaded))
+        fonts.add(definition);
+}
 /** Decodes the inlined WOFF2 bytes of the bundled font, which is what `FontFace` takes. */
 export function decodeEmbeddedFont() {
     return decodeBase64Bytes(FIRA_MONO_MEDIUM_SUBSET_BASE64);
@@ -66,6 +99,25 @@ async function registerDefaultFont() {
     await face.load();
     fonts.add(face);
 }
+/**
+ * The CSS font shorthand that selects `face` at `fontSize`.
+ *
+ * Order follows the shorthand's grammar — style, weight, stretch, size, family — because Canvas2D
+ * parses the value as one. Two of the axes are conditional:
+ *
+ * - `font-stretch` keywords are only kept by the parser when the face has a `wdth` axis. A static
+ *   face drops the keyword and draws every stop identically, which is why the bundled subset cannot
+ *   show a `FontWidth` difference at all.
+ * - `italic` is the only slant Canvas2D keeps; `oblique <angle>` reads back as plain `italic`.
+ *
+ * A weight the loaded face does not carry is synthesised by the browser (one emboldened step, which
+ * keeps the advance), so `weight` at least changes what is drawn for the bundled static face.
+ */
+export function canvasFontString(face, fontSize) {
+    const style = face.style === "italic" ? "italic " : "";
+    const stretch = face.width === "normal" ? "" : `${face.width} `;
+    return `${style}${face.weight} ${stretch}${fontSize}px "${face.family}"`;
+}
 /**
  * Canvas2D glyph source, doubling as the layout `TextMeasurer` so the canvas is only set up
  * once per canvas-configured face and every `measureText` result is cached.
@@ -109,16 +161,16 @@ export class CanvasGlyphRasterizer {
         }
         return this.#surface;
     }
-    #font(fontFamily, fontSize) {
-        return `${fontSize}px "${fontFamily}"`;
+    #font(face, fontSize) {
+        return canvasFontString(face, fontSize);
     }
-    verticalMetrics(fontFamily, fontSize) {
-        const key = `${fontFamily}|${fontSize}`;
+    verticalMetrics(face, fontSize) {
+        const key = `${fontFaceKey(face)}|${fontSize}`;
         const cached = this.#vertical.get(key);
         if (cached !== undefined)
             return cached;
         const context = this.#ensureSurface().context;
-        context.font = this.#font(fontFamily, fontSize);
+        context.font = this.#font(face, fontSize);
         const metrics = context.measureText("M");
         const ascent = metrics.fontBoundingBoxAscent > 0 ? metrics.fontBoundingBoxAscent : fontSize * FALLBACK_ASCENT_RATIO;
         const descent = metrics.fontBoundingBoxDescent > 0 ? metrics.fontBoundingBoxDescent : fontSize * FALLBACK_DESCENT_RATIO;
@@ -126,13 +178,13 @@ export class CanvasGlyphRasterizer {
         this.#vertical.set(key, value);
         return value;
     }
-    glyphMetrics(character, fontFamily, fontSize) {
-        const key = `${fontFamily}|${fontSize}|${character}`;
+    glyphMetrics(character, face, fontSize) {
+        const key = `${fontFaceKey(face)}|${fontSize}|${character}`;
         const cached = this.#metrics.get(key);
         if (cached !== undefined)
             return cached;
         const context = this.#ensureSurface().context;
-        context.font = this.#font(fontFamily, fontSize);
+        context.font = this.#font(face, fontSize);
         const metrics = context.measureText(character);
         const bearingLeft = -metrics.actualBoundingBoxLeft;
         const value = {
@@ -145,10 +197,10 @@ export class CanvasGlyphRasterizer {
         this.#metrics.set(key, value);
         return value;
     }
-    rasterize(character, fontFamily, rasterSize) {
+    rasterize(character, face, rasterSize) {
         // The raster size *is* the face size here: `measureText` and the fill both work in the texels the
         // atlas will store, and the layout's own measurements never pass through this path.
-        const glyph = this.glyphMetrics(character, fontFamily, rasterSize);
+        const glyph = this.glyphMetrics(character, face, rasterSize);
         if (!(glyph.width > 0) || !(glyph.height > 0))
             return undefined;
         // The ink box is fractional; the mask rounds up so no edge pixel is lost.
@@ -160,7 +212,7 @@ export class CanvasGlyphRasterizer {
             canvas.height = Math.max(canvas.height, height);
         }
         context.clearRect(0, 0, width, height);
-        context.font = this.#font(fontFamily, rasterSize);
+        context.font = this.#font(face, rasterSize);
         context.textAlign = "left";
         context.textBaseline = "alphabetic";
         context.fillStyle = "#fff";

package/dist/text-layout.d.ts

@@ -40,12 +40,62 @@ export type GlyphMetrics = {
     /** Ink box top edge relative to the baseline, y down: positive is below the baseline. */
     readonly bearingTop: number;
 };
+/**
+ * reference `FontStyle`, minus `Oblique(angle)`.
+ *
+ * Canvas2D accepts the `italic` keyword in its font shorthand and silently drops the slant angle —
+ * `oblique 14deg` reads back as `italic` — so an oblique angle could not be honoured and is left out
+ * rather than accepted and ignored. A face without an italic face is slanted by the browser.
+ */
+export type TextFontStyle = "normal" | "italic";
+/**
+ * reference `FontWidth` stops, spelled as the CSS `font-stretch` keywords Canvas2D understands.
+ *
+ * reference takes a percentage (`FontWidth::SEMI_CONDENSED` is 87.5), but Canvas2D rejects a percentage in
+ * the font shorthand and only accepts these nine keywords. The axis is inert unless the face actually
+ * carries a `wdth` axis: a static face like the bundled subset keeps the keyword out of its resolved
+ * font, so every stop draws the same width there.
+ */
+export type TextFontWidth = "ultra-condensed" | "extra-condensed" | "condensed" | "semi-condensed" | "normal" | "semi-expanded" | "expanded" | "extra-expanded" | "ultra-expanded";
+/** Every `FontWidth` stop, in reference order. */
+export declare const TEXT_FONT_WIDTHS: readonly TextFontWidth[];
+/** Every `FontStyle` variant this implementation can honour. */
+export declare const TEXT_FONT_STYLES: readonly TextFontStyle[];
+/** reference `FontWeight::NORMAL`, and the value the CSS font shorthand defaults to. */
+export declare const DEFAULT_FONT_WEIGHT = 400;
+/** reference `FontWeight` range, 1 to 1000. */
+export declare const MIN_FONT_WEIGHT = 1;
+export declare const MAX_FONT_WEIGHT = 1000;
+/**
+ * One face request: everything that decides which glyphs a character rasterises to.
+ *
+ * This is the unit the glyph atlas keys on, so two blocks that differ only in weight cannot share a
+ * rasterised glyph. A source with a single fixed face reports the parts it cannot change through
+ * `GlyphRasterizer.faceKey`.
+ */
+export type FontFace = {
+    readonly family: string;
+    readonly weight: number;
+    readonly style: TextFontStyle;
+    readonly width: TextFontWidth;
+};
+/** A face with the axes left optional, which is how callers and spans express one. */
+export type FontFaceOptions = {
+    readonly family: string;
+    readonly weight?: number | undefined;
+    readonly style?: TextFontStyle | undefined;
+    readonly width?: TextFontWidth | undefined;
+};
+/** Folds a face's optional axes into the complete request the measurer and the atlas take. */
+export declare function resolveFontFace(options: FontFaceOptions): FontFace;
+/** Every field that can change which glyphs are rasterised, joined into one cache key. */
+export declare function fontFaceKey(face: FontFace): string;
 /** Source of glyph metrics. The browser implementation measures through Canvas2D. */
 export interface TextMeasurer {
-    /** Vertical metrics for a `fontSize`-sized face of `fontFamily`. */
-    verticalMetrics(fontFamily: string, fontSize: number): VerticalMetrics;
+    /** Vertical metrics for a `fontSize`-sized instance of `face`. */
+    verticalMetrics(face: FontFace, fontSize: number): VerticalMetrics;
     /** Metrics for one character. Whitespace returns a zero-size ink box. */
-    glyphMetrics(character: string, fontFamily: string, fontSize: number): GlyphMetrics;
+    glyphMetrics(character: string, face: FontFace, fontSize: number): GlyphMetrics;
 }
 /** Reference `Justify`. `start`/`end` resolve to left/right in this LTR-only layout. */
 export type TextJustify = "left" | "center" | "right" | "justified" | "start" | "end";
@@ -62,6 +112,9 @@ export type TextSpanInput = {
     readonly color?: Rgba;
     readonly fontSize?: number;
     readonly fontFamily?: string;
+    readonly weight?: number;
+    readonly style?: TextFontStyle;
+    readonly width?: TextFontWidth;
 };
 /** reference `LineHeight` default, `RelativeToFont(1.2)`. */
 export declare const DEFAULT_LINE_HEIGHT_SCALE = 1.2;
@@ -69,6 +122,12 @@ export type TextLayoutOptions = {
     readonly color: Rgba;
     readonly fontSize: number;
     readonly fontFamily: string;
+    /** Block default for `FontFace.weight`; spans override it. */
+    readonly weight?: number | undefined;
+    /** Block default for `FontFace.style`; spans override it. */
+    readonly style?: TextFontStyle | undefined;
+    /** Block default for `FontFace.width`; spans override it. */
+    readonly width?: TextFontWidth | undefined;
     /**
      * Absolute line height in layout units, reference `LineHeight::Px`. When omitted the line height
      * is `lineHeightScale` times the line's own largest font size, which is reference
@@ -95,7 +154,7 @@ export type TextLayoutOptions = {
 /** One laid-out glyph, ready to become an instance once its atlas rectangle is known. */
 export type PositionedGlyph = {
     readonly character: string;
-    readonly fontFamily: string;
+    readonly face: FontFace;
     readonly fontSize: number;
     readonly color: Rgba;
     /** Ink box centre relative to the block's anchor point, y down. */

package/dist/text-layout.js

@@ -18,6 +18,38 @@
  * Layout happens in one local space: origin at the block's anchor point, x to the right and
  * **y down**, matching Canvas2D. The renderer flips y for spaces where up is +y.
  */
+/** Every `FontWidth` stop, in reference order. */
+export const TEXT_FONT_WIDTHS = [
+    "ultra-condensed",
+    "extra-condensed",
+    "condensed",
+    "semi-condensed",
+    "normal",
+    "semi-expanded",
+    "expanded",
+    "extra-expanded",
+    "ultra-expanded",
+];
+/** Every `FontStyle` variant this implementation can honour. */
+export const TEXT_FONT_STYLES = ["normal", "italic"];
+/** reference `FontWeight::NORMAL`, and the value the CSS font shorthand defaults to. */
+export const DEFAULT_FONT_WEIGHT = 400;
+/** reference `FontWeight` range, 1 to 1000. */
+export const MIN_FONT_WEIGHT = 1;
+export const MAX_FONT_WEIGHT = 1000;
+/** Folds a face's optional axes into the complete request the measurer and the atlas take. */
+export function resolveFontFace(options) {
+    return {
+        family: options.family,
+        weight: options.weight ?? DEFAULT_FONT_WEIGHT,
+        style: options.style ?? "normal",
+        width: options.width ?? "normal",
+    };
+}
+/** Every field that can change which glyphs are rasterised, joined into one cache key. */
+export function fontFaceKey(face) {
+    return `${face.family}|${face.weight}|${face.width}|${face.style}`;
+}
 const TEXT_ANCHORS = {
     center: [0.5, 0.5],
     "top-left": [0, 0],
@@ -144,13 +176,20 @@ function measureLine(characters, letterSpacing) {
     while (end > 0 && content[end - 1].isSpace)
         end--;
     let fontSize = 0;
-    for (const character of content)
-        fontSize = Math.max(fontSize, character.fontSize);
+    let face;
+    // The line box follows the line's own largest run, so the face recorded here is that run's.
+    for (const character of content) {
+        if (character.fontSize > fontSize) {
+            fontSize = character.fontSize;
+            face = character.face;
+        }
+    }
     return {
         characters: content.slice(0, end),
         advance: runWidth(content.slice(0, end), letterSpacing),
         fullAdvance: runWidth(content, letterSpacing),
         fontSize,
+        face,
         isEmpty: content.length === 0,
     };
 }
@@ -241,20 +280,31 @@ function countSpaces(characters) {
  */
 export function layoutText(spans, options, measurer) {
     const items = [];
+    const blockFace = resolveFontFace({
+        family: options.fontFamily,
+        weight: options.weight,
+        style: options.style,
+        width: options.width,
+    });
     for (const span of spans) {
         const fontSize = span.fontSize ?? options.fontSize;
-        const fontFamily = span.fontFamily ?? options.fontFamily;
+        const face = resolveFontFace({
+            family: span.fontFamily ?? options.fontFamily,
+            weight: span.weight ?? options.weight,
+            style: span.style ?? options.style,
+            width: span.width ?? options.width,
+        });
         const color = span.color ?? options.color;
         // Iterating the string yields code points, so surrogate pairs stay whole.
         for (const character of span.text) {
             if (character === "\n") {
-                items.push({ character, fontFamily, fontSize, color, advance: 0, width: 0, height: 0, bearingLeft: 0, bearingTop: 0, isSpace: false });
+                items.push({ character, face, fontSize, color, advance: 0, width: 0, height: 0, bearingLeft: 0, bearingTop: 0, isSpace: false });
                 continue;
             }
-            const metrics = measurer.glyphMetrics(character, fontFamily, fontSize);
+            const metrics = measurer.glyphMetrics(character, face, fontSize);
             items.push({
                 character,
-                fontFamily,
+                face,
                 fontSize,
                 color,
                 advance: metrics.advance,
@@ -273,7 +323,7 @@ export function layoutText(spans, options, measurer) {
     // instead of being held to the block's default size.
     const boxes = lines.map((line) => {
         const fontSize = line.fontSize > 0 ? line.fontSize : options.fontSize;
-        const base = measurer.verticalMetrics(options.fontFamily, fontSize);
+        const base = measurer.verticalMetrics(line.face ?? blockFace, fontSize);
         const height = options.lineHeight ?? (options.lineHeightScale ?? DEFAULT_LINE_HEIGHT_SCALE) * fontSize;
         return { base, height, halfLeading: (height - (base.ascent + base.descent)) / 2 };
     });
@@ -310,7 +360,7 @@ export function layoutText(spans, options, measurer) {
             if (character.width > 0 && character.height > 0) {
                 glyphs.push({
                     character: character.character,
-                    fontFamily: character.fontFamily,
+                    face: character.face,
                     fontSize: character.fontSize,
                     color: character.color,
                     center: [offsetX + penX + character.bearingLeft + character.width / 2, offsetY + baseline + character.bearingTop + character.height / 2],

package/dist/text-msdf-baked.d.ts

@@ -15,7 +15,7 @@
  * baking: one set of texels serves every size.
  */
 import { type GlyphRasterizer, type RasterizedGlyph } from "./text-font.js";
-import type { GlyphMetrics, TextMeasurer, VerticalMetrics } from "./text-layout.js";
+import type { FontFace, GlyphMetrics, TextMeasurer, VerticalMetrics } from "./text-layout.js";
 export declare class BakedMsdfRasterizer implements GlyphRasterizer, TextMeasurer {
     #private;
     readonly encoding: "msdf";
@@ -30,7 +30,12 @@ export declare class BakedMsdfRasterizer implements GlyphRasterizer, TextMeasure
     get ready(): boolean;
     /** Decompresses the inlined page. Idempotent, so calling it per frame is harmless. */
     load(): Promise<void>;
-    verticalMetrics(_fontFamily: string, fontSize: number): VerticalMetrics;
-    glyphMetrics(character: string, _fontFamily: string, fontSize: number): GlyphMetrics;
-    rasterize(character: string, fontFamily: string, fontSize: number): RasterizedGlyph | undefined;
+    /**
+     * The page stores one face, so the axes cannot change a sliced glyph. Keying on the family alone
+     * keeps the atlas from packing the same texels once per requested weight.
+     */
+    readonly faceKey: (face: FontFace) => string;
+    verticalMetrics(_face: FontFace, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, _face: FontFace, fontSize: number): GlyphMetrics;
+    rasterize(character: string, face: FontFace, fontSize: number): RasterizedGlyph | undefined;
 }

package/dist/text-msdf-baked.js

@@ -48,11 +48,16 @@ export class BakedMsdfRasterizer {
         }
         this.#page = page;
     }
-    verticalMetrics(_fontFamily, fontSize) {
+    /**
+     * The page stores one face, so the axes cannot change a sliced glyph. Keying on the family alone
+     * keeps the atlas from packing the same texels once per requested weight.
+     */
+    faceKey = (face) => face.family;
+    verticalMetrics(_face, fontSize) {
         const scale = fontSize / BAKED_MSDF_BAKE_SIZE;
         return { ascent: BAKED_MSDF_ASCENT * scale, descent: BAKED_MSDF_DESCENT * scale };
     }
-    glyphMetrics(character, _fontFamily, fontSize) {
+    glyphMetrics(character, _face, fontSize) {
         const key = `${fontSize}|${character}`;
         const cached = this.#metrics.get(key);
         if (cached !== undefined)
@@ -71,7 +76,7 @@ export class BakedMsdfRasterizer {
         this.#metrics.set(key, value);
         return value;
     }
-    rasterize(character, fontFamily, fontSize) {
+    rasterize(character, face, fontSize) {
         const page = this.#page;
         if (page === undefined)
             throw new Error("BakedMsdfRasterizer.load() must resolve before glyphs are requested");
@@ -96,7 +101,7 @@ export class BakedMsdfRasterizer {
         }
         // The texels stay at their baked size; only the placement scales with the requested font size.
         const scale = fontSize / BAKED_MSDF_BAKE_SIZE;
-        const metrics = this.glyphMetrics(character, fontFamily, fontSize);
+        const metrics = this.glyphMetrics(character, face, fontSize);
         return {
             width,
             height,

package/dist/text-msdf-font.d.ts

@@ -13,7 +13,7 @@
 import type { Font } from "opentype.js";
 import { type GlyphRasterizer, type RasterizedGlyph } from "./text-font.js";
 import { type OutlineSegment } from "./text-msdf.js";
-import type { GlyphMetrics, TextMeasurer, VerticalMetrics } from "./text-layout.js";
+import type { FontFace, GlyphMetrics, TextMeasurer, VerticalMetrics } from "./text-layout.js";
 /** The subset of `opentype.js`'s path commands this source understands. */
 type OutlineCommand = {
     readonly type: "M";
@@ -72,8 +72,14 @@ export declare class OutlineGlyphRasterizer implements GlyphRasterizer, TextMeas
     constructor(options?: OutlineGlyphRasterizerOptions);
     /** The face this source reads, for callers that want to name it. */
     get font(): Font;
-    verticalMetrics(_fontFamily: string, fontSize: number): VerticalMetrics;
-    glyphMetrics(character: string, _fontFamily: string, fontSize: number): GlyphMetrics;
-    rasterize(character: string, _fontFamily: string, rasterSize: number): RasterizedGlyph | undefined;
+    /**
+     * This source holds one parsed buffer, so a weight, width or slant it was not built with cannot
+     * change the outlines it returns. Keying on the family alone keeps the atlas from caching the same
+     * glyph once per axis value.
+     */
+    readonly faceKey: (face: FontFace) => string;
+    verticalMetrics(_face: FontFace, fontSize: number): VerticalMetrics;
+    glyphMetrics(character: string, _face: FontFace, fontSize: number): GlyphMetrics;
+    rasterize(character: string, _face: FontFace, rasterSize: number): RasterizedGlyph | undefined;
 }
 export {};

package/dist/text-msdf-font.js

@@ -105,7 +105,13 @@ export class OutlineGlyphRasterizer {
         const bottom = Number.isFinite(box.y2) ? box.y2 : top;
         return { left, top, width: Math.max(0, right - left), height: Math.max(0, bottom - top) };
     }
-    verticalMetrics(_fontFamily, fontSize) {
+    /**
+     * This source holds one parsed buffer, so a weight, width or slant it was not built with cannot
+     * change the outlines it returns. Keying on the family alone keeps the atlas from caching the same
+     * glyph once per axis value.
+     */
+    faceKey = (face) => face.family;
+    verticalMetrics(_face, fontSize) {
         const cached = this.#vertical.get(String(fontSize));
         if (cached !== undefined)
             return cached;
@@ -114,7 +120,7 @@ export class OutlineGlyphRasterizer {
         this.#vertical.set(String(fontSize), value);
         return value;
     }
-    glyphMetrics(character, _fontFamily, fontSize) {
+    glyphMetrics(character, _face, fontSize) {
         const key = `${fontSize}|${character}`;
         const cached = this.#metrics.get(key);
         if (cached !== undefined)
@@ -131,7 +137,7 @@ export class OutlineGlyphRasterizer {
         this.#metrics.set(key, value);
         return value;
     }
-    rasterize(character, _fontFamily, rasterSize) {
+    rasterize(character, _face, rasterSize) {
         const ink = this.#inkBox(character, rasterSize);
         if (!(ink.width > 0) || !(ink.height > 0))
             return undefined;

package/dist/vector-math.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Small vector helpers shared by the geometry generators and the example layouts.
+ *
+ * These live in the library rather than next to the gallery scenes because
+ * `geometry-generators.ts` needs them, and a library module must not reach into
+ * the example code.
+ */
+import type { Vec3 } from "./frame-draw-list.js";
+export declare function normalizeVector(p: Vec3): Vec3;
+export declare function crossVector(a: Vec3, b: Vec3): Vec3;
+/** Right-handed Rodrigues rotation, equivalent to reference `Vector3.rotated(axis, angle)`. */
+export declare function rotateAroundAxis(p: Vec3, axis: Vec3, angle: number): Vec3;
+export type CircleBasis = {
+    readonly x: Vec3;
+    readonly y: Vec3;
+    readonly z: Vec3;
+};
+/** Orthonormal basis for a circle in the plane whose normal is `normal`. */
+export declare function circleBasis(normal: Vec3, angle: number): CircleBasis;

package/dist/vector-math.js

@@ -0,0 +1,37 @@
+/**
+ * Small vector helpers shared by the geometry generators and the example layouts.
+ *
+ * These live in the library rather than next to the gallery scenes because
+ * `geometry-generators.ts` needs them, and a library module must not reach into
+ * the example code.
+ */
+export function normalizeVector(p) {
+    const length = Math.hypot(p[0], p[1], p[2]) || 1;
+    return [p[0] / length, p[1] / length, p[2] / length];
+}
+export function crossVector(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+/** Right-handed Rodrigues rotation, equivalent to reference `Vector3.rotated(axis, angle)`. */
+export function rotateAroundAxis(p, axis, angle) {
+    const a = normalizeVector(axis);
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const dot = p[0] * a[0] + p[1] * a[1] + p[2] * a[2];
+    const cross = crossVector(a, p);
+    return [
+        p[0] * cos + cross[0] * sin + a[0] * dot * (1 - cos),
+        p[1] * cos + cross[1] * sin + a[1] * dot * (1 - cos),
+        p[2] * cos + cross[2] * sin + a[2] * dot * (1 - cos),
+    ];
+}
+/** Orthonormal basis for a circle in the plane whose normal is `normal`. */
+export function circleBasis(normal, angle) {
+    const n = normalizeVector(normal);
+    const reference = Math.abs(n[0]) > 0.95 ? [0, 0, 1] : [1, 0, 0];
+    const projection = reference[0] * n[0] + reference[1] * n[1] + reference[2] * n[2];
+    const planar = [reference[0] - n[0] * projection, reference[1] - n[1] * projection, reference[2] - n[2] * projection];
+    const widthAxis = normalizeVector(rotateAroundAxis(normalizeVector(planar), n, angle));
+    const heightAxis = normalizeVector(crossVector(n, widthAxis));
+    return { x: widthAxis, y: heightAxis, z: n };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgpu-render",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "WebGPU debug-draw, gizmo, infinite grid and text layer built on vgpu",
   "license": "MIT",
   "type": "module",