@motion-core/motion-gpu 0.2.0 → 0.4.0

package/dist/core/renderer.d.ts

@@ -1,4 +1,14 @@
 import type { Renderer, RendererOptions } from './types.js';
+/**
+ * Computes dirty float ranges between two uniform snapshots.
+ *
+ * Adjacent dirty ranges separated by a gap smaller than or equal to
+ * {@link DIRTY_RANGE_MERGE_GAP} are merged to reduce `writeBuffer` calls.
+ */
+export declare function findDirtyFloatRanges(previous: Float32Array, next: Float32Array, mergeGapThreshold?: number): Array<{
+    start: number;
+    count: number;
+}>;
 /**
  * Creates the WebGPU renderer used by `FragCanvas`.
  *

package/dist/core/renderer.js

@@ -78,9 +78,45 @@ async function assertCompilation(module, options) {
         ...(options?.defineBlockSource !== undefined
             ? { defineBlockSource: options.defineBlockSource }
             : {}),
-        materialSource: options?.materialSource ?? null
+        materialSource: options?.materialSource ?? null,
+        ...(options?.runtimeContext !== undefined ? { runtimeContext: options.runtimeContext } : {})
     });
 }
+function toSortedUniqueStrings(values) {
+    return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
+}
+function buildPassGraphSnapshot(passes) {
+    const declaredPasses = passes ?? [];
+    let enabledPassCount = 0;
+    const inputs = [];
+    const outputs = [];
+    for (const pass of declaredPasses) {
+        if (pass.enabled === false) {
+            continue;
+        }
+        enabledPassCount += 1;
+        const needsSwap = pass.needsSwap ?? true;
+        const input = pass.input ?? 'source';
+        const output = pass.output ?? (needsSwap ? 'target' : 'source');
+        inputs.push(input);
+        outputs.push(output);
+    }
+    return {
+        passCount: declaredPasses.length,
+        enabledPassCount,
+        inputs: toSortedUniqueStrings(inputs),
+        outputs: toSortedUniqueStrings(outputs)
+    };
+}
+function buildShaderCompilationRuntimeContext(options) {
+    const passList = options.getPasses?.() ?? options.passes;
+    const renderTargetMap = options.getRenderTargets?.() ?? options.renderTargets;
+    return {
+        ...(options.materialSignature ? { materialSignature: options.materialSignature } : {}),
+        passGraph: buildPassGraphSnapshot(passList),
+        activeRenderTargets: Object.keys(renderTargetMap ?? {}).sort((a, b) => a.localeCompare(b))
+    };
+}
 /**
  * Creates a 1x1 white fallback texture used before user textures become available.
  */
@@ -182,10 +218,19 @@ function createBindGroupLayoutEntries(textureBindings) {
     }
     return entries;
 }
+/**
+ * Maximum gap (in floats) between two dirty ranges that triggers merge.
+ *
+ * Set to 4 (16 bytes) which covers one vec4f alignment slot.
+ */
+const DIRTY_RANGE_MERGE_GAP = 4;
 /**
  * Computes dirty float ranges between two uniform snapshots.
+ *
+ * Adjacent dirty ranges separated by a gap smaller than or equal to
+ * {@link DIRTY_RANGE_MERGE_GAP} are merged to reduce `writeBuffer` calls.
  */
