@peter.prib/renderengine 0.15.2 → 0.16.0

package/src/compute/selectBackend.js

@@ -0,0 +1,85 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+import { CpuBackend } from './CpuBackend.js';
+import { WebGpuBackend } from './WebGpuBackend.js';
+
+/**
+ * Registry of available compute backends.
+ */
+export const BACKENDS = {
+    cpu: CpuBackend,
+    webgpu: WebGpuBackend,
+};
+
+const _navigatorGpu = () => (typeof navigator !== 'undefined' ? navigator.gpu : null);
+
+async function _available(name, Backend, { gpu } = {}) {
+    if (name === 'webgpu') return Backend.isAvailable(gpu ?? _navigatorGpu());
+    return Backend.isAvailable();
+}
+
+function _construct(name, { gpu } = {}) {
+    if (name === 'webgpu') return new WebGpuBackend({ gpu: gpu ?? _navigatorGpu() });
+    return new CpuBackend();
+}
+
+/**
+ * Returns list of backend names available in the current runtime without initializing them.
+ * @param {object} [options]
+ * @param {object} [options.gpu]
+ * @returns {Promise<string[]>}
+ */
+export async function availableBackends({ gpu } = {}) {
+    const out = [];
+    for (const [name, Backend] of Object.entries(BACKENDS)) {
+        if (await _available(name, Backend, { gpu })) out.push(name);
+    }
+    return out;
+}
+
+/**
+ * Select and optionally initialize the fastest available compute backend.
+ * Falls back gracefully to CpuBackend if WebGPU is unavailable or fails to initialize.
+ *
+ * @param {object} [options]
+ * @param {string[]} [options.prefer=['webgpu', 'cpu']]
+ * @param {object} [options.gpu]
+ * @param {boolean} [options.init=true]
+ * @returns {Promise<{backend: import('./ComputeBackend.js').ComputeBackend, attempts: Array<{backend: string, ok: boolean, reason?: string}>}>}
+ */
+export async function selectBackend({
+    prefer = ['webgpu', 'cpu'],
+    gpu,
+    init = true,
+} = {}) {
+    const attempts = [];
+
+    for (const name of prefer) {
+        const Backend = BACKENDS[name];
+        if (!Backend) {
+            attempts.push({ backend: name, ok: false, reason: `unknown backend '${name}'` });
+            continue;
+        }
+        try {
+            const available = await _available(name, Backend, { gpu });
+            if (!available) {
+                attempts.push({ backend: name, ok: false, reason: 'not available here' });
+                continue;
+            }
+            const backend = _construct(name, { gpu });
+            if (init) await backend.init();
+            return { backend, attempts: [...attempts, { backend: name, ok: true }] };
+        } catch (err) {
+            attempts.push({ backend: name, ok: false, reason: err.message });
+        }
+    }
+
+    // Default fallback to CPU
+    if (!prefer.includes('cpu')) {
+        const cpu = new CpuBackend();
+        return { backend: cpu, attempts: [...attempts, { backend: 'cpu', ok: true, reason: 'fallback' }] };
+    }
+
+    throw new Error(
+        `No compute backend could be started. Tried: ${attempts.map(a => `${a.backend} (${a.reason})`).join(', ')}`
+    );
+}