@driftengine/core 4.8.1 → 4.8.2

package/dist/render/particlePool.js

@@ -38,6 +38,15 @@ export class ParticlePool {
      * together.
      */
     seedOf;
+    /**
+     * Where each slot's particle sits in the drawn streams, or -1 where it sits nowhere.
+     *
+     * **What lets `emit` draw a particle the frame it is born.** The streams are compacted, so a
+     * slot's entry is wherever `update` last put it; an emit into a slot that has one overwrites
+     * that entry, and an emit into one that has none appends. Without it a new particle waited for
+     * the next `update` to be drawn at all.
+     */
+    drawnAt;
     next = 0;
     constructor(options) {
         this.options = options;
@@ -60,6 +69,7 @@ export class ParticlePool {
         this.spin = new Float32Array(capacity);
         this.scale = new Float32Array(capacity).fill(1);
         this.seedOf = new Float32Array(capacity);
+        this.drawnAt = new Int32Array(capacity).fill(-1);
     }
     /** How many particles are alive. */
     get live() {
@@ -95,6 +105,18 @@ export class ParticlePool {
         this.spin[i] = (hash - Math.floor(hash)) * Math.PI * 2;
         this.scale[i] = sizeScale;
         this.seedOf[i] = seed;
+        /*
+         * Drawn now, at birth, rather than at the next `update`: into the entry this slot already
+         * has when it is taking over a particle that was drawn, and onto the end otherwise.
+         */
+        const held = this.drawnAt[i];
+        const at = held >= 0 ? held : this.particles.count;
+        this.writeDrawn(i, at, 0, x, y, z, vx, vy, vz);
+        if (held < 0) {
+            this.drawnAt[i] = at;
+            this.instances.count = at + 1;
+            this.particles.count = at + 1;
+        }
     }
     /**
      * Advance every particle and rebuild the instance buffer.
@@ -108,12 +130,15 @@ export class ParticlePool {
         let count = 0;
         for (let i = 0; i < this.age.length; i++) {
             const age = this.age[i];
-            if (age === Infinity)
+            if (age === Infinity) {
+                this.drawnAt[i] = -1;
                 continue;
+            }
             const life = this.life[i];
             const next = age + dt;
             if (next >= life) {
                 this.age[i] = Infinity;
+                this.drawnAt[i] = -1;
                 continue;
             }
             this.age[i] = next;
@@ -131,50 +156,60 @@ export class ParticlePool {
             this.x[i] = px;
             this.y[i] = py;
             this.z[i] = pz;
-            const t = next / life;
-            const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * this.scale[i];
-            const r = o.colorStart[0] + (o.colorEnd[0] - o.colorStart[0]) * t;
-            const g = o.colorStart[1] + (o.colorEnd[1] - o.colorStart[1]) * t;
-            const b = o.colorStart[2] + (o.colorEnd[2] - o.colorStart[2]) * t;
-            /*
-             * Colour carries the fade rather than an alpha channel: the instanced
-             * path multiplies a tint into the base mesh and has no per-instance
-             * opacity, and for an additive puff darkening to nothing *is* fading out.
-             * It also means the effect needs no blend-state change.
-             */
-            const fade = 1 - t * t;
-            writeInstance(this.instances, count, px, py, pz, size, this.spin[i], r * fade, g * fade, b * fade, 0, 0, 0);
-            /*
-             * The same particle for a material that has a real opacity channel. Colour
-             * is written *unfaded* here, because dimming it is the scatter path's
-             * workaround and doing both would fade twice — a puff that vanished at half
-             * its life while still occluding what was behind it.
-             */
-            const p = this.particles;
-            const alphaStart = o.alphaStart ?? 1;
-            const alphaEnd = o.alphaEnd ?? 0;
-            p.positions[count * 3] = px;
-            p.positions[count * 3 + 1] = py;
-            p.positions[count * 3 + 2] = pz;
-            p.sizes[count] = size;
-            p.spins[count] = this.spin[i];
-            p.colors[count * 3] = r;
-            p.colors[count * 3 + 1] = g;
-            p.colors[count * 3 + 2] = b;
-            p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
-            p.ages[count] = t;
-            p.seeds[count] = this.seedOf[i];
-            p.velocities[count * 3] = vx;
-            p.velocities[count * 3 + 1] = vy;
-            p.velocities[count * 3 + 2] = vz;
+            this.drawnAt[i] = count;
+            this.writeDrawn(i, count, next / life, px, py, pz, vx, vy, vz);
             count++;
         }
         this.instances.count = count;
         this.particles.count = count;
     }
+    /**
+     * One particle's entry in both drawn streams, at `t` of its life: what `update` writes for every
+     * live particle and `emit` for a new one, so the two cannot disagree about what a particle looks
+     * like.
+     */
+    writeDrawn(i, count, t, px, py, pz, vx, vy, vz) {
+        const o = this.options;
+        const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * this.scale[i];
+        const r = o.colorStart[0] + (o.colorEnd[0] - o.colorStart[0]) * t;
+        const g = o.colorStart[1] + (o.colorEnd[1] - o.colorStart[1]) * t;
+        const b = o.colorStart[2] + (o.colorEnd[2] - o.colorStart[2]) * t;
+        /*
+         * Colour carries the fade rather than an alpha channel: the instanced
+         * path multiplies a tint into the base mesh and has no per-instance
+         * opacity, and for an additive puff darkening to nothing *is* fading out.
+         * It also means the effect needs no blend-state change.
+         */
+        const fade = 1 - t * t;
+        writeInstance(this.instances, count, px, py, pz, size, this.spin[i], r * fade, g * fade, b * fade, 0, 0, 0);
+        /*
+         * The same particle for a material that has a real opacity channel. Colour
+         * is written *unfaded* here, because dimming it is the scatter path's
+         * workaround and doing both would fade twice — a puff that vanished at half
+         * its life while still occluding what was behind it.
+         */
+        const p = this.particles;
+        const alphaStart = o.alphaStart ?? 1;
+        const alphaEnd = o.alphaEnd ?? 0;
+        p.positions[count * 3] = px;
+        p.positions[count * 3 + 1] = py;
+        p.positions[count * 3 + 2] = pz;
+        p.sizes[count] = size;
+        p.spins[count] = this.spin[i];
+        p.colors[count * 3] = r;
+        p.colors[count * 3 + 1] = g;
+        p.colors[count * 3 + 2] = b;
+        p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
+        p.ages[count] = t;
+        p.seeds[count] = this.seedOf[i];
+        p.velocities[count * 3] = vx;
+        p.velocities[count * 3 + 1] = vy;
+        p.velocities[count * 3 + 2] = vz;
+    }
     /** Drop everything, for a respawn or a scene change. */
     clear() {
         this.age.fill(Infinity);
+        this.drawnAt.fill(-1);
         this.instances.count = 0;
         this.particles.count = 0;
         this.next = 0;

package/dist/render/pass.d.ts

@@ -122,6 +122,18 @@ export type PassContext = {
     readonly pass: GPURenderPassEncoder;
     /** The frame's jitter, the same array `PrepareContext.jitter` held. */
     readonly jitter: Float32Array;
+    /**
+     * The colour format, depth format and sample count of the pass this draw lands in, which a
+     * pipeline set on it must match exactly.
+     *
+     * **Not always the device's.** `PassDevice` says what the frame is; a pass drawn after
+     * `endFrame` lands on the canvas, at the canvas's format and one sample, where the frame is
+     * the scene target at the scene's samples. A pass that is drawn in both places keeps a
+     * pipeline for each and chooses here; one built only from the device is refused by the other.
+     */
+    readonly format: GPUTextureFormat;
+    readonly depthFormat: GPUTextureFormat;
+    readonly samples: number;
 });
 /**
  * What a pass is handed once a frame, before the frame's own target exists.

package/dist/render/renderQuality.d.ts

@@ -185,12 +185,13 @@ export interface RenderQuality {
      * existed: a pane casts nothing at all.
      *
      * Nothing is allocated until a glass caster first reaches a shadow, so a scene with no glass pays
-     * no memory and no pass whatever this says. **The lit shader is the exception**: `'full'` and
-     * `'half'` compile the glass lookup into it, and a lookup that finds no glass and returns at its
-     * first line still costs the lit pass its registers — measured on the courtyard at night, 0.27 ms
-     * at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K. `'off'` compiles none of it, so a world
-     * that never casts through glass is that much faster for saying so. What would make `'full'` wrong
-     * is a phone budget with a lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
+     * no memory and no pass whatever this says. **Nor any shader, since 4.8.2**: the lit shader is
+     * built without the glass lookup and rebuilt with it when the first glass caster reaches a shadow.
+     * A lookup that finds no glass still cost the lit pass its registers — measured on the courtyard at
+     * night, 0.27 ms at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K — and from 4.5.0 to 4.8.1
+     * every scene paid it, glass or none: about 30% of the lit shader's instructions, which on a phone
+     * was the lit pass. `'off'` never rebuilds. What would make `'full'` wrong is a phone budget with a
+     * lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
      */
     readonly glassShadows: GlassShadows;
     /** Horizontal world-space reach over which a directional shadow dissolves. */

package/dist/render/shaders/flat/glassTint.d.ts

@@ -4,3 +4,31 @@
  * outside every conditional, so each lookup can call it whichever shadows a permutation compiles.
  */
 export declare function glassTintGlsl(glassShadows: boolean): string;
+/**
+ * The lit stage's switches, by the name of the constant each is: the decision both backends make
+ * about which optional code a lit program carries. See `litSwitchesGlsl`.
+ */
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT';
+/** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
+export declare function noLitSwitches(): Record<LitSwitch, boolean>;
+/** Which of the lit stage's optional features a build reads. See `litSwitchesGlsl`. */
+export interface LitSwitches {
+    readonly clusteredLights: boolean;
+    readonly lightFixtures: boolean;
+    readonly surfaceEffects: boolean;
+    readonly driftLight: boolean;
+}
+/**
+ * The lit stage's other switches, declared after `GLASS_SHADOWS` so that one keeps the id 0 the
+ * pipelines and their tests already name, each a pipeline-overridable constant on the generated
+ * WGSL and a written-in value on WebGL2 — the arrangement `GLASS_SHADOWS` has, for its reason:
+ * code a branch never runs still costs a shader its registers, and the device compiles it away
+ * only where the switch is a constant.
+ *
+ * **Clustering is the profile's and fixed.** The other three are content, off until a consumer
+ * first uses them — a measured profile or a cookie, a material with an effects table, a DriftLight
+ * volume — and then on for good; see `PipelineCache.enable` and the WebGL2 renderer's rebuild.
+ * Measured on RADV against the lit shader with glass already out: 6,852 instructions and 120
+ * registers, 4,641 and 96 with all four out.
+ */
+export declare function litSwitchesGlsl(switches: LitSwitches): string;

package/dist/render/shaders/flat/glassTint.js

@@ -23,3 +23,34 @@ vec4 glassUnmix(vec4 mip, float centreClarity) {
 }
 `;
 }
+/** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
+export function noLitSwitches() {
+    return {
+        GLASS_SHADOWS: false,
+        CLUSTERED_LIGHTS: false,
+        LIGHT_FIXTURES: false,
+        SURFACE_EFFECTS: false,
+        DRIFT_LIGHT: false,
+    };
+}
+/**
+ * The lit stage's other switches, declared after `GLASS_SHADOWS` so that one keeps the id 0 the
+ * pipelines and their tests already name, each a pipeline-overridable constant on the generated
+ * WGSL and a written-in value on WebGL2 — the arrangement `GLASS_SHADOWS` has, for its reason:
+ * code a branch never runs still costs a shader its registers, and the device compiles it away
+ * only where the switch is a constant.
+ *
+ * **Clustering is the profile's and fixed.** The other three are content, off until a consumer
+ * first uses them — a measured profile or a cookie, a material with an effects table, a DriftLight
+ * volume — and then on for good; see `PipelineCache.enable` and the WebGL2 renderer's rebuild.
+ * Measured on RADV against the lit shader with glass already out: 6,852 instructions and 120
+ * registers, 4,641 and 96 with all four out.
+ */
+export function litSwitchesGlsl(switches) {
+    return /* glsl */ `
+const bool CLUSTERED_LIGHTS = ${switches.clusteredLights ? 'true' : 'false'};  // wgsl:override
+const bool LIGHT_FIXTURES = ${switches.lightFixtures ? 'true' : 'false'};  // wgsl:override
+const bool SURFACE_EFFECTS = ${switches.surfaceEffects ? 'true' : 'false'};  // wgsl:override
+const bool DRIFT_LIGHT = ${switches.driftLight ? 'true' : 'false'};  // wgsl:override
+`;
+}

package/dist/render/shaders/flat/index.d.ts

@@ -92,6 +92,18 @@ export interface FlatShaderOptions {
      * courtyard at night, measured, and nothing once compiled out.
      */
     readonly glassShadows?: boolean;
+    /**
+     * Whether this build has the clustered arm of the light loop: `clusteredLights`, fixed per
+     * renderer. True when absent, which is what the generated WGSL is built with. See
+     * `litSwitchesGlsl`.
+     */
+    readonly clusteredLights?: boolean;
+    /** Whether it reads measured profiles and cookies. True when absent. See `litSwitchesGlsl`. */
+    readonly lightFixtures?: boolean;
+    /** Whether it reads a material's effects table. True when absent. See `litSwitchesGlsl`. */
+    readonly surfaceEffects?: boolean;
+    /** Whether it reads a DriftLight volume. True when absent. See `litSwitchesGlsl`. */
+    readonly driftLight?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

package/dist/render/shaders/flat/index.js

@@ -7,7 +7,7 @@ import { preambleGlsl } from './preamble.js';
 import { LOBES_GLSL } from './lobes.js';
 import { POINTSHADOW_GLSL } from './pointShadow.js';
 import { DIRECTIONALSHADOW_GLSL } from './directionalShadow.js';
-import { glassTintGlsl } from './glassTint.js';
+import { glassTintGlsl, litSwitchesGlsl } from './glassTint.js';
 import { MORPH_GLSL } from '../morph.js';
 import { SKINNING_GLSL } from '../skinning.js';
 import { SURFACE_GLSL } from './surface.js';
@@ -359,6 +359,12 @@ export function flatFrag(options) {
         /* Depth zero as well: both glass lookups, sun and lamps, call it, and every permutation
            declares its switch, which the pipelines set whether the permutation reads it or not. */
         glassTintGlsl(options.glassShadows ?? true),
+        litSwitchesGlsl({
+            clusteredLights: options.clusteredLights ?? true,
+            lightFixtures: options.lightFixtures ?? true,
+            surfaceEffects: options.surfaceEffects ?? true,
+            driftLight: options.driftLight ?? true,
+        }),
         LOBES_GLSL,
         POINTSHADOW_GLSL,
         DIRECTIONALSHADOW_GLSL,