@motion-core/motion-gpu 0.4.0 → 0.4.2

package/src/lib/core/uniforms.ts

@@ -0,0 +1,282 @@
+import type {
+	UniformLayout,
+	UniformLayoutEntry,
+	UniformMap,
+	UniformMat4Value,
+	UniformType,
+	UniformValue
+} from './types.js';
+
+/**
+ * Internal representation of explicitly typed uniform input.
+ */
+type UniformTypedInput = Extract<UniformValue, { type: UniformType; value: unknown }>;
+
+/**
+ * Valid WGSL identifier pattern used for uniform and texture keys.
+ */
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Rounds a value up to the nearest multiple of `alignment`.
+ */
+function roundUp(value: number, alignment: number): number {
+	return Math.ceil(value / alignment) * alignment;
+}
+
+/**
+ * Returns WGSL std140-like alignment and size metadata for a uniform type.
+ */
+function getTypeLayout(type: UniformType): { alignment: number; size: number } {
+	switch (type) {
+		case 'f32':
+			return { alignment: 4, size: 4 };
+		case 'vec2f':
+			return { alignment: 8, size: 8 };
+		case 'vec3f':
+			return { alignment: 16, size: 12 };
+		case 'vec4f':
+			return { alignment: 16, size: 16 };
+		case 'mat4x4f':
+			return { alignment: 16, size: 64 };
+		default:
+			throw new Error(`Unsupported uniform type: ${type satisfies never}`);
+	}
+}
+
+/**
+ * Type guard for explicitly typed uniform objects.
+ */
+function isTypedUniformValue(value: UniformValue): value is UniformTypedInput {
+	return typeof value === 'object' && value !== null && 'type' in value && 'value' in value;
+}
+
+/**
+ * Validates numeric tuple input with a fixed length.
+ */
+function isTuple(value: unknown, size: number): value is number[] {
+	return (
+		Array.isArray(value) &&
+		value.length === size &&
+		value.every((entry) => typeof entry === 'number' && Number.isFinite(entry))
+	);
+}
+
+/**
+ * Type guard for accepted 4x4 matrix uniform values.
+ */
+function isMat4Value(value: unknown): value is UniformMat4Value {
+	if (value instanceof Float32Array) {
+		return value.length === 16;
+	}
+
+	return (
+		Array.isArray(value) &&
+		value.length === 16 &&
+		value.every((entry) => typeof entry === 'number' && Number.isFinite(entry))
+	);
+}
+
+/**
+ * Asserts that a name can be safely used as a WGSL identifier.
+ *
+ * @param name - Candidate uniform/texture name.
+ * @throws {Error} When the identifier is invalid.
+ */
+export function assertUniformName(name: string): void {
+	if (!IDENTIFIER_PATTERN.test(name)) {
+		throw new Error(`Invalid uniform name: ${name}`);
+	}
+}
+
+/**
+ * Infers the WGSL type tag from a runtime uniform value.
+ *
+ * @param value - Uniform input value.
+ * @returns Inferred uniform type.
+ * @throws {Error} When the value does not match any supported shape.
+ */
+export function inferUniformType(value: UniformValue): UniformType {
+	if (isTypedUniformValue(value)) {
+		return value.type;
+	}
+
+	if (typeof value === 'number') {
+		return 'f32';
+	}
+
+	if (Array.isArray(value)) {
+		if (value.length === 2) {
+			return 'vec2f';
+		}
+		if (value.length === 3) {
+			return 'vec3f';
+		}
+		if (value.length === 4) {
+			return 'vec4f';
+		}
+	}
+
+	throw new Error('Uniform value must resolve to f32, vec2f, vec3f, vec4f or mat4x4f');
+}
+
+/**
+ * Validates that a uniform value matches an explicit uniform type declaration.
+ *
+ * @param type - Declared WGSL type.
+ * @param value - Runtime value to validate.
+ * @throws {Error} When the value shape is incompatible with the declared type.
+ */
+export function assertUniformValueForType(type: UniformType, value: UniformValue): void {
+	const input = isTypedUniformValue(value) ? value.value : value;
+
+	if (type === 'f32') {
+		if (typeof input !== 'number' || !Number.isFinite(input)) {
+			throw new Error('Uniform f32 value must be a finite number');
+		}
+		return;
+	}
+
+	if (type === 'vec2f') {
+		if (!isTuple(input, 2)) {
+			throw new Error('Uniform vec2f value must be a tuple with 2 numbers');
+		}
+		return;
+	}
+
+	if (type === 'vec3f') {
+		if (!isTuple(input, 3)) {
+			throw new Error('Uniform vec3f value must be a tuple with 3 numbers');
+		}
+		return;
+	}
+
+	if (type === 'vec4f') {
+		if (!isTuple(input, 4)) {
+			throw new Error('Uniform vec4f value must be a tuple with 4 numbers');
+		}
+		return;
+	}
+
+	if (!isMat4Value(input)) {
+		throw new Error('Uniform mat4x4f value must contain 16 numbers');
+	}
+}
+
+/**
+ * Resolves a deterministic packed uniform buffer layout from a uniform map.
+ *
+ * @param uniforms - Input uniform definitions.
+ * @returns Sorted layout with byte offsets and final buffer byte length.
+ */
+export function resolveUniformLayout(uniforms: UniformMap): UniformLayout {
+	const names = Object.keys(uniforms).sort();
+	let offset = 0;
+	const entries: UniformLayoutEntry[] = [];
+	const byName: Record<string, UniformLayoutEntry> = {};
+
+	for (const name of names) {
+		assertUniformName(name);
+		const type = inferUniformType(uniforms[name] as UniformValue);
+		const { alignment, size } = getTypeLayout(type);
+		offset = roundUp(offset, alignment);
+
+		const entry: UniformLayoutEntry = {
+			name,
+			type,
+			offset,
+			size
+		};
+
+		entries.push(entry);
+		byName[name] = entry;
+		offset += size;
+	}
+
+	const byteLength = Math.max(16, roundUp(offset, 16));
+	return { entries, byName, byteLength };
+}
+
+/**
+ * Writes one validated uniform value directly into the output float buffer.
+ */
+function writeUniformValue(
+	type: UniformType,
+	value: UniformValue,
+	data: Float32Array,
+	base: number
+): void {
+	const input = isTypedUniformValue(value) ? value.value : value;
+	assertUniformValueForType(type, value);
+
+	if (type === 'f32') {
+		data[base] = input as number;
+		return;
+	}
+
+	if (type === 'mat4x4f') {
+		const matrix = input as UniformMat4Value;
+		if (matrix instanceof Float32Array) {
+			for (let index = 0; index < 16; index += 1) {
+				data[base + index] = matrix[index] ?? 0;
+			}
+			return;
+		}
+
+		for (let index = 0; index < 16; index += 1) {
+			data[base + index] = matrix[index] ?? 0;
+		}
+		return;
+	}
+
+	const tuple = input as number[];
+	const length = type === 'vec2f' ? 2 : type === 'vec3f' ? 3 : 4;
+	for (let index = 0; index < length; index += 1) {
+		data[base + index] = tuple[index] ?? 0;
+	}
+}
+
+/**
+ * Packs uniforms into a newly allocated `Float32Array`.
+ *
+ * @param uniforms - Uniform values to pack.
+ * @param layout - Target layout definition.
+ * @returns Packed float buffer sized to `layout.byteLength`.
+ */
+export function packUniforms(uniforms: UniformMap, layout: UniformLayout): Float32Array {
+	const data = new Float32Array(layout.byteLength / 4);
+	packUniformsInto(uniforms, layout, data);
+	return data;
+}
+
+/**
+ * Packs uniforms into an existing output buffer and zeroes missing values.
+ *
+ * @param uniforms - Uniform values to pack.
+ * @param layout - Target layout metadata.
+ * @param data - Destination float buffer.
+ * @throws {Error} When `data` size does not match the required layout size.
+ */
+export function packUniformsInto(
+	uniforms: UniformMap,
+	layout: UniformLayout,
+	data: Float32Array
+): void {
+	const requiredLength = layout.byteLength / 4;
+	if (data.length !== requiredLength) {
+		throw new Error(
+			`Uniform output buffer size mismatch. Expected ${requiredLength}, got ${data.length}`
+		);
+	}
+
+	data.fill(0);
+	for (const entry of layout.entries) {
+		const raw = uniforms[entry.name];
+		if (raw === undefined) {
+			continue;
+		}
+
+		const base = entry.offset / 4;
+		writeUniformValue(entry.type, raw, data, base);
+	}
+}

