@motion-core/motion-gpu 0.4.1 → 0.5.0

package/src/lib/react/use-texture.ts

@@ -0,0 +1,233 @@
+import { useCallback, useEffect, useRef } from 'react';
+import {
+	createCurrentWritable as currentWritable,
+	type CurrentReadable
+} from '../core/current-value.js';
+import {
+	isAbortError,
+	loadTexturesFromUrls,
+	type LoadedTexture,
+	type TextureLoadOptions
+} from '../core/texture-loader.js';
+import { toMotionGPUErrorReport, type MotionGPUErrorReport } from '../core/error-report.js';
+
+/**
+ * Reactive state returned by `useTexture`.
+ */
+export interface UseTextureResult {
+	/**
+	 * Loaded textures or `null` when unavailable/failed.
+	 */
+	textures: CurrentReadable<LoadedTexture[] | null>;
+	/**
+	 * `true` while an active load request is running.
+	 */
+	loading: CurrentReadable<boolean>;
+	/**
+	 * Last loading error.
+	 */
+	error: CurrentReadable<Error | null>;
+	/**
+	 * Last loading error normalized to MotionGPU diagnostics report shape.
+	 */
+	errorReport: CurrentReadable<MotionGPUErrorReport | null>;
+	/**
+	 * Reloads all textures using current URL input.
+	 */
+	reload: () => Promise<void>;
+}
+
+/**
+ * Supported URL input variants for `useTexture`.
+ */
+export type TextureUrlInput = string[] | (() => string[]);
+
+/**
+ * Normalizes unknown thrown values to an `Error` instance.
+ */
+function toError(error: unknown): Error {
+	if (error instanceof Error) {
+		return error;
+	}
+
+	return new Error('Unknown texture loading error');
+}
+
+/**
+ * Releases GPU-side resources for a list of loaded textures.
+ */
+function disposeTextures(list: LoadedTexture[] | null): void {
+	for (const texture of list ?? []) {
+		texture.dispose();
+	}
+}
+
+interface MergedAbortSignal {
+	signal: AbortSignal;
+	dispose: () => void;
+}
+
+function mergeAbortSignals(
+	primary: AbortSignal,
+	secondary: AbortSignal | undefined
+): MergedAbortSignal {
+	if (!secondary) {
+		return {
+			signal: primary,
+			dispose: () => {}
+		};
+	}
+
+	if (typeof AbortSignal.any === 'function') {
+		return {
+			signal: AbortSignal.any([primary, secondary]),
+			dispose: () => {}
+		};
+	}
+
+	const fallback = new AbortController();
+	let disposed = false;
+	const cleanup = (): void => {
+		if (disposed) {
+			return;
+		}
+		disposed = true;
+		primary.removeEventListener('abort', abort);
+		secondary.removeEventListener('abort', abort);
+	};
+	const abort = (): void => fallback.abort();
+
+	primary.addEventListener('abort', abort, { once: true });
+	secondary.addEventListener('abort', abort, { once: true });
+
+	return {
+		signal: fallback.signal,
+		dispose: cleanup
+	};
+}
+
+/**
+ * Loads textures from URLs and exposes reactive loading/error state.
+ *
+ * @param urlInput - URLs array or lazy URL provider.
+ * @param options - Loader options passed to URL fetch/decode pipeline.
+ * @returns Reactive texture loading state with reload support.
+ */
+export function useTexture(
+	urlInput: TextureUrlInput,
+	options: TextureLoadOptions = {}
+): UseTextureResult {
+	const texturesRef = useRef(currentWritable<LoadedTexture[] | null>(null));
+	const loadingRef = useRef(currentWritable(true));
+	const errorRef = useRef(currentWritable<Error | null>(null));
+	const errorReportRef = useRef(currentWritable<MotionGPUErrorReport | null>(null));
+	const activeControllerRef = useRef<AbortController | null>(null);
+	const runningLoadRef = useRef<Promise<void> | null>(null);
+	const reloadQueuedRef = useRef(false);
+	const requestVersionRef = useRef(0);
+	const disposedRef = useRef(false);
+	const optionsRef = useRef(options);
+	const urlInputRef = useRef(urlInput);
+
+	optionsRef.current = options;
+	urlInputRef.current = urlInput;
+
+	const getUrls = useCallback((): string[] => {
+		const currentInput = urlInputRef.current;
+		return typeof currentInput === 'function' ? currentInput() : currentInput;
+	}, []);
+
+	const executeLoad = useCallback(async (): Promise<void> => {
+		if (disposedRef.current) {
+			return;
+		}
+
+		const version = ++requestVersionRef.current;
+		const controller = new AbortController();
+		activeControllerRef.current = controller;
+		loadingRef.current.set(true);
+		errorRef.current.set(null);
+		errorReportRef.current.set(null);
+
+		const previous = texturesRef.current.current;
+		const mergedSignal = mergeAbortSignals(controller.signal, optionsRef.current.signal);
+		try {
+			const loaded = await loadTexturesFromUrls(getUrls(), {
+				...optionsRef.current,
+				signal: mergedSignal.signal
+			});
+			if (disposedRef.current || version !== requestVersionRef.current) {
+				disposeTextures(loaded);
+				return;
+			}
+
+			texturesRef.current.set(loaded);
+			disposeTextures(previous);
+		} catch (nextError) {
+			if (disposedRef.current || version !== requestVersionRef.current) {
+				return;
+			}
+
+			if (isAbortError(nextError)) {
+				return;
+			}
+
+			disposeTextures(previous);
+			texturesRef.current.set(null);
+			const normalizedError = toError(nextError);
+			errorRef.current.set(normalizedError);
+			errorReportRef.current.set(toMotionGPUErrorReport(normalizedError, 'initialization'));
+		} finally {
+			if (!disposedRef.current && version === requestVersionRef.current) {
+				loadingRef.current.set(false);
+			}
+			if (activeControllerRef.current === controller) {
+				activeControllerRef.current = null;
+			}
+			mergedSignal.dispose();
+		}
+	}, [getUrls]);
+
+	const runLoadLoop = useCallback(async (): Promise<void> => {
+		do {
+			reloadQueuedRef.current = false;
+			await executeLoad();
+		} while (reloadQueuedRef.current && !disposedRef.current);
+	}, [executeLoad]);
+
+	const load = useCallback((): Promise<void> => {
+		activeControllerRef.current?.abort();
+		if (runningLoadRef.current) {
+			reloadQueuedRef.current = true;
+			return runningLoadRef.current;
+		}
+
+		const pending = runLoadLoop();
+		const trackedPending = pending.finally(() => {
+			if (runningLoadRef.current === trackedPending) {
+				runningLoadRef.current = null;
+			}
+		});
+		runningLoadRef.current = trackedPending;
+		return trackedPending;
+	}, [runLoadLoop]);
+
+	useEffect(() => {
+		void load();
+
+		return () => {
+			disposedRef.current = true;
+			requestVersionRef.current += 1;
+			activeControllerRef.current?.abort();
+			disposeTextures(texturesRef.current.current);
+		};
+	}, [load]);
+
+	return {
+		textures: texturesRef.current,
+		loading: loadingRef.current,
+		error: errorRef.current,
+		errorReport: errorReportRef.current,
+		reload: load
+	};
+}

