multi-gauge 0.1.0

package/src/gpu/TextAtlas.js

@@ -0,0 +1,304 @@
+const FONT_FAMILY = 'MultiGauge Inter';
+const FONT_URL = new URL('../assets/fonts/InterVariable.woff2', import.meta.url);
+const CHARACTERS = [...new Set(
+    Array.from({ length: 95 }, (_, index) => String.fromCharCode(index + 32)).join('')
+    + '°…µ·'
+)].join('');
+
+const STYLE_DEFINITIONS = Object.freeze([
+    { id: 'uiSmall', role: 'regular', logicalSize: 10, weight: 400 },
+    { id: 'uiMedium', role: 'regular', logicalSize: 11, weight: 400 },
+    { id: 'unitSmall', role: 'unit', logicalSize: 11, weight: 400 },
+    { id: 'unitMedium', role: 'unit', logicalSize: 12, weight: 400 },
+    { id: 'unitLarge', role: 'unit', logicalSize: 13, weight: 400 },
+    { id: 'labelSmall', role: 'label', logicalSize: 10, weight: 600 },
+    { id: 'labelMedium', role: 'label', logicalSize: 12, weight: 600 },
+    { id: 'valueSmall', role: 'value', logicalSize: 17, weight: 600, tabular: true },
+    { id: 'valueMedium', role: 'value', logicalSize: 23, weight: 500, tabular: true },
+    { id: 'valueLarge', role: 'value', logicalSize: 29, weight: 500, tabular: true },
+    { id: 'header', role: 'header', logicalSize: 16, weight: 600 }
+]);
+
+function nextPowerOfTwo(value) {
+    let result = 1;
+    while (result < value) {
+        result *= 2;
+    }
+    return result;
+}
+
+function makeCanvas(width, height) {
+    return typeof OffscreenCanvas === 'function'
+        ? new OffscreenCanvas(width, height)
+        : Object.assign(document.createElement('canvas'), { width, height });
+}
+
+function fontString(style, pixelRatio) {
+    return `${style.weight} ${style.logicalSize * pixelRatio}px "${FONT_FAMILY}"`;
+}
+
+function finiteMetric(value, fallback = 0) {
+    return Number.isFinite(value) ? value : fallback;
+}
+
+/** A DPR-aware bitmap atlas with a small set of fixed Inter typography styles. */
+export class TextAtlas {
+    static CHARACTERS = CHARACTERS;
+    static STYLES = STYLE_DEFINITIONS;
+
+    #device;
+    #pixelRatio;
+    #texture;
+    #view;
+    #sampler;
+    #styles = new Map();
+    #stylesByRole = new Map();
+    #styleCache = new Map();
+    #metricsCache = new Map();
+    #measureCache = new Map();
+    #fontFace;
+
+    constructor(device, pixelRatio = globalThis.devicePixelRatio || 1) {
+        this.#device = device;
+        this.#pixelRatio = Math.max(1, Number(pixelRatio) || 1);
+    }
+
+    get view() {
+        return this.#view;
+    }
+
+    get sampler() {
+        return this.#sampler;
+    }
+
+    get pixelRatio() {
+        return this.#pixelRatio;
+    }
+
+    style(role = 'regular', size = 10) {
+        const key = `${role}\0${size}`;
+        const cached = this.#styleCache.get(key);
+        if (cached) {
+            return cached;
+        }
+        const candidates = this.#stylesByRole.get(role) ?? this.#stylesByRole.get('regular');
+        const resolved = candidates.reduce((best, candidate) => {
+            const distance = Math.abs(candidate.logicalSize - size);
+            const bestDistance = Math.abs(best.logicalSize - size);
+            return distance < bestDistance
+                || (distance === bestDistance && candidate.logicalSize > best.logicalSize)
+                ? candidate
+                : best;
+        });
+        this.#styleCache.set(key, resolved);
+        return resolved;
+    }
+
+    glyph(character, role = 'regular', size = 10) {
+        const style = this.style(role, size);
+        return style.glyphs.get(character) ?? style.glyphs.get('?');
+    }
+
+    metrics(size, role = 'regular') {
+        const style = this.style(role, size);
+        const key = `${style.id}\0${size}`;
+        const cached = this.#metricsCache.get(key);
+        if (cached) {
+            return cached;
+        }
+        const scale = size / style.logicalSize / this.#pixelRatio;
+        const metrics = {
+            style: style.id,
+            ascent: style.ascent * scale,
+            descent: style.descent * scale,
+            lineHeight: style.lineHeight * scale
+        };
+        this.#metricsCache.set(key, metrics);
+        return metrics;
+    }
+
+    measure(text, size, role = 'regular') {
+        const style = this.style(role, size);
+        const value = String(text);
+        const key = `${style.id}\0${size}\0${value}`;
+        const cached = this.#measureCache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const scale = size / style.logicalSize / this.#pixelRatio;
+        let width = 0;
+        for (const character of value) {
+            width += (style.glyphs.get(character) ?? style.glyphs.get('?')).advance * scale;
+        }
+        if (this.#measureCache.size >= 8192) {
+            this.#measureCache.delete(this.#measureCache.keys().next().value);
+        }
+        this.#measureCache.set(key, width);
+        return width;
+    }
+
+    async initialize() {
+        await this.#loadFont();
+        const measurementCanvas = makeCanvas(1, 1);
+        const measurement = measurementCanvas.getContext('2d', { alpha: true });
+        measurement.textBaseline = 'alphabetic';
+        measurement.fontKerning = 'none';
+        const padding = Math.max(2, Math.ceil(this.#pixelRatio));
+        const styles = STYLE_DEFINITIONS.map((definition) => this.#measureStyle(
+            measurement,
+            definition,
+            padding
+        ));
+        const atlasWidth = 2048;
+        let x = 1;
+        let y = 1;
+        let rowHeight = 0;
+        for (const style of styles) {
+            for (const glyph of style.glyphs.values()) {
+                if (x + glyph.width + 1 > atlasWidth) {
+                    x = 1;
+                    y += rowHeight + 1;
+                    rowHeight = 0;
+                }
+                glyph.x = x;
+                glyph.y = y;
+                x += glyph.width + 1;
+                rowHeight = Math.max(rowHeight, glyph.height);
+            }
+        }
+        const atlasHeight = nextPowerOfTwo(y + rowHeight + 1);
+        const maxDimension = this.#device.limits?.maxTextureDimension2D ?? 8192;
+        if (atlasHeight > maxDimension || atlasWidth > maxDimension) {
+            throw new Error(`MultiGauge text atlas exceeds the GPU texture limit (${atlasWidth}×${atlasHeight}).`);
+        }
+
+        const canvas = makeCanvas(atlasWidth, atlasHeight);
+        const context = canvas.getContext('2d', { alpha: true });
+        context.clearRect(0, 0, atlasWidth, atlasHeight);
+        context.fillStyle = '#ffffff';
+        context.textBaseline = 'alphabetic';
+        context.fontKerning = 'none';
+        for (const style of styles) {
+            context.font = fontString(style, this.#pixelRatio);
+            for (const [character, glyph] of style.glyphs) {
+                if (character !== ' ') {
+                    context.fillText(
+                        character,
+                        glyph.x + padding + glyph.left,
+                        glyph.y + padding + glyph.ascent
+                    );
+                }
+                glyph.u0 = glyph.x / atlasWidth;
+                glyph.v0 = glyph.y / atlasHeight;
+                glyph.u1 = (glyph.x + glyph.width) / atlasWidth;
+                glyph.v1 = (glyph.y + glyph.height) / atlasHeight;
+            }
+            this.#styles.set(style.id, style);
+            const roleStyles = this.#stylesByRole.get(style.role) ?? [];
+            roleStyles.push(style);
+            roleStyles.sort((a, b) => a.logicalSize - b.logicalSize);
+            this.#stylesByRole.set(style.role, roleStyles);
+        }
+
+        this.#texture = this.#device.createTexture({
+            label: `MultiGauge Inter glyph atlas @${this.#pixelRatio}x`,
+            size: [atlasWidth, atlasHeight],
+            format: 'rgba8unorm',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
+                | GPUTextureUsage.RENDER_ATTACHMENT
+        });
+        this.#device.queue.copyExternalImageToTexture(
+            { source: canvas },
+            { texture: this.#texture },
+            [atlasWidth, atlasHeight]
+        );
+        this.#view = this.#texture.createView();
+        this.#sampler = this.#device.createSampler({
+            magFilter: 'linear',
+            minFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge'
+        });
+    }
+
+    destroy() {
+        this.#texture?.destroy();
+        this.#styleCache.clear();
+        this.#metricsCache.clear();
+        this.#measureCache.clear();
+        if (this.#fontFace && globalThis.document?.fonts) {
+            document.fonts.delete(this.#fontFace);
+        }
+    }
+
+    async #loadFont() {
+        if (typeof FontFace !== 'function' || !globalThis.document?.fonts) {
+            throw new Error('MultiGauge requires the CSS Font Loading API to build its Inter atlas.');
+        }
+        const face = new FontFace(FONT_FAMILY, `url("${FONT_URL.href}") format("woff2")`, {
+            style: 'normal',
+            weight: '100 900'
+        });
+        this.#fontFace = await face.load();
+        document.fonts.add(this.#fontFace);
+        await Promise.all([...new Set(STYLE_DEFINITIONS.map(({ weight }) => weight))]
+            .map((weight) => document.fonts.load(`${weight} 16px "${FONT_FAMILY}"`, 'Hgm0123°µ·')));
+        await document.fonts.ready;
+        for (const weight of new Set(STYLE_DEFINITIONS.map((style) => style.weight))) {
+            if (!document.fonts.check(`${weight} 16px "${FONT_FAMILY}"`, 'Hgm0123°µ·')) {
+                throw new Error(`Inter Variable weight ${weight} did not load for the MultiGauge atlas.`);
+            }
+        }
+    }
+
+    #measureStyle(context, definition, padding) {
+        const style = { ...definition, glyphs: new Map() };
+        context.font = fontString(style, this.#pixelRatio);
+        const records = [];
+        for (const character of CHARACTERS) {
+            const metrics = context.measureText(character);
+            const left = finiteMetric(metrics.actualBoundingBoxLeft);
+            const right = finiteMetric(metrics.actualBoundingBoxRight, metrics.width);
+            const ascent = Math.max(0, finiteMetric(metrics.actualBoundingBoxAscent,
+                style.logicalSize * this.#pixelRatio * 0.8));
+            const descent = Math.max(0, finiteMetric(metrics.actualBoundingBoxDescent,
+                style.logicalSize * this.#pixelRatio * 0.2));
+            const inkWidth = character === ' ' ? 0 : Math.max(1, Math.ceil(left + right));
+            const inkHeight = character === ' ' ? 0 : Math.max(1, Math.ceil(ascent + descent));
+            const record = {
+                character,
+                left,
+                ascent,
+                descent,
+                bearingLeft: left + padding,
+                bearingTop: ascent + padding,
+                width: Math.max(1, inkWidth + padding * 2),
+                height: Math.max(1, inkHeight + padding * 2),
+                advance: Math.max(1, metrics.width),
+                offsetX: 0
+            };
+            records.push(record);
+            style.glyphs.set(character, record);
+        }
+        if (style.tabular) {
+            const digitAdvance = Math.max(...[...'0123456789']
+                .map((digit) => style.glyphs.get(digit).advance));
+            for (const digit of '0123456789') {
+                const glyph = style.glyphs.get(digit);
+                glyph.offsetX = (digitAdvance - glyph.advance) / 2;
+                glyph.advance = digitAdvance;
+            }
+        }
+        const sample = context.measureText('Hgjpqy°µ');
+        style.ascent = Math.max(
+            finiteMetric(sample.fontBoundingBoxAscent),
+            ...records.map((record) => record.ascent)
+        );
+        style.descent = Math.max(
+            finiteMetric(sample.fontBoundingBoxDescent),
+            ...records.map((record) => record.descent)
+        );
+        style.lineHeight = style.ascent + style.descent;
+        return style;
+    }
+}

package/src/gpu/shaders.js

@@ -0,0 +1,212 @@
+export const SHAPE_SHADER = /* wgsl */ `
+struct Viewport {
+    size: vec2f,
+    _padding: vec2f,
+}
+
+struct VertexOutput {
+    @builtin(position) position: vec4f,
+    @location(0) local: vec2f,
+    @location(1) @interpolate(flat) instance: u32,
+}
+
+@group(0) @binding(0) var<storage, read> shapes: array<vec4f>;
+@group(0) @binding(1) var<storage, read> dynamics: array<vec4f>;
+@group(0) @binding(2) var<uniform> viewport: Viewport;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) vertex: u32, @builtin(instance_index) instance: u32) -> VertexOutput {
+    let corners = array<vec2f, 6>(
+        vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(-1.0, 1.0),
+        vec2f(-1.0, 1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0)
+    );
+    let geometry = shapes[instance * 5u];
+    let local = corners[vertex];
+    let pixel = geometry.xy + local * geometry.zw;
+    var output: VertexOutput;
+    output.position = vec4f(pixel.x / viewport.size.x * 2.0 - 1.0, 1.0 - pixel.y / viewport.size.y * 2.0, 0.0, 1.0);
+    output.local = local;
+    output.instance = instance;
+    return output;
+}
+
+fn roundedBox(point: vec2f, halfSize: vec2f, radius: f32) -> f32 {
+    let q = abs(point) - halfSize + vec2f(radius);
+    return length(max(q, vec2f(0.0))) + min(max(q.x, q.y), 0.0) - radius;
+}
+
+fn coverage(distance: f32, antialias: f32) -> f32 {
+    return 1.0 - smoothstep(-antialias, antialias, distance);
+}
+
+@fragment
+fn fragmentMain(input: VertexOutput) -> @location(0) vec4f {
+    let base = input.instance * 5u;
+    let geometry = shapes[base];
+    var rgba = shapes[base + 1u];
+    let parameters = shapes[base + 2u];
+    let extra = shapes[base + 3u];
+    let kind = u32(parameters.x + 0.5);
+    let gaugeIndex = u32(max(extra.y, 0.0) + 0.5);
+    let dynamicMode = u32(extra.z + 0.5);
+    let dynamic = dynamics[gaugeIndex * 2u];
+    let dynamicColor = dynamics[gaugeIndex * 2u + 1u];
+    let halfSize = geometry.zw;
+    let point = input.local * halfSize;
+    // This unconditional derivative keeps the transition close to one physical pixel.
+    let antialias = max(max(fwidth(point.x), fwidth(point.y)) * 0.5, 0.001);
+    var alpha = 0.0;
+
+    if (kind == 0u) {
+        let radius = parameters.y;
+        let border = parameters.z;
+        let distance = roundedBox(point, halfSize, radius);
+        alpha = coverage(distance, antialias);
+        if (border > 0.0) {
+            let inner = roundedBox(point, halfSize - vec2f(border), max(0.0, radius - border));
+            alpha = alpha * (1.0 - coverage(inner, antialias));
+        }
+        if (dynamicMode == 2u && input.local.x > dynamic.x * 2.0 - 1.0) {
+            discard;
+        }
+        if (dynamicMode == 3u && input.local.y < 1.0 - dynamic.x * 2.0) {
+            discard;
+        }
+        if (dynamicMode == 6u) {
+            rgba = dynamicColor;
+        }
+    } else if (kind == 1u) {
+        let radius = length(point);
+        let inner = parameters.w;
+        let outer = extra.x;
+        var endAngle = parameters.z;
+        if (dynamicMode == 1u) {
+            endAngle = mix(parameters.y, parameters.z, dynamic.x);
+        }
+        let angle = atan2(point.x, -point.y);
+        let tau = 6.28318530718;
+        var relative = angle - parameters.y;
+        relative = relative - floor(relative / tau) * tau;
+        var span = endAngle - parameters.y;
+        span = span - floor(span / tau) * tau;
+        if (abs(endAngle - parameters.y) >= tau - 0.001) {
+            span = tau;
+        }
+        let ring = max(inner - radius, radius - outer);
+        alpha = coverage(ring, antialias);
+        if (relative > span) {
+            discard;
+        }
+    } else if (kind == 2u) {
+        let distance = roundedBox(point, halfSize, min(halfSize.x, halfSize.y));
+        alpha = coverage(distance, antialias);
+        if (dynamicMode == 2u && input.local.x > dynamic.x * 2.0 - 1.0) {
+            discard;
+        }
+        if (dynamicMode == 3u && input.local.y < 1.0 - dynamic.x * 2.0) {
+            discard;
+        }
+    } else if (kind == 3u) {
+        var position = dynamic.x;
+        if (dynamicMode == 4u) {
+            let marker = abs(point.x - mix(-halfSize.x, halfSize.x, position));
+            alpha = coverage(marker - parameters.y, antialias);
+        } else {
+            let marker = abs(point.y - mix(halfSize.y, -halfSize.y, position));
+            alpha = coverage(marker - parameters.y, antialias);
+        }
+    } else if (kind == 4u) {
+        let angle = dynamic.x * 6.28318530718;
+        let direction = vec2f(sin(angle), -cos(angle));
+        let along = dot(point, direction);
+        let across = abs(point.x * direction.y - point.y * direction.x);
+        let distance = max(across - parameters.y, max(-along, along - parameters.z));
+        alpha = coverage(distance, antialias);
+    } else if (kind == 5u) {
+        let distance = length(point) - parameters.y;
+        alpha = coverage(distance, antialias);
+        if (dynamicMode == 6u) {
+            rgba = dynamicColor;
+        }
+    } else if (kind == 6u) {
+        let angle = dynamic.x * 6.28318530718;
+        let direction = vec2f(sin(angle), -cos(angle));
+        let along = dot(point, direction);
+        let across = point.x * direction.y - point.y * direction.x;
+        let markerPoint = vec2f(across, along - parameters.z);
+        let distance = roundedBox(
+            markerPoint,
+            vec2f(parameters.y, parameters.w),
+            parameters.y
+        );
+        alpha = coverage(distance, antialias);
+    } else if (kind == 7u) {
+        let angle = extra.x;
+        let direction = vec2f(sin(angle), -cos(angle));
+        let along = dot(point, direction);
+        let across = point.x * direction.y - point.y * direction.x;
+        let markerPoint = vec2f(across, along - parameters.z);
+        let distance = roundedBox(
+            markerPoint,
+            vec2f(parameters.y, parameters.w),
+            parameters.y
+        );
+        alpha = coverage(distance, antialias);
+    }
+
+    if (alpha <= 0.0) {
+        discard;
+    }
+    return vec4f(rgba.rgb, rgba.a * alpha);
+}
+`;
+
+export const TEXTURE_SHADER = /* wgsl */ `
+struct Viewport {
+    size: vec2f,
+    _padding: vec2f,
+}
+
+struct VertexOutput {
+    @builtin(position) position: vec4f,
+    @location(0) uv: vec2f,
+    @location(1) color: vec4f,
+}
+
+@group(0) @binding(0) var<storage, read> sprites: array<vec4f>;
+@group(0) @binding(1) var<uniform> viewport: Viewport;
+@group(0) @binding(2) var atlas: texture_2d<f32>;
+@group(0) @binding(3) var atlasSampler: sampler;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) vertex: u32, @builtin(instance_index) instance: u32) -> VertexOutput {
+    let corners = array<vec2f, 6>(
+        vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(-1.0, 1.0),
+        vec2f(-1.0, 1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0)
+    );
+    let base = instance * 4u;
+    let geometry = sprites[base];
+    let uvRect = sprites[base + 1u];
+    let rgba = sprites[base + 2u];
+    let transform = sprites[base + 3u];
+    let local = corners[vertex];
+    let offset = local * geometry.zw;
+    let rotated = vec2f(
+        offset.x * transform.x - offset.y * transform.y,
+        offset.x * transform.y + offset.y * transform.x
+    );
+    let pixel = geometry.xy + rotated;
+    let unit = local * 0.5 + vec2f(0.5);
+    var output: VertexOutput;
+    output.position = vec4f(pixel.x / viewport.size.x * 2.0 - 1.0, 1.0 - pixel.y / viewport.size.y * 2.0, 0.0, 1.0);
+    output.uv = mix(uvRect.xy, uvRect.zw, unit);
+    output.color = rgba;
+    return output;
+}
+
+@fragment
+fn fragmentMain(input: VertexOutput) -> @location(0) vec4f {
+    let sampled = textureSample(atlas, atlasSampler, input.uv);
+    return vec4f(input.color.rgb, input.color.a * sampled.a);
+}
+`;

package/src/index.js

@@ -0,0 +1,2 @@
+export { MultiGauge } from './MultiGauge.js';
+export { MultiGaugeError } from './errors.js';