@motion-core/motion-gpu 0.4.2 → 0.5.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;
@@ -81,6 +83,10 @@ 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[] = [];
@@ -241,6 +247,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,6 +279,67 @@ 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) {
@@ -324,6 +395,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,
@@ -380,6 +454,8 @@ export function createMotionGPURuntimeLoop(
 				delta,
 				setUniform,
 				setTexture,
+				writeStorageBuffer,
+				readStorageBuffer,
 				invalidate,
 				advance,
 				renderMode: registry.getRenderMode(),
@@ -413,7 +489,10 @@ export function createMotionGPURuntimeLoop(
 					renderMode: registry.getRenderMode(),
 					uniforms: renderUniforms,
 					textures: renderTextures,
-					canvasSize
+					canvasSize,
+					...(pendingStorageWrites.length > 0
+						? { pendingStorageWrites: pendingStorageWrites.splice(0) }
+						: {})
 				});
 			}
 

package/src/lib/core/shader.ts

@@ -1,6 +1,6 @@
 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';
 
 /**
  * Fallback uniform field used when no custom uniforms are provided.
@@ -72,6 +72,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.
  */
@@ -143,7 +175,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 +187,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 +206,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 +248,8 @@ export function buildShaderSourceWithMap(
 	options?: {
 		convertLinearToSrgb?: boolean;
 		fragmentLineMap?: MaterialLineMap;
+		storageBufferKeys?: string[];
+		storageBufferDefinitions?: Record<string, { type: StorageBufferType }>;
 	}
 ): BuiltShaderSource {
 	const code = buildShaderSource(fragmentWgsl, uniformLayout, textureKeys, options);

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,18 @@ export interface NormalizedTextureDefinition {
 	 * Effective V address mode.
 	 */
 	addressModeV: GPUAddressMode;
+	/**
+	 * Whether this texture is a storage texture (writable by compute).
+	 */
+	storage: 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 +102,29 @@ 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
 	};
 
+	if (definition?.width !== undefined) {
+		normalized.width = definition.width;
+	}
+	if (definition?.height !== undefined) {
+		normalized.height = definition.height;
+	}
+
 	if (definition?.update !== undefined) {
 		normalized.update = definition.update;
 	}

package/src/lib/core/types.ts

@@ -199,6 +199,26 @@ export interface TextureDefinition {
 	 * V axis address mode.
 	 */
 	addressModeV?: GPUAddressMode;
+	/**
+	 * When true, this texture is also writable by compute passes.
+	 */
+	storage?: boolean;
+	/**
+	 * Required when storage is true. Must be a storage-compatible format.
+	 */
+	format?: GPUTextureFormat;
+	/**
+	 * Explicit texture width. Required for storage textures without a source.
+	 */
+	width?: number;
+	/**
+	 * Explicit texture height. Required for storage textures without a source.
+	 */
+	height?: number;
+	/**
+	 * When true, texture is visible (sampled) in fragment shader. Default: true.
+	 */
+	fragmentVisible?: boolean;
 }
 
 /**
@@ -211,6 +231,56 @@ export type TextureDefinitionMap<TKey extends string = string> = Record<TKey, Te
  */
 export type TextureMap<TKey extends string = string> = Record<TKey, TextureValue>;
 
+// ── Storage buffer types ────────────────────────────────────────────────────
+
+/**
+ * Access mode for storage buffers in compute shaders.
+ */
+export type StorageBufferAccess = 'read' | 'read-write';
+
+/**
+ * WGSL storage buffer element type.
+ */
+export type StorageBufferType =
+	| 'array<f32>'
+	| 'array<vec2f>'
+	| 'array<vec3f>'
+	| 'array<vec4f>'
+	| 'array<u32>'
+	| 'array<i32>'
+	| 'array<vec4u>'
+	| 'array<vec4i>';
+
+/**
+ * Definition of a single storage buffer resource.
+ */
+export interface StorageBufferDefinition {
+	/**
+	 * Buffer size in bytes. Must be > 0 and multiple of 4.
+	 */
+	size: number;
+	/**
+	 * WGSL type annotation for codegen.
+	 */
+	type: StorageBufferType;
+	/**
+	 * Access mode in compute shader. Default: 'read-write'.
+	 */
+	access?: StorageBufferAccess;
+	/**
+	 * Initial data uploaded on creation.
+	 */
+	initialData?: Float32Array | Uint32Array | Int32Array;
+}
+
+/**
+ * Map of named storage buffer definitions.
+ */
+export type StorageBufferDefinitionMap<TKey extends string = string> = Record<
+	TKey,
+	StorageBufferDefinition
+>;
+
 /**
  * Output color space requested for final canvas presentation.
  */
@@ -368,6 +438,40 @@ export interface RenderPassContext extends Required<RenderPassFlags> {
 	}) => GPURenderPassEncoder;
 }
 
+/**
+ * Context provided to compute pass render calls.
+ */
+export interface ComputePassContext {
+	/**
+	 * Active GPU device.
+	 */
+	device: GPUDevice;
+	/**
+	 * Shared command encoder for this frame.
+	 */
+	commandEncoder: GPUCommandEncoder;
+	/**
+	 * Frame width in pixels.
+	 */
+	width: number;
+	/**
+	 * Frame height in pixels.
+	 */
+	height: number;
+	/**
+	 * Frame timestamp in seconds.
+	 */
+	time: number;
+	/**
+	 * Frame delta in seconds.
+	 */
+	delta: number;
+	/**
+	 * Begins a compute pass on the shared command encoder.
+	 */
+	beginComputePass: () => GPUComputePassEncoder;
+}
+
 /**
  * Formal render pass contract used by MotionGPU render graph.
  */
@@ -402,6 +506,22 @@ export interface RenderPass extends RenderPassFlags {
 	dispose?: () => void;
 }
 
+/**
+ * Minimal interface for compute passes in the render graph.
+ * Compute passes do not participate in slot routing.
+ */
+export interface ComputePassLike {
+	readonly isCompute: true;
+	enabled?: boolean;
+	setSize?: (width: number, height: number) => void;
+	dispose?: () => void;
+}
+
+/**
+ * Union type for all pass types accepted by the render graph.
+ */
+export type AnyPass = RenderPass | ComputePassLike;
+
 /**
  * Frame submission strategy for the scheduler.
  */
@@ -432,6 +552,14 @@ export interface FrameState {
 	 * Sets a texture value for current/next frame.
 	 */
 	setTexture: (name: string, value: TextureValue) => void;
+	/**
+	 * Writes data to a named storage buffer.
+	 */
+	writeStorageBuffer: (name: string, data: ArrayBufferView, options?: { offset?: number }) => void;
+	/**
+	 * Async readback of storage buffer data.
+	 */
+	readStorageBuffer: (name: string) => Promise<ArrayBuffer>;
 	/**
 	 * Invalidates frame for on-demand rendering.
 	 */
@@ -457,6 +585,18 @@ export interface FrameState {
 /**
  * Internal renderer construction options resolved from material/context state.
  */
+/**
+ * Pending storage buffer write queued from FrameState.
+ */
+export interface PendingStorageWrite {
+	/** Storage buffer name. */
+	name: string;
+	/** Data to write. */
+	data: ArrayBufferView;
+	/** Byte offset into the storage buffer. */
+	offset: number;
+}
+
 export interface RendererOptions {
 	/**
 	 * Target canvas.
@@ -513,22 +653,34 @@ export interface RendererOptions {
 	 * Texture definitions by key.
 	 */
 	textureDefinitions: TextureDefinitionMap;
+	/**
+	 * Sorted storage buffer keys.
+	 */
+	storageBufferKeys?: string[];
+	/**
+	 * Storage buffer definitions by key.
+	 */
+	storageBufferDefinitions?: Record<string, import('./types.js').StorageBufferDefinition>;
+	/**
+	 * Sorted storage texture keys (textures with storage:true).
+	 */
+	storageTextureKeys?: string[];
 	/**
 	 * Static render target definitions.
 	 */
 	renderTargets?: RenderTargetDefinitionMap;
 	/**
-	 * Static render passes.
+	 * Static render and compute passes.
 	 */
-	passes?: RenderPass[];
+	passes?: AnyPass[];
 	/**
 	 * Dynamic render targets provider.
 	 */
 	getRenderTargets?: () => RenderTargetDefinitionMap | undefined;
 	/**
-	 * Dynamic render passes provider.
+	 * Dynamic render and compute passes provider.
 	 */
-	getPasses?: () => RenderPass[] | undefined;
+	getPasses?: () => AnyPass[] | undefined;
 	/**
 	 * Requested output color space.
 	 */
@@ -574,7 +726,16 @@ export interface Renderer {
 			width: number;
 			height: number;
 		};
+		pendingStorageWrites?: PendingStorageWrite[];
 	}) => void;
+	/**
+	 * Returns the GPU buffer for a named storage buffer, if allocated.
+	 */
+	getStorageBuffer?: (name: string) => GPUBuffer | undefined;
+	/**
+	 * Returns the active GPU device (for readback operations).
+	 */
+	getDevice?: () => GPUDevice;
 	/**
 	 * Releases GPU resources and subscriptions.
 	 */