package/src/lib/svelte/FragCanvas.svelte

@@ -0,0 +1,249 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import type { Snippet } from 'svelte';
+	import type { FragMaterial } from '../core/material';
+	import { createCurrentWritable as currentWritable } from '../core/current-value';
+	import { toMotionGPUErrorReport, type MotionGPUErrorReport } from '../core/error-report';
+	import MotionGPUErrorOverlay from './MotionGPUErrorOverlay.svelte';
+	import { createMotionGPURuntimeLoop } from '../core/runtime-loop';
+	import type {
+		AnyPass,
+		FrameInvalidationToken,
+		OutputColorSpace,
+		RenderMode,
+		RenderTargetDefinitionMap
+	} from '../core/types';
+	import { provideMotionGPUContext } from './motiongpu-context';
+	import { createFrameRegistry, provideFrameRegistry } from './frame-context';
+
+	interface Props {
+		material: FragMaterial;
+		renderTargets?: RenderTargetDefinitionMap;
+		passes?: AnyPass[];
+		clearColor?: [number, number, number, number];
+		outputColorSpace?: OutputColorSpace;
+		renderMode?: RenderMode;
+		autoRender?: boolean;
+		maxDelta?: number;
+		adapterOptions?: GPURequestAdapterOptions;
+		deviceDescriptor?: GPUDeviceDescriptor;
+		dpr?: number;
+		showErrorOverlay?: boolean;
+		errorRenderer?: Snippet<[MotionGPUErrorReport]>;
+		onError?: (report: MotionGPUErrorReport) => void;
+		errorHistoryLimit?: number;
+		onErrorHistory?: (history: MotionGPUErrorReport[]) => void;
+		class?: string;
+		style?: string;
+		children?: Snippet;
+	}
+
+	const initialDpr = typeof window === 'undefined' ? 1 : (window.devicePixelRatio ?? 1);
+
+	let {
+		material,
+		renderTargets = {},
+		passes = [],
+		clearColor = [0, 0, 0, 1],
+		outputColorSpace = 'srgb',
+		renderMode = 'always',
+		autoRender = true,
+		maxDelta = 0.1,
+		adapterOptions = undefined,
+		deviceDescriptor = undefined,
+		dpr = initialDpr,
+		showErrorOverlay = true,
+		errorRenderer = undefined,
+		onError = undefined,
+		errorHistoryLimit = 0,
+		onErrorHistory = undefined,
+		class: className = '',
+		style = '',
+		children
+	}: Props = $props();
+
+	let canvas: HTMLCanvasElement | undefined;
+	let errorReport = $state<MotionGPUErrorReport | null>(null);
+	let errorHistory = $state<MotionGPUErrorReport[]>([]);
+
+	let normalizedErrorHistoryLimit = $derived.by(() => {
+		if (!Number.isFinite(errorHistoryLimit) || errorHistoryLimit <= 0) {
+			return 0;
+		}
+		return Math.floor(errorHistoryLimit);
+	});
+
+	const bindCanvas = (node: HTMLCanvasElement) => {
+		canvas = node;
+		return () => {
+			if (canvas === node) {
+				canvas = undefined;
+			}
+		};
+	};
+
+	const registry = createFrameRegistry({ maxDelta: 0.1 });
+	provideFrameRegistry(registry);
+	let requestFrameSignal: (() => void) | null = null;
+	const requestFrame = (): void => {
+		requestFrameSignal?.();
+	};
+	const invalidateFrame = (token?: FrameInvalidationToken): void => {
+		registry.invalidate(token);
+		requestFrame();
+	};
+	const advanceFrame = (): void => {
+		registry.advance();
+		requestFrame();
+	};
+	const size = currentWritable({ width: 0, height: 0 });
+	const dprState = currentWritable(initialDpr, requestFrame);
+	const maxDeltaState = currentWritable<number>(0.1, (value) => {
+		registry.setMaxDelta(value);
+		requestFrame();
+	});
+	const renderModeState = currentWritable<RenderMode>('always', (value) => {
+		registry.setRenderMode(value);
+		requestFrame();
+	});
+	const autoRenderState = currentWritable<boolean>(true, (value) => {
+		registry.setAutoRender(value);
+		requestFrame();
+	});
+	const userState = currentWritable<Record<string | symbol, unknown>>({});
+
+	provideMotionGPUContext({
+		get canvas() {
+			return canvas;
+		},
+		size,
+		dpr: dprState,
+		maxDelta: maxDeltaState,
+		renderMode: renderModeState,
+		autoRender: autoRenderState,
+		user: userState,
+		invalidate: () => invalidateFrame(),
+		advance: advanceFrame,
+		scheduler: {
+			createStage: registry.createStage,
+			getStage: registry.getStage,
+			setDiagnosticsEnabled: registry.setDiagnosticsEnabled,
+			getDiagnosticsEnabled: registry.getDiagnosticsEnabled,
+			getLastRunTimings: registry.getLastRunTimings,
+			getSchedule: registry.getSchedule,
+			setProfilingEnabled: registry.setProfilingEnabled,
+			setProfilingWindow: registry.setProfilingWindow,
+			resetProfiling: registry.resetProfiling,
+			getProfilingEnabled: registry.getProfilingEnabled,
+			getProfilingWindow: registry.getProfilingWindow,
+			getProfilingSnapshot: registry.getProfilingSnapshot
+		}
+	});
+
+	$effect(() => {
+		renderModeState.set(renderMode);
+		autoRenderState.set(autoRender);
+		maxDeltaState.set(maxDelta);
+		dprState.set(dpr);
+		requestFrame();
+	});
+
+	$effect(() => {
+		const limit = normalizedErrorHistoryLimit;
+		if (limit <= 0) {
+			if (errorHistory.length === 0) {
+				return;
+			}
+			errorHistory = [];
+			onErrorHistory?.([]);
+			return;
+		}
+
+		if (errorHistory.length <= limit) {
+			return;
+		}
+
+		const trimmed = errorHistory.slice(errorHistory.length - limit);
+		errorHistory = trimmed;
+		onErrorHistory?.(trimmed);
+	});
+
+	onMount(() => {
+		if (!canvas) {
+			const report = toMotionGPUErrorReport(
+				new Error('Canvas element is not available'),
+				'initialization'
+			);
+			errorReport = report;
+			const historyLimit = normalizedErrorHistoryLimit;
+			if (historyLimit > 0) {
+				const nextHistory = [report].slice(-historyLimit);
+				errorHistory = nextHistory;
+				onErrorHistory?.(nextHistory);
+			}
+			onError?.(report);
+			return () => registry.clear();
+		}
+
+		const runtimeLoop = createMotionGPURuntimeLoop({
+			canvas,
+			registry,
+			size,
+			dpr: dprState,
+			maxDelta: maxDeltaState,
+			getMaterial: () => material,
+			getRenderTargets: () => renderTargets,
+			getPasses: () => passes,
+			getClearColor: () => clearColor,
+			getOutputColorSpace: () => outputColorSpace,
+			getAdapterOptions: () => adapterOptions,
+			getDeviceDescriptor: () => deviceDescriptor,
+			getOnError: () => onError,
+			getErrorHistoryLimit: () => errorHistoryLimit,
+			getOnErrorHistory: () => onErrorHistory,
+			reportErrorHistory: (history) => {
+				errorHistory = history;
+			},
+			reportError: (report) => {
+				errorReport = report;
+			}
+		});
+		requestFrameSignal = runtimeLoop.requestFrame;
+
+		return () => {
+			requestFrameSignal = null;
+			runtimeLoop.destroy();
+		};
+	});
+</script>
+
+<div class="motiongpu-canvas-wrap">
+	<canvas {@attach bindCanvas} class={className} {style}></canvas>
+	{#if showErrorOverlay && errorReport}
+		{#if errorRenderer}
+			{@render errorRenderer(errorReport)}
+		{:else}
+			<MotionGPUErrorOverlay report={errorReport} />
+		{/if}
+	{/if}
+	{@render children?.()}
+</div>
+
+<style>
+	.motiongpu-canvas-wrap {
+		position: relative;
+		width: 100%;
+		height: 100%;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+	}
+
+	canvas {
+		position: absolute;
+		inset: 0;
+		display: block;
+		width: 100%;
+		height: 100%;
+	}
+</style>