diff --git a/.github/affected.js b/.github/affected.js
new file mode 100644
index 0000000..152b81f
--- /dev/null
+++ b/.github/affected.js
@@ -0,0 +1,204 @@
+// What a change has to be checked by, and nothing else.
+//
+// node .github/affected.js -> GITHUB_OUTPUT lines: node, types, gpu
+//
+// NODE SUITES: a suite runs when a changed file is in what it imports, or reads
+// through new URL(..., import.meta.url), followed all the way down. They take
+// seconds; the point is the GPU suite.
+//
+// THE GPU SUITE takes minutes on a runner with no GPU, and nearly every change
+// reaches only some of it. test/gpu-map.json says, for every function in src/
+// the suite runs, which checks run it -- '*' for the setup every check draws on
+// (GPU_MAP=1 node test/gpu.ci.js makes it, at a commit it records). A changed
+// line is carried from this change's code back to the map's commit through git
+// diff, and its innermost function names the checks. A line in no function --
+// a shader's source, a constant -- reaches every check of its file. The checks
+// chosen are split across up to RUNNERS runners, balanced by the time each took.
+//
+// WHEN IN DOUBT, EVERYTHING: a change to the suite, its fixtures or runner, to
+// CI or to this file, a new file in src/, a map from a commit git cannot find,
+// or a base it cannot diff against.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, appendFileSync } from 'node:fs';
+import { dirname, join, normalize, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const RUNNERS = 4;
+/**
+ * A runner's worth of checks, in CI's time (test/gpu-map.json's ciMs, from
+ * .github/ci-times.js; where a check has none, its time on the real GPU the map
+ * was made on, about seven times quicker). Each runner also starts Chrome and
+ * builds the setup every check needs, a minute or so, so a handful of quick
+ * checks share one rather than taking four.
+ */
+const PER_RUNNER_MS = 60000;
+
+/** Changes that are checked by everything there is. */
+const EVERYTHING = [/^package\.json$/, /^\.github\/workflows\//, /^\.github\/affected\.js$/, /^serve\.js$/];
+/** Changes that the GPU suite as a whole checks. */
+const WHOLE_GPU = [/^test\/gpu\.(test|ci)\.js$/, /^test\/gpu\.html$/, /^test\/fixtures\//];
+
+const git = (...args) => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 << 20 });
+
+/** Every file `file` reaches: its imports and new URL() references, followed down. Paths relative to the root. */
+export function reaches(file, read = (f) => readFileSync(join(ROOT, f), 'utf8'), seen = new Set()) {
+ if (seen.has(file)) return seen;
+ seen.add(file);
+ if (!/\.m?js$/.test(file)) return seen;
+ let text;
+ try { text = read(file); } catch { return seen; }
+ const refs = [
+ ...text.matchAll(/\bfrom\s*['"](\.{1,2}\/[^'"]+)['"]/g),
+ ...text.matchAll(/\bimport\s*\(?\s*['"](\.{1,2}\/[^'"]+)['"]/g),
+ ...text.matchAll(/new URL\(\s*['"](\.{1,2}\/[^'"]+)['"]\s*,\s*import\.meta\.url\s*\)/g),
+ ];
+ for (const [, ref] of refs) reaches(normalize(join(dirname(file), ref)).replaceAll('\\', '/'), read, seen);
+ return seen;
+}
+
+/** The lines of `path` a diff touches, in its new version: [first, last] pairs. A deletion touches the line either side. */
+export function touched(diff) {
+ const out = [];
+ for (const [, , , start, count = '1'] of diff.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+ const s = Number(start), n = Number(count);
+ out.push(n === 0 ? [s, s + 1] : [s, s + n - 1]);
+ }
+ return out;
+}
+
+/**
+ * Carry a range of lines in a file's new version back to its old one, through
+ * the hunks of the diff between them. A line inside a changed hunk is the whole
+ * of that hunk's old lines; one outside moves by what the hunks before it added.
+ */
+export function carry([first, last], diff) {
+ // A count of 0 places the start BEFORE the lines: an insertion sits after old
+ // line os, a deletion after new line ns. The last line each side is then os
+ // or ns itself, and the line after a hunk moves by the difference of the two.
+ const hunks = [...diff.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)].map(([, os, oc = '1', ns, nc = '1']) => {
+ const o = { start: +os, count: +oc }, n = { start: +ns, count: +nc };
+ return {
+ o, n,
+ oldFirst: o.count === 0 ? o.start : o.start, oldLast: o.count === 0 ? o.start + 1 : o.start + o.count - 1,
+ newLast: n.count === 0 ? n.start : n.start + n.count - 1,
+ };
+ });
+ const one = (line, end) => {
+ let shift = 0;
+ for (const h of hunks) {
+ if (h.n.count > 0 && line >= h.n.start && line <= h.newLast) return end ? h.oldLast : h.oldFirst;
+ if (line <= h.newLast) break;
+ shift = (h.o.count === 0 ? h.o.start : h.o.start + h.o.count - 1) - h.newLast;
+ }
+ return line + shift;
+ };
+ return [one(first, false), one(last, true)];
+}
+
+/**
+ * The checks a touched range of `path` (map lines) reaches, by the map's
+ * functions: '*' when it reaches the setup, so every check.
+ */
+export function checksFor(functions, [first, last]) {
+ const out = new Set();
+ const ranges = Object.entries(functions).map(([key, ids]) => [...key.split('-').map(Number), ids]);
+ for (let line = first; line <= last; line++) {
+ let best = null;
+ for (const r of ranges) if (r[0] <= line && line <= r[1] && (best === null || r[1] - r[0] < best[1] - best[0])) best = r;
+ // In no function: a shader's source, a constant -- whatever reads it.
+ const ids = best !== null ? best[2] : ranges.flatMap((r) => r[2]);
+ for (const id of ids) out.add(id);
+ }
+ return out;
+}
+
+/** Split checks across up to RUNNERS runners, the longest first onto the least loaded. */
+export function shard(ids, ms, runners = RUNNERS) {
+ const total = ids.reduce((t, id) => t + (ms[id] ?? 7000), 0);
+ const n = Math.max(1, Math.min(runners, ids.length, Math.ceil(total / PER_RUNNER_MS)));
+ const bins = Array.from({ length: n }, () => ({ total: 0, ids: [] }));
+ for (const id of [...ids].sort((a, b) => (ms[b] ?? 1000) - (ms[a] ?? 1000))) {
+ const bin = bins.reduce((x, y) => (y.total < x.total ? y : x));
+ bin.ids.push(id);
+ bin.total += ms[id] ?? 7000;
+ }
+ return bins.map((bin, i) => ({ shard: `${i}/${n}`, steps: bin.ids.join(',') }));
+}
+
+/** The plan for the change base..head. */
+export function plan(base, head) {
+ const suites = readdirSync(join(ROOT, 'test')).filter((f) => f.endsWith('.test.js') && f !== 'gpu.test.js').map((f) => `test/${f}`);
+ const all = { node: suites, types: true, gpu: Array.from({ length: RUNNERS }, (_, i) => ({ shard: `${i}/${RUNNERS}` })), why: [] };
+ let changed;
+ try {
+ if (/^0+$/.test(base)) throw new Error('no base');
+ changed = git('diff', '--name-only', base, head).split('\n').filter(Boolean);
+ } catch {
+ return { ...all, why: ['no base to compare with: everything'] };
+ }
+ // A release bumps package.json's version and nothing else of it: that runs nothing.
+ const versionOnly = (f) => f === 'package.json'
+ && git('diff', '-U0', base, head, '--', f).split('\n').filter((l) => /^[+-](?![+-])/.test(l)).every((l) => /"version":/.test(l));
+ if (changed.some((f) => EVERYTHING.some((re) => re.test(f)) && !versionOnly(f))) return { ...all, why: ['CI itself changed: everything'] };
+
+ const node = suites.filter((suite) => { const set = reaches(suite); return changed.some((f) => set.has(f)); });
+ const types = changed.some((f) => /\.d\.ts$/.test(f) || f === 'test/types.ts');
+
+ const why = [];
+ let map = null;
+ try {
+ map = JSON.parse(readFileSync(join(ROOT, 'test/gpu-map.json'), 'utf8'));
+ git('cat-file', '-e', `${map.commit}^{commit}`);
+ } catch { map = null; }
+ const ms = map === null ? {} : Object.fromEntries(Object.entries(map.steps).map(([id, s]) => [id, s.ciMs ?? (s.ms ?? 1000) * 7]));
+ // Every check, balanced by the map's times -- one it does not know yet runs
+ // in shard 0 -- or dealt out in turn without one.
+ const whole = map === null ? all.gpu : shard(Object.keys(ms), ms);
+
+ let gpu = [];
+ const source = changed.filter((f) => /^src\/.*\.js$/.test(f));
+ if (changed.some((f) => WHOLE_GPU.some((re) => re.test(f)))) {
+ gpu = whole;
+ why.push('the GPU suite itself changed: all of it');
+ } else if (source.length > 0 && map === null) {
+ gpu = whole;
+ why.push('no usable test/gpu-map.json: all of the GPU suite');
+ } else if (source.length > 0) {
+ const chosen = new Set();
+ for (const file of source) {
+ if (!existsSync(join(ROOT, file))) continue; // deleted: what used it changed too
+ try { git('cat-file', '-e', `${map.commit}:${file}`); } catch {
+ chosen.add('*');
+ why.push(`${file} is new since the map: all of the GPU suite`);
+ break;
+ }
+ const functions = map.files[file];
+ if (!functions) continue; // nothing the suite runs is in it
+ const sinceMap = git('diff', '-U0', map.commit, head, '--', file);
+ for (const range of touched(git('diff', '-U0', base, head, '--', file))) {
+ for (const id of checksFor(functions, carry(range, sinceMap))) chosen.add(id);
+ }
+ if (chosen.has('*')) { why.push(`${file} changes what every check sets up: all of the GPU suite`); break; }
+ }
+ if (chosen.has('*')) gpu = whole;
+ else if (chosen.size > 0) {
+ gpu = shard([...chosen], ms);
+ why.push(`${chosen.size} of ${Object.keys(map.steps).length} GPU checks reach the change`);
+ }
+ }
+ return { node, types, gpu, why: [...why, `${node.length} of ${suites.length} Node suites`] };
+}
+
+if (process.argv[1] && relative(process.argv[1], fileURLToPath(import.meta.url)) === '') {
+ const [base = 'HEAD~1', head = 'HEAD'] = process.argv.slice(2);
+ const p = plan(base, head);
+ const lines = [`node=${p.node.join(' ')}`, `types=${p.types}`, `gpu=${JSON.stringify(p.gpu)}`];
+ if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `${lines.join('\n')}\n`);
+ console.log(lines.join('\n'));
+ for (const reason of p.why) console.log(`# ${reason}`);
+ if (process.env.GITHUB_STEP_SUMMARY) {
+ appendFileSync(process.env.GITHUB_STEP_SUMMARY, `### What this change is checked by\n\n${p.why.map((w) => `- ${w}`).join('\n')}\n- GPU runners: ${p.gpu.length}\n`);
+ }
+}
diff --git a/.github/ci-times.js b/.github/ci-times.js
new file mode 100644
index 0000000..5c1fe54
--- /dev/null
+++ b/.github/ci-times.js
@@ -0,0 +1,20 @@
+// What each GPU check takes on CI, into test/gpu-map.json, so .github/affected.js
+// balances the runners by it. CI's GPU is software, and it does not slow every
+// check alike: balanced by a real GPU's times, four runners took 113 to 227 s.
+//
+// gh run view --log | node .github/ci-times.js
+//
+// Reads the "[id ms]" gpu.ci.js prints after each check; a check run on more
+// than one runner keeps its longest.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const path = new URL('../test/gpu-map.json', import.meta.url);
+const map = JSON.parse(readFileSync(path, 'utf8'));
+const log = readFileSync(0, 'utf8');
+const times = new Map();
+for (const [, id, ms] of log.matchAll(/\[([0-9a-z]+) (\d+) ms\]/g)) times.set(id, Math.max(times.get(id) ?? 0, Number(ms)));
+let n = 0;
+for (const [id, ms] of times) if (map.steps[id]) { map.steps[id].ciMs = ms; n++; }
+writeFileSync(path, `${JSON.stringify(map)}\n`);
+console.log(`${n} checks timed, of ${Object.keys(map.steps).length}`);
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a8d2ef2..9296264 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,24 +1,61 @@
-# The Node suites on every push and pull request, and the GPU suite beside them.
+# What a change is checked by, and nothing else.
#
-# There is no install step for the Node suites because there are no
-# dependencies: nothing to cache, nothing to audit, nothing to go stale between
-# a green run and a red one.
+# The plan job reads the commits a push brought (or a pull request from a fork)
+# and .github/affected.js decides what reaches them:
+#
+# Node suites the ones whose imports reach a changed file, on Node 20, 22
+# and 24. Seconds; none at all for a change no suite reads.
+# types the declarations against the docs' examples, when either
+# changed.
+# GPU suite only its checks that run a changed function, by the map in
+# test/gpu-map.json, split across up to four runners by the
+# time each takes; all of it when the change reaches what every
+# check sets up, or when the suite itself changed. None for
+# docs, the changelog, benchmarks or tools.
+#
+# Nothing runs twice: a branch here is checked when it is pushed, so its pull
+# request is not checked again, and main -- which takes pull requests only --
+# not at all. A release, which changes the version and the docs, checks the docs.
+#
+# No install step: there are no dependencies -- nothing to cache, nothing to
+# audit, nothing to go stale between a green run and a red one.
#
# The GPU suite runs test/gpu.html in headless Chrome. The runner has no GPU,
# so Chrome's own SwiftShader stands in: a software device, slow, but it
-# compiles and runs every shader and reads back every frame, which is the point -- nearly
-# everything this engine has got wrong was invisible to the Node
-# suites. A pass there is not a pass on every real GPU; the page at
-# test/gpu.html still is the test of one.
+# compiles and runs every shader and reads back every frame, which is the
+# point -- nearly everything this engine has got wrong was invisible to the
+# Node suites. A pass there is not a pass on every real GPU; the page at
+# test/gpu.html, opened by hand, runs every check.
name: CI
on:
push:
- branches: [main, develop]
+ branches-ignore: [main]
pull_request:
jobs:
+ plan:
+ # A pull request from a branch here was checked when it was pushed.
+ if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+ runs-on: ubuntu-latest
+ outputs:
+ node: ${{ steps.plan.outputs.node }}
+ types: ${{ steps.plan.outputs.types }}
+ gpu: ${{ steps.plan.outputs.gpu }}
+ steps:
+ - uses: actions/checkout@v5
+ with:
+ fetch-depth: 0 # the base to compare with, and the map's commit
+ - uses: actions/setup-node@v5
+ with:
+ node-version: 22
+ - id: plan
+ run: node .github/affected.js "$BASE" "$GITHUB_SHA"
+ env:
+ BASE: ${{ github.event_name == 'push' && github.event.before || github.event.pull_request.base.sha }}
+
test:
+ needs: plan
runs-on: ubuntu-latest
strategy:
fail-fast: false
@@ -29,13 +66,25 @@ jobs:
- uses: actions/setup-node@v5
with:
node-version: ${{ matrix.node }}
- - run: npm test
- # The types, against the docs' examples. TypeScript is fetched for this
- # step alone; the package still depends on nothing.
- - run: npx -y -p typescript@7 tsc --noEmit --strict --target es2022 --module nodenext --lib es2022,dom test/types.ts
+ - name: The Node suites the change reaches
+ run: |
+ if [ -z "$SUITES" ]; then echo "No Node suite reaches this change."; exit 0; fi
+ for suite in $SUITES; do node "$suite" || exit 1; done
+ env:
+ SUITES: ${{ needs.plan.outputs.node }}
+ # TypeScript is fetched for this step alone; the package still depends on nothing.
+ - if: needs.plan.outputs.types == 'true'
+ run: npx -y -p typescript@7 tsc --noEmit --strict --target es2022 --module nodenext --lib es2022,dom test/types.ts
gpu:
+ needs: plan
+ if: needs.plan.outputs.gpu != '[]'
+ name: gpu ${{ matrix.shard }}
runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ include: ${{ fromJSON(needs.plan.outputs.gpu) }}
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
@@ -45,3 +94,6 @@ jobs:
# even though WebGPU itself then runs on SwiftShader.
- run: sudo apt-get update && sudo apt-get install -y --no-install-recommends mesa-vulkan-drivers
- run: node test/gpu.ci.js
+ env:
+ GPU_SHARD: ${{ matrix.shard }}
+ GPU_STEPS: ${{ matrix.steps }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b448878..c9cc2cb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [1.7.0] - 2026-10-09
+
+**Ask first.** `Winding.supported()` says whether an engine can be made here, so a page can show
+something else where WebGPU is missing. The README has a face now -- a walker robot, rendered in
+Winding, waving beside the name -- and its engine comparison is a slideshow, a chart at a time. And
+CI checks only what a change reaches: a docs change in seconds, a full run split across four runners.
+
+### Added
+
+- **[`Winding.supported()`](docs/API.md#winding-supported)**: whether `Winding.create` can work in
+ this browser -- WebGPU, and a GPU it will hand out -- as `true` or `false`, never a throw. Ask
+ before creating an engine and show a still, a video or a message where the answer is no; the
+ README's install section shows how.
+
## [1.6.1] - 2026-10-09
**Off means off, for every scene.** A sweep of every feature for work done with nothing to do,
@@ -2468,7 +2482,8 @@ First public release.
- 261 checks under Node, plus a browser suite that boots the engine on a real
device and verifies what WGSL cannot be verified without one.
-[Unreleased]: https://github.com/nolanbaxter/winding/compare/v1.6.1...HEAD
+[Unreleased]: https://github.com/nolanbaxter/winding/compare/v1.7.0...HEAD
+[1.7.0]: https://github.com/nolanbaxter/winding/compare/v1.6.1...v1.7.0
[1.6.1]: https://github.com/nolanbaxter/winding/compare/v1.6.0...v1.6.1
[1.6.0]: https://github.com/nolanbaxter/winding/compare/v1.5.0...v1.6.0
[1.5.0]: https://github.com/nolanbaxter/winding/compare/v1.4.0...v1.5.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ba5e0f8..7049c99 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,7 @@ npm test
```
The Node suites: about 750 checks, no browser, no install (there is nothing to install). CI runs
-them on Node 20, 22 and 24 for every push and pull request.
+them on Node 20, 22 and 24 -- the ones your change reaches (see below).
```bash
npm run test:gpu
@@ -31,11 +31,29 @@ fails the pull request. A software GPU is not your GPU, though: run the page on
before any pull request that touches `src/render` or `src/rhi`, and say in the pull request that
it passed.
+### What CI runs
+
+Only what a change reaches. `.github/affected.js` reads the change and picks the Node suites whose
+imports reach a changed file, the type check if declarations changed, and the GPU checks that run a
+changed function -- from `test/gpu-map.json`, which records, for every function in `src/` the GPU
+suite runs, which checks run it. Those are split across up to four runners. A change to what every
+check sets up, to the GPU suite itself, or to CI runs all of it; docs, the changelog and benchmarks
+run nothing of it. `node .github/affected.js ` shows the plan for any range.
+
+The map stays usable as the code moves -- line numbers are carried from its commit through git --
+and a check it does not know always runs. Remake it after adding or reshaping GPU checks, or once a
+release, on a machine with a GPU and `src/` committed:
+
+```bash
+npm run test:gpu:map
+```
+
## What a change includes
- **A test that fails without it.** A bug fix starts from a script or a frame that shows the bug;
the fix comes with a test that fails on the old code. Node tests live in `test/*.test.js`, GPU
- steps in `test/gpu.test.js`.
+ steps in `test/gpu.test.js`. Models to test against go in `test/assets/`, each listed in its
+ README with where it came from and its licence; nothing there is published.
- **The API reference.** `docs/API.md` is updated in the same change as anything a user can see:
a new call, a changed option or default, a new error message, behaviour a fix changes. A new
entry gets an `` anchor and a line in the index. `npm test` checks that every public method
diff --git a/README.md b/README.md
index 1d6c74d..2ed5e1b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+
+
@@ -119,9 +121,11 @@ Chrome 154. Both at 1280×720. Each number is the median of eight alternating bl
timed to the GPU finishing, averaged over two runs; Three.js r186, Babylon.js 9.29, PlayCanvas 2.23.
Matched: four 1024×1024 shadow cascades to 40 m, ACES tone mapping, and no antialiasing, bloom,
ambient occlusion or TAA. Not matched: Winding lights its ambient from an environment map where the
-others use a flat term, and it culls by occlusion as well as by view. To rerun it, open
-bench/compare.html as a file in Chrome or Edge: it runs every scene twice and shows the
-results.
+others use a flat term, and it culls by occlusion as well as by view. Winding draws with WebGPU
+only; the other three can also draw with WebGL. The chart shows a comparison at a time, turning every
+seven seconds, and holds still for anyone who asked for less motion; every number is in its
+description. To rerun it, open bench/compare.html as a file in Chrome or Edge: it runs
+every scene twice and shows the results.
## Install
@@ -132,7 +136,7 @@ import are the files in this repository.
```html
```
@@ -157,13 +161,26 @@ completion and hover help.
```
+**Check first, where WebGPU may be missing.** Winding draws with WebGPU alone -- no WebGL fallback,
+since the culling, clustering and merged draws that make it fast need compute shaders WebGL does not
+have. Chrome, Edge and Safari have it, and Firefox on Windows; for the rest, ask before you start and
+show something else:
+
+```js
+if (await Winding.supported()) {
+ const engine = await Winding.create(canvas);
+} else {
+ canvas.replaceWith(Object.assign(new Image(), { src: 'still.jpg', alt: 'The scene' }));
+}
+```
+
**Pin the version.** `@latest` re-resolves on every page load, so a release you have never seen can
change what your page runs. A pinned URL is immutable on both jsDelivr and unpkg.
diff --git a/bench/compare.html b/bench/compare.html
index 6fe508c..736f632 100644
--- a/bench/compare.html
+++ b/bench/compare.html
@@ -72,7 +72,7 @@
// --- the suite: every scene twice, a page load each, results kept in between ---
/** The commit a page opened as a file measures. */
-const WINDING_COMMIT = '52d010e9585d732aa5a14a5cefcf710a4ea04f62';
+const WINDING_COMMIT = '697f25f10bae2f132cc89211bcd51a95a7f7db4f';
const FROM_FILE = location.protocol === 'file:';
const PLAN = ['sponza', 'cubes', 'lights', 'sponza', 'cubes', 'lights'];
const NAMES = { sponza: 'Sponza, sun shadows', cubes: '10,000 moving cubes', lights: '256 point lights' };
diff --git a/docs/API.md b/docs/API.md
index 920c436..4368efb 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -87,7 +87,7 @@ Every call, setting and entry, A to Z by its name.
**R** [`scene.raycast()`](#scene-raycast) · [`camera.rayFromScreen()`](#camera-rayfromscreen) · [`engine.gpu.readPixels()`](#engine-gpu-readpixels) · [`scene.remove()`](#scene-remove) · [`engine.renderer`](#engine-renderer) · [`engine.renderFrame()`](#engine-renderframe) · [`benchmark.report()`](#benchmark-report) · [`engine.renderer.post.requestedLevels` (renamed)](#post-requestedlevels) · [`engine.renderer.resolution`](#renderer-resolution) · [`engine.rhi` (renamed)](#engine-rhi) · [`camera.rotation` (renamed)](#camera2d-rotation) · [`engine.run()`](#engine-run) · [`benchmark.run()`](#benchmark-run)
-**S** [`new Scene()`](#scene-constructor) · [`camera.screenToWorld()`](#camera2d-screentoworld) · [`node.setAngle()`](#node-setangle) · [`node.setAxisAngle()`](#node-setaxisangle) · [`scene.setDecal()`](#scene-setdecal) · [`node.setDirection()`](#node-setdirection) · [`scene.setEmitter()`](#scene-setemitter) · [`node.setEuler()`](#node-seteuler) · [`scene.setLight()`](#scene-setlight) · [`node.setParent()`](#node-setparent) · [`scene.setPath()`](#scene-setpath) · [`node.setPosition()`](#node-setposition) · [`scene.setProbe()`](#scene-setprobe) · [`node.setRotation()`](#node-setrotation) · [`node.setScale()`](#node-setscale) · [`scene.setShape()`](#scene-setshape) · [`scene.setSprite()`](#scene-setsprite) · [`scene.setText()`](#scene-settext) · [`scene.setTile()`](#scene-settile) · [`scene.setTilemap()`](#scene-settilemap) · [`scene.setTiles()`](#scene-settiles) · [`engine.renderer.shadowDistance`](#renderer-shadowdistance) · [`engine.renderer.shadows`](#renderer-shadows) · [`scene.shapeOf()`](#scene-shapeof) · [`engine.skippedFrames`](#engine-skippedframes) · [`engine.renderer.skybox`](#renderer-skybox) · [`engine.renderer.softShadows`](#renderer-softshadows) · [`engine.debug.sphere()`](#debug-sphere) · [`engine.renderer.splatCull`](#renderer-splatcull) · [`scene.splatsOf()`](#scene-splatsof) · [`scene.spriteOf()`](#scene-spriteof) · [`spriteSheet()`](#spritesheet) · [`sRGB colours`](#view2d-colour) · [`srgbToLinear()`](#color-srgbtolinear) · [`benchmark.start()`](#benchmark-start) · [`engine.stats`](#engine-stats) · [`new StatsOverlay()`](#statsoverlay) · [`engine.stop()`](#engine-stop) · [`node.stop()`](#node-stop) · [`engine.renderer.post.strength`](#post-strength) · [`orbit.syncFromCamera()`](#orbitcontroller-syncfromcamera)
+**S** [`new Scene()`](#scene-constructor) · [`camera.screenToWorld()`](#camera2d-screentoworld) · [`node.setAngle()`](#node-setangle) · [`node.setAxisAngle()`](#node-setaxisangle) · [`scene.setDecal()`](#scene-setdecal) · [`node.setDirection()`](#node-setdirection) · [`scene.setEmitter()`](#scene-setemitter) · [`node.setEuler()`](#node-seteuler) · [`scene.setLight()`](#scene-setlight) · [`node.setParent()`](#node-setparent) · [`scene.setPath()`](#scene-setpath) · [`node.setPosition()`](#node-setposition) · [`scene.setProbe()`](#scene-setprobe) · [`node.setRotation()`](#node-setrotation) · [`node.setScale()`](#node-setscale) · [`scene.setShape()`](#scene-setshape) · [`scene.setSprite()`](#scene-setsprite) · [`scene.setText()`](#scene-settext) · [`scene.setTile()`](#scene-settile) · [`scene.setTilemap()`](#scene-settilemap) · [`scene.setTiles()`](#scene-settiles) · [`engine.renderer.shadowDistance`](#renderer-shadowdistance) · [`engine.renderer.shadows`](#renderer-shadows) · [`scene.shapeOf()`](#scene-shapeof) · [`engine.skippedFrames`](#engine-skippedframes) · [`engine.renderer.skybox`](#renderer-skybox) · [`engine.renderer.softShadows`](#renderer-softshadows) · [`engine.debug.sphere()`](#debug-sphere) · [`engine.renderer.splatCull`](#renderer-splatcull) · [`scene.splatsOf()`](#scene-splatsof) · [`scene.spriteOf()`](#scene-spriteof) · [`spriteSheet()`](#spritesheet) · [`sRGB colours`](#view2d-colour) · [`srgbToLinear()`](#color-srgbtolinear) · [`benchmark.start()`](#benchmark-start) · [`engine.stats`](#engine-stats) · [`new StatsOverlay()`](#statsoverlay) · [`engine.stop()`](#engine-stop) · [`node.stop()`](#node-stop) · [`engine.renderer.post.strength`](#post-strength) · [`Winding.supported()`](#winding-supported) · [`orbit.syncFromCamera()`](#orbitcontroller-syncfromcamera)
**T** [`engine.renderer.taa`](#renderer-taa) · [`scene.textOf()`](#scene-textof) · [`engine.renderer.post.threshold`](#post-threshold) · [`scene.tileAt()`](#scene-tileat) · [`scene.tilemapOf()`](#scene-tilemapof)
@@ -160,6 +160,24 @@ const engine = await Winding.create(canvas, {
Notes: a `shadows.shadowDistance` is ignored; use the top-level `shadowDistance`.
+
+### `Winding.supported()` → `Promise`
+
+Whether [`Winding.create`](#winding-create) can work in this browser: it has WebGPU, and a GPU it will hand out. Ask before creating an engine, and show something else where the answer is no -- a still, a video, a message.
+
+Returns: `true` or `false`. Never throws.
+
+```js
+if (await Winding.supported()) {
+ const engine = await Winding.create(canvas);
+ // ...
+} else {
+ canvas.replaceWith(Object.assign(new Image(), { src: 'still.jpg', alt: 'The scene' }));
+}
+```
+
+Notes: costs one request for the GPU, which `create` makes again. `false` on a browser without WebGPU (one too old, or some on Linux and Android), on a page that is not a secure context (https or localhost), and where the browser keeps the GPU from pages, as it does for drivers it has blocklisted.
+
### `engine.createScene(options)` → `Scene`
diff --git a/docs/images/compare-dark.svg b/docs/images/compare-dark.svg
index 8fa90f1..bf71b88 100644
--- a/docs/images/compare-dark.svg
+++ b/docs/images/compare-dark.svg
@@ -1,55 +1,75 @@
-
@@ -119,9 +121,11 @@ Chrome 154. Both at 1280×720. Each number is the median of eight alternating bl
timed to the GPU finishing, averaged over two runs; Three.js r186, Babylon.js 9.29, PlayCanvas 2.23.
Matched: four 1024×1024 shadow cascades to 40 m, ACES tone mapping, and no antialiasing, bloom,
ambient occlusion or TAA. Not matched: Winding lights its ambient from an environment map where the
-others use a flat term, and it culls by occlusion as well as by view. To rerun it, open
-