@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/color.js

@@ -0,0 +1,41 @@
+/**
+ * Colour helpers. The renderer works in **linear** RGB (HDR allowed, values > 1 glow).
+ * Author colours as sRGB hex and convert with `hex()`.
+ */
+export function srgbToLinear(c) {
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+export function linearToSrgb(c) {
+    return c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055;
+}
+/**
+ * Parse `#rgb`, `#rrggbb` or `#rrggbbaa` (sRGB) into linear RGBA, optionally scaled by
+ * `intensity` (HDR multiplier on RGB, alpha untouched).
+ */
+export function hex(value, intensity = 1) {
+    let h = value.startsWith('#') ? value.slice(1) : value;
+    if (h.length === 3 || h.length === 4) {
+        h = h
+            .split('')
+            .map((ch) => ch + ch)
+            .join('');
+    }
+    const n = (i) => Number.parseInt(h.slice(i, i + 2), 16) / 255;
+    if (!/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(h))
+        throw new Error(`hex(): bad colour ${value}`);
+    const a = h.length === 8 ? n(6) : 1;
+    return [
+        srgbToLinear(n(0)) * intensity,
+        srgbToLinear(n(2)) * intensity,
+        srgbToLinear(n(4)) * intensity,
+        a,
+    ];
+}
+/** Linear RGBA from components (no conversion). */
+export function rgba(r, g, b, a = 1) {
+    return [r, g, b, a];
+}
+/** Scale RGB by `k` (alpha untouched). Returns a new array. */
+export function scaleRgb(c, k) {
+    return [c[0] * k, c[1] * k, c[2] * k, c[3] ?? 1];
+}

package/dist/render/compressed.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Block-compressed textures (ws/render-5): which compression families the device has
+ * (`RendererCaps`), the features to ask an adapter for, and `uploadKtx2`, which puts a parsed
+ * KTX2 file (`@thunderclap-engine/engine/assets` `parseKtx2`) on the GPU in its own format, every mip
+ * level written with its block-aligned row pitch. No transcoder: a Basis Universal (BasisLZ /
+ * UASTC) or supercompressed payload, or a format the device lacks, throws
+ * `CompressedTextureError`.
+ */
+import { type Ktx2Texture } from '../assets/ktx2.js';
+import { Texture } from './texture.js';
+/** A block-compression feature family. */
+export type CompressionFamily = 'bc' | 'etc2' | 'astc';
+/** The WebGPU feature of each family. */
+export declare const COMPRESSION_FEATURES: Readonly<Record<CompressionFamily, GPUFeatureName>>;
+/** What the renderer's device can do beyond core WebGPU (`renderer.caps`). */
+export interface RendererCaps {
+    /** The compressed texture families the device was created with. */
+    readonly compressed: Readonly<Record<CompressionFamily, boolean>>;
+}
+/** Anything with a feature set: a `GPUAdapter` or a `GPUDevice`. */
+interface HasFeatures {
+    readonly features?: {
+        has(name: string): boolean;
+    };
+}
+/**
+ * The compression features `adapter` offers, to spread into `requestDevice`'s
+ * `requiredFeatures` (a device only gets the features it asks for):
+ * `adapter.requestDevice({ requiredFeatures: [...compressionFeatures(adapter)] })`.
+ */
+export declare function compressionFeatures(adapter: HasFeatures): GPUFeatureName[];
+/** The caps of `device`, read from its features (none on a device without a feature set). */
+export declare function rendererCaps(device: HasFeatures): RendererCaps;
+/** Why `uploadKtx2` could not upload a file: names the format and the device's caps. */
+export declare class CompressedTextureError extends Error {
+    /** The file's WebGPU format, or `vk:<VkFormat>` when WebGPU has none. */
+    readonly format: string;
+    /** The family the format needs, or null (no WebGPU twin, or a payload to transcode). */
+    readonly family: CompressionFamily | null;
+    readonly caps: RendererCaps;
+    constructor(message: string, format: string, family: CompressionFamily | null, caps: RendererCaps);
+}
+/** Block footprint of a format: texels per block in x and y, and bytes per block. */
+export interface BlockInfo {
+    width: number;
+    height: number;
+    bytes: number;
+    /** The feature family it needs, or null for an uncompressed format. */
+    family: CompressionFamily | null;
+}
+/**
+ * The block footprint of `format`: 4×4 blocks of 8 bytes (BC1, BC4, ETC2 RGB8 / RGB8A1, EAC
+ * R11) or 16 (BC2/3/5/6H/7, ETC2 RGBA8, EAC RG11), ASTC's W×H blocks of 16 bytes, and 1×1
+ * "blocks" of a texel for the uncompressed formats. Null for a format it does not know.
+ */
+export declare function blockInfo(format: GPUTextureFormat): BlockInfo | null;
+/** Options of `uploadKtx2`. */
+export interface UploadKtx2Options {
+    /**
+     * Upload as the sRGB (true) or linear (false) twin of the file's format, when it has one: a
+     * colour map stored as `bc7-rgba-unorm` reads as `bc7-rgba-unorm-srgb` with `srgb: true`.
+     * Default: the file's own format.
+     */
+    srgb?: boolean;
+    /** Texture label. Default `'ktx2'`. */
+    label?: string;
+}
+/** What `uploadKtx2` needs of a renderer: its device and caps. */
+export interface CompressedUploadTarget {
+    readonly device: GPUDevice;
+    readonly caps: RendererCaps;
+}
+/** One level's copy: its block-aligned pitch, rows and copy extent (`ktx2LevelLayout`). */
+export interface Ktx2LevelLayout {
+    bytesPerRow: number;
+    rowsPerImage: number;
+    /** The copy extent in texels: the level's size rounded up to whole blocks. */
+    width: number;
+    height: number;
+    /** Bytes one image (layer or face) of the level holds. */
+    imageBytes: number;
+}
+/**
+ * The copy layout of mip level `level` of a `width × height` texture in blocks of `block`:
+ * `bytesPerRow = ceil(w / bw) · blockBytes`, `rowsPerImage = ceil(h / bh)`, the extent rounded up
+ * to whole blocks (a 2×2 mip of a BC texture is copied as one 4×4 block).
+ */
+export declare function ktx2LevelLayout(width: number, height: number, level: number, block: BlockInfo): Ktx2LevelLayout;
+/**
+ * Upload a parsed KTX2 file as a `Texture` in its own format (`ktx2ToWebGpuFormat`, through
+ * `opts.srgb`'s colour space): a 2D texture, or a 2D array for a file with layers or cube faces
+ * (layer-major, faces within). Every level the file carries is written with
+ * `queue.writeTexture` at its block-aligned `bytesPerRow` (`ktx2LevelLayout`); the texture has
+ * exactly that many mips. The result binds anywhere a `TextureLike` does (a standard
+ * material's map).
+ *
+ * Throws `CompressedTextureError` when the payload needs a transcoder (BasisLZ, UASTC,
+ * `vkFormat` 0, or Zstd / ZLIB supercompression: none is bundled), when WebGPU has no such
+ * format, or when the device lacks the format's family (`renderer.caps.compressed`; the
+ * message names the format and the caps). Throws `Error` for a 3D texture, a block-compressed
+ * level 0 that is not whole blocks, or a level shorter than its layout.
+ */
+export declare function uploadKtx2(renderer: CompressedUploadTarget, ktx2: Ktx2Texture, opts?: UploadKtx2Options): Texture;
+export {};

package/dist/render/compressed.js

@@ -0,0 +1,248 @@
+/**
+ * Block-compressed textures (ws/render-5): which compression families the device has
+ * (`RendererCaps`), the features to ask an adapter for, and `uploadKtx2`, which puts a parsed
+ * KTX2 file (`@thunderclap-engine/engine/assets` `parseKtx2`) on the GPU in its own format, every mip
+ * level written with its block-aligned row pitch. No transcoder: a Basis Universal (BasisLZ /
+ * UASTC) or supercompressed payload, or a format the device lacks, throws
+ * `CompressedTextureError`.
+ */
+import { ktx2ToWebGpuFormat } from '../assets/ktx2.js';
+import { Texture } from './texture.js';
+/** The WebGPU feature of each family. */
+export const COMPRESSION_FEATURES = {
+    bc: 'texture-compression-bc',
+    etc2: 'texture-compression-etc2',
+    astc: 'texture-compression-astc',
+};
+/**
+ * The compression features `adapter` offers, to spread into `requestDevice`'s
+ * `requiredFeatures` (a device only gets the features it asks for):
+ * `adapter.requestDevice({ requiredFeatures: [...compressionFeatures(adapter)] })`.
+ */
+export function compressionFeatures(adapter) {
+    const out = [];
+    const f = adapter.features;
+    if (!f || typeof f.has !== 'function')
+        return out;
+    for (const k of ['bc', 'etc2', 'astc']) {
+        if (f.has(COMPRESSION_FEATURES[k]))
+            out.push(COMPRESSION_FEATURES[k]);
+    }
+    return out;
+}
+/** The caps of `device`, read from its features (none on a device without a feature set). */
+export function rendererCaps(device) {
+    const f = device.features;
+    const has = (k) => !!f && typeof f.has === 'function' && f.has(COMPRESSION_FEATURES[k]);
+    return { compressed: { bc: has('bc'), etc2: has('etc2'), astc: has('astc') } };
+}
+/** Why `uploadKtx2` could not upload a file: names the format and the device's caps. */
+export class CompressedTextureError extends Error {
+    /** The file's WebGPU format, or `vk:<VkFormat>` when WebGPU has none. */
+    format;
+    /** The family the format needs, or null (no WebGPU twin, or a payload to transcode). */
+    family;
+    caps;
+    constructor(message, format, family, caps) {
+        super(message);
+        this.name = 'CompressedTextureError';
+        this.format = format;
+        this.family = family;
+        this.caps = caps;
+    }
+}
+const PLAIN_BYTES = {
+    r8unorm: 1,
+    r8snorm: 1,
+    r8uint: 1,
+    r8sint: 1,
+    rg8unorm: 2,
+    rg8snorm: 2,
+    rg8uint: 2,
+    rg8sint: 2,
+    r16uint: 2,
+    r16sint: 2,
+    r16float: 2,
+    depth16unorm: 2,
+    rgba8unorm: 4,
+    'rgba8unorm-srgb': 4,
+    rgba8snorm: 4,
+    rgba8uint: 4,
+    rgba8sint: 4,
+    bgra8unorm: 4,
+    'bgra8unorm-srgb': 4,
+    rgb10a2unorm: 4,
+    rg11b10ufloat: 4,
+    rgb9e5ufloat: 4,
+    rg16uint: 4,
+    rg16sint: 4,
+    rg16float: 4,
+    r32uint: 4,
+    r32sint: 4,
+    r32float: 4,
+    depth32float: 4,
+    rgba16uint: 8,
+    rgba16sint: 8,
+    rgba16float: 8,
+    rg32uint: 8,
+    rg32sint: 8,
+    rg32float: 8,
+    rgba32uint: 16,
+    rgba32sint: 16,
+    rgba32float: 16,
+};
+/**
+ * The block footprint of `format`: 4×4 blocks of 8 bytes (BC1, BC4, ETC2 RGB8 / RGB8A1, EAC
+ * R11) or 16 (BC2/3/5/6H/7, ETC2 RGBA8, EAC RG11), ASTC's W×H blocks of 16 bytes, and 1×1
+ * "blocks" of a texel for the uncompressed formats. Null for a format it does not know.
+ */
+export function blockInfo(format) {
+    const f = format;
+    if (f.startsWith('bc')) {
+        const eight = f.startsWith('bc1-') || f.startsWith('bc4-');
+        return { width: 4, height: 4, bytes: eight ? 8 : 16, family: 'bc' };
+    }
+    if (f.startsWith('etc2-')) {
+        return { width: 4, height: 4, bytes: f.startsWith('etc2-rgba8') ? 16 : 8, family: 'etc2' };
+    }
+    if (f.startsWith('eac-')) {
+        return { width: 4, height: 4, bytes: f.startsWith('eac-rg11') ? 16 : 8, family: 'etc2' };
+    }
+    if (f.startsWith('astc-')) {
+        const m = /^astc-(\d+)x(\d+)-/.exec(f);
+        if (!m)
+            return null;
+        return { width: Number(m[1]), height: Number(m[2]), bytes: 16, family: 'astc' };
+    }
+    const n = PLAIN_BYTES[f];
+    return n ? { width: 1, height: 1, bytes: n, family: null } : null;
+}
+/** `format` in sRGB (`srgb` true) or linear (false) form, when it has that twin. */
+function withColorSpace(format, srgb) {
+    if (srgb === undefined)
+        return format;
+    const f = format;
+    if (srgb) {
+        if (f.endsWith('-srgb'))
+            return format;
+        const twin = `${f}-srgb`;
+        return SRGB_TWINS.has(twin) ? twin : format;
+    }
+    return (f.endsWith('-srgb') ? f.slice(0, -5) : f);
+}
+/** The formats that have an `-srgb` form. */
+const SRGB_TWINS = new Set([
+    'rgba8unorm-srgb',
+    'bgra8unorm-srgb',
+    'bc1-rgba-unorm-srgb',
+    'bc2-rgba-unorm-srgb',
+    'bc3-rgba-unorm-srgb',
+    'bc7-rgba-unorm-srgb',
+    'etc2-rgb8unorm-srgb',
+    'etc2-rgb8a1unorm-srgb',
+    'etc2-rgba8unorm-srgb',
+    ...[
+        '4x4',
+        '5x4',
+        '5x5',
+        '6x5',
+        '6x6',
+        '8x5',
+        '8x6',
+        '8x8',
+        '10x5',
+        '10x6',
+        '10x8',
+        '10x10',
+        '12x10',
+        '12x12',
+    ].map((s) => `astc-${s}-unorm-srgb`),
+]);
+/**
+ * The copy layout of mip level `level` of a `width × height` texture in blocks of `block`:
+ * `bytesPerRow = ceil(w / bw) · blockBytes`, `rowsPerImage = ceil(h / bh)`, the extent rounded up
+ * to whole blocks (a 2×2 mip of a BC texture is copied as one 4×4 block).
+ */
+export function ktx2LevelLayout(width, height, level, block) {
+    const w = Math.max(1, width >> level);
+    const h = Math.max(1, height >> level);
+    const bx = Math.ceil(w / block.width);
+    const by = Math.ceil(h / block.height);
+    const bytesPerRow = bx * block.bytes;
+    return {
+        bytesPerRow,
+        rowsPerImage: by,
+        width: bx * block.width,
+        height: by * block.height,
+        imageBytes: bytesPerRow * by,
+    };
+}
+/**
+ * Upload a parsed KTX2 file as a `Texture` in its own format (`ktx2ToWebGpuFormat`, through
+ * `opts.srgb`'s colour space): a 2D texture, or a 2D array for a file with layers or cube faces
+ * (layer-major, faces within). Every level the file carries is written with
+ * `queue.writeTexture` at its block-aligned `bytesPerRow` (`ktx2LevelLayout`); the texture has
+ * exactly that many mips. The result binds anywhere a `TextureLike` does (a standard
+ * material's map).
+ *
+ * Throws `CompressedTextureError` when the payload needs a transcoder (BasisLZ, UASTC,
+ * `vkFormat` 0, or Zstd / ZLIB supercompression: none is bundled), when WebGPU has no such
+ * format, or when the device lacks the format's family (`renderer.caps.compressed`; the
+ * message names the format and the caps). Throws `Error` for a 3D texture, a block-compressed
+ * level 0 that is not whole blocks, or a level shorter than its layout.
+ */
+export function uploadKtx2(renderer, ktx2, opts = {}) {
+    const caps = renderer.caps;
+    const capsText = () => {
+        const c = caps.compressed;
+        const on = ['bc', 'etc2', 'astc'].filter((k) => c[k]);
+        return on.length ? on.join(', ') : 'none';
+    };
+    if (ktx2.supercompression !== 'none' || ktx2.vkFormat === 0 || ktx2.levels.length === 0) {
+        const what = ktx2.supercompression !== 'none' ? ktx2.supercompression : 'basis';
+        throw new CompressedTextureError(`uploadKtx2: the ${what} payload needs a transcoder (none is bundled); compressed caps: ${capsText()}`, `vk:${ktx2.vkFormat}`, null, caps);
+    }
+    const fileFormat = ktx2ToWebGpuFormat(ktx2.vkFormat);
+    if (!fileFormat) {
+        throw new CompressedTextureError(`uploadKtx2: VkFormat ${ktx2.vkFormat} has no WebGPU format; compressed caps: ${capsText()}`, `vk:${ktx2.vkFormat}`, null, caps);
+    }
+    const format = withColorSpace(fileFormat, opts.srgb);
+    const block = blockInfo(format);
+    if (!block) {
+        throw new CompressedTextureError(`uploadKtx2: format ${format} is not uploadable; compressed caps: ${capsText()}`, format, null, caps);
+    }
+    if (block.family && !caps.compressed[block.family]) {
+        throw new CompressedTextureError(`uploadKtx2: format ${format} needs ${COMPRESSION_FEATURES[block.family]}, which the device lacks; compressed caps: ${capsText()}`, format, block.family, caps);
+    }
+    if (ktx2.depth > 1)
+        throw new Error('uploadKtx2: 3D textures are not supported');
+    const width = Math.max(1, ktx2.width);
+    const height = Math.max(1, ktx2.height);
+    if (width % block.width !== 0 || height % block.height !== 0) {
+        throw new Error(`uploadKtx2: ${width}×${height} is not whole ${block.width}×${block.height} blocks of ${format}`);
+    }
+    const images = Math.max(1, ktx2.layers) * Math.max(1, ktx2.faces);
+    const array = ktx2.layers > 0 || ktx2.faces > 1;
+    const levels = ktx2.levels;
+    const tex = new Texture(renderer.device, {
+        width,
+        height,
+        ...(array ? { layers: images } : {}),
+        mipLevelCount: levels.length,
+        format,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        label: opts.label ?? 'ktx2',
+    });
+    const queue = renderer.device.queue;
+    for (let i = 0; i < levels.length; i++) {
+        const lv = ktx2LevelLayout(width, height, i, block);
+        const bytes = levels[i].bytes;
+        const need = lv.imageBytes * images;
+        if (bytes.byteLength < need) {
+            tex.destroy();
+            throw new Error(`uploadKtx2: level ${i} holds ${bytes.byteLength} bytes, needs ${need}`);
+        }
+        queue.writeTexture({ texture: tex.texture, mipLevel: i }, bytes, { offset: 0, bytesPerRow: lv.bytesPerRow, rowsPerImage: lv.rowsPerImage }, [lv.width, lv.height, images]);
+    }
+    return tex;
+}

package/dist/render/diagnostics.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GPU error reporting. Every WGSL compile error and uncaptured validation error goes through
+ * `reportGpuError`, which logs loudly and keeps the last messages for tests/debug overlays.
+ */
+export declare const gpuDiagnostics: {
+    /** Most recent error messages (bounded). */
+    errors: string[];
+    /** Total errors reported since load. */
+    errorCount: number;
+};
+export declare function reportGpuError(message: string): void;
+/** Subscribe to GPU errors (e.g. to show a dev toast). Returns unsubscribe. */
+export declare function onGpuError(fn: (message: string) => void): () => void;
+/** Route uncaptured device errors (validation, OOM, internal) to `reportGpuError`. */
+export declare function installGpuErrorLogging(device: GPUDevice): void;

package/dist/render/diagnostics.js

@@ -0,0 +1,43 @@
+/**
+ * GPU error reporting. Every WGSL compile error and uncaptured validation error goes through
+ * `reportGpuError`, which logs loudly and keeps the last messages for tests/debug overlays.
+ */
+const MAX_KEPT = 50;
+export const gpuDiagnostics = {
+    /** Most recent error messages (bounded). */
+    errors: [],
+    /** Total errors reported since load. */
+    errorCount: 0,
+};
+const listeners = new Set();
+export function reportGpuError(message) {
+    console.error(message);
+    gpuDiagnostics.errorCount++;
+    gpuDiagnostics.errors.push(message);
+    if (gpuDiagnostics.errors.length > MAX_KEPT)
+        gpuDiagnostics.errors.shift();
+    for (const fn of listeners)
+        fn(message);
+}
+/** Subscribe to GPU errors (e.g. to show a dev toast). Returns unsubscribe. */
+export function onGpuError(fn) {
+    listeners.add(fn);
+    return () => listeners.delete(fn);
+}
+const logged = new WeakSet();
+/** Route uncaptured device errors (validation, OOM, internal) to `reportGpuError`. */
+export function installGpuErrorLogging(device) {
+    // Several renderers may share a device (e.g. a SnapshotRenderer); log each error once.
+    if (logged.has(device))
+        return;
+    logged.add(device);
+    device.addEventListener('uncapturederror', (ev) => {
+        const e = ev.error;
+        const kind = e instanceof GPUValidationError
+            ? 'validation'
+            : e instanceof GPUOutOfMemoryError
+                ? 'out-of-memory'
+                : 'internal';
+        reportGpuError(`[gpu] uncaptured ${kind} error: ${e.message}`);
+    });
+}

package/dist/render/dynamic-resolution.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Dynamic resolution: a small controller that turns GPU frame-time samples into a render
+ * scale. Pure (no GPU, no clock): feed it `sample(gpuMs, nowMs)` and apply the returned scale
+ * with `Renderer.setResolution({ scale })` when it changes.
+ *
+ * Design goals: steady image, no pumping.
+ * - Drops only after a sustained over-budget window (`dropAfterMs`), one step at a time.
+ * - Raises only after a longer window of clear headroom (`raiseAfterMs`), and only when the
+ *   predicted cost at the higher scale (time ∝ pixels ∝ scale²) stays under
+ *   `budgetMs × raiseMargin`. That gap between drop and raise thresholds is the hysteresis.
+ * - A cooldown after every change lets the new size settle before the next decision.
+ * - A raise that is followed quickly by a drop "burns" that level: the controller will not try
+ *   to raise past it again for `burnMs`, so a scene that sits right at the edge settles
+ *   instead of oscillating.
+ */
+export interface DynamicResolutionOptions {
+    /** GPU time budget per frame (ms). Default 14 (headroom under a 16.7 ms vsync). */
+    budgetMs?: number;
+    /** Lowest scale. Default 0.5. */
+    minScale?: number;
+    /** Highest scale. Default 1. */
+    maxScale?: number;
+    /** Step per change. Default 0.1. */
+    step?: number;
+    /** Sustained over-budget time before dropping (ms). Default 1000. */
+    dropAfterMs?: number;
+    /** Sustained headroom before raising (ms). Default 3000. */
+    raiseAfterMs?: number;
+    /** Predicted time at the higher scale must be below budget × this. Default 0.85. */
+    raiseMargin?: number;
+    /** Quiet time after any change (ms). Default 1500. */
+    cooldownMs?: number;
+    /** How long a level that dropped right after a raise stays off limits (ms). Default 20000. */
+    burnMs?: number;
+    /** Smoothing for the time estimate, 0..1 (weight of each new sample). Default 0.2. */
+    smoothing?: number;
+}
+export declare class DynamicResolution {
+    readonly budgetMs: number;
+    readonly minScale: number;
+    readonly maxScale: number;
+    private readonly step;
+    private readonly dropAfterMs;
+    private readonly raiseAfterMs;
+    private readonly raiseMargin;
+    private readonly cooldownMs;
+    private readonly burnMs;
+    private readonly smoothing;
+    private _scale;
+    private ema;
+    private overSince;
+    private underSince;
+    private lastChange;
+    private lastRaise;
+    /** Scale above which we will not raise until `ceilingUntil`. */
+    private ceiling;
+    private ceilingUntil;
+    constructor(opts?: DynamicResolutionOptions);
+    /** Current scale. */
+    get scale(): number;
+    /** Smoothed GPU time (ms), or -1 before the first sample. */
+    get estimateMs(): number;
+    /** True when the scale is at its floor and frames are still over budget. */
+    get saturated(): boolean;
+    /** Forget history and return to `scale` (default max), e.g. on a scene change. */
+    reset(scale?: number, nowMs?: number): void;
+    /** Feed a GPU time sample. Returns the (possibly new) scale. */
+    sample(gpuMs: number, nowMs: number): number;
+    private change;
+}

package/dist/render/dynamic-resolution.js

@@ -0,0 +1,126 @@
+/**
+ * Dynamic resolution: a small controller that turns GPU frame-time samples into a render
+ * scale. Pure (no GPU, no clock): feed it `sample(gpuMs, nowMs)` and apply the returned scale
+ * with `Renderer.setResolution({ scale })` when it changes.
+ *
+ * Design goals: steady image, no pumping.
+ * - Drops only after a sustained over-budget window (`dropAfterMs`), one step at a time.
+ * - Raises only after a longer window of clear headroom (`raiseAfterMs`), and only when the
+ *   predicted cost at the higher scale (time ∝ pixels ∝ scale²) stays under
+ *   `budgetMs × raiseMargin`. That gap between drop and raise thresholds is the hysteresis.
+ * - A cooldown after every change lets the new size settle before the next decision.
+ * - A raise that is followed quickly by a drop "burns" that level: the controller will not try
+ *   to raise past it again for `burnMs`, so a scene that sits right at the edge settles
+ *   instead of oscillating.
+ */
+export class DynamicResolution {
+    budgetMs;
+    minScale;
+    maxScale;
+    step;
+    dropAfterMs;
+    raiseAfterMs;
+    raiseMargin;
+    cooldownMs;
+    burnMs;
+    smoothing;
+    _scale;
+    ema = -1;
+    overSince = -1;
+    underSince = -1;
+    lastChange = Number.NEGATIVE_INFINITY;
+    lastRaise = Number.NEGATIVE_INFINITY;
+    /** Scale above which we will not raise until `ceilingUntil`. */
+    ceiling = Number.POSITIVE_INFINITY;
+    ceilingUntil = Number.NEGATIVE_INFINITY;
+    constructor(opts = {}) {
+        this.budgetMs = opts.budgetMs ?? 14;
+        this.minScale = opts.minScale ?? 0.5;
+        this.maxScale = opts.maxScale ?? 1;
+        this.step = opts.step ?? 0.1;
+        this.dropAfterMs = opts.dropAfterMs ?? 1000;
+        this.raiseAfterMs = opts.raiseAfterMs ?? 3000;
+        this.raiseMargin = opts.raiseMargin ?? 0.85;
+        this.cooldownMs = opts.cooldownMs ?? 1500;
+        this.burnMs = opts.burnMs ?? 20000;
+        this.smoothing = opts.smoothing ?? 0.2;
+        this._scale = this.maxScale;
+    }
+    /** Current scale. */
+    get scale() {
+        return this._scale;
+    }
+    /** Smoothed GPU time (ms), or -1 before the first sample. */
+    get estimateMs() {
+        return this.ema;
+    }
+    /** True when the scale is at its floor and frames are still over budget. */
+    get saturated() {
+        return this._scale <= this.minScale + 1e-6 && this.overSince >= 0;
+    }
+    /** Forget history and return to `scale` (default max), e.g. on a scene change. */
+    reset(scale = this.maxScale, nowMs = Number.NEGATIVE_INFINITY) {
+        this._scale = clamp(scale, this.minScale, this.maxScale);
+        this.ema = -1;
+        this.overSince = -1;
+        this.underSince = -1;
+        this.lastChange = nowMs;
+    }
+    /** Feed a GPU time sample. Returns the (possibly new) scale. */
+    sample(gpuMs, nowMs) {
+        if (!(gpuMs >= 0) || !Number.isFinite(gpuMs))
+            return this._scale;
+        // Samples right after a change describe the old size; let them flush.
+        if (nowMs - this.lastChange < this.cooldownMs) {
+            this.ema = gpuMs;
+            this.overSince = -1;
+            this.underSince = -1;
+            return this._scale;
+        }
+        this.ema = this.ema < 0 ? gpuMs : this.ema + (gpuMs - this.ema) * this.smoothing;
+        if (this.ema > this.budgetMs) {
+            this.underSince = -1;
+            if (this.overSince < 0)
+                this.overSince = nowMs;
+            if (nowMs - this.overSince >= this.dropAfterMs && this._scale > this.minScale + 1e-6) {
+                // A drop soon after a raise means that level is too expensive: remember it.
+                if (nowMs - this.lastRaise < this.raiseAfterMs + this.cooldownMs) {
+                    this.ceiling = this._scale - 1e-6;
+                    this.ceilingUntil = nowMs + this.burnMs;
+                }
+                // Drop by enough to get under budget, at least one step, at most three.
+                const want = this._scale * Math.sqrt((this.budgetMs * this.raiseMargin) / this.ema);
+                const steps = clamp(Math.ceil((this._scale - want) / this.step), 1, 3);
+                this.change(this._scale - steps * this.step, nowMs);
+                this.overSince = nowMs;
+            }
+            return this._scale;
+        }
+        this.overSince = -1;
+        const next = Math.min(this.maxScale, this._scale + this.step);
+        const predicted = this.ema * (next / this._scale) ** 2;
+        const blocked = nowMs < this.ceilingUntil && next > this.ceiling;
+        if (next > this._scale + 1e-6 && !blocked && predicted < this.budgetMs * this.raiseMargin) {
+            if (this.underSince < 0)
+                this.underSince = nowMs;
+            if (nowMs - this.underSince >= this.raiseAfterMs) {
+                this.change(next, nowMs);
+                this.lastRaise = nowMs;
+            }
+        }
+        else {
+            this.underSince = -1;
+        }
+        return this._scale;
+    }
+    change(scale, nowMs) {
+        // Snap to the step grid so repeated changes don't accumulate float drift.
+        const snapped = Math.round(scale / this.step) * this.step;
+        this._scale = clamp(Number(snapped.toFixed(4)), this.minScale, this.maxScale);
+        this.lastChange = nowMs;
+        this.underSince = -1;
+    }
+}
+function clamp(x, lo, hi) {
+    return Math.min(hi, Math.max(lo, x));
+}