@motion-core/motion-gpu 0.4.1 → 0.5.0

package/src/lib/passes/FullscreenPass.ts

@@ -0,0 +1,173 @@
+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 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: GPUFilterMode;
+	private device: GPUDevice | null = null;
+	private sampler: GPUSampler | null = null;
+	private bindGroupLayout: GPUBindGroupLayout | null = null;
+	private shaderModule: GPUShaderModule | null = null;
+	private readonly pipelineByFormat = new Map<GPUTextureFormat, GPURenderPipeline>();
+	private bindGroupByView = new WeakMap<GPUTextureView, GPUBindGroup>();
+
+	protected constructor(options: FullscreenPassOptions = {}) {
+		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';
+	}
+
+	protected abstract getProgram(): string;
+	protected abstract getVertexEntryPoint(): string;
+	protected abstract getFragmentEntryPoint(): string;
+
+	protected invalidateFullscreenCache(): void {
+		this.shaderModule = null;
+		this.pipelineByFormat.clear();
+		this.bindGroupByView = new WeakMap();
+	}
+
+	private ensureResources(
+		device: GPUDevice,
+		format: GPUTextureFormat
+	): {
+		sampler: GPUSampler;
+		bindGroupLayout: GPUBindGroupLayout;
+		pipeline: GPURenderPipeline;
+	} {
+		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: number, height: number): void {
+		void width;
+		void height;
+	}
+
+	protected renderFullscreen(context: RenderPassContext): void {
+		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: RenderPassContext): void {
+		this.renderFullscreen(context);
+	}
+
+	dispose(): void {
+		this.device = null;
+		this.sampler = null;
+		this.bindGroupLayout = null;
+		this.invalidateFullscreenCache();
+	}
+}

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

@@ -0,0 +1,89 @@
+import { FullscreenPass, type FullscreenPassOptions } from './FullscreenPass.js';
+
+const SHADER_PASS_CONTRACT =
+	/\bfn\s+shade\s*\(\s*inputColor\s*:\s*vec4f\s*,\s*uv\s*:\s*vec2f\s*\)\s*->\s*vec4f/;
+
+export interface ShaderPassOptions extends FullscreenPassOptions {
+	fragment: string;
+}
+
+function buildShaderPassProgram(fragment: string): string {
+	if (!SHADER_PASS_CONTRACT.test(fragment)) {
+		throw new Error(
+			'ShaderPass fragment must declare `fn shade(inputColor: vec4f, uv: vec2f) -> vec4f`.'
+		);
+	}
+
+	return `
+struct MotionGPUVertexOut {
+	@builtin(position) position: vec4f,
+	@location(0) uv: vec2f,
+};
+
+@group(0) @binding(0) var motiongpuShaderPassSampler: sampler;
+@group(0) @binding(1) var motiongpuShaderPassTexture: texture_2d<f32>;
+
+@vertex
+fn motiongpuShaderPassVertex(@builtin(vertex_index) index: u32) -> MotionGPUVertexOut {
+	var positions = array<vec2f, 3>(
+		vec2f(-1.0, -3.0),
+		vec2f(-1.0, 1.0),
+		vec2f(3.0, 1.0)
+	);
+
+	let position = positions[index];
+	var out: MotionGPUVertexOut;
+	out.position = vec4f(position, 0.0, 1.0);
+	out.uv = (position + vec2f(1.0, 1.0)) * 0.5;
+	return out;
+}
+
+${fragment}
+
+@fragment
+fn motiongpuShaderPassFragment(in: MotionGPUVertexOut) -> @location(0) vec4f {
+	let inputColor = textureSample(motiongpuShaderPassTexture, motiongpuShaderPassSampler, in.uv);
+	return shade(inputColor, in.uv);
+}
+`;
+}
+
+/**
+ * Fullscreen programmable shader pass.
+ */
+export class ShaderPass extends FullscreenPass {
+	private fragment: string;
+	private program: string;
+
+	constructor(options: ShaderPassOptions) {
+		super(options);
+		this.fragment = options.fragment;
+		this.program = buildShaderPassProgram(options.fragment);
+	}
+
+	/**
+	 * Replaces current shader fragment and invalidates pipeline cache.
+	 */
+	setFragment(fragment: string): void {
+		const nextProgram = buildShaderPassProgram(fragment);
+		this.fragment = fragment;
+		this.program = nextProgram;
+		this.invalidateFullscreenCache();
+	}
+
+	getFragment(): string {
+		return this.fragment;
+	}
+
+	protected getProgram(): string {
+		return this.program;
+	}
+
+	protected getVertexEntryPoint(): string {
+		return 'motiongpuShaderPassVertex';
+	}
+
+	protected getFragmentEntryPoint(): string {
+		return 'motiongpuShaderPassFragment';
+	}
+}

package/src/lib/passes/index.ts

@@ -0,0 +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';