@motion-core/motion-gpu 0.4.2 → 0.5.0

package/src/lib/passes/ComputePass.ts

@@ -0,0 +1,136 @@
+import { assertComputeContract, extractWorkgroupSize } from '../core/compute-shader.js';
+
+/**
+ * Dispatch context provided to dynamic dispatch callbacks.
+ */
+export interface ComputeDispatchContext {
+	width: number;
+	height: number;
+	time: number;
+	delta: number;
+	workgroupSize: [number, number, number];
+}
+
+/**
+ * Options for constructing a `ComputePass`.
+ */
+export interface ComputePassOptions {
+	/**
+	 * Compute shader WGSL source code.
+	 * Must declare `@compute @workgroup_size(...) fn compute(@builtin(global_invocation_id) ...)`.
+	 */
+	compute: string;
+	/**
+	 * Dispatch workgroup counts.
+	 * - Static tuple: `[x]`, `[x, y]`, or `[x, y, z]`
+	 * - `'auto'`: derived from canvas size / workgroup size
+	 * - Function: dynamic dispatch based on frame context
+	 */
+	dispatch?:
+		| [number, number?, number?]
+		| 'auto'
+		| ((ctx: ComputeDispatchContext) => [number, number, number]);
+	/**
+	 * Enables/disables this compute pass.
+	 */
+	enabled?: boolean;
+}
+
+/**
+ * Compute pass class used within the render graph.
+ *
+ * Validates compute shader contract, parses workgroup size,
+ * and resolves dispatch dimensions. Does **not** manage GPU resources
+ * (that responsibility belongs to the renderer).
+ */
+export class ComputePass {
+	/**
+	 * Enables/disables this pass without removing it from graph.
+	 */
+	enabled: boolean;
+
+	/**
+	 * Discriminant flag for render graph to identify compute passes.
+	 */
+	readonly isCompute = true as const;
+
+	private compute: string;
+	private workgroupSize: [number, number, number];
+	private dispatch: ComputePassOptions['dispatch'];
+
+	constructor(options: ComputePassOptions) {
+		assertComputeContract(options.compute);
+		const workgroupSize = extractWorkgroupSize(options.compute);
+		this.compute = options.compute;
+		this.workgroupSize = workgroupSize;
+		this.dispatch = options.dispatch ?? 'auto';
+		this.enabled = options.enabled ?? true;
+	}
+
+	/**
+	 * Replaces current compute shader and updates workgroup size.
+	 *
+	 * @param compute - New compute shader WGSL source.
+	 * @throws {Error} When shader does not match the compute contract.
+	 */
+	setCompute(compute: string): void {
+		assertComputeContract(compute);
+		const workgroupSize = extractWorkgroupSize(compute);
+		this.compute = compute;
+		this.workgroupSize = workgroupSize;
+	}
+
+	/**
+	 * Updates dispatch strategy.
+	 */
+	setDispatch(dispatch: ComputePassOptions['dispatch']): void {
+		this.dispatch = dispatch ?? 'auto';
+	}
+
+	/**
+	 * Returns current compute shader source.
+	 */
+	getCompute(): string {
+		return this.compute;
+	}
+
+	/**
+	 * Returns parsed workgroup size from current compute shader.
+	 */
+	getWorkgroupSize(): [number, number, number] {
+		return [...this.workgroupSize];
+	}
+
+	/**
+	 * Resolves dispatch workgroup counts for current frame.
+	 *
+	 * @param ctx - Dispatch context with canvas dimensions and timing.
+	 * @returns Tuple [x, y, z] workgroup counts.
+	 */
+	resolveDispatch(ctx: ComputeDispatchContext): [number, number, number] {
+		if (this.dispatch === 'auto') {
+			return [
+				Math.ceil(ctx.width / this.workgroupSize[0]),
+				Math.ceil(ctx.height / this.workgroupSize[1]),
+				Math.ceil(1 / this.workgroupSize[2])
+			];
+		}
+
+		if (typeof this.dispatch === 'function') {
+			return this.dispatch(ctx);
+		}
+
+		if (Array.isArray(this.dispatch)) {
+			return [this.dispatch[0], this.dispatch[1] ?? 1, this.dispatch[2] ?? 1];
+		}
+
+		return [1, 1, 1];
+	}
+
+	/**
+	 * Releases resources (no-op since GPU resource lifecycle is renderer-managed).
+	 */
+	dispose(): void {
+		// No-op — GPU resources are managed by the renderer.
+	}
+}

