Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(renderer): add an opt-in WebGPU path with automatic WebGL2 fallback and move the Restyle rim light to TSL

nirholasf0634f5a5b7a
diff --git a/pages/restyle.html b/pages/restyle.html
index a60e2e38e..b714c725b 100644
--- a/pages/restyle.html
+++ b/pages/restyle.html
@@ -138,6 +138,7 @@
<button class="rs-btn" id="retry" data-i18n="restyle.load_the_sample_model">Load the sample model</button>
</div>
<div class="rs-stage-hint">Drag to orbit · scroll to zoom · drop a .glb to load</div>
+ <div class="rs-stage-hint" style="left: auto; right: 12px" title="Renderer in use. Add ?renderer=webgpu to the URL to opt in to WebGPU."><span class="sr-only">Renderer: </span><span id="renderer-badge">WebGL2</span></div>
</div>
<!-- Controls -->
@@ -199,9 +200,11 @@
<div class="rs-slider"><label for="metalness" data-i18n="restyle.metalness">Metalness</label><input id="metalness" type="range" min="0" max="1" step="0.01" /></div>
<div class="rs-slider"><label for="roughness" data-i18n="restyle.roughness">Roughness</label><input id="roughness" type="range" min="0" max="1" step="0.01" /></div>
<div class="rs-slider"><label for="emissive" data-i18n="restyle.emissive">Emissive</label><input id="emissive" type="range" min="0" max="4" step="0.05" /></div>
+ <div class="rs-slider"><label for="rim" title="View-only Fresnel edge light. Not written to the exported GLB.">Rim light</label><input id="rim" type="range" min="0" max="3" step="0.05" value="0" /></div>
<div class="rs-colors">
<label class="rs-color">Base <input id="basecolor" type="color" value="#888888" /></label>
<label class="rs-color">Glow <input id="emissivecolor" type="color" value="#000000" /></label>
+ <label class="rs-color">Rim <input id="rimcolor" type="color" value="#6ea8ff" /></label>
</div>
</div>
diff --git a/scripts/renderer-bench.mjs b/scripts/renderer-bench.mjs
new file mode 100644
index 000000000..e78ea1d19
--- /dev/null
+++ b/scripts/renderer-bench.mjs
@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// Renderer parity + perf harness for the opt-in WebGPU path (src/renderer-factory.js).
+//
+// Loads the Restyle Studio (`/restyle?bench`) with the same model under three
+// conditions and reports, for each: the backend that actually rendered, console
+// errors, an offscreen frame of the live scene, and render cost per frame.
+//
+// default no opt-in -> classic WebGL2
+// webgpu ?renderer=webgpu, GPU present -> WebGPURenderer
+// webgpu-denied ?renderer=webgpu, navigator.gpu removed -> must fall back to WebGL2
+//
+// Parity and timing are measured offscreen (render target + readback) because
+// headless software WebGPU cannot present to a canvas. Numbers from a software
+// adapter compare the two code paths, not GPU hardware; run the same command on
+// a machine with a real GPU for hardware numbers.
+//
+// Usage: node scripts/renderer-bench.mjs [--base http://localhost:3000] [--frames 60]
+// [--json out.json] [--shots dir] [--headed]
+// Needs a dev/preview server running and Playwright's chromium installed.
+
+import { chromium } from 'playwright';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { PNG } from 'pngjs';
+
+const args = process.argv.slice(2);
+const opt = (name, dflt) => {
+ const i = args.indexOf(`--${name}`);
+ return i >= 0 ? args[i + 1] : dflt;
+};
+const base = opt('base', 'http://localhost:3000');
+const frames = Number(opt('frames', '60'));
+const jsonOut = opt('json', '');
+const shotsDir = opt('shots', '');
+const W = 384;
+const H = 512;
+
+const GPU_ARGS = [
+ '--enable-unsafe-webgpu',
+ '--enable-features=Vulkan,WebGPU',
+ '--use-angle=swiftshader',
+ '--use-webgpu-adapter=swiftshader',
+ '--ignore-gpu-blocklist',
+];
+
+const CASES = [
+ { name: 'default', query: '', denyGpu: false },
+ { name: 'webgpu', query: '&renderer=webgpu', denyGpu: false },
+ { name: 'webgpu-denied', query: '&renderer=webgpu', denyGpu: true },
+];
+
+async function run(browser, c) {
+ const ctx = await browser.newContext({ viewport: { width: 960, height: 640 }, deviceScaleFactor: 1 });
+ const page = await ctx.newPage();
+ if (c.denyGpu) {
+ await page.addInitScript(() => {
+ Object.defineProperty(navigator, 'gpu', { value: undefined });
+ });
+ }
+ const errors = [];
+ page.on('pageerror', (e) => errors.push(`pageerror: ${e.message}`));
+ page.on('console', (m) => {
+ if (m.type() === 'error') errors.push(`console.error: ${m.text()}`);
+ });
+ await page.goto(`${base}/restyle?bench${c.query}`, { waitUntil: 'domcontentloaded' });
+ await page.waitForFunction(() => window.__restyleBench, null, { timeout: 90000 });
+ await page.waitForFunction(
+ () => document.getElementById('status').hidden && document.getElementById('error').hidden,
+ null,
+ { timeout: 90000 },
+ );
+ await page.waitForTimeout(1500);
+ const backend = await page.$eval('#canvas-wrap canvas', (cv) => cv.dataset.renderer);
+ const badge = await page.$eval('#renderer-badge', (n) => n.textContent);
+ const pixels = await page.evaluate(([w, h]) => window.__restyleBench.capture(w, h), [W, H]);
+ await page.evaluate(() => window.__restyleBench.setRim(1.5));
+ const rimPixels = await page.evaluate(([w, h]) => window.__restyleBench.capture(w, h), [W, H]);
+ await page.evaluate(() => window.__restyleBench.setRim(0));
+ const renderMs = await page.evaluate(([w, h, n]) => window.__restyleBench.renderMs(w, h, n), [W, H, frames]);
+ await ctx.close();
+ return { case: c.name, backend, badge, errors, renderMs, pixels: Uint8Array.from(pixels), rimPixels: Uint8Array.from(rimPixels) };
+}
+
+function toPng(px) {
+ const png = new PNG({ width: W, height: H });
+ png.data = Buffer.from(px);
+ return PNG.sync.write(png);
+}
+
+function compare(a, b) {
+ let sum = 0;
+ let covered = 0;
+ let both = 0;
+ for (let i = 0; i < a.length; i += 4) {
+ const ca = a[i + 3] > 0;
+ const cb = b[i + 3] > 0;
+ if (ca) covered++;
+ if (ca && cb) both++;
+ sum += (Math.abs(a[i] - b[i]) + Math.abs(a[i + 1] - b[i + 1]) + Math.abs(a[i + 2] - b[i + 2])) / 3;
+ }
+ return { meanAbsDiff: sum / (a.length / 4), silhouetteOverlap: covered ? both / covered : 0 };
+}
+
+const browser = await chromium.launch({ args: GPU_ARGS, headless: !args.includes('--headed') });
+const results = [];
+for (const c of CASES) results.push(await run(browser, c));
+await browser.close();
+
+const ref = results[0];
+const rows = results.map((r) => {
+ const cmp = r === ref ? null : compare(ref.pixels, r.pixels);
+ return {
+ case: r.case,
+ backend: r.backend,
+ badge: r.badge,
+ renderMsPerFrame: Number(r.renderMs.toFixed(2)),
+ errors: r.errors,
+ rimVsDefault: r === ref ? null : Number(compare(ref.rimPixels, r.rimPixels).meanAbsDiff.toFixed(2)),
+ rimEffectOnDefault: Number(compare(r.pixels, r.rimPixels).meanAbsDiff.toFixed(2)),
+ vsDefault: cmp && {
+ meanAbsDiff0to255: Number(cmp.meanAbsDiff.toFixed(2)),
+ silhouetteOverlap: Number(cmp.silhouetteOverlap.toFixed(4)),
+ },
+ };
+});
+for (const r of rows) {
+ console.log(
+ `${r.case.padEnd(14)} backend=${r.backend} badge=${r.badge} render=${r.renderMsPerFrame}ms/frame` +
+ (r.vsDefault ? ` diff=${r.vsDefault.meanAbsDiff0to255}/255 silhouette=${r.vsDefault.silhouetteOverlap}` : '') +
+ ` rimEffect=${r.rimEffectOnDefault}/255 rimDiffVsDefault=${r.rimVsDefault ?? 0}/255 errors=${r.errors.length}`,
+ );
+ for (const e of r.errors) console.log(` ${e}`);
+}
+if (shotsDir) {
+ mkdirSync(shotsDir, { recursive: true });
+ for (const r of results) {
+ writeFileSync(`${shotsDir}/${r.case}.png`, toPng(r.pixels));
+ writeFileSync(`${shotsDir}/${r.case}-rim.png`, toPng(r.rimPixels));
+ }
+}
+if (jsonOut) writeFileSync(jsonOut, JSON.stringify({ frames, size: [W, H], rows }, null, 2));
+
+const failed =
+ results.some((r) => r.errors.length > 0) ||
+ results[0].backend !== 'webgl' ||
+ results[2].backend !== 'webgl';
+process.exit(failed ? 1 : 0);
diff --git a/src/renderer-factory.js b/src/renderer-factory.js
new file mode 100644
index 000000000..a839547ee
--- /dev/null
+++ b/src/renderer-factory.js
@@ -0,0 +1,93 @@
+// Renderer factory: WebGPU when the browser supports it AND the page opted in,
+// the classic WebGL2 renderer otherwise.
+//
+// WebGPU is strictly opt-in. A surface asks for it with `?renderer=webgpu` in
+// the page URL or a `renderer="webgpu"` attribute on <agent-3d>. Anything else
+// (no opt-in, no `navigator.gpu`, no adapter, the WebGPU renderer failing to
+// initialise) resolves to the existing guarded WebGL path in webgl-support.js,
+// so a default visit is byte-for-byte what shipped before and a failed opt-in
+// degrades silently to the same picture instead of a blank canvas.
+//
+// The backend that was actually chosen is returned (and stamped on the canvas as
+// `data-renderer`) so callers branch on what they got, never on what was asked.
+
+import { createRenderer as createWebGLRenderer } from './webgl-support.js';
+
+export const BACKEND_WEBGPU = 'webgpu';
+export const BACKEND_WEBGL = 'webgl';
+
+/**
+ * Pure opt-in parser. The attribute wins over the query string so an embedder
+ * can pin a backend regardless of the host page URL. Only the exact value
+ * "webgpu" opts in; "webgl" (or anything else) forces the classic path.
+ *
+ * @param {{ search?: string, attr?: string | null }} [src]
+ * @returns {'webgpu' | 'webgl'}
+ */
+export function resolveRendererPreference({ search = '', attr = null } = {}) {
+ const pick = (v) => (typeof v === 'string' ? v.trim().toLowerCase() : '');
+ const fromAttr = pick(attr);
+ if (fromAttr) return fromAttr === 'webgpu' ? BACKEND_WEBGPU : BACKEND_WEBGL;
+ const fromQuery = pick(new URLSearchParams(search).get('renderer'));
+ return fromQuery === 'webgpu' ? BACKEND_WEBGPU : BACKEND_WEBGL;
+}
+
+/** The preference of the current page, optionally overridden by an element attribute. */
+export function pagePreference(el) {
+ const search = typeof location !== 'undefined' ? location.search : '';
+ return resolveRendererPreference({ search, attr: el?.getAttribute?.('renderer') ?? null });
+}
+
+/**
+ * True when a WebGPU adapter can actually be acquired. `navigator.gpu` alone is
+ * not enough: Chromium on a blocklisted GPU exposes the object but resolves
+ * `requestAdapter()` to null.
+ */
+export async function isWebGPUAvailable() {
+ try {
+ if (typeof navigator === 'undefined' || !navigator.gpu) return false;
+ const adapter = await navigator.gpu.requestAdapter();
+ return !!adapter;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Build a renderer for `prefer`, falling back to WebGL2 whenever WebGPU is not
+ * both requested and working.
+ *
+ * @param {object} [options] Passed to the renderer constructor (antialias, alpha, ...).
+ * @param {{ prefer?: 'webgpu' | 'webgl', fallback?: Element }} [guard]
+ * @returns {Promise<{ renderer: any, backend: 'webgpu' | 'webgl', reason: string }>}
+ * @throws {import('./webgl-support.js').WebGLUnavailableError} when neither backend starts.
+ */
+export async function createAutoRenderer(options = {}, { prefer = BACKEND_WEBGL, fallback } = {}) {
+ let reason = 'webgl default';
+ if (prefer === BACKEND_WEBGPU) {
+ if (!(await isWebGPUAvailable())) {
+ reason = 'webgpu requested but no adapter, using webgl';
+ } else {
+ try {
+ const { WebGPURenderer } = await import('three/webgpu');
+ // forceWebGL stays false: a WebGPU opt-in that cannot get a GPU device
+ // must land on the CLASSIC renderer below, not on the node renderer's
+ // own GL2 backend, so the fallback is exactly the shipped picture.
+ const renderer = new WebGPURenderer({ ...options, forceWebGL: false });
+ await renderer.init();
+ const usedBackend = renderer.backend?.isWebGPUBackend ? BACKEND_WEBGPU : null;
+ if (usedBackend) {
+ renderer.domElement.dataset.renderer = BACKEND_WEBGPU;
+ return { renderer, backend: BACKEND_WEBGPU, reason: 'webgpu' };
+ }
+ renderer.dispose?.();
+ reason = 'webgpu renderer fell back internally, using webgl';
+ } catch (err) {
+ reason = `webgpu init failed (${err?.message || err}), using webgl`;
+ }
+ }
+ }
+ const renderer = createWebGLRenderer(options, { fallback });
+ renderer.domElement.dataset.renderer = BACKEND_WEBGL;
+ return { renderer, backend: BACKEND_WEBGL, reason };
+}
diff --git a/src/restyle-effects.js b/src/restyle-effects.js
new file mode 100644
index 000000000..e030a0a04
--- /dev/null
+++ b/src/restyle-effects.js
@@ -0,0 +1,159 @@
+// Restyle view effects that run on whichever backend the renderer factory chose.
+//
+// The Restyle Studio edits plain glTF PBR materials. A view effect is something
+// the live preview adds on top of those materials without changing the exported
+// asset, so it must never leak into the GLB. Two implementations of the same
+// look share one parameter set:
+//
+// webgl MeshStandardMaterial + an `onBeforeCompile` patch that adds a
+// Fresnel rim term to `totalEmissiveRadiance`.
+// webgpu MeshStandardNodeMaterial / MeshPhysicalNodeMaterial with an
+// `emissiveNode` built from TSL (`three/tsl`), the same term.
+//
+// Because node materials are not glTF-exportable, the WebGPU path swaps the
+// loaded materials for node materials on mount and `withClassicMaterials`
+// swaps the original classic materials back for the duration of an export, so
+// the exported GLB is identical regardless of backend.
+
+import { Color } from 'three';
+
+export const RIM_POWER = 3;
+
+const classicOf = new WeakMap(); // node material -> the glTF material it replaced
+
+function isGltfPbr(m) {
+ return !!m && 'metalness' in m && 'roughness' in m && !!m.color && typeof m.color.getHex === 'function';
+}
+
+function eachMaterialSlot(root, visit) {
+ root.traverse((node) => {
+ if (!node.material) return;
+ if (Array.isArray(node.material)) {
+ node.material = node.material.map((m) => visit(m, node));
+ } else {
+ node.material = visit(node.material, node);
+ }
+ });
+}
+
+/**
+ * Backend adapter for one Restyle session.
+ *
+ * @param {'webgpu' | 'webgl'} backend
+ * @returns {Promise<{
+ * backend: string,
+ * adopt: (root: import('three').Object3D) => void,
+ * setRim: (p: { strength?: number, color?: string }) => void,
+ * withClassicMaterials: <T>(root: import('three').Object3D, fn: () => Promise<T>) => Promise<T>,
+ * }>}
+ */
+export async function createRestyleEffects(backend) {
+ const rim = { color: new Color('#6ea8ff'), strength: 0 };
+ const webgpu = backend === 'webgpu';
+
+ let tsl = null;
+ let nodes = null;
+ let rimNodeUniforms = null;
+ if (webgpu) {
+ const [tslMod, webgpuMod] = await Promise.all([import('three/tsl'), import('three/webgpu')]);
+ tsl = tslMod;
+ nodes = webgpuMod;
+ rimNodeUniforms = { color: tsl.uniform(rim.color), strength: tsl.uniform(rim.strength) };
+ }
+ const glslUniforms = { uRimColor: { value: rim.color }, uRimStrength: { value: rim.strength } };
+
+ const patched = new WeakSet();
+
+ function patchClassic(m) {
+ if (!isGltfPbr(m) || patched.has(m)) return m;
+ m.onBeforeCompile = (shader) => {
+ shader.uniforms.uRimColor = glslUniforms.uRimColor;
+ shader.uniforms.uRimStrength = glslUniforms.uRimStrength;
+ shader.fragmentShader = shader.fragmentShader
+ .replace(
+ '#include <common>',
+ '#include <common>\nuniform vec3 uRimColor;\nuniform float uRimStrength;',
+ )
+ .replace(
+ '#include <emissivemap_fragment>',
+ `#include <emissivemap_fragment>
+totalEmissiveRadiance += uRimColor * uRimStrength * pow(1.0 - clamp(dot(normalize(normal), normalize(vViewPosition)), 0.0, 1.0), ${RIM_POWER.toFixed(1)});`,
+ );
+ };
+ m.customProgramCacheKey = () => 'restyle-rim';
+ // A WeakSet, not userData: userData is serialised into the GLB.
+ patched.add(m);
+ m.needsUpdate = true;
+ return m;
+ }
+
+ function toNodeMaterial(m) {
+ if (!isGltfPbr(m) || m.isNodeMaterial) return m;
+ const Cls = m.isMeshPhysicalMaterial ? nodes.MeshPhysicalNodeMaterial : nodes.MeshStandardNodeMaterial;
+ const node = new Cls();
+ for (const key in m) node[key] = m[key];
+ const { materialEmissive, normalView, positionViewDirection, dot, saturate, oneMinus, pow, float } = tsl;
+ const fresnel = pow(oneMinus(saturate(dot(normalView, positionViewDirection))), float(RIM_POWER));
+ node.emissiveNode = materialEmissive.add(rimNodeUniforms.color.mul(rimNodeUniforms.strength).mul(fresnel));
+ classicOf.set(node, m);
+ node.needsUpdate = true;
+ return node;
+ }
+
+ function adopt(root) {
+ const done = new Map();
+ eachMaterialSlot(root, (m) => {
+ if (done.has(m)) return done.get(m);
+ const next = webgpu ? toNodeMaterial(m) : patchClassic(m);
+ done.set(m, next);
+ return next;
+ });
+ }
+
+ function setRim({ strength, color } = {}) {
+ if (typeof strength === 'number' && Number.isFinite(strength)) {
+ rim.strength = Math.max(0, strength);
+ glslUniforms.uRimStrength.value = rim.strength;
+ if (rimNodeUniforms) rimNodeUniforms.strength.value = rim.strength;
+ }
+ if (color) {
+ rim.color.set(color);
+ // The uniforms hold the same Color instance, so both paths follow it.
+ }
+ }
+
+ async function withClassicMaterials(root, fn) {
+ if (!webgpu) return fn();
+ const restore = new Map(); // classic -> node material
+ eachMaterialSlot(root, (m) => {
+ const classic = classicOf.get(m);
+ if (!classic) return m;
+ // Sync every live edit made on the node material back onto the classic
+ // one it replaced, so the export carries the user's changes.
+ for (const key of SYNCED_KEYS) if (key in m) copyProp(classic, key, m[key]);
+ restore.set(classic, m);
+ return classic;
+ });
+ try {
+ return await fn();
+ } finally {
+ eachMaterialSlot(root, (m) => restore.get(m) ?? m);
+ }
+ }
+
+ return { backend, adopt, setRim, withClassicMaterials };
+}
+
+const SYNCED_KEYS = [
+ 'color', 'metalness', 'roughness', 'emissive', 'emissiveIntensity', 'opacity', 'transparent',
+ 'map', 'normalMap', 'roughnessMap', 'metalnessMap', 'emissiveMap', 'aoMap', 'alphaMap',
+ 'envMapIntensity', 'side', 'alphaTest',
+ 'clearcoat', 'clearcoatRoughness', 'transmission', 'thickness', 'ior', 'sheen', 'sheenRoughness',
+ 'sheenColor', 'iridescence', 'iridescenceIOR', 'specularIntensity', 'specularColor',
+];
+
+function copyProp(target, key, value) {
+ const cur = target[key];
+ if (cur && cur.isColor && value && value.isColor) cur.copy(value);
+ else target[key] = value;
+}
diff --git a/src/restyle.js b/src/restyle.js
index 5c10d0123..f5b36de3c 100644
--- a/src/restyle.js
+++ b/src/restyle.js
@@ -32,6 +32,8 @@ import {
import { optimizeAndValidateGlb } from './avatar-studio-optimize.js';
import { seedLineage, appendVersion, summarizeLineage } from '../mcp-server/src/tools/_lineage.js';
import { verifyPreserved } from '../api/_lib/preserve-contract.js';
+import { createAutoRenderer, pagePreference } from './renderer-factory.js';
+import { createRestyleEffects } from './restyle-effects.js';
// A small, always-present local sample so the page is never an empty void — the
// platform's default humanoid, served from /avatars.
@@ -65,15 +67,18 @@ const state = {
selectedPartIndex: null,
dimmed: [], // [{ material, opacity, transparent }] restored on deselect
regenRunToken: 0,
+ benchHold: false, // ?bench hook: pause the on-screen loop while it renders offscreen
+ backend: 'webgl', // which renderer the factory actually produced
+ fx: null, // view effects for that backend (restyle-effects.js)
};
const el = {};
document.addEventListener('DOMContentLoaded', init);
-function init() {
+async function init() {
cache();
- buildScene();
+ await buildScene();
buildPresetButtons();
wireControls();
const url = new URL(location.href).searchParams.get('url');
@@ -84,7 +89,7 @@ function init() {
function cache() {
for (const id of [
'stage', 'canvas-wrap', 'presets', 'variants', 'variant-strip', 'history',
- 'metalness', 'roughness', 'emissive', 'basecolor', 'emissivecolor',
+ 'metalness', 'roughness', 'emissive', 'basecolor', 'emissivecolor', 'rim', 'rimcolor', 'renderer-badge',
'seed', 'variant-count', 'gen-variants', 'reset', 'export', 'export-note',
'file', 'upload', 'url-input', 'load-url', 'load-note', 'status', 'error', 'error-msg', 'retry',
'ai-instruction', 'ai-restyle', 'ai-texture', 'ai-note',
@@ -98,8 +103,17 @@ function cache() {
}
// ── scene ────────────────────────────────────────────────────────────────────
-function buildScene() {
- const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true, preserveDrawingBuffer: true });
+async function buildScene() {
+ const { renderer, backend, reason } = await createAutoRenderer(
+ { antialias: true, alpha: true, preserveDrawingBuffer: true },
+ { prefer: pagePreference(), fallback: el['canvas-wrap'] },
+ );
+ state.backend = backend;
+ state.fx = await createRestyleEffects(backend);
+ if (el['renderer-badge']) {
+ el['renderer-badge'].textContent = backend === 'webgpu' ? 'WebGPU' : 'WebGL2';
+ el['renderer-badge'].title = reason;
+ }
renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.05;
@@ -111,7 +125,8 @@ function buildScene() {
state.scene = scene;
// RoomEnvironment gives metals/glass something real to reflect — chrome and
// gold read as metal, not flat grey, without shipping an HDRI asset.
- const pmrem = new THREE.PMREMGenerator(renderer);
+ const Pmrem = backend === 'webgpu' ? (await import('three/webgpu')).PMREMGenerator : THREE.PMREMGenerator;
+ const pmrem = new Pmrem(renderer);
scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
const key = new THREE.DirectionalLight(0xffffff, 2.2);
@@ -132,15 +147,71 @@ function buildScene() {
controls.target.set(0, 1, 0);
state.controls = controls;
+ if (new URLSearchParams(location.search).has('bench')) exposeBenchHook(renderer, scene, camera, backend);
+
onResize();
const tick = () => {
state.raf = requestAnimationFrame(tick);
controls.update();
- renderer.render(scene, camera);
+ if (!state.benchHold) renderer.render(scene, camera);
};
tick();
}
+// scripts/renderer-bench.mjs hook (opt-in via ?bench). Headless software WebGPU
+// cannot present to a canvas, so parity is measured offscreen: render the live
+// scene into a render target and read the pixels back on either backend.
+function exposeBenchHook(renderer, scene, camera, backend) {
+ const gpu = backend === 'webgpu';
+ const makeTarget = async (w, h) => {
+ if (!gpu) return new THREE.WebGLRenderTarget(w, h);
+ return new (await import('three/webgpu')).RenderTarget(w, h);
+ };
+ const readback = async (rt, w, h) => {
+ if (gpu) {
+ const raw = await renderer.readRenderTargetPixelsAsync(rt, 0, 0, w, h);
+ const stride = Math.ceil((w * 4) / 256) * 256;
+ const out = new Uint8Array(w * h * 4);
+ for (let y = 0; y < h; y++) out.set(raw.subarray(y * stride, y * stride + w * 4), y * w * 4);
+ return out;
+ }
+ const raw = new Uint8Array(w * h * 4);
+ renderer.readRenderTargetPixels(rt, 0, 0, w, h, raw);
+ // GL reads bottom-up; flip to the top-down order WebGPU returns.
+ const out = new Uint8Array(w * h * 4);
+ for (let y = 0; y < h; y++) out.set(raw.subarray((h - 1 - y) * w * 4, (h - y) * w * 4), y * w * 4);
+ return out;
+ };
+ window.__restyleBench = {
+ backend,
+ setRim: (strength) => state.fx.setRim({ strength }),
+ async capture(w, h) {
+ state.benchHold = true;
+ const rt = await makeTarget(w, h);
+ renderer.setRenderTarget(rt);
+ renderer.render(scene, camera);
+ renderer.setRenderTarget(null);
+ const px = Array.from(await readback(rt, w, h));
+ state.benchHold = false;
+ return px;
+ },
+ async renderMs(w, h, frames) {
+ state.benchHold = true;
+ const rt = await makeTarget(w, h);
+ renderer.setRenderTarget(rt);
+ renderer.render(scene, camera); // warm-up: pipeline + shader compile
+ await readback(rt, w, h);
+ const t0 = performance.now();
+ for (let i = 0; i < frames; i++) renderer.render(scene, camera);
+ await readback(rt, w, h); // forces the GPU queue to drain
+ const ms = (performance.now() - t0) / frames;
+ renderer.setRenderTarget(null);
+ state.benchHold = false;
+ return ms;
+ },
+ };
+}
+
function onResize() {
const wrap = el['canvas-wrap'];
if (!wrap || !state.renderer) return;
@@ -196,6 +267,7 @@ function mountModel(newRoot, label, opts = {}) {
state.lineage = [];
state.manual = { metalness: null, roughness: null, emissiveIntensity: 0 };
state.sourceLabel = label || '';
+ state.fx.adopt(newRoot);
captureOriginals(newRoot);
frameModel(newRoot);
state.scene.add(newRoot);
@@ -257,14 +329,23 @@ function mountModel(newRoot, label, opts = {}) {
renderLineageStrip();
}
+// Serialise a root to GLB with the classic glTF materials in place, so a WebGPU
+// session exports the same asset a WebGL one does (see restyle-effects.js).
+function exportGlb(root) {
+ const exporter = new GLTFExporter();
+ return state.fx.withClassicMaterials(
+ root,
+ () => new Promise((res, rej) => {
+ exporter.parse(root, (result) => res(result), (err) => rej(err), { binary: true });
+ }),
+ );
+}
+
// Export the CURRENT root as-is (used only to mint an origin URL for a
// locally-uploaded File that has none — runs once, right after mount, before
// any edit, so the "origin" checkpoint really is the original file).
async function uploadOriginBytes(root) {
- const exporter = new GLTFExporter();
- const glb = await new Promise((res, rej) => {
- exporter.parse(root, (result) => res(result), (err) => rej(err), { binary: true });
- });
+ const glb = await exportGlb(root);
return uploadGlbBytes(glb);
}
@@ -886,10 +967,7 @@ async function aiRestyle() {
// button and any edit (e.g. a part regenerate) that needs to record a durable
// lineage entry on its own rather than wait for a manual save.
async function persistCurrentSceneAsVersion({ instruction, refKind, onStatus }) {
- const exporter = new GLTFExporter();
- const glb = await new Promise((res, rej) => {
- exporter.parse(state.root, (result) => res(result), (err) => rej(err), { binary: true });
- });
+ const glb = await exportGlb(state.root);
const rawBlob = new Blob([glb], { type: 'model/gltf-binary' });
const { blob } = await optimizeAndValidateGlb(rawBlob, { onStatus });
const url = await uploadGlbBytes(blob);
@@ -972,10 +1050,7 @@ async function exportModel() {
el.export.disabled = true;
setNote(el['export-note'], 'Exporting…');
try {
- const exporter = new GLTFExporter();
- const glb = await new Promise((res, rej) => {
- exporter.parse(state.root, (result) => res(result), (err) => rej(err), { binary: true });
- });
+ const glb = await exportGlb(state.root);
const rawBlob = new Blob([glb], { type: 'model/gltf-binary' });
const { blob, optimized, outputBytes, report } = await optimizeAndValidateGlb(rawBlob, {
onStatus: (s) => setNote(el['export-note'], s),
@@ -1015,6 +1090,8 @@ function wireControls() {
el.emissive.addEventListener('input', () => setManual('emissiveIntensity', +el.emissive.value));
el.basecolor.addEventListener('input', () => setManual('color', el.basecolor.value));
el.emissivecolor.addEventListener('input', () => setManual('emissive', el.emissivecolor.value));
+ el.rim.addEventListener('input', () => state.fx.setRim({ strength: +el.rim.value }));
+ el.rimcolor.addEventListener('input', () => state.fx.setRim({ color: el.rimcolor.value }));
el['gen-variants'].addEventListener('click', generateVariants);
el['save-variants'].addEventListener('click', persistVariants);
el.reset.addEventListener('click', resetModel);
diff --git a/tests/renderer-factory.test.js b/tests/renderer-factory.test.js
new file mode 100644
index 000000000..533061434
--- /dev/null
+++ b/tests/renderer-factory.test.js
@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { MeshStandardMaterial, Mesh, BoxGeometry, Group } from 'three';
+
+const createWebGL = vi.fn((options) => ({ kind: 'webgl', options, domElement: { dataset: {} } }));
+vi.mock('../src/webgl-support.js', () => ({ createRenderer: (...a) => createWebGL(...a) }));
+
+const { resolveRendererPreference, isWebGPUAvailable, createAutoRenderer } = await import('../src/renderer-factory.js');
+const { createRestyleEffects } = await import('../src/restyle-effects.js');
+
+describe('resolveRendererPreference', () => {
+ it('defaults to webgl with no opt-in', () => {
+ expect(resolveRendererPreference()).toBe('webgl');
+ expect(resolveRendererPreference({ search: '?url=x.glb' })).toBe('webgl');
+ });
+ it('opts in from the query string, case-insensitively', () => {
+ expect(resolveRendererPreference({ search: '?renderer=webgpu' })).toBe('webgpu');
+ expect(resolveRendererPreference({ search: '?a=1&renderer=WebGPU' })).toBe('webgpu');
+ });
+ it('treats any other value as webgl', () => {
+ expect(resolveRendererPreference({ search: '?renderer=vulkan' })).toBe('webgl');
+ expect(resolveRendererPreference({ search: '?renderer=' })).toBe('webgl');
+ });
+ it('lets the element attribute win over the query string both ways', () => {
+ expect(resolveRendererPreference({ search: '?renderer=webgl', attr: 'webgpu' })).toBe('webgpu');
+ expect(resolveRendererPreference({ search: '?renderer=webgpu', attr: 'webgl' })).toBe('webgl');
+ expect(resolveRendererPreference({ search: '?renderer=webgpu', attr: '' })).toBe('webgpu');
+ });
+});
+
+describe('createAutoRenderer fallback', () => {
+ beforeEach(() => createWebGL.mockClear());
+ afterEach(() => vi.unstubAllGlobals());
+
+ it('never touches WebGPU unless asked', async () => {
+ const gpu = { requestAdapter: vi.fn() };
+ vi.stubGlobal('navigator', { gpu });
+ const r = await createAutoRenderer({ antialias: true });
+ expect(r.backend).toBe('webgl');
+ expect(gpu.requestAdapter).not.toHaveBeenCalled();
+ expect(r.renderer.domElement.dataset.renderer).toBe('webgl');
+ expect(createWebGL).toHaveBeenCalledWith({ antialias: true }, { fallback: undefined });
+ });
+
+ it('falls back when navigator.gpu is missing', async () => {
+ vi.stubGlobal('navigator', {});
+ expect(await isWebGPUAvailable()).toBe(false);
+ const r = await createAutoRenderer({}, { prefer: 'webgpu' });
+ expect(r.backend).toBe('webgl');
+ expect(r.reason).toMatch(/no adapter/);
+ });
+
+ it('falls back when the adapter request resolves to null', async () => {
+ vi.stubGlobal('navigator', { gpu: { requestAdapter: async () => null } });
+ expect(await isWebGPUAvailable()).toBe(false);
+ expect((await createAutoRenderer({}, { prefer: 'webgpu' })).backend).toBe('webgl');
+ });
+
+ it('falls back when requestAdapter throws', async () => {
+ vi.stubGlobal('navigator', {
+ gpu: {
+ requestAdapter: async () => {
+ throw new Error('blocked');
+ },
+ },
+ });
+ expect(await isWebGPUAvailable()).toBe(false);
+ });
+});
+
+describe('restyle effects (webgl path)', () => {
+ it('patches glTF PBR materials with a rim term that stays out of the export', async () => {
+ const fx = await createRestyleEffects('webgl');
+ const mat = new MeshStandardMaterial();
+ const root = new Group();
+ root.add(new Mesh(new BoxGeometry(), mat));
+ fx.adopt(root);
+ expect(root.children[0].material).toBe(mat);
+ expect(mat.userData).toEqual({});
+
+ const shader = {
+ uniforms: {},
+ fragmentShader: '#include <common>\n#include <emissivemap_fragment>\n',
+ };
+ mat.onBeforeCompile(shader);
+ expect(shader.fragmentShader).toContain('uniform vec3 uRimColor;');
+ expect(shader.fragmentShader).toMatch(/totalEmissiveRadiance \+= uRimColor \* uRimStrength/);
+
+ fx.setRim({ strength: 2, color: '#ff0000' });
+ expect(shader.uniforms.uRimStrength.value).toBe(2);
+ expect(shader.uniforms.uRimColor.value.r).toBeGreaterThan(0.9);
+ });
+
+ it('runs the export callback untouched when no node materials are in play', async () => {
+ const fx = await createRestyleEffects('webgl');
+ const out = await fx.withClassicMaterials(new Group(), async () => 'glb');
+ expect(out).toBe('glb');
+ });
+
+ it('ignores non-finite strengths', async () => {
+ const fx = await createRestyleEffects('webgl');
+ const mat = new MeshStandardMaterial();
+ const root = new Group();
+ root.add(new Mesh(new BoxGeometry(), mat));
+ fx.adopt(root);
+ const shader = { uniforms: {}, fragmentShader: '#include <common>\n#include <emissivemap_fragment>' };
+ mat.onBeforeCompile(shader);
+ fx.setRim({ strength: 1 });
+ fx.setRim({ strength: Number.NaN });
+ expect(shader.uniforms.uRimStrength.value).toBe(1);
+ });
+});