@motion-core/motion-gpu 0.4.1 → 0.5.0

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/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/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();
+	}
+}