@motion-core/motion-gpu 0.4.2 → 0.6.0

package/src/lib/core/runtime-loop.ts

@@ -10,11 +10,13 @@ import { buildRendererPipelineSignature } from './recompile-policy.js';
 import { assertUniformValueForType } from './uniforms.js';
 import type { FrameRegistry } from './frame-registry.js';
 import type {
+	AnyPass,
 	FrameInvalidationToken,
 	OutputColorSpace,
-	RenderPass,
+	PendingStorageWrite,
 	Renderer,
 	RenderTargetDefinitionMap,
+	StorageBufferDefinitionMap,
 	TextureMap,
 	TextureValue,
 	UniformType,
@@ -29,7 +31,7 @@ export interface MotionGPURuntimeLoopOptions {
 	maxDelta: CurrentReadable<number>;
 	getMaterial: () => FragMaterial;
 	getRenderTargets: () => RenderTargetDefinitionMap;
-	getPasses: () => RenderPass[];
+	getPasses: () => AnyPass[];
 	getClearColor: () => [number, number, number, number];
 	getOutputColorSpace: () => OutputColorSpace;
 	getAdapterOptions: () => GPURequestAdapterOptions | undefined;
@@ -52,6 +54,8 @@ function getRendererRetryDelayMs(attempt: number): number {
 	return Math.min(8000, 250 * 2 ** Math.max(0, attempt - 1));
 }
 
+const ERROR_CLEAR_GRACE_MS = 750;
+
 export function createMotionGPURuntimeLoop(
 	options: MotionGPURuntimeLoopOptions
 ): MotionGPURuntimeLoop {
@@ -81,9 +85,23 @@ export function createMotionGPURuntimeLoop(
 	const renderUniforms: Record<string, UniformValue> = {};
 	const renderTextures: TextureMap = {};
 	const canvasSize = { width: 0, height: 0 };
+	let storageBufferKeys: string[] = [];
+	let storageBufferKeySet = new Set<string>();
+	let storageBufferDefinitions: StorageBufferDefinitionMap = {};
+	const pendingStorageWrites: PendingStorageWrite[] = [];
 	let shouldContinueAfterFrame = false;
 	let activeErrorKey: string | null = null;
 	let errorHistory: MotionGPUErrorReport[] = [];
+	let errorClearReadyAtMs = 0;
+	let lastFrameTimestampMs = performance.now();
+
+	const resolveNowMs = (nowMs?: number): number => {
+		if (typeof nowMs === 'number' && Number.isFinite(nowMs)) {
+			return nowMs;
+		}
+
+		return lastFrameTimestampMs;
+	};
 
 	const getHistoryLimit = (): number => {
 		const value = options.getErrorHistoryLimit?.() ?? 0;
@@ -123,12 +141,13 @@ export function createMotionGPURuntimeLoop(
 			return;
 		}
 
-		errorHistory = errorHistory.slice(errorHistory.length - limit);
+		errorHistory.splice(0, errorHistory.length - limit);
 		publishErrorHistory();
 	};
 
-	const setError = (error: unknown, phase: MotionGPUErrorPhase): void => {
+	const setError = (error: unknown, phase: MotionGPUErrorPhase, nowMs?: number): void => {
 		const report = toMotionGPUErrorReport(error, phase);
+		errorClearReadyAtMs = resolveNowMs(nowMs) + ERROR_CLEAR_GRACE_MS;
 		const reportKey = JSON.stringify({
 			phase: report.phase,
 			title: report.title,
@@ -141,9 +160,9 @@ export function createMotionGPURuntimeLoop(
 		activeErrorKey = reportKey;
 		const historyLimit = getHistoryLimit();
 		if (historyLimit > 0) {
-			errorHistory = [...errorHistory, report];
+			errorHistory.push(report);
 			if (errorHistory.length > historyLimit) {
-				errorHistory = errorHistory.slice(errorHistory.length - historyLimit);
+				errorHistory.splice(0, errorHistory.length - historyLimit);
 			}
 			publishErrorHistory();
 		}
@@ -160,12 +179,16 @@ export function createMotionGPURuntimeLoop(
 		}
 	};
 
-	const clearError = (): void => {
+	const maybeClearError = (nowMs?: number): void => {
 		if (activeErrorKey === null) {
 			return;
 		}
+		if (resolveNowMs(nowMs) < errorClearReadyAtMs) {
+			return;
+		}
 
 		activeErrorKey = null;
+		errorClearReadyAtMs = 0;
 		options.reportError(null);
 	};
 
@@ -194,13 +217,13 @@ export function createMotionGPURuntimeLoop(
 	const resetRuntimeMaps = (): void => {
 		for (const key of Object.keys(runtimeUniforms)) {
 			if (!uniformKeySet.has(key)) {
-				Reflect.deleteProperty(runtimeUniforms, key);
+				delete runtimeUniforms[key];
 			}
 		}
 
 		for (const key of Object.keys(runtimeTextures)) {
 			if (!textureKeySet.has(key)) {
-				Reflect.deleteProperty(runtimeTextures, key);
+				delete runtimeTextures[key];
 			}
 		}
 	};
@@ -208,13 +231,13 @@ export function createMotionGPURuntimeLoop(
 	const resetRenderPayloadMaps = (): void => {
 		for (const key of Object.keys(renderUniforms)) {
 			if (!uniformKeySet.has(key)) {
-				Reflect.deleteProperty(renderUniforms, key);
+				delete renderUniforms[key];
 			}
 		}
 
 		for (const key of Object.keys(renderTextures)) {
 			if (!textureKeySet.has(key)) {
-				Reflect.deleteProperty(renderTextures, key);
+				delete renderTextures[key];
 			}
 		}
 	};
@@ -241,6 +264,10 @@ export function createMotionGPURuntimeLoop(
 		textureKeys = materialState.textureKeys;
 		uniformKeySet = new Set(uniformKeys);
 		textureKeySet = new Set(textureKeys);
+		storageBufferKeys = materialState.storageBufferKeys;
+		storageBufferKeySet = new Set(storageBufferKeys);
+		storageBufferDefinitions = (options.getMaterial().storageBuffers ??
+			{}) as StorageBufferDefinitionMap;
 		resetRuntimeMaps();
 		resetRenderPayloadMaps();
 		activeMaterialSignature = materialState.signature;
@@ -269,18 +296,80 @@ export function createMotionGPURuntimeLoop(
 		runtimeTextures[name] = value;
 	};
 
+	const writeStorageBuffer = (
+		name: string,
+		data: ArrayBufferView,
+		writeOptions?: { offset?: number }
+	): void => {
+		if (!storageBufferKeySet.has(name)) {
+			throw new Error(
+				`Unknown storage buffer "${name}". Declare it in material.storageBuffers first.`
+			);
+		}
+		const definition = storageBufferDefinitions[name];
+		if (!definition) {
+			throw new Error(`Missing definition for storage buffer "${name}".`);
+		}
+		const offset = writeOptions?.offset ?? 0;
+		if (offset < 0 || offset + data.byteLength > definition.size) {
+			throw new Error(
+				`Storage buffer "${name}" write out of bounds: offset=${offset}, dataSize=${data.byteLength}, bufferSize=${definition.size}.`
+			);
+		}
+		pendingStorageWrites.push({ name, data, offset });
+	};
+
+	const readStorageBuffer = (name: string): Promise<ArrayBuffer> => {
+		if (!storageBufferKeySet.has(name)) {
+			throw new Error(
+				`Unknown storage buffer "${name}". Declare it in material.storageBuffers first.`
+			);
+		}
+		if (!renderer) {
+			return Promise.reject(
+				new Error(`Cannot read storage buffer "${name}": renderer not initialized.`)
+			);
+		}
+		const gpuBuffer = renderer.getStorageBuffer?.(name);
+		if (!gpuBuffer) {
+			return Promise.reject(new Error(`Storage buffer "${name}" not allocated on GPU.`));
+		}
+		const device = renderer.getDevice?.();
+		if (!device) {
+			return Promise.reject(new Error('Cannot read storage buffer: GPU device unavailable.'));
+		}
+		const definition = storageBufferDefinitions[name];
+		if (!definition) {
+			return Promise.reject(new Error(`Missing definition for storage buffer "${name}".`));
+		}
+		const stagingBuffer = device.createBuffer({
+			size: definition.size,
+			usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
+		});
+		const commandEncoder = device.createCommandEncoder();
+		commandEncoder.copyBufferToBuffer(gpuBuffer, 0, stagingBuffer, 0, definition.size);
+		device.queue.submit([commandEncoder.finish()]);
+		return stagingBuffer.mapAsync(GPUMapMode.READ).then(() => {
+			const result = stagingBuffer.getMappedRange().slice(0);
+			stagingBuffer.unmap();
+			stagingBuffer.destroy();
+			return result;
+		});
+	};
+
 	const renderFrame = (timestamp: number): void => {
 		frameId = null;
 		if (isDisposed) {
 			return;
 		}
+		lastFrameTimestampMs = timestamp;
 		syncErrorHistory();
 
 		let materialState: ResolvedMaterial;
 		try {
 			materialState = resolveActiveMaterial();
 		} catch (error) {
-			setError(error, 'initialization');
+			setError(error, 'initialization', timestamp);
 			scheduleFrame();
 			return;
 		}
@@ -324,6 +413,9 @@ export function createMotionGPURuntimeLoop(
 							uniformLayout: materialState.uniformLayout,
 							textureKeys: materialState.textureKeys,
 							textureDefinitions: materialState.textures,
+							storageBufferKeys: materialState.storageBufferKeys,
+							storageBufferDefinitions,
+							storageTextureKeys: materialState.storageTextureKeys,
 							getRenderTargets: options.getRenderTargets,
 							getPasses: options.getPasses,
 							outputColorSpace,
@@ -344,7 +436,7 @@ export function createMotionGPURuntimeLoop(
 						failedRendererSignature = null;
 						failedRendererAttempts = 0;
 						nextRendererRetryAt = 0;
-						clearError();
+						maybeClearError(performance.now());
 					} catch (error) {
 						failedRendererSignature = rendererSignature;
 						failedRendererAttempts += 1;
@@ -380,6 +472,8 @@ export function createMotionGPURuntimeLoop(
 				delta,
 				setUniform,
 				setTexture,
+				writeStorageBuffer,
+				readStorageBuffer,
 				invalidate,
 				advance,
 				renderMode: registry.getRenderMode(),
@@ -413,13 +507,19 @@ export function createMotionGPURuntimeLoop(
 					renderMode: registry.getRenderMode(),
 					uniforms: renderUniforms,
 					textures: renderTextures,
-					canvasSize
+					canvasSize,
+					pendingStorageWrites: pendingStorageWrites.length > 0 ? pendingStorageWrites : undefined
 				});
+				// Clear in-place after synchronous render() completes — avoids
+				// the splice(0) copy and eliminates the conditional spread object.
+				if (pendingStorageWrites.length > 0) {
+					pendingStorageWrites.length = 0;
+				}
 			}
 
-			clearError();
+			maybeClearError(timestamp);
 		} catch (error) {
-			setError(error, 'render');
+			setError(error, 'render', timestamp);
 		} finally {
 			registry.endFrame();
 		}

package/src/lib/core/shader.ts

@@ -1,6 +1,11 @@
 import { assertUniformName } from './uniforms.js';
 import type { MaterialLineMap, MaterialSourceLocation } from './material-preprocess.js';
-import type { UniformLayout } from './types.js';
+import type { StorageBufferType, UniformLayout } from './types.js';
+
+type ComputeShaderSourceLocation = {
+	kind: 'compute';
+	line: number;
+};
 
 /**
  * Fallback uniform field used when no custom uniforms are provided.
@@ -72,6 +77,38 @@ function buildTextureBindings(textureKeys: string[]): string {
 	return declarations.join('\n');
 }
 
+/**
+ * Builds read-only storage buffer bindings for fragment shader.
+ */
+function buildFragmentStorageBufferBindings(
+	storageBufferKeys: string[],
+	definitions: Record<string, { type: StorageBufferType }>
+): string {
+	if (storageBufferKeys.length === 0) {
+		return '';
+	}
+
+	const declarations: string[] = [];
+
+	for (let index = 0; index < storageBufferKeys.length; index += 1) {
+		const key = storageBufferKeys[index];
+		if (key === undefined) {
+			continue;
+		}
+
+		const definition = definitions[key];
+		if (!definition) {
+			continue;
+		}
+
+		declarations.push(
+			`@group(1) @binding(${index}) var<storage, read> ${key}: ${definition.type};`
+		);
+	}
+
+	return declarations.join('\n');
+}
+
 /**
  * Optionally returns helper WGSL for linear-to-sRGB conversion.
  */
@@ -114,7 +151,7 @@ function buildFragmentOutput(keepAliveExpression: string, enableSrgbTransform: b
 /**
  * 1-based map from generated WGSL lines to original material source lines.
  */
-export type ShaderLineMap = Array<MaterialSourceLocation | null>;
+export type ShaderLineMap = Array<(MaterialSourceLocation | ComputeShaderSourceLocation) | null>;
 
 /**
  * Result of shader source generation with line mapping metadata.
@@ -143,7 +180,11 @@ export function buildShaderSource(
 	fragmentWgsl: string,
 	uniformLayout: UniformLayout,
 	textureKeys: string[] = [],
-	options?: { convertLinearToSrgb?: boolean }
+	options?: {
+		convertLinearToSrgb?: boolean;
+		storageBufferKeys?: string[];
+		storageBufferDefinitions?: Record<string, { type: StorageBufferType }>;
+	}
 ): string {
 	const uniformFields = buildUniformStruct(uniformLayout);
 	const keepAliveExpression = getKeepAliveExpression(uniformLayout);
@@ -151,6 +192,10 @@ export function buildShaderSource(
 	const enableSrgbTransform = options?.convertLinearToSrgb ?? false;
 	const colorTransformHelpers = buildColorTransformHelpers(enableSrgbTransform);
 	const fragmentOutput = buildFragmentOutput(keepAliveExpression, enableSrgbTransform);
+	const storageBufferBindings = buildFragmentStorageBufferBindings(
+		options?.storageBufferKeys ?? [],
+		options?.storageBufferDefinitions ?? {}
+	);
 
 	return `
 struct MotionGPUFrame {
@@ -166,6 +211,7 @@ struct MotionGPUUniforms {
 @group(0) @binding(0) var<uniform> motiongpuFrame: MotionGPUFrame;
 @group(0) @binding(1) var<uniform> motiongpuUniforms: MotionGPUUniforms;
 ${textureBindings}
+${storageBufferBindings ? '\n' + storageBufferBindings : ''}
 ${colorTransformHelpers}
 
 struct MotionGPUVertexOut {
@@ -207,6 +253,8 @@ export function buildShaderSourceWithMap(
 	options?: {
 		convertLinearToSrgb?: boolean;
 		fragmentLineMap?: MaterialLineMap;
+		storageBufferKeys?: string[];
+		storageBufferDefinitions?: Record<string, { type: StorageBufferType }>;
 	}
 ): BuiltShaderSource {
 	const code = buildShaderSource(fragmentWgsl, uniformLayout, textureKeys, options);
@@ -241,7 +289,9 @@ export function buildShaderSourceWithMap(
 /**
  * Converts source location metadata to user-facing diagnostics label.
  */
-export function formatShaderSourceLocation(location: MaterialSourceLocation | null): string | null {
+export function formatShaderSourceLocation(
+	location: (MaterialSourceLocation | ComputeShaderSourceLocation) | null
+): string | null {
 	if (!location) {
 		return null;
 	}
@@ -254,5 +304,9 @@ export function formatShaderSourceLocation(location: MaterialSourceLocation | nu
 		return `include <${location.include}> line ${location.line}`;
 	}
 
+	if (location.kind === 'compute') {
+		return `compute line ${location.line}`;
+	}
+
 	return `define "${location.define}" line ${location.line}`;
 }

package/src/lib/core/storage-buffers.ts

@@ -0,0 +1,142 @@
+import { assertUniformName } from './uniforms.js';
+import type {
+	StorageBufferDefinition,
+	StorageBufferDefinitionMap,
+	StorageBufferType
+} from './types.js';
+
+/**
+ * Valid WGSL storage buffer element types.
+ */
+const VALID_STORAGE_BUFFER_TYPES: ReadonlySet<string> = new Set<StorageBufferType>([
+	'array<f32>',
+	'array<vec2f>',
+	'array<vec3f>',
+	'array<vec4f>',
+	'array<u32>',
+	'array<i32>',
+	'array<vec4u>',
+	'array<vec4i>'
+]);
+
+/**
+ * Storage-compatible texture formats for `texture_storage_2d`.
+ */
+export const STORAGE_TEXTURE_FORMATS: ReadonlySet<GPUTextureFormat> = new Set([
+	'r32float',
+	'r32sint',
+	'r32uint',
+	'rg32float',
+	'rg32sint',
+	'rg32uint',
+	'rgba8unorm',
+	'rgba8snorm',
+	'rgba8uint',
+	'rgba8sint',
+	'rgba16float',
+	'rgba16uint',
+	'rgba16sint',
+	'rgba32float',
+	'rgba32uint',
+	'rgba32sint',
+	'bgra8unorm'
+] as GPUTextureFormat[]);
+
+/**
+ * Validates a single storage buffer definition.
+ *
+ * @param name - Buffer identifier.
+ * @param definition - Storage buffer definition to validate.
+ * @throws {Error} When any field is invalid.
+ */
+export function assertStorageBufferDefinition(
+	name: string,
+	definition: StorageBufferDefinition
+): void {
+	assertUniformName(name);
+
+	if (!Number.isFinite(definition.size) || definition.size <= 0) {
+		throw new Error(
+			`Storage buffer "${name}" size must be a finite number greater than 0, got ${definition.size}`
+		);
+	}
+
+	if (definition.size % 4 !== 0) {
+		throw new Error(
+			`Storage buffer "${name}" size must be a multiple of 4, got ${definition.size}`
+		);
+	}
+
+	if (!VALID_STORAGE_BUFFER_TYPES.has(definition.type)) {
+		throw new Error(
+			`Storage buffer "${name}" has unknown type "${definition.type}". Supported types: ${[...VALID_STORAGE_BUFFER_TYPES].join(', ')}`
+		);
+	}
+
+	if (
+		definition.access !== undefined &&
+		definition.access !== 'read' &&
+		definition.access !== 'read-write'
+	) {
+		throw new Error(
+			`Storage buffer "${name}" has invalid access mode "${definition.access}". Use 'read' or 'read-write'.`
+		);
+	}
+
+	if (definition.initialData !== undefined) {
+		if (definition.initialData.byteLength > definition.size) {
+			throw new Error(
+				`Storage buffer "${name}" initialData byte length (${definition.initialData.byteLength}) exceeds buffer size (${definition.size})`
+			);
+		}
+	}
+}
+
+/**
+ * Validates and returns sorted storage buffer keys.
+ *
+ * @param definitions - Storage buffer definition map.
+ * @returns Lexicographically sorted buffer keys.
+ */
+export function resolveStorageBufferKeys(definitions: StorageBufferDefinitionMap): string[] {
+	const keys = Object.keys(definitions).sort();
+	for (const key of keys) {
+		const definition = definitions[key];
+		if (definition) {
+			assertStorageBufferDefinition(key, definition);
+		}
+	}
+	return keys;
+}
+
+/**
+ * Normalizes a storage buffer definition with defaults applied.
+ *
+ * @param definition - Raw definition.
+ * @returns Normalized definition with access default.
+ */
+export function normalizeStorageBufferDefinition(
+	definition: StorageBufferDefinition
+): Required<Pick<StorageBufferDefinition, 'size' | 'type' | 'access'>> {
+	return {
+		size: definition.size,
+		type: definition.type,
+		access: definition.access ?? 'read-write'
+	};
+}
+
+/**
+ * Validates that a texture format is storage-compatible.
+ *
+ * @param name - Texture identifier.
+ * @param format - GPU texture format.
+ * @throws {Error} When format is not storage-compatible.
+ */
+export function assertStorageTextureFormat(name: string, format: GPUTextureFormat): void {
+	if (!STORAGE_TEXTURE_FORMATS.has(format)) {
+		throw new Error(
+			`Texture "${name}" with storage:true requires a storage-compatible format, but got "${format}". ` +
+				`Supported formats: ${[...STORAGE_TEXTURE_FORMATS].join(', ')}`
+		);
+	}
+}

package/src/lib/core/texture-loader.ts

@@ -406,6 +406,7 @@ export async function loadTextureFromUrl(
 			throw createAbortError();
 		}
 
+		let disposed = false;
 		const loaded: LoadedTexture = {
 			url,
 			source: bitmap,
@@ -413,7 +414,12 @@ export async function loadTextureFromUrl(
 			height: bitmap.height,
 			colorSpace: normalized.colorSpace,
 			dispose: () => {
+				if (disposed) {
+					return;
+				}
+				disposed = true;
 				bitmap?.close();
+				bitmap = null;
 			}
 		};
 

package/src/lib/core/textures.ts

@@ -55,6 +55,22 @@ export interface NormalizedTextureDefinition {
 	 * Effective V address mode.
 	 */
 	addressModeV: GPUAddressMode;
+	/**
+	 * Whether this texture is a storage texture (writable by compute).
+	 */
+	storage: boolean;
+	/**
+	 * Whether this texture should be exposed as a fragment-stage sampled binding.
+	 */
+	fragmentVisible: boolean;
+	/**
+	 * Explicit width for storage textures. Undefined when derived from source.
+	 */
+	width?: number;
+	/**
+	 * Explicit height for storage textures. Undefined when derived from source.
+	 */
+	height?: number;
 }
 
 /**
@@ -90,19 +106,30 @@ export function resolveTextureKeys(textures: TextureDefinitionMap): string[] {
 export function normalizeTextureDefinition(
 	definition: TextureDefinition | undefined
 ): NormalizedTextureDefinition {
+	const isStorage = definition?.storage === true;
+	const defaultFormat = definition?.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb';
 	const normalized: NormalizedTextureDefinition = {
 		source: definition?.source ?? null,
 		colorSpace: definition?.colorSpace ?? 'srgb',
-		format: definition?.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb',
+		format: definition?.format ?? defaultFormat,
 		flipY: definition?.flipY ?? true,
 		generateMipmaps: definition?.generateMipmaps ?? false,
 		premultipliedAlpha: definition?.premultipliedAlpha ?? false,
 		anisotropy: Math.max(1, Math.min(16, Math.floor(definition?.anisotropy ?? 1))),
 		filter: definition?.filter ?? DEFAULT_TEXTURE_FILTER,
 		addressModeU: definition?.addressModeU ?? DEFAULT_TEXTURE_ADDRESS_MODE,
-		addressModeV: definition?.addressModeV ?? DEFAULT_TEXTURE_ADDRESS_MODE
+		addressModeV: definition?.addressModeV ?? DEFAULT_TEXTURE_ADDRESS_MODE,
+		storage: isStorage,
+		fragmentVisible: definition?.fragmentVisible ?? true
 	};
 
+	if (definition?.width !== undefined) {
+		normalized.width = definition.width;
+	}
+	if (definition?.height !== undefined) {
+		normalized.height = definition.height;
+	}
+
 	if (definition?.update !== undefined) {
 		normalized.update = definition.update;
 	}