package/src/lib/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Root package entrypoint.
+ *
+ * Framework-agnostic core entrypoint.
+ */
+export * from './core/index.js';

package/src/lib/passes/BlitPass.ts

@@ -0,0 +1,54 @@
+import { FullscreenPass, type FullscreenPassOptions } from './FullscreenPass.js';
+
+const FULLSCREEN_BLIT_SHADER = `
+struct MotionGPUVertexOut {
+	@builtin(position) position: vec4f,
+	@location(0) uv: vec2f,
+};
+
+@group(0) @binding(0) var motiongpuBlitSampler: sampler;
+@group(0) @binding(1) var motiongpuBlitTexture: texture_2d<f32>;
+
+@vertex
+fn motiongpuBlitVertex(@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
+fn motiongpuBlitFragment(in: MotionGPUVertexOut) -> @location(0) vec4f {
+	return textureSample(motiongpuBlitTexture, motiongpuBlitSampler, in.uv);
+}
+`;
+
+export type BlitPassOptions = FullscreenPassOptions;
+
+/**
+ * Fullscreen texture blit pass.
+ */
+export class BlitPass extends FullscreenPass {
+	protected getProgram(): string {
+		return FULLSCREEN_BLIT_SHADER;
+	}
+
+	constructor(options: BlitPassOptions = {}) {
+		super(options);
+	}
+
+	protected getVertexEntryPoint(): string {
+		return 'motiongpuBlitVertex';
+	}
+
+	protected getFragmentEntryPoint(): string {
+		return 'motiongpuBlitFragment';
+	}
+}

