@driftengine/core 4.6.1 → 4.7.1

package/src/render/backend/webgpu/renderer.ts

@@ -586,7 +586,9 @@ import type { WorldLightFieldOptions } from '../../driftLight/worldLightField.ts
 import { createDriftLightUniforms, resolveDriftLight } from '../../driftLight/uniforms.ts';
 
 /**
- * How many draws one frame may make before the ring is full.
+ * How many draws one frame is prepared for before anything grows: `drawsPerFrame`'s default, and
+ * the starting size of the arena and the command pool, which reallocate on demand. The two rings
+ * that cannot grow take `drawsPerFrame` itself.
  *
  * **Four thousand and ninety-six, and the number is an allocation rather than a limit.**
  * `UniformRing.flush` uploads `used * slotSize`, so a frame that draws two hundred pays for two
@@ -644,37 +646,6 @@ const MAX_OVERLAYS = 64;
  */
 const MAX_SKY_DRAWS = 64;
 
-/**
- * Distinct materials a frame may set.
- *
- * A slot is spent per *change*, not per draw, so this counts how many times a scene switches
- * material rather than how much it draws.
- *
- * **A thousand and twenty-four, and it is the expensive one of the two.** A slot is the fragment
- * block — 3,376 to 6,656 bytes depending on which of the sixteen permutations is built — paid
- * twice for staging and buffer, so **7,168 to 13,312 bytes a slot** against 1,540 for a draw.
- * Raising it from 256 costs 5.25 to 9.75 MB.
- *
- * It is worth paying for how it *fails* rather than how it performs. Past the ring
- * `materialSlotForDraw` returns null and **every draw that needed a new material is skipped** —
- * a stretch of the world simply not drawn, which has been reported from a consumer as
- * ground that appears and disappears as the camera moves. A budget that hopes to stay under a
- * ceiling is a budget that ships this the first time somebody adds a model.
- *
- * **This comment said "silently reuses the last material" until 2026-09-02, and so did the
- * warning, and neither was ever true.** The skip has been there since `9d90bf7` wrote both
- * halves in one diff. It is recorded because the wrong failure was the stated argument for
- * raising this number from 256, and because "wrong texture" and "no geometry" send a consumer
- * looking in completely different places — one at materials, the other at culling, which is
- * where the reporting game spent its weeks. `frameBudget` reports the count now, so the next
- * consumer reads a number instead of a sentence.
- *
- * **What would make it wrong** is a scene switching material every draw: a thousand material
- * changes is a thousand uniform copies, and a consumer reaching this has a batching problem no
- * ring size answers — many copies of one mesh want one material and one instanced draw.
- */
-const MAX_MATERIALS_PER_FRAME = 1024;
-
 /**
  * Whether the environment probe's permutation fits this device's per-stage binding limits.
  *
@@ -1584,8 +1555,37 @@ export class WebGPURenderer implements RendererApi {
    * geometry come first.
    */
   private readonly budget = new FrameBudget();
-  private readonly drawBudget = this.budget.line('draws', MAX_DRAWS_PER_FRAME);
-  private readonly materialBudget = this.budget.line('materials', MAX_MATERIALS_PER_FRAME);
+  private readonly drawBudget = this.budget.line('draws', null);
+  /**
+   * Distinct materials a frame may set: `materialChangesPerFrame`, 1,024 unless a consumer asks.
+   *
+   * A slot is spent per *change*, not per draw, so this counts how many times a scene switches
+   * material rather than how much it draws.
+   *
+   * **A thousand and twenty-four by default, and it is the expensive one of the two.** A slot is the fragment
+   * block — 3,376 to 6,656 bytes depending on which of the sixteen permutations is built — paid
+   * twice for staging and buffer, so **7,168 to 13,312 bytes a slot** against 1,540 for a draw.
+   * Raising it from 256 costs 5.25 to 9.75 MB.
+   *
+   * It is worth paying for how it *fails* rather than how it performs. Past the ring
+   * `materialSlotForDraw` returns null and **every draw that needed a new material is skipped** —
+   * a stretch of the world simply not drawn, which has been reported from a consumer as
+   * ground that appears and disappears as the camera moves. A budget that hopes to stay under a
+   * ceiling is a budget that ships this the first time somebody adds a model.
+   *
+   * **This comment said "silently reuses the last material" until 2026-09-02, and so did the
+   * warning, and neither was ever true.** The skip has been there since `9d90bf7` wrote both
+   * halves in one diff. It is recorded because the wrong failure was the stated argument for
+   * raising this number from 256, and because "wrong texture" and "no geometry" send a consumer
+   * looking in completely different places — one at materials, the other at culling, which is
+   * where the reporting game spent its weeks. `frameBudget` reports the count now, so the next
+   * consumer reads a number instead of a sentence.
+   *
+   * **What would make it wrong** is a scene switching material every draw: a thousand material
+   * changes is a thousand uniform copies, and a consumer reaching this has a batching problem no
+   * ring size answers — many copies of one mesh want one material and one instanced draw.
+   */
+  private readonly materialBudget = this.budget.line('materials', null);
   /**
    * Native bind groups built this frame, which is the one cost a consumer could not see.
    *
@@ -1596,7 +1596,7 @@ export class WebGPURenderer implements RendererApi {
    * in draw order, precisely because the frame reported draws and material changes and never this.
    */
   private readonly bindGroupBudget = this.budget.line('bind groups', null);
-  private readonly shadowDrawBudget = this.budget.line('shadow draws', MAX_DRAWS_PER_FRAME);
+  private readonly shadowDrawBudget = this.budget.line('shadow draws', null);
   private readonly scatterDepthBudget = this.budget.line(
     'scatter shadow draws',
     MAX_SCATTER_DEPTH_DRAWS,
@@ -5909,6 +5909,9 @@ export class WebGPURenderer implements RendererApi {
         }
       : quality;
     quality = this.quality;
+    this.materialBudget.limit(quality.materialChangesPerFrame);
+    this.drawBudget.limit(quality.drawsPerFrame);
+    this.shadowDrawBudget.limit(quality.drawsPerFrame);
     this.maxDrawingBufferPixels = quality.maxDrawingBufferPixels;
     this.exposure = quality.outputExposure;
     this.flushSchedule =
@@ -6014,7 +6017,7 @@ export class WebGPURenderer implements RendererApi {
     this.perDraw = new UniformRing(
       device,
       FLAT_VERT_SIZE,
-      MAX_DRAWS_PER_FRAME,
+      quality.drawsPerFrame,
       USAGE_UNIFORM_DST,
       'flat.vertRing',
       this.drawBudget,
@@ -6038,7 +6041,7 @@ export class WebGPURenderer implements RendererApi {
     this.perFrame = new UniformRing(
       device,
       this.fragment.uniformSize,
-      MAX_MATERIALS_PER_FRAME,
+      this.quality.materialChangesPerFrame,
       USAGE_UNIFORM_DST,
       'flat.fragRing',
       this.materialBudget,
@@ -6773,7 +6776,7 @@ export class WebGPURenderer implements RendererApi {
       device,
       /* The cutout block is the plain one and two fields more, and a slot must hold either. */
       Math.max(DEPTH_VERT_SIZE, DEPTH_CUTOUT_VERT_SIZE),
-      MAX_DRAWS_PER_FRAME,
+      quality.drawsPerFrame,
       USAGE_UNIFORM_DST,
       'shadow.drawRing',
       this.shadowDrawBudget,
@@ -8208,7 +8211,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.warnedMaterialsFull) {
         this.warnedMaterialsFull = true;
         console.warn(
-          `WebGPU: more than ${MAX_MATERIALS_PER_FRAME} material changes in a frame; the draws asking for the rest are skipped. renderer.frameBudget names the line and the count.`,
+          `WebGPU: more than ${this.quality.materialChangesPerFrame} material changes in a frame; the draws asking for the rest are skipped. renderer.frameBudget names the line and the count.`,
         );
       }
       return null;
@@ -8432,7 +8435,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.warnedFull) {
         this.warnedFull = true;
         console.warn(
-          `WebGPU: more than ${MAX_DRAWS_PER_FRAME} draws in a frame; the rest are skipped`,
+          `WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`,
         );
       }
       return;
@@ -8598,7 +8601,7 @@ export class WebGPURenderer implements RendererApi {
     /*
      * Guards the draw call only, not the restore below.
      *
-     * `materialSlotForDraw` returns null once `MAX_MATERIALS_PER_FRAME` is exhausted, and an
+     * `materialSlotForDraw` returns null once `materialChangesPerFrame` is exhausted, and an
      * early `return` here used to skip the restore too — which left `uOpacity`,
      * `uLightingEnabled` and `uFogEnabled` dirtied in `perFrameFloats`/`perFrameInts` for the
      * rest of the frame, since that scratch block is cumulative state shared by every draw
@@ -8888,7 +8891,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.warnedFull) {
         this.warnedFull = true;
         console.warn(
-          `WebGPU: more than ${MAX_DRAWS_PER_FRAME} draws in a frame; the rest are skipped`,
+          `WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`,
         );
       }
       return;
@@ -9272,7 +9275,7 @@ export class WebGPURenderer implements RendererApi {
    * *unchanged*, so a run of entries sharing one material has no shorter spelling and the sink
    * bound once per entry. On this backend that is a cliff rather than a slope: `setMaterial`
    * dirties `materialSlot`, so a bind per entry is a **slot per draw** out of
-   * `MAX_MATERIALS_PER_FRAME` — and past the ring `materialSlotForDraw` returns null and the draw
+   * `materialChangesPerFrame` — and past the ring `materialSlotForDraw` returns null and the draw
    * is skipped, which is the world that appears and disappears that constant's own comment
    * describes. A consumer measured 82 materials a model over two to four draws each, and a
    * reflection replaying the frame shares the ring with the pass that recorded it.

package/src/render/pass.ts

@@ -37,7 +37,8 @@ import type { FrameResource } from './frame/index.ts';
  */
 export type PassDevice = {
   /**
-   * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. Identity on WebGL2.
+   * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. On WebGL2 it is
+   * the depth remap while that context draws reversed depth, and the identity where it cannot.
    *
    * A contributed pass takes its camera from its caller, so it never sees the corrected matrix the
    * renderer built for its own verbs. Without this it would have to copy four numbers — and a
@@ -58,7 +59,8 @@ export type PassDevice = {
    */
   readonly clipCorrection: Float32Array;
   /**
-   * Pre-multiply a projection by this **if you wrote your WGSL by hand**. Identity on WebGL2.
+   * Pre-multiply a projection by this **if you wrote your WGSL by hand**. On WebGL2 it is the same
+   * matrix as `clipCorrection`.
    *
    * The same matrix without the Y negation, because there is no generated negation to cancel.
    * Taking `clipCorrection` in a hand-written shader mirrors the picture vertically — and mirrors

package/src/render/renderQuality.ts

@@ -97,6 +97,37 @@ export interface RenderQuality {
    * halved frame rate rather than a slightly slower one.
    */
   readonly maxDrawingBufferPixels: number;
+  /**
+   * How many times a frame may change material, on a backend that keeps a slot for each.
+   *
+   * **WebGPU spends a slot of a uniform ring per material change and skips every draw past it**,
+   * because a buffer rewritten between two draws would hand both of them its last contents. So
+   * this is a ceiling on what a frame can show, not a performance hint: a scene that needs more
+   * loses whatever it asks for last — measured on a bought city of 1,139 materials, whose street
+   * spends some nine hundred and whose river's planar mirror spends the rest twice over.
+   *
+   * **What it costs is memory, paid at construction**: a slot is the fragment block twice over,
+   * staging and buffer, so 7 to 13 KB depending on the permutation built — 1,024 is 7 to 13 MB
+   * and 2,048 twice that. Hence a default that suits most scenes and an option for the one that
+   * measures past it, rather than a number every consumer pays for. WebGL2 writes each uniform
+   * into the command stream and keeps no ring, so there it is read and does nothing, and its
+   * budget line reports no ceiling. What would make it wrong is a scene that switches material
+   * every draw, which no ring answers: many copies of one mesh want one instanced draw.
+   */
+  readonly materialChangesPerFrame: number;
+  /**
+   * How many draws a frame may make, on a backend that keeps a uniform slot for each — the main
+   * pass and the shadow passes each hold this many.
+   *
+   * **The same shape as `materialChangesPerFrame` and the same failure**: WebGPU skips every draw
+   * past the ring. A frame that draws two hundred pays for two hundred whatever this says, so
+   * raising it costs no bandwidth; it costs memory at construction, 1,540 bytes a slot — 6 MB at
+   * the default 4,096. A city whose street spends three and a half thousand and whose river
+   * mirrors that street spends more than the default, and a scene in the ordinary band of two to
+   * ten thousand draws can meet it. WebGL2 keeps no ring and reads this without effect. What would
+   * make it wrong is a frame that approaches it on the CPU first, which four thousand draws can.
+   */
+  readonly drawsPerFrame: number;
   readonly directionalShadows: boolean;
   readonly pointShadows: boolean;
   /**
@@ -573,10 +604,10 @@ export interface RenderQuality {
    * the output size with no upscaling, which is a temporal antialiaser with a better neighbourhood
    * rule than `temporalAa`'s. A sentinel that collided with it would make that unaskable.
    *
-   * The range is 1.3 to 2 and a value inside it is clamped to the end it is nearest. Below 1.3 the
-   * render saves less than a third of the fragment work and the resolve's own cost eats it; above 2
-   * the render is a quarter of the output and no reconstruction holds an edge through that. A
-   * negative number is off, not a clamp to the bottom: it cannot mean "a little".
+   * The range is 1.3 to 2 and a positive value outside it is clamped to the end it is nearest.
+   * Below 1.3 the render saves less than a third of the fragment work and the resolve's own cost
+   * eats it; above 2 the render is a quarter of the output and no reconstruction holds an edge
+   * through that. A negative number is off, not a clamp to the bottom: it cannot mean "a little".
    *
    * **What it needs from you.** A `createMover()` per moving object, passed with that object's
    * draws where `drawMesh` takes last frame's matrix — the renderer keeps last frame's model and,
@@ -821,6 +852,10 @@ export interface RenderQuality {
 export type RenderQualityOptions = Partial<RenderQuality>;
 
 export const MAX_SHADOW_FILTER_TAPS = 12;
+/** The most material changes a frame may be built to hold. See `materialChangesPerFrame`. */
+export const MAX_MATERIAL_CHANGES_PER_FRAME = 8192;
+/** The most draws a frame may be built to hold. See `drawsPerFrame`. */
+export const MAX_DRAWS_PER_FRAME = 65536;
 export const MAX_WATER_REFLECTION_FILTER_TAPS = 9;
 export const POINT_SHADOW_FADE_START = 0.35;
 export const DIRECTIONAL_SHADOW_FADE_START = 0.65;
@@ -864,6 +899,8 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
    * if it is above where people actually are. Consumers wanting the pixels set it to 0.
    */
   maxDrawingBufferPixels: 12_000_000,
+  materialChangesPerFrame: 1024,
+  drawsPerFrame: 4096,
   directionalShadows: true,
   pointShadows: true,
   /* The engine's own budgets, which the renderer lowers per device when it has to. */
@@ -1015,6 +1052,9 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
     maxDevicePixelRatio: options.maxDevicePixelRatio ?? DEFAULT_RENDER_QUALITY.maxDevicePixelRatio,
     maxDrawingBufferPixels:
       options.maxDrawingBufferPixels ?? DEFAULT_RENDER_QUALITY.maxDrawingBufferPixels,
+    materialChangesPerFrame:
+      options.materialChangesPerFrame ?? DEFAULT_RENDER_QUALITY.materialChangesPerFrame,
+    drawsPerFrame: options.drawsPerFrame ?? DEFAULT_RENDER_QUALITY.drawsPerFrame,
     directionalShadows: options.directionalShadows ?? DEFAULT_RENDER_QUALITY.directionalShadows,
     pointShadows: options.pointShadows ?? DEFAULT_RENDER_QUALITY.pointShadows,
     /* Whole slots, at least one, never above what the shader is written for: these two are
@@ -1132,6 +1172,21 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
   // Zero is legal and means uncapped, so this is the non-negative check rather than
   // the positive one.
   nonNegative('maxDrawingBufferPixels', quality.maxDrawingBufferPixels);
+  positiveInteger('materialChangesPerFrame', quality.materialChangesPerFrame);
+  if (quality.materialChangesPerFrame > MAX_MATERIAL_CHANGES_PER_FRAME) {
+    throw new Error(
+      `materialChangesPerFrame is ${quality.materialChangesPerFrame}, and at most ` +
+        `${MAX_MATERIAL_CHANGES_PER_FRAME} are kept: past that the ring is a hundred megabytes, ` +
+        'and a frame changing material that often wants its draws batched instead.',
+    );
+  }
+  positiveInteger('drawsPerFrame', quality.drawsPerFrame);
+  if (quality.drawsPerFrame > MAX_DRAWS_PER_FRAME) {
+    throw new Error(
+      `drawsPerFrame is ${quality.drawsPerFrame}, and at most ${MAX_DRAWS_PER_FRAME} are kept: ` +
+        'past that the rings are a hundred megabytes, and a frame drawing that often wants instancing.',
+    );
+  }
   positiveInteger('directionalShadowMapSize', quality.directionalShadowMapSize);
   positiveInteger('pointShadowFaceSize', quality.pointShadowFaceSize);
   positiveInteger('shadowFilterTaps', quality.shadowFilterTaps);

package/src/render/rendererHarness.ts

@@ -160,7 +160,14 @@ export function recordingGl(
          and a small answer is read as a device that cannot do the thing. */
       return 4096;
     },
-    getExtension: (name: unknown) => (extensions.has(String(name)) ? {} : null),
+    getExtension: (name: unknown) => {
+      if (!extensions.has(String(name))) return null;
+      /* Clip control is called as well as asked for, so its object has to carry the call. */
+      if (name === 'EXT_clip_control') {
+        return { LOWER_LEFT_EXT: 0x8ca1, ZERO_TO_ONE_EXT: 0x935f, clipControlEXT: () => undefined };
+      }
+      return {};
+    },
     getShaderParameter: () => true,
     /*
      * A shader remembers its own source, and a program remembers its fragment one, so a link can

package/src/world/freeze.ts

@@ -24,7 +24,7 @@
  * What freezing needs of a world.
  *
  * Taken as a parameter rather than imported, on `AGENTS.md`'s rule: core has no entity store and a
- * consumer may be holding one of several. Six methods, all of which any store can answer.
+ * consumer may be holding one of several. Five methods, all of which any store can answer.
  */
 export interface FreezableWorld {
   /** Every entity whose home is this cell, live or not. */