@motion-core/motion-gpu 0.4.2 → 0.6.0

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[] | undefined;
 	}) => 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.
 	 */

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;