@driftengine/core 4.8.1 → 4.8.3

package/dist/render/sceneCoverage.js

@@ -0,0 +1,72 @@
+/**
+ * What a blended draw into the scene does to its alpha, which holds how much of each pixel is still
+ * the opaque surface — the share ambient occlusion is allowed to darken.
+ *
+ * **Occlusion is applied in the composite, from the depth the opaque world left**, after every
+ * translucent draw has landed, and a particle or a pane writes no depth: so a puff of smoke in front
+ * of a wall was darkened by the corner behind it. Reported from a game as walls and two figures
+ * standing behind a cloud showing through it as outlines, and nothing at all with occlusion off.
+ *
+ * So the scene's alpha is a running share. The frame clears it to 1 and an opaque draw writes 1,
+ * which is the whole of the surface; then each draw blended in front of it says which of three
+ * things it is, and the composite darkens `share` of the pixel and leaves the rest:
+ *
+ * - **It covers**: glass, smoke, water, a line, text in the world, a panel. The share falls by what
+ *   the draw lets through, `share * (1 - a)`.
+ * - **It transmits**: the medium, the order-independent composite. Its alpha already *is* what gets
+ *   through, `share * a`.
+ * - **It keeps**: light added to the surface or a layer of the surface itself — caustics, a light
+ *   volume, a bolt, a wet film, a decal, a reflection. The share is unchanged.
+ *
+ * **What it gives up** is added light in front of an occluded corner: a glow or a spark adds to the
+ * pixel and keeps the share, so the composite darkens what it added along with the surface — which
+ * is how every blended draw behaved before this, and one multiply cannot tell the two apart. **What
+ * would make it wrong** is an opaque pass writing an alpha below 1: its surface would then take less
+ * occlusion than it should, which is the safe direction, and is the lit shader's own case at a
+ * cutout's edge or under a per-vertex alpha lane.
+ *
+ * **It survives the temporal passes.** A temporal resolve passes the frame's alpha through, since
+ * it is a fact about this frame and takes no history; a reconstruction reads it from the scene it
+ * rebuilt into the picture it shows, and the blended draws that land after it cover that picture.
+ *
+ * **One pipeline does not take part**: the GPU-driven pass blends its own surfaces into a target
+ * whose alpha is the mask its blit reads to tell a drawn pixel from an undrawn one, and that blit
+ * writes the share back to 1. Its panes still take the occlusion of what they cover. What would
+ * close it is a channel for that mask other than alpha.
+ *
+ * A contributed pass drawing something blended into the scene states the same thing for its own
+ * pipeline with `SCENE_ALPHA_COVERS`, `SCENE_ALPHA_TRANSMITS` or `SCENE_ALPHA_KEEPS`.
+ */
+/** A blended draw that covers the surface by its alpha: `share * (1 - a)`. */
+export const SCENE_ALPHA_COVERS = {
+    srcFactor: 'zero',
+    dstFactor: 'one-minus-src-alpha',
+    operation: 'add',
+};
+/** A draw whose alpha is what gets through it, a transmittance or a revealage: `share * a`. */
+export const SCENE_ALPHA_TRANSMITS = {
+    srcFactor: 'zero',
+    dstFactor: 'src-alpha',
+    operation: 'add',
+};
+/** Light added to the surface, or a layer of it: the share unchanged. */
+export const SCENE_ALPHA_KEEPS = {
+    srcFactor: 'zero',
+    dstFactor: 'one',
+    operation: 'add',
+};
+/**
+ * The same three on WebGL2, as the alpha half of `blendFuncSeparate` beside the colour half a
+ * caller already had. `src` and `dst` are the colour factors.
+ */
+export function blendCovering(gl, src, dst) {
+    gl.blendFuncSeparate(src, dst, gl.ZERO, gl.ONE_MINUS_SRC_ALPHA);
+}
+/** `SCENE_ALPHA_TRANSMITS` on WebGL2, beside the colour factors `src` and `dst`. */
+export function blendTransmitting(gl, src, dst) {
+    gl.blendFuncSeparate(src, dst, gl.ZERO, gl.SRC_ALPHA);
+}
+/** `SCENE_ALPHA_KEEPS` on WebGL2, beside the colour factors `src` and `dst`. */
+export function blendKeeping(gl, src, dst) {
+    gl.blendFuncSeparate(src, dst, gl.ZERO, gl.ONE);
+}

package/dist/render/sdfTextRenderer.js

@@ -2,6 +2,7 @@ import { SdfTextLayout } from './sdfTextLayout.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { SDF_TEXT_FRAG, SDF_TEXT_VERT } from './shaders/sdfText.js';
 import { SDF_TEXT_TEXTURE_UNIT } from './lightBudget.js';
+import { blendCovering } from './sceneCoverage.js';
 /**
  * Text from a signed distance field, on WebGL2.
  *
@@ -126,7 +127,7 @@ export class SdfTextRenderer {
          */
         gl.depthMask(false);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         this.atlas.bind(gl, SDF_TEXT_TEXTURE_UNIT);
         const u = this.uniforms;
         gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);

package/dist/render/shaders/depth.js

@@ -59,12 +59,13 @@ ${CHANNEL_BEND}
 
 #if CUTOUT
 /*
- * **What a cutout caster adds, and where.** The UV at location 5, where every mesh carries it; two
+ * **What a cutout caster adds, and where.** The UV at location 5, where every mesh carries it; three
  * uniforms declared after every other, so no field of the plain variant moves and a binder written
  * against it stays right for this one; and two outputs after vLightPosition, which keeps location 0.
  */
 layout(location = 5) in vec3 aUv;
 uniform vec2 uUvScale;
+uniform vec2 uUvOffset;
 uniform float uAlphaCutout;
 #endif
 
@@ -103,7 +104,7 @@ void main() {
   vLightPosition = uLightViewProj * vec4(bent, world.w);
   gl_Position = vLightPosition;
 #if CUTOUT
-  vUv = vec3(aUv.xy * uUvScale, aUv.z);
+  vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
   vAlphaCutout = uAlphaCutout;
 #endif
 #if GLASS

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';
@@ -61,6 +61,11 @@ uniform mat4 uLightViewProj;
  * when no texture is bound.
  */
 uniform vec2 uUvScale;
+/**
+ * Where the texture starts, per axis, added after the scale: \`uv * uUvScale + uUvOffset\`. What
+ * picks a cell of a flipbook or an atlas through the material. See \`SurfaceMaterial.uOffset\`.
+ */
+uniform vec2 uUvOffset;
 
 /*
  * **Placement and tint are declared last of the shared uniforms, and the position is the
@@ -243,7 +248,7 @@ void main() {
   vColor = aColor * tint;
   vEmissive = aEmissive;
   vSpecular = aSpecular;
-  vUv = vec3(aUv.xy * uUvScale, aUv.z);
+  vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
   vEmissiveColor = aEmissiveColor;
   vRoughness = aRoughness;
   vGrain = aGrain;
@@ -359,6 +364,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,