@driftengine/core 4.1.3 → 4.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 The runtime everything needs: renderer, loop, camera, input, geometry. Collision and dynamics live in [`@driftengine/physics`](../physics/README.md), which this package depends on and re-exports whole, so reaching for them through this barrel works as it always did.
 
-**Cost: 698.4 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 721.2 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/index.js

@@ -102,8 +102,18 @@ export { createRenderer } from './render/backend/createRenderer.js';
  * A consumer who names neither pays nothing: `core-only` is measured with these exported and does
  * not move, because nothing in the forward path reaches them.
  *
- * It draws vertex colour, one directional term, a hemispheric ambient and an emissive add — not
- * the standard material. `DRAFT_SCENES`, never `SCENES`, until it draws the six published ones.
+ * **It draws vertex colour, one directional term, a hemispheric ambient and an emissive add — not
+ * the standard material**, and that is the sentence to read before reaching for it. There is no
+ * flag that routes `drawMesh` through this: a consumer packs a scene and contributes the pass, and
+ * `setMaterial`, `setSurfaceGrain`, `setSurfaceRelief` and a skin palette reach none of it. What
+ * would change that is a second copy of the standard material, which `gpuDrivenPass.ts` refuses in
+ * its own header.
+ *
+ * **The line that used to be here said `DRAFT_SCENES`, never `SCENES`, and it went stale the day
+ * the city was published.** `city` is in `SCENES` and says `pipelines: ['gpu-driven']`, so a host
+ * that cannot run the second pipeline reads that from the list rather than from a mount that
+ * refuses. The rule it was standing in for is the one above: what gates a scene is whether this
+ * pass can draw it, not which array it is in.
  */
 export { GPU_DRIVEN_LISTS, GpuDrivenPass, MATERIAL_FLOATS, 
 /*

package/dist/render/backend/webgpu/gpuDrivenPass.d.ts

@@ -470,6 +470,30 @@ export declare class GpuDrivenPass implements PassDefinition {
      * before the device answers, which nobody sees; the alternative is a frame that draws nothing.
      */
     private blendUsable;
+    /**
+     * The same question about *every other* pipeline in this pass, and the reason it exists is that
+     * 4.1.3 asked it about one.
+     *
+     * **The guard above was written from a log that named `gpu-driven blend`, and the four render
+     * pipelines and eight compute pipelines beside it were left with the shape that caused the
+     * report.** Reported again from an Android handset once that fix shipped: the transparent pass
+     * now skips itself correctly, the overlay still draws and the frame counter still counts — and
+     * the world is black, which is what an invalid *opaque* pipeline looks like once the blended one
+     * has stopped taking the command buffer with it.
+     *
+     * So the whole of `buildPipelines` is built inside one pair of scopes and nothing this pass
+     * encodes runs until they come back clean. The blend pipeline pushes its own pair *inside* that
+     * region, so the two verdicts stay separate: a device that refuses only the transparent pipeline
+     * still draws everything opaque, and a device that refuses anything else turns this pass off
+     * rather than encoding against a handle the driver has already rejected.
+     *
+     * **What it gives up** is the first frames, which draw nothing while the device is still
+     * answering. **What would make it wrong** is a device that never resolves an error scope; the
+     * `popErrorScope` check below is the same concession the blend guard makes, for the same reason.
+     */
+    private usable;
+    /** Why this pass refused itself, in the words the device used, or null while it has not. */
+    private refusal;
     /** Builds the transparent raster's bindings, held until there is a pipeline worth binding to. */
     private makeBlendGroup;
     private blendResolvePipeline;
@@ -641,6 +665,28 @@ export declare class GpuDrivenPass implements PassDefinition {
      * this came from was five errors that were all the same one.
      */
     private watchBlendPipeline;
+    /**
+     * Close the scopes every other pipeline was built in, and refuse the pass where one came back.
+     *
+     * **This is `watchBlendPipeline` widened to the rest of the pass**, and the reason it is separate
+     * is that the two refusals mean different things: a blend pipeline nobody can compile costs the
+     * glass, and a raster, shadow, blit or compute pipeline nobody can compile costs the world. The
+     * first degrades; the second has nothing to degrade to, so it says so and draws nothing rather
+     * than encoding a command buffer the driver will reject whole.
+     *
+     * A device with no scopes is taken at its word, exactly as the blend guard takes it: refusing to
+     * draw on hardware that never said no is the worse of the two failures.
+     */
+    private watchPipelines;
+    /**
+     * Why this pass is drawing nothing, in the words the device used, or null where it is not.
+     *
+     * **Exposed because a black frame that says nothing is the bug this was reported as, twice.** A
+     * pipeline refusal arrives asynchronously, long after `createRenderer` has decided the backend
+     * can run this at all, so there is no earlier place to throw — and a scene that can read this can
+     * tell somebody what happened instead of presenting an empty picture.
+     */
+    refusedBecause(): string | null;
     private buildPipelines;
     /**
      * The groups that name `history` and `drawn`, rebuilt when the two swap.

package/dist/render/backend/webgpu/gpuDrivenPass.js

@@ -445,6 +445,30 @@ export class GpuDrivenPass {
      * before the device answers, which nobody sees; the alternative is a frame that draws nothing.
      */
     blendUsable = false;
+    /**
+     * The same question about *every other* pipeline in this pass, and the reason it exists is that
+     * 4.1.3 asked it about one.
+     *
+     * **The guard above was written from a log that named `gpu-driven blend`, and the four render
+     * pipelines and eight compute pipelines beside it were left with the shape that caused the
+     * report.** Reported again from an Android handset once that fix shipped: the transparent pass
+     * now skips itself correctly, the overlay still draws and the frame counter still counts — and
+     * the world is black, which is what an invalid *opaque* pipeline looks like once the blended one
+     * has stopped taking the command buffer with it.
+     *
+     * So the whole of `buildPipelines` is built inside one pair of scopes and nothing this pass
+     * encodes runs until they come back clean. The blend pipeline pushes its own pair *inside* that
+     * region, so the two verdicts stay separate: a device that refuses only the transparent pipeline
+     * still draws everything opaque, and a device that refuses anything else turns this pass off
+     * rather than encoding against a handle the driver has already rejected.
+     *
+     * **What it gives up** is the first frames, which draw nothing while the device is still
+     * answering. **What would make it wrong** is a device that never resolves an error scope; the
+     * `popErrorScope` check below is the same concession the blend guard makes, for the same reason.
+     */
+    usable = false;
+    /** Why this pass refused itself, in the words the device used, or null while it has not. */
+    refusal = null;
     /** Builds the transparent raster's bindings, held until there is a pipeline worth binding to. */
     makeBlendGroup = null;
     blendResolvePipeline = null;
@@ -687,7 +711,18 @@ export class GpuDrivenPass {
             });
         }
         this.buildBuffers(device.device);
+        /*
+         * **Every pipeline this pass owns, inside one pair of scopes.** See `usable`: the blend
+         * pipeline pushes its own pair within this region, so its refusal stays its own and any other
+         * refusal is caught here and turns the pass off instead of reaching an encoder.
+         */
+        const scoped = typeof device.device.pushErrorScope === 'function';
+        if (scoped) {
+            device.device.pushErrorScope('validation');
+            device.device.pushErrorScope('internal');
+        }
         this.buildPipelines(device.device, device.format, device.samples);
+        this.watchPipelines(device.device, scoped);
         if (this.width > 0)
             this.buildTargets(device.device);
     }
@@ -1000,6 +1035,50 @@ export class GpuDrivenPass {
         void device.popErrorScope().then((error) => settle(error, 'internal'));
         void device.popErrorScope().then((error) => settle(error, 'validation'));
     }
+    /**
+     * Close the scopes every other pipeline was built in, and refuse the pass where one came back.
+     *
+     * **This is `watchBlendPipeline` widened to the rest of the pass**, and the reason it is separate
+     * is that the two refusals mean different things: a blend pipeline nobody can compile costs the
+     * glass, and a raster, shadow, blit or compute pipeline nobody can compile costs the world. The
+     * first degrades; the second has nothing to degrade to, so it says so and draws nothing rather
+     * than encoding a command buffer the driver will reject whole.
+     *
+     * A device with no scopes is taken at its word, exactly as the blend guard takes it: refusing to
+     * draw on hardware that never said no is the worse of the two failures.
+     */
+    watchPipelines(device, scoped) {
+        if (!scoped || typeof device.popErrorScope !== 'function') {
+            this.usable = true;
+            return;
+        }
+        let outstanding = 2;
+        const settle = (error, scope) => {
+            outstanding -= 1;
+            if (error !== null && this.refusal === null) {
+                this.refusal = error.message;
+                console.warn(`[driftengine] this device refused a gpu-driven pipeline (${scope}), so this pass draws ` +
+                    `nothing and the rest of the frame is unaffected: ${error.message}`);
+            }
+            /* Usable only once both have come back clean, which is what keeps an invalid handle out. */
+            if (outstanding > 0 || this.refusal !== null)
+                return;
+            this.usable = true;
+        };
+        void device.popErrorScope().then((error) => settle(error, 'internal'));
+        void device.popErrorScope().then((error) => settle(error, 'validation'));
+    }
+    /**
+     * Why this pass is drawing nothing, in the words the device used, or null where it is not.
+     *
+     * **Exposed because a black frame that says nothing is the bug this was reported as, twice.** A
+     * pipeline refusal arrives asynchronously, long after `createRenderer` has decided the backend
+     * can run this at all, so there is no earlier place to throw — and a scene that can read this can
+     * tell somebody what happened instead of presenting an empty picture.
+     */
+    refusedBecause() {
+        return this.refusal;
+    }
     buildPipelines(device, format, samples) {
         const compute = (label, code) => device.createComputePipeline({
             label: `gpu-driven ${label}`,
@@ -1935,6 +2014,9 @@ export class GpuDrivenPass {
     prepare(ctx) {
         if (ctx.backend !== 'webgpu')
             return;
+        /* Nothing is encoded until the device has answered for the pipelines. See `usable`. */
+        if (!this.usable)
+            return;
         const device = this.device;
         if (device === null || this.levels.length === 0)
             return;
@@ -2165,6 +2247,26 @@ export class GpuDrivenPass {
                 return;
             }
             case 'blendResolve': {
+                /*
+                 * **Skipped on the same verdict as the draw, because the draw is what clears what this
+                 * reads.** This is the whole of the reported black frame, and the line above it predicted
+                 * it: the blend pass clears reveal to one, meaning nothing has covered this pixel yet, and
+                 * says in as many words that cleared to zero "the resolve would show no scene anywhere the
+                 * pass ran, which is a black frame that looks like the blend working".
+                 *
+                 * 4.1.2 skipped the draw and took its clear with it, and left this running against textures
+                 * nothing had written — a reveal of zero over every pixel, which is exactly "fully covered".
+                 * Reported from a Galaxy S23 Ultra and then an Adreno 740, both of which refuse only
+                 * `gpu-driven blend` and both of which drew the city into a buffer this then wiped: the
+                 * page's own readout said 43 fps and 1,087 clusters drawn while the screen was black.
+                 *
+                 * There is nothing to composite when nothing was rasterised, so the honest answer is not to
+                 * composite. **What would make it wrong** is a caller that expects this pass to have run for
+                 * some other reason; nothing does, and the opaque image is already in `colourView` before
+                 * this would load it.
+                 */
+                if (!this.blendUsable)
+                    return;
                 const pass = encoder.beginRenderPass({
                     label: 'gpu-driven blend resolve',
                     colorAttachments: [
@@ -2468,6 +2570,9 @@ export class GpuDrivenPass {
     draw(ctx) {
         if (ctx.backend !== 'webgpu')
             return;
+        /* The same gate as `prepare`: an unanswered or refused pipeline set encodes nothing at all. */
+        if (!this.usable)
+            return;
         if (this.blitPipeline === null || this.blitGroup === null)
             return;
         if (ctx.outputTransform !== 0 && !this.gradeWarned) {

package/dist/render/backend/webgpu/renderer.js

@@ -38,6 +38,7 @@ import { POINT_SHADOW_SAMPLER, PointShadowSystem, } from '../../pointShadowSyste
 import { GpuPointShadowArray, GpuPointShadowMap } from './pointShadowPass.js';
 import { createPanelBindGroup, createPanelBindGroupLayout, createPanelCorners, panelPipeline, PANEL_FRAG_FIELDS, PANEL_FRAG_SIZE, PANEL_VERTEX_COUNT, PANEL_VERT_FIELDS, PANEL_VERT_SIZE, } from './panelPass.js';
 import { createGpuTextCube, createTextBindGroup, createTextBindGroupLayout, GpuText, textPipeline, TEXT_FRAG_FIELDS, TEXT_FRAG_SIZE, TEXT_VERT_FIELDS, TEXT_VERT_SIZE, } from './textPass.js';
+import { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.js';
 import { GpuSurfaceTexture } from './surfaceTexturePass.js';
 import { createSdfTextBindGroup, createSdfTextBindGroupLayout, GpuSdfText, sdfTextPipeline, SDF_TEXT_FRAG_FIELDS, SDF_TEXT_FRAG_SIZE, SDF_TEXT_VERT_FIELDS, SDF_TEXT_VERT_SIZE, } from './sdfTextPass.js';
 import { createFilmBindGroup, createFilmBindGroupLayout, filmPipeline, FILM_FRAG_FIELDS, FILM_FRAG_SIZE, FILM_VERT_FIELDS, FILM_VERT_SIZE, } from './filmPass.js';
@@ -2485,8 +2486,15 @@ export class WebGPURenderer {
         const at = (name) => TEXT_VERT_FIELDS[name]?.offset ?? 0;
         const v = this.textVerts;
         v.writeFloats(vertexSlot, at('uViewport'), [viewportWidth, viewportHeight]);
-        v.writeFloats(vertexSlot, at('uOrigin'), [originX, originY]);
-        v.writeFloat(vertexSlot, at('uCellSize'), style.cellSize);
+        /* Snapped with the cell below: a whole pitch on a fractional origin still splits a stroke.
+           See `deviceSnappedOrigin`. */
+        v.writeFloats(vertexSlot, at('uOrigin'), [
+            deviceSnappedOrigin(originX, viewportWidth, this.surface.canvas.width),
+            deviceSnappedOrigin(originY, viewportHeight, this.surface.canvas.height),
+        ]);
+        /* Whole device pixels per cell, or a 5x7 face draws strokes of two different widths. The
+           decision is shared with WebGL2; only this binding is per-backend. See `textLayout.ts`. */
+        v.writeFloat(vertexSlot, at('uCellSize'), deviceSnappedCellSize(style.cellSize, viewportWidth, this.surface.canvas.width));
         /* Far enough that a whole line barely converges, near enough that a turn reads as a turn. */
         v.writeFloat(vertexSlot, at('uDepth'), Math.max(viewportWidth, 600) * 1.4);
         v.writeFloat(vertexSlot, at('uReveal'), style.reveal);