package/src/lib/passes/CopyPass.ts

@@ -0,0 +1,80 @@
+import type {
+	RenderPass,
+	RenderPassContext,
+	RenderPassFlags,
+	RenderPassInputSlot,
+	RenderPassOutputSlot
+} from '../core/types.js';
+import { BlitPass } from './BlitPass.js';
+
+export interface CopyPassOptions extends RenderPassFlags {
+	enabled?: boolean;
+	needsSwap?: boolean;
+	input?: RenderPassInputSlot;
+	output?: RenderPassOutputSlot;
+	filter?: GPUFilterMode;
+}
+
+/**
+ * Texture copy pass with fullscreen-blit fallback.
+ */
+export class CopyPass implements RenderPass {
+	enabled: boolean;
+	needsSwap: boolean;
+	input: RenderPassInputSlot;
+	output: RenderPassOutputSlot;
+	clear: boolean;
+	clearColor: [number, number, number, number];
+	preserve: boolean;
+	private readonly fallbackBlit: BlitPass;
+
+	constructor(options: CopyPassOptions = {}) {
+		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.fallbackBlit = new BlitPass({
+			enabled: true,
+			needsSwap: false,
+			input: this.input,
+			output: this.output,
+			...(options.filter !== undefined ? { filter: options.filter } : {})
+		});
+	}
+
+	setSize(width: number, height: number): void {
+		this.fallbackBlit.setSize(width, height);
+	}
+
+	render(context: RenderPassContext): void {
+		const source = context.input;
+		const target = context.output;
+		const canDirectCopy =
+			context.clear === false &&
+			context.preserve === true &&
+			source.texture !== target.texture &&
+			source.texture !== context.canvas.texture &&
+			target.texture !== context.canvas.texture &&
+			source.width === target.width &&
+			source.height === target.height &&
+			source.format === target.format;
+
+		if (canDirectCopy) {
+			context.commandEncoder.copyTextureToTexture(
+				{ texture: source.texture },
+				{ texture: target.texture },
+				{ width: source.width, height: source.height, depthOrArrayLayers: 1 }
+			);
+			return;
+		}
+
+		this.fallbackBlit.render(context);
+	}
+
+	dispose(): void {
+		this.fallbackBlit.dispose();
+	}
+}

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/ShaderPass.ts

@@ -0,0 +1,88 @@
+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 {
+		this.fragment = fragment;
+		this.program = buildShaderPassProgram(fragment);
+		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,3 @@
+export { BlitPass, type BlitPassOptions } from './BlitPass.js';
+export { CopyPass, type CopyPassOptions } from './CopyPass.js';
+export { ShaderPass, type ShaderPassOptions } from './ShaderPass.js';