-function findDirtyFloatRanges(previous, next) {
+export function findDirtyFloatRanges(previous, next, mergeGapThreshold = DIRTY_RANGE_MERGE_GAP) {
     const ranges = [];
     let start = -1;
     for (let index = 0; index < next.length; index += 1) {
@@ -203,7 +248,22 @@ function findDirtyFloatRanges(previous, next) {
     if (start !== -1) {
         ranges.push({ start, count: next.length - start });
     }
-    return ranges;
+    if (ranges.length <= 1) {
+        return ranges;
+    }
+    const merged = [ranges[0]];
+    for (let index = 1; index < ranges.length; index += 1) {
+        const prev = merged[merged.length - 1];
+        const curr = ranges[index];
+        const gap = curr.start - (prev.start + prev.count);
+        if (gap <= mergeGapThreshold) {
+            prev.count = curr.start + curr.count - prev.start;
+        }
+        else {
+            merged.push(curr);
+        }
+    }
+    return merged;
 }
 /**
  * Determines whether shader output should perform linear-to-sRGB conversion.
@@ -339,6 +399,7 @@ export async function createRenderer(options) {
     };
     device.addEventListener('uncapturederror', handleUncapturedError);
     try {
+        const runtimeContext = buildShaderCompilationRuntimeContext(options);
         const convertLinearToSrgb = shouldConvertLinearToSrgb(options.outputColorSpace, format);
         const builtShader = buildShaderSourceWithMap(options.fragmentWgsl, options.uniformLayout, options.textureKeys, {
             convertLinearToSrgb,
@@ -352,7 +413,8 @@ export async function createRenderer(options) {
             ...(options.defineBlockSource !== undefined
                 ? { defineBlockSource: options.defineBlockSource }
                 : {}),
-            materialSource: options.materialSource ?? null
+            materialSource: options.materialSource ?? null,
+            runtimeContext
         });
         const normalizedTextureDefinitions = normalizeTextureDefinitions(options.textureDefinitions, options.textureKeys);
         const textureBindings = options.textureKeys.map((key, index) => {

package/dist/core/runtime-loop.d.ts

@@ -21,6 +21,9 @@ export interface MotionGPURuntimeLoopOptions {
     getDeviceDescriptor: () => GPUDeviceDescriptor | undefined;
     getOnError: () => ((report: MotionGPUErrorReport) => void) | undefined;
     reportError: (report: MotionGPUErrorReport | null) => void;
+    getErrorHistoryLimit?: () => number | undefined;
+    getOnErrorHistory?: () => ((history: MotionGPUErrorReport[]) => void) | undefined;
+    reportErrorHistory?: (history: MotionGPUErrorReport[]) => void;
 }
 export interface MotionGPURuntimeLoop {
     requestFrame: () => void;

package/dist/core/runtime-loop.js

@@ -33,12 +33,81 @@ export function createMotionGPURuntimeLoop(options) {
     const renderTextures = {};
     const canvasSize = { width: 0, height: 0 };
     let shouldContinueAfterFrame = false;
+    let activeErrorKey = null;
+    let errorHistory = [];
+    const getHistoryLimit = () => {
+        const value = options.getErrorHistoryLimit?.() ?? 0;
+        if (!Number.isFinite(value) || value <= 0) {
+            return 0;
+        }
+        return Math.floor(value);
+    };
+    const publishErrorHistory = () => {
+        options.reportErrorHistory?.(errorHistory);
+        const onErrorHistory = options.getOnErrorHistory?.();
+        if (!onErrorHistory) {
+            return;
+        }
+        try {
+            onErrorHistory(errorHistory);
+        }
+        catch {
+            // User-provided error history handlers must not break runtime error recovery.
+        }
+    };
+    const syncErrorHistory = () => {
+        const limit = getHistoryLimit();
+        if (limit <= 0) {
+            if (errorHistory.length === 0) {
+                return;
+            }
+            errorHistory = [];
+            publishErrorHistory();
+            return;
+        }
+        if (errorHistory.length <= limit) {
+            return;
+        }
+        errorHistory = errorHistory.slice(errorHistory.length - limit);
+        publishErrorHistory();
+    };
     const setError = (error, phase) => {
         const report = toMotionGPUErrorReport(error, phase);
+        const reportKey = JSON.stringify({
+            phase: report.phase,
+            title: report.title,
+            message: report.message,
+            rawMessage: report.rawMessage
+        });
+        if (activeErrorKey === reportKey) {
+            return;
+        }
+        activeErrorKey = reportKey;
+        const historyLimit = getHistoryLimit();
+        if (historyLimit > 0) {
+            errorHistory = [...errorHistory, report];
+            if (errorHistory.length > historyLimit) {
+                errorHistory = errorHistory.slice(errorHistory.length - historyLimit);
+            }
+            publishErrorHistory();
+        }
         options.reportError(report);
-        options.getOnError()?.(report);
+        const onError = options.getOnError();
+        if (!onError) {
+            return;
+        }
+        try {
+            onError(report);
+        }
+        catch {
+            // User-provided error handlers must not break runtime error recovery.
+        }
     };
     const clearError = () => {
+        if (activeErrorKey === null) {
+            return;
+        }
+        activeErrorKey = null;
         options.reportError(null);
     };
     const scheduleFrame = () => {
@@ -127,6 +196,7 @@ export function createMotionGPURuntimeLoop(options) {
         if (isDisposed) {
             return;
         }
+        syncErrorHistory();
         let materialState;
         try {
             materialState = resolveActiveMaterial();
@@ -165,6 +235,7 @@ export function createMotionGPURuntimeLoop(options) {
                             includeSources: materialState.includeSources,
                             defineBlockSource: materialState.defineBlockSource,
                             materialSource: materialState.source,
+                            materialSignature: materialState.signature,
                             uniformLayout: materialState.uniformLayout,
                             textureKeys: materialState.textureKeys,
                             textureDefinitions: materialState.textures,

package/dist/core/types.d.ts

@@ -11,7 +11,21 @@ export type UniformType = 'f32' | 'vec2f' | 'vec3f' | 'vec4f' | 'mat4x4f';
  * @typeParam TType - WGSL type tag.
  * @typeParam TValue - Runtime value shape for the selected type.
  */
-export interface TypedUniform<TType extends UniformType = UniformType, TValue = unknown> {
+/**
+ * Accepted matrix value formats for `mat4x4f` uniforms.
+ */
+export type UniformMat4Value = number[] | Float32Array;
+/**
+ * Runtime value shape by WGSL uniform type tag.
+ */
+export interface UniformValueByType {
+    f32: number;
+    vec2f: [number, number];
+    vec3f: [number, number, number];
+    vec4f: [number, number, number, number];
+    mat4x4f: UniformMat4Value;
+}
+export interface TypedUniform<TType extends UniformType = UniformType, TValue extends UniformValueByType[TType] = UniformValueByType[TType]> {
     /**
      * WGSL type tag.
      */
@@ -21,18 +35,14 @@ export interface TypedUniform<TType extends UniformType = UniformType, TValue =
      */
     value: TValue;
 }
-/**
- * Accepted matrix value formats for `mat4x4f` uniforms.
- */
-export type UniformMat4Value = number[] | Float32Array;
 /**
  * Supported uniform input shapes accepted by material and render APIs.
  */
-export type UniformValue = number | [number, number] | [number, number, number] | [number, number, number, number] | TypedUniform<'f32', number> | TypedUniform<'vec2f', [number, number]> | TypedUniform<'vec3f', [number, number, number]> | TypedUniform<'vec4f', [number, number, number, number]> | TypedUniform<'mat4x4f', UniformMat4Value>;
+export type UniformValue = number | [number, number] | [number, number, number] | [number, number, number, number] | TypedUniform<'f32'> | TypedUniform<'vec2f'> | TypedUniform<'vec3f'> | TypedUniform<'vec4f'> | TypedUniform<'mat4x4f'>;
 /**
  * Uniform map keyed by WGSL identifier names.
  */
-export type UniformMap = Record<string, UniformValue>;
+export type UniformMap<TKey extends string = string> = Record<TKey, UniformValue>;
 /**
  * Resolved layout metadata for a single uniform field inside the packed uniform buffer.
  */
@@ -168,11 +178,11 @@ export interface TextureDefinition {
 /**
  * Texture definition map keyed by uniform-compatible texture names.
  */
-export type TextureDefinitionMap = Record<string, TextureDefinition>;
+export type TextureDefinitionMap<TKey extends string = string> = Record<TKey, TextureDefinition>;
 /**
  * Runtime texture value map keyed by texture uniform names.
  */
-export type TextureMap = Record<string, TextureValue>;
+export type TextureMap<TKey extends string = string> = Record<TKey, TextureValue>;
 /**
  * Output color space requested for final canvas presentation.
  */
@@ -226,7 +236,7 @@ export interface RenderTarget {
 /**
  * Named render target definitions keyed by output slot names.
  */
-export type RenderTargetDefinitionMap = Record<string, RenderTargetDefinition>;
+export type RenderTargetDefinitionMap<TKey extends string = string> = Record<TKey, RenderTargetDefinition>;
 /**
  * User-defined render slot name (mapped to `renderTargets` keys).
  */
@@ -443,6 +453,10 @@ export interface RendererOptions {
         column?: number;
         functionName?: string;
     } | null;
+    /**
+     * Stable material signature captured during resolution.
+     */
+    materialSignature?: string;
     /**
      * Resolved uniform layout.
      */

package/dist/passes/BlitPass.d.ts

@@ -1,32 +1,11 @@
-import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types.js';
-export interface BlitPassOptions extends RenderPassFlags {
-    enabled?: boolean;
-    needsSwap?: boolean;
-    input?: RenderPassInputSlot;
-    output?: RenderPassOutputSlot;
-    filter?: GPUFilterMode;
-}
+import { FullscreenPass, type FullscreenPassOptions } from './FullscreenPass.js';
+export type BlitPassOptions = FullscreenPassOptions;
 /**
  * Fullscreen texture blit pass.
  */
-export declare class BlitPass implements RenderPass {
-    enabled: boolean;
-    needsSwap: boolean;
-    input: RenderPassInputSlot;
-    output: RenderPassOutputSlot;
-    clear: boolean;
-    clearColor: [number, number, number, number];
-    preserve: boolean;
-    private readonly filter;
-    private device;
-    private sampler;
-    private bindGroupLayout;
-    private shaderModule;
-    private readonly pipelineByFormat;
-    private bindGroupByView;
+export declare class BlitPass extends FullscreenPass {
+    protected getProgram(): string;
     constructor(options?: BlitPassOptions);
-    private ensureResources;
-    setSize(width: number, height: number): void;
-    render(context: RenderPassContext): void;
-    dispose(): void;
+    protected getVertexEntryPoint(): string;
+    protected getFragmentEntryPoint(): string;
 }

package/dist/passes/BlitPass.js

@@ -1,3 +1,4 @@
+import { FullscreenPass } from './FullscreenPass.js';
 const FULLSCREEN_BLIT_SHADER = `
 struct MotionGPUVertexOut {
 	@builtin(position) position: vec4f,
@@ -30,129 +31,17 @@ fn motiongpuBlitFragment(in: MotionGPUVertexOut) -> @location(0) vec4f {
 /**
  * Fullscreen texture blit pass.
  */
-export class BlitPass {
-    enabled;
-    needsSwap;
-    input;
-    output;
-    clear;
-    clearColor;
-    preserve;
-    filter;
-    device = null;
-    sampler = null;
-    bindGroupLayout = null;
-    shaderModule = null;
-    pipelineByFormat = new Map();
-    bindGroupByView = new WeakMap();
-    constructor(options = {}) {
-        this.enabled = options.enabled ?? true;
-        this.needsSwap = options.needsSwap ?? true;
-        this.input = options.input ?? 'source';
-        this.output = options.output ?? (this.needsSwap ? 'target' : 'source');
-        this.clear = options.clear ?? false;
-        this.clearColor = options.clearColor ?? [0, 0, 0, 1];
-        this.preserve = options.preserve ?? true;
-        this.filter = options.filter ?? 'linear';
-    }
-    ensureResources(device, format) {
-        if (this.device !== device) {
-            this.device = device;
-            this.sampler = null;
-            this.bindGroupLayout = null;
-            this.shaderModule = null;
-            this.pipelineByFormat.clear();
-            this.bindGroupByView = new WeakMap();
-        }
-        if (!this.sampler) {
-            this.sampler = device.createSampler({
-                magFilter: this.filter,
-                minFilter: this.filter,
-                addressModeU: 'clamp-to-edge',
-                addressModeV: 'clamp-to-edge'
-            });
-        }
-        if (!this.bindGroupLayout) {
-            this.bindGroupLayout = device.createBindGroupLayout({
-                entries: [
-                    {
-                        binding: 0,
-                        visibility: GPUShaderStage.FRAGMENT,
-                        sampler: { type: 'filtering' }
-                    },
-                    {
-                        binding: 1,
-                        visibility: GPUShaderStage.FRAGMENT,
-                        texture: {
-                            sampleType: 'float',
-                            viewDimension: '2d',
-                            multisampled: false
-                        }
-                    }
-                ]
-            });
-        }
-        if (!this.shaderModule) {
-            this.shaderModule = device.createShaderModule({
-                code: FULLSCREEN_BLIT_SHADER
-            });
-        }
-        let pipeline = this.pipelineByFormat.get(format);
-        if (!pipeline) {
-            const pipelineLayout = device.createPipelineLayout({
-                bindGroupLayouts: [this.bindGroupLayout]
-            });
-            pipeline = device.createRenderPipeline({
-                layout: pipelineLayout,
-                vertex: {
-                    module: this.shaderModule,
-                    entryPoint: 'motiongpuBlitVertex'
-                },
-                fragment: {
-                    module: this.shaderModule,
-                    entryPoint: 'motiongpuBlitFragment',
-                    targets: [{ format }]
-                },
-                primitive: { topology: 'triangle-list' }
-            });
-            this.pipelineByFormat.set(format, pipeline);
-        }
-        return {
-            sampler: this.sampler,
-            bindGroupLayout: this.bindGroupLayout,
-            pipeline
-        };
+export class BlitPass extends FullscreenPass {
+    getProgram() {
+        return FULLSCREEN_BLIT_SHADER;
     }
-    setSize(width, height) {
-        void width;
-        void height;
+    constructor(options = {}) {
+        super(options);
     }
-    render(context) {
-        const { sampler, bindGroupLayout, pipeline } = this.ensureResources(context.device, context.output.format);
-        const inputView = context.input.view;
-        let bindGroup = this.bindGroupByView.get(inputView);
-        if (!bindGroup) {
-            bindGroup = context.device.createBindGroup({
-                layout: bindGroupLayout,
-                entries: [
-                    { binding: 0, resource: sampler },
-                    { binding: 1, resource: inputView }
-                ]
-            });
-            this.bindGroupByView.set(inputView, bindGroup);
-        }
-        const pass = context.beginRenderPass();
-        pass.setPipeline(pipeline);
-        pass.setBindGroup(0, bindGroup);
-        pass.draw(3);
-        pass.end();
+    getVertexEntryPoint() {
+        return 'motiongpuBlitVertex';
     }
-    dispose() {
-        this.device = null;
-        this.sampler = null;
-        this.bindGroupLayout = null;
-        this.shaderModule = null;
-        this.pipelineByFormat.clear();
-        this.bindGroupByView = new WeakMap();
+    getFragmentEntryPoint() {
+        return 'motiongpuBlitFragment';
     }
 }

package/dist/passes/FullscreenPass.d.ts

@@ -0,0 +1,37 @@
+import type { RenderPass, RenderPassContext, RenderPassFlags, RenderPassInputSlot, RenderPassOutputSlot } from '../core/types.js';
+export interface FullscreenPassOptions extends RenderPassFlags {
+    enabled?: boolean;
+    needsSwap?: boolean;
+    input?: RenderPassInputSlot;
+    output?: RenderPassOutputSlot;
+    filter?: GPUFilterMode;
+}
+/**
+ * Shared base for fullscreen texture sampling passes.
+ */
+export declare abstract class FullscreenPass implements RenderPass {
+    enabled: boolean;
+    needsSwap: boolean;
+    input: RenderPassInputSlot;
+    output: RenderPassOutputSlot;
+    clear: boolean;
+    clearColor: [number, number, number, number];
+    preserve: boolean;
+    private readonly filter;
+    private device;
+    private sampler;
+    private bindGroupLayout;
+    private shaderModule;
+    private readonly pipelineByFormat;
+    private bindGroupByView;
+    protected constructor(options?: FullscreenPassOptions);
+    protected abstract getProgram(): string;
+    protected abstract getVertexEntryPoint(): string;
+    protected abstract getFragmentEntryPoint(): string;
+    protected invalidateFullscreenCache(): void;
+    private ensureResources;
+    setSize(width: number, height: number): void;
+    protected renderFullscreen(context: RenderPassContext): void;
+    render(context: RenderPassContext): void;
+    dispose(): void;
+}

package/dist/passes/FullscreenPass.js

@@ -0,0 +1,131 @@
+/**
+ * Shared base for fullscreen texture sampling passes.
+ */
+export class FullscreenPass {
+    enabled;
+    needsSwap;
+    input;
+    output;
+    clear;
+    clearColor;
+    preserve;
+    filter;
+    device = null;
+    sampler = null;
+    bindGroupLayout = null;
+    shaderModule = null;
+    pipelineByFormat = new Map();
+    bindGroupByView = new WeakMap();
+    constructor(options = {}) {
+        this.enabled = options.enabled ?? true;
+        this.needsSwap = options.needsSwap ?? true;
+        this.input = options.input ?? 'source';
+        this.output = options.output ?? (this.needsSwap ? 'target' : 'source');
+        this.clear = options.clear ?? false;
+        this.clearColor = options.clearColor ?? [0, 0, 0, 1];
+        this.preserve = options.preserve ?? true;
+        this.filter = options.filter ?? 'linear';
+    }
+    invalidateFullscreenCache() {
+        this.shaderModule = null;
+        this.pipelineByFormat.clear();
+        this.bindGroupByView = new WeakMap();
+    }
+    ensureResources(device, format) {
+        if (this.device !== device) {
+            this.device = device;
+            this.sampler = null;
+            this.bindGroupLayout = null;
+            this.invalidateFullscreenCache();
+        }
+        if (!this.sampler) {
+            this.sampler = device.createSampler({
+                magFilter: this.filter,
+                minFilter: this.filter,
+                addressModeU: 'clamp-to-edge',
+                addressModeV: 'clamp-to-edge'
+            });
+        }
+        if (!this.bindGroupLayout) {
+            this.bindGroupLayout = device.createBindGroupLayout({
+                entries: [
+                    {
+                        binding: 0,
+                        visibility: GPUShaderStage.FRAGMENT,
+                        sampler: { type: 'filtering' }
+                    },
+                    {
+                        binding: 1,
+                        visibility: GPUShaderStage.FRAGMENT,
+                        texture: {
+                            sampleType: 'float',
+                            viewDimension: '2d',
+                            multisampled: false
+                        }
+                    }
+                ]
+            });
+        }
+        if (!this.shaderModule) {
+            this.shaderModule = device.createShaderModule({ code: this.getProgram() });
+        }
+        let pipeline = this.pipelineByFormat.get(format);
+        if (!pipeline) {
+            const pipelineLayout = device.createPipelineLayout({
+                bindGroupLayouts: [this.bindGroupLayout]
+            });
+            pipeline = device.createRenderPipeline({
+                layout: pipelineLayout,
+                vertex: {
+                    module: this.shaderModule,
+                    entryPoint: this.getVertexEntryPoint()
+                },
+                fragment: {
+                    module: this.shaderModule,
+                    entryPoint: this.getFragmentEntryPoint(),
+                    targets: [{ format }]
+                },
+                primitive: { topology: 'triangle-list' }
+            });
+            this.pipelineByFormat.set(format, pipeline);
+        }
+        return {
+            sampler: this.sampler,
+            bindGroupLayout: this.bindGroupLayout,
+            pipeline
+        };
+    }
+    setSize(width, height) {
+        void width;
+        void height;
+    }
+    renderFullscreen(context) {
+        const { sampler, bindGroupLayout, pipeline } = this.ensureResources(context.device, context.output.format);
+        const inputView = context.input.view;
+        let bindGroup = this.bindGroupByView.get(inputView);
+        if (!bindGroup) {
+            bindGroup = context.device.createBindGroup({
+                layout: bindGroupLayout,
+                entries: [
+                    { binding: 0, resource: sampler },
+                    { binding: 1, resource: inputView }
+                ]
+            });
+            this.bindGroupByView.set(inputView, bindGroup);
+        }
+        const pass = context.beginRenderPass();
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.draw(3);
+        pass.end();
+    }
+    render(context) {
+        this.renderFullscreen(context);
+    }
+    dispose() {
+        this.device = null;
+        this.sampler = null;
+        this.bindGroupLayout = null;
+        this.invalidateFullscreenCache();
+    }
+}