Skip to content

Code-first video & image, rendered natively on WebGPU.

6.0 KB
Raw Blame
/**
 * Headless (Node) WebGPU session provider.
 *
 * Runs `onnxruntime-web`'s WebGPU execution provider against the WebGPU device
 * the process already has — the Dawn device the renderer creates, or one this
 * ensures. `AutoSessionProvider` uses it when no provider is passed, falling
 * back to the CPU `NodeSessionProvider` if a WebGPU session can't be created.
 *
 * `onnxruntime-web` and `webgpu` are imported lazily behind non-analyzable
 * specifiers, so the browser entry never pulls this module's runtime imports.
 */

import type {
	SessionProvider,
	VisionSession,
	VisionSessionOptions,
} from "./session-provider.js";
import {
	type OrtWebModule,
	WebGPUProvider,
	type WebGPUProviderOptions,
} from "./webgpu-provider.js";

const ORT_WEBGPU_SPECIFIER = "onnxruntime-web/webgpu";
const WEBGPU_SPECIFIER = "webgpu";

let nodeWebGPUReady: Promise<void> | undefined;

interface NodeGPUAdapter {
	readonly features: object;
	readonly info?: {
		readonly vendor?: string;
		readonly architecture?: string;
		readonly device?: string;
		readonly description?: string;
		readonly isFallbackAdapter?: boolean;
	};
	readonly isFallbackAdapter?: boolean;
}

interface NodeGPU {
	requestAdapter(options?: {
		powerPreference?: "low-power" | "high-performance";
	}): Promise<NodeGPUAdapter | null>;
}

/** CPU rasterizers (lavapipe, llvmpipe, SwiftShader): slower than the CPU EP. */
const SOFTWARE_ADAPTER = /llvmpipe|lavapipe|swiftshader|software/i;

/**
 * Ensure `globalThis.navigator.gpu` exists and has a hardware adapter that
 * onnxruntime-web's WebGPU EP can use. In the renderer this is already the Dawn
 * device; otherwise imports the `webgpu` (Dawn) package and installs its
 * globals. Rejects when the only adapter is a software rasterizer.
 */
export function ensureNodeWebGPU(): Promise<void> {
	if (!nodeWebGPUReady) {
		nodeWebGPUReady = (async () => {
			const g = globalThis as { navigator?: { gpu?: NodeGPU } };
			if (!g.navigator?.gpu) {
				const { create, globals } = (await import(
					/* @vite-ignore */ WEBGPU_SPECIFIER
				)) as {
					create: (flags: string[]) => NodeGPU;
					globals: Record<string, unknown>;
				};
				Object.assign(globalThis, globals);
				g.navigator ??= {};
				Object.defineProperty(g.navigator, "gpu", {
					value: create([]),
					configurable: true,
					writable: true,
				});
			}
			const gpu = g.navigator?.gpu as NodeGPU;
			const adapter = await gpu.requestAdapter({
				powerPreference: "high-performance",
			});
			if (!adapter) throw new Error("No WebGPU adapter.");
			const info = adapter.info ?? {};
			const name = [
				info.vendor,
				info.architecture,
				info.device,
				info.description,
			]
				.filter(Boolean)
				.join(" ");
			if (
				adapter.isFallbackAdapter === true ||
				info.isFallbackAdapter === true ||
				SOFTWARE_ADAPTER.test(name)
			) {
				throw new Error(`WebGPU adapter is a software rasterizer (${name}).`);
			}
			patchSupportedFeatures(adapter.features);
		})();
		nodeWebGPUReady.catch(() => {
			nodeWebGPUReady = undefined;
		});
	}
	return nodeWebGPUReady;
}

/**
 * Dawn's Node `GPUSupportedFeatures` has `has`/`keys`/`size` but no `forEach`,
 * which onnxruntime-web's WebGPU build calls on adapter and device features
 * (they share the class). Adds the missing set-like methods once.
 */
function patchSupportedFeatures(features: object): void {
	const proto = Object.getPrototypeOf(features) as {
		keys?: () => IterableIterator<string>;
		forEach?: unknown;
		values?: unknown;
		entries?: unknown;
		[Symbol.iterator]?: unknown;
	} | null;
	if (!proto || typeof proto.keys !== "function") return;
	type SetLike = { keys(): IterableIterator<string> };
	if (typeof proto.forEach !== "function") {
		Object.defineProperty(proto, "forEach", {
			value(
				this: SetLike,
				callback: (value: string, key: string, set: SetLike) => void,
				thisArg?: unknown,
			) {
				for (const key of this.keys()) callback.call(thisArg, key, key, this);
			},
			configurable: true,
			writable: true,
		});
	}
	if (typeof proto.values !== "function") {
		Object.defineProperty(proto, "values", {
			value(this: SetLike) {
				return this.keys();
			},
			configurable: true,
			writable: true,
		});
	}
	if (typeof proto.entries !== "function") {
		Object.defineProperty(proto, "entries", {
			*value(this: SetLike) {
				for (const key of this.keys()) yield [key, key];
			},
			configurable: true,
			writable: true,
		});
	}
}

/** Options mirror the browser provider; the loader is overridden for Node. */
export type NodeWebGPUProviderOptions = WebGPUProviderOptions;

export class NodeWebGPUProvider implements SessionProvider {
	public readonly kind = "webgpu" as const;
	public readonly device?: GPUDevice;

	private readonly _inner: WebGPUProvider;

	constructor(options: NodeWebGPUProviderOptions = {}) {
		const loader =
			options.loader ??
			(async (): Promise<OrtWebModule> => {
				await ensureNodeWebGPU();
				const mod = (await import(
					/* @vite-ignore */ ORT_WEBGPU_SPECIFIER
				)) as OrtWebModule & {
					env?: {
						wasm?: { numThreads?: number };
						webgpu?: { powerPreference?: string };
					};
				};
				// Single-threaded WASM: Node has no cross-origin isolation, and the
				// WASM path is only a fallback behind the WebGPU EP.
				if (mod.env?.wasm) mod.env.wasm.numThreads = 1;
				if (mod.env?.webgpu)
					mod.env.webgpu.powerPreference = "high-performance";
				return mod;
			});
		// No WASM fallback inside the WebGPU provider: when WebGPU isn't possible
		// the caller (AutoSessionProvider) falls back to the node CPU provider,
		// which is faster than wasm and already installed.
		this.device = options.device;
		this._inner = new WebGPUProvider({
			wasmFallback: false,
			...options,
			loader,
		});
	}

	public createSession(
		modelBytes: Uint8Array,
		options?: VisionSessionOptions,
	): Promise<VisionSession> {
		return this._inner.createSession(modelBytes, options);
	}
}

export function createNodeWebGPUProvider(
	options?: NodeWebGPUProviderOptions,
): NodeWebGPUProvider {
	return new NodeWebGPUProvider(options);
}