package/src/lib/passes/PingPongComputePass.ts

@@ -0,0 +1,180 @@
+import { assertComputeContract, extractWorkgroupSize } from '../core/compute-shader.js';
+import type { ComputePassOptions, ComputeDispatchContext } from './ComputePass.js';
+
+/**
+ * Options for constructing a `PingPongComputePass`.
+ */
+export interface PingPongComputePassOptions {
+	/**
+	 * Compute shader WGSL source code.
+	 */
+	compute: string;
+	/**
+	 * Target texture key from `material.textures`.
+	 * The engine will auto-generate `{target}A` and `{target}B` bindings.
+	 */
+	target: string;
+	/**
+	 * Number of compute iterations per frame. Default: 1.
+	 */
+	iterations?: number;
+	/**
+	 * Dispatch workgroup counts (same as ComputePass).
+	 */
+	dispatch?: ComputePassOptions['dispatch'];
+	/**
+	 * Enables/disables this pass.
+	 */
+	enabled?: boolean;
+}
+
+/**
+ * Ping-pong compute pass for iterative GPU simulations.
+ *
+ * Manages two texture buffers (A/B) and alternates between them each iteration,
+ * enabling read-from-previous-write patterns commonly used in fluid simulations,
+ * reaction-diffusion, and particle systems.
+ */
+export class PingPongComputePass {
+	/**
+	 * Enables/disables this pass without removing it from graph.
+	 */
+	enabled: boolean;
+
+	/**
+	 * Discriminant flag for render graph to identify compute passes.
+	 */
+	readonly isCompute = true as const;
+
+	/**
+	 * Discriminant flag to identify ping-pong compute passes.
+	 */
+	readonly isPingPong = true as const;
+
+	private compute: string;
+	private target: string;
+	private iterations: number;
+	private dispatch: ComputePassOptions['dispatch'];
+	private workgroupSize: [number, number, number];
+	private frameCount: number = 0;
+
+	constructor(options: PingPongComputePassOptions) {
+		assertComputeContract(options.compute);
+		const workgroupSize = extractWorkgroupSize(options.compute);
+		this.compute = options.compute;
+		this.target = options.target;
+		this.iterations = PingPongComputePass.assertIterations(options.iterations ?? 1);
+		this.dispatch = options.dispatch ?? 'auto';
+		this.enabled = options.enabled ?? true;
+		this.workgroupSize = workgroupSize;
+	}
+
+	private static assertIterations(count: number): number {
+		if (!Number.isFinite(count) || count < 1 || !Number.isInteger(count)) {
+			throw new Error(
+				`PingPongComputePass iterations must be a positive integer >= 1, got ${count}`
+			);
+		}
+		return count;
+	}
+
+	/**
+	 * Returns the texture key holding the latest result.
+	 * Alternates between `{target}A` and `{target}B` based on total iteration parity.
+	 */
+	getCurrentOutput(): string {
+		const totalIterations = this.frameCount * this.iterations;
+		return totalIterations % 2 === 0 ? `${this.target}A` : `${this.target}B`;
+	}
+
+	/**
+	 * Advances the internal frame counter (called by renderer after each frame's iterations).
+	 */
+	advanceFrame(): void {
+		this.frameCount += 1;
+	}
+
+	/**
+	 * Replaces compute shader and updates workgroup size.
+	 */
+	setCompute(compute: string): void {
+		assertComputeContract(compute);
+		const workgroupSize = extractWorkgroupSize(compute);
+		this.compute = compute;
+		this.workgroupSize = workgroupSize;
+	}
+
+	/**
+	 * Updates iteration count.
+	 *
+	 * @param count - Must be >= 1.
+	 */
+	setIterations(count: number): void {
+		this.iterations = PingPongComputePass.assertIterations(count);
+	}
+
+	/**
+	 * Updates dispatch strategy.
+	 */
+	setDispatch(dispatch: ComputePassOptions['dispatch']): void {
+		this.dispatch = dispatch ?? 'auto';
+	}
+
+	/**
+	 * Returns the target texture key.
+	 */
+	getTarget(): string {
+		return this.target;
+	}
+
+	/**
+	 * Returns the current iteration count.
+	 */
+	getIterations(): number {
+		return this.iterations;
+	}
+
+	/**
+	 * Returns current compute shader source.
+	 */
+	getCompute(): string {
+		return this.compute;
+	}
+
+	/**
+	 * Returns parsed workgroup size.
+	 */
+	getWorkgroupSize(): [number, number, number] {
+		return [...this.workgroupSize];
+	}
+
+	/**
+	 * Resolves dispatch workgroup counts for current frame.
+	 */
+	resolveDispatch(ctx: ComputeDispatchContext): [number, number, number] {
+		if (this.dispatch === 'auto') {
+			return [
+				Math.ceil(ctx.width / this.workgroupSize[0]),
+				Math.ceil(ctx.height / this.workgroupSize[1]),
+				Math.ceil(1 / this.workgroupSize[2])
+			];
+		}
+
+		if (typeof this.dispatch === 'function') {
+			return this.dispatch(ctx);
+		}
+
+		if (Array.isArray(this.dispatch)) {
+			return [this.dispatch[0], this.dispatch[1] ?? 1, this.dispatch[2] ?? 1];
+		}
+
+		return [1, 1, 1];
+	}
+
+	/**
+	 * Releases resources (no-op, GPU lifecycle is renderer-managed).
+	 */
+	dispose(): void {
+		// No-op
+	}
+}

package/src/lib/passes/ShaderPass.ts

@@ -65,8 +65,9 @@ export class ShaderPass extends FullscreenPass {
 	 * Replaces current shader fragment and invalidates pipeline cache.
 	 */
 	setFragment(fragment: string): void {
+		const nextProgram = buildShaderPassProgram(fragment);
 		this.fragment = fragment;
-		this.program = buildShaderPassProgram(fragment);
+		this.program = nextProgram;
 		this.invalidateFullscreenCache();
 	}
 

package/src/lib/passes/index.ts

@@ -1,3 +1,9 @@
 export { BlitPass, type BlitPassOptions } from './BlitPass.js';
 export { CopyPass, type CopyPassOptions } from './CopyPass.js';
 export { ShaderPass, type ShaderPassOptions } from './ShaderPass.js';
+export {
+	ComputePass,
+	type ComputePassOptions,
+	type ComputeDispatchContext
+} from './ComputePass.js';
+export { PingPongComputePass, type PingPongComputePassOptions } from './PingPongComputePass.js';

package/src/lib/react/FragCanvas.tsx

@@ -4,8 +4,8 @@ import type { FragMaterial } from '../core/material.js';
 import { createFrameRegistry } from '../core/frame-registry.js';
 import { createMotionGPURuntimeLoop } from '../core/runtime-loop.js';
 import type {
+	AnyPass,
 	OutputColorSpace,
-	RenderPass,
 	RenderMode,
 	RenderTargetDefinitionMap
 } from '../core/types.js';
@@ -17,7 +17,7 @@ import { MotionGPUReactContext, type MotionGPUContext } from './motiongpu-contex
 export interface FragCanvasProps {
 	material: FragMaterial;
 	renderTargets?: RenderTargetDefinitionMap;
-	passes?: RenderPass[];
+	passes?: AnyPass[];
 	clearColor?: [number, number, number, number];
 	outputColorSpace?: OutputColorSpace;
 	renderMode?: RenderMode;
@@ -39,7 +39,7 @@ export interface FragCanvasProps {
 interface RuntimePropsSnapshot {
 	material: FragMaterial;
 	renderTargets: RenderTargetDefinitionMap;
-	passes: RenderPass[];
+	passes: AnyPass[];
 	clearColor: [number, number, number, number];
 	outputColorSpace: OutputColorSpace;
 	adapterOptions: GPURequestAdapterOptions | undefined;

package/src/lib/react/MotionGPUErrorOverlay.tsx

@@ -75,6 +75,19 @@ const MOTIONGPU_ERROR_OVERLAY_STYLES = `
 	border-bottom: 1px solid var(--motiongpu-color-border);
 }
 
+.motiongpu-error-header-top {
+	display: flex;
+	align-items: flex-start;
+	gap: 0.75rem;
+}
+
+.motiongpu-error-badges {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.4rem;
+	flex-wrap: wrap;
+}
+
 .motiongpu-error-badge-wrap {
 	display: inline-flex;
 	align-items: center;
@@ -86,7 +99,7 @@ const MOTIONGPU_ERROR_OVERLAY_STYLES = `
 	background: var(--motiongpu-color-background-muted);
 }
 
-.motiongpu-error-phase {
+.motiongpu-error-badge {
 	display: inline-flex;
 	align-items: center;
 	margin: 0;
@@ -106,6 +119,20 @@ const MOTIONGPU_ERROR_OVERLAY_STYLES = `
 	box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.24);
 }
 
+.motiongpu-error-recoverable {
+	margin: 0;
+	font-size: 0.67rem;
+	line-height: 1.2;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--motiongpu-color-foreground-muted);
+}
+
+.motiongpu-error-recoverable span {
+	font-family: var(--motiongpu-font-mono);
+	color: var(--motiongpu-color-foreground);
+}
+
 .motiongpu-error-title {
 	margin: 0;
 	font-size: clamp(1.02rem, 1vw + 0.72rem, 1.32rem);
@@ -285,6 +312,11 @@ const MOTIONGPU_ERROR_OVERLAY_STYLES = `
 	.motiongpu-error-title {
 		font-size: 1.02rem;
 	}
+
+	.motiongpu-error-header-top {
+		flex-direction: column;
+		align-items: flex-start;
+	}
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -302,7 +334,87 @@ function normalizeErrorText(value: string): string {
 }
 
 function shouldShowErrorMessage(value: MotionGPUErrorReport): boolean {
-	return normalizeErrorText(value.message) !== normalizeErrorText(value.title);
+	return resolveDisplayMessage(value).length > 0;
+}
+
+function resolveDisplayMessage(value: MotionGPUErrorReport): string {
+	const rawMessage = value.message.trim();
+	if (rawMessage.length === 0) {
+		return '';
+	}
+
+	const normalizedMessage = normalizeErrorText(rawMessage);
+	const normalizedTitle = normalizeErrorText(value.title);
+	if (normalizedMessage === normalizedTitle) {
+		return '';
+	}
+
+	const escapedTitle = value.title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+	const prefixPattern = new RegExp(`^${escapedTitle}\\s*[:\\-|]\\s*`, 'i');
+	const stripped = rawMessage.replace(prefixPattern, '').trim();
+	return stripped.length > 0 ? stripped : rawMessage;
+}
+
+function formatRuntimeContext(context: MotionGPUErrorReport['context']): string {
+	if (!context) {
+		return '';
+	}
+
+	const indentBlock = (value: string, spaces = 2): string => {
+		const prefix = ' '.repeat(spaces);
+		return value
+			.split('\n')
+			.map((line) => `${prefix}${line}`)
+			.join('\n');
+	};
+
+	const formatMaterialSignature = (value: string): string => {
+		const trimmed = value.trim();
+		if (trimmed.length === 0) {
+			return '<empty>';
+		}
+		try {
+			return JSON.stringify(JSON.parse(trimmed), null, 2);
+		} catch {
+			return trimmed;
+		}
+	};
+
+	const lines: string[] = [];
+	if (context.materialSignature) {
+		lines.push('materialSignature:');
+		lines.push(indentBlock(formatMaterialSignature(context.materialSignature)));
+	}
+	if (context.passGraph) {
+		lines.push('passGraph:');
+		lines.push(`  passCount: ${context.passGraph.passCount}`);
+		lines.push(`  enabledPassCount: ${context.passGraph.enabledPassCount}`);
+		lines.push('  inputs:');
+		if (context.passGraph.inputs.length === 0) {
+			lines.push('    - <none>');
+		} else {
+			for (const input of context.passGraph.inputs) {
+				lines.push(`    - ${input}`);
+			}
+		}
+		lines.push('  outputs:');
+		if (context.passGraph.outputs.length === 0) {
+			lines.push('    - <none>');
+		} else {
+			for (const output of context.passGraph.outputs) {
+				lines.push(`    - ${output}`);
+			}
+		}
+	}
+	lines.push('activeRenderTargets:');
+	if (context.activeRenderTargets.length === 0) {
+		lines.push('  - <none>');
+	} else {
+		for (const target of context.activeRenderTargets) {
+			lines.push(`  - ${target}`);
+		}
+	}
+	return lines.join('\n');
 }
 
 export function MotionGPUErrorOverlay({ report }: MotionGPUErrorOverlayProps) {
@@ -320,14 +432,28 @@ export function MotionGPUErrorOverlay({ report }: MotionGPUErrorOverlayProps) {
 					data-testid="motiongpu-error"
 				>
 					<header className="motiongpu-error-header">
-						<div className="motiongpu-error-badge-wrap">
-							<p className="motiongpu-error-phase">{report.phase}</p>
+						<div className="motiongpu-error-header-top">
+							<div className="motiongpu-error-badges">
+								<div className="motiongpu-error-badge-wrap">
+									<p className="motiongpu-error-badge motiongpu-error-badge-phase">
+										{report.phase}
+									</p>
+								</div>
+								<div className="motiongpu-error-badge-wrap">
+									<p className="motiongpu-error-badge motiongpu-error-badge-severity">
+										{report.severity}
+									</p>
+								</div>
+							</div>
 						</div>
 						<h2 className="motiongpu-error-title">{report.title}</h2>
+						<p className="motiongpu-error-recoverable">
+							Recoverable: <span>{report.recoverable ? 'yes' : 'no'}</span>
+						</p>
 					</header>
 					<div className="motiongpu-error-body">
 						{shouldShowErrorMessage(report) ? (
-							<p className="motiongpu-error-message">{report.message}</p>
+							<p className="motiongpu-error-message">{resolveDisplayMessage(report)}</p>
 						) : null}
 						<p className="motiongpu-error-hint">{report.hint}</p>
 					</div>
@@ -384,6 +510,12 @@ export function MotionGPUErrorOverlay({ report }: MotionGPUErrorOverlayProps) {
 								<pre>{report.stack.join('\n')}</pre>
 							</details>
 						) : null}
+						{report.context ? (
+							<details className="motiongpu-error-details">
+								<summary>Runtime context</summary>
+								<pre>{formatRuntimeContext(report.context)}</pre>
+							</details>
+						) : null}
 					</div>
 				</section>
 			</div>

package/src/lib/react/index.ts

@@ -3,7 +3,13 @@
  */
 export { FragCanvas } from './FragCanvas.js';
 export { defineMaterial } from '../core/material.js';
-export { BlitPass, CopyPass, ShaderPass } from '../passes/index.js';
+export {
+	BlitPass,
+	CopyPass,
+	ShaderPass,
+	ComputePass,
+	PingPongComputePass
+} from '../passes/index.js';
 export { useMotionGPU } from './motiongpu-context.js';
 export { useFrame } from './frame-context.js';
 export { useTexture } from './use-texture.js';
@@ -11,6 +17,8 @@ export type {
 	FrameInvalidationToken,
 	FrameState,
 	OutputColorSpace,
+	AnyPass,
+	ComputePassLike,
 	RenderPass,
 	RenderPassContext,
 	RenderPassFlags,
@@ -49,3 +57,12 @@ export type {
 export type { MotionGPUContext } from './motiongpu-context.js';
 export type { UseFrameOptions, UseFrameResult } from './frame-context.js';
 export type { TextureUrlInput, UseTextureResult } from './use-texture.js';
+export type {
+	StorageBufferAccess,
+	StorageBufferDefinition,
+	StorageBufferDefinitionMap,
+	StorageBufferType,
+	ComputePassContext
+} from '../core/types.js';
+export type { ComputePassOptions, ComputeDispatchContext } from '../passes/ComputePass.js';
+export type { PingPongComputePassOptions } from '../passes/PingPongComputePass.js';

package/src/lib/svelte/FragCanvas.svelte

@@ -7,9 +7,9 @@
 	import MotionGPUErrorOverlay from './MotionGPUErrorOverlay.svelte';
 	import { createMotionGPURuntimeLoop } from '../core/runtime-loop';
 	import type {
+		AnyPass,
 		FrameInvalidationToken,
 		OutputColorSpace,
-		RenderPass,
 		RenderMode,
 		RenderTargetDefinitionMap
 	} from '../core/types';
@@ -19,7 +19,7 @@
 	interface Props {
 		material: FragMaterial;
 		renderTargets?: RenderTargetDefinitionMap;
-		passes?: RenderPass[];
+		passes?: AnyPass[];
 		clearColor?: [number, number, number, number];
 		outputColorSpace?: OutputColorSpace;
 		renderMode?: RenderMode;