@driftengine/core 3.61.0

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

@@ -0,0 +1,387 @@
+import { resolveConditionals } from '../conditionals.js';
+import { OCTAHEDRAL_GLSL } from '../octahedral.js';
+import { PROBEGRID_GLSL } from './probeGrid.js';
+import { TANGENT_FRAME_GLSL } from '../tangentFrame.js';
+import { preambleGlsl } from './preamble.js';
+import { LOBES_GLSL } from './lobes.js';
+import { POINTSHADOW_GLSL } from './pointShadow.js';
+import { DIRECTIONALSHADOW_GLSL } from './directionalShadow.js';
+import { MORPH_GLSL } from '../morph.js';
+import { SKINNING_GLSL } from '../skinning.js';
+import { SURFACE_GLSL } from './surface.js';
+import { MAIN_GLSL } from './main.js';
+import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.js';
+import { FULL_LIGHT_BUDGET } from '../../uniformVectorBudget.js';
+/**
+ * Flat-shaded vertex colours with one dominant directional source, ambient,
+ * point lights, emissive geometry, directional + omnidirectional shadows and
+ * the shared atmospheric medium. Colour comes from vertex data and shader
+ * maths; no image assets are involved.
+ */
+const FLAT_VERT_SOURCE = `#version 300 es
+layout(location = 0) in vec3 aPosition;
+layout(location = 1) in vec3 aNormal;
+layout(location = 2) in vec3 aColor;
+layout(location = 3) in float aEmissive;
+layout(location = 4) in float aSpecular;
+layout(location = 5) in vec2 aUv;
+layout(location = 6) in vec3 aEmissiveColor;
+layout(location = 7) in float aRoughness;
+layout(location = 8) in float aGrain;
+layout(location = 9) in float aRelief;
+/**
+ * Which way is along the texture, four floats a vertex.
+ *
+ * xyz is the tangent and w is the bitangent sign, which is what a mirrored UV island needs: an
+ * artist mapping the left and right of a model onto one patch gives one side a flipped frame, and
+ * a bitangent computed without the sign lights that side inside out. See geometry/tangents.ts.
+ *
+ * Location 10 because that is where both backends already upload it — buffers.ts lists it and
+ * mesh.ts attaches it — and nothing consumed it until now.
+ */
+layout(location = 10) in vec4 aTangent;
+#if SKINNED
+${SKINNING_GLSL}
+#endif
+
+uniform mat4 uViewProj;
+/** 1 when the mesh carries a tangent frame. See vHasTangents. */
+uniform int uHasTangents;
+uniform mat4 uLightViewProj;
+/**
+ * How often the surface texture repeats across this mesh's UV range, per axis.
+ *
+ * Per-draw rather than baked into vertex data, so geometry built once in metres can be
+ * textured at whatever density a material wants without rebuilding it — and so the same
+ * wall mesh can carry a fine tile in one biome and a coarse one in another. Ignored
+ * when no texture is bound.
+ */
+uniform vec2 uUvScale;
+
+/*
+ * **Placement and tint are declared last of the shared uniforms, and the position is the
+ * requirement** — the same requirement, and for the same reason, that morph's uniforms are
+ * declared after everything below.
+ *
+ * A uniform block is packed in declaration order and the renderer writes it by offset. The
+ * instanced variant does not declare these two at all, so anything declared *after* them moves
+ * when they go: with uModel second, the instanced block put uHasTangents at 64 where the plain
+ * one has it at 128, and a renderer writing by the plain table would have written the tangent
+ * flag into the model matrix. Measured, not feared — that is what the generated bindings said
+ * before this block moved down here.
+ *
+ * Declared last, every field the two variants share keeps the offset it had, and the instanced
+ * block is simply shorter.
+ */
+#if INSTANCED
+/**
+ * One instance's placement, four vec4 columns because GLSL ES 3.00 has no mat4 attribute, and
+ * its tint.
+ *
+ * Locations 11 to 15, which is exactly the five left once the base mesh has spent eleven of
+ * WebGL2's guaranteed sixteen.
+ *
+ * What it gives up is skinning: 11 and 12 are the joint indices and weights, so a draw cannot be
+ * both, and flatVert refuses the pair rather than silently dropping one of them. Morphing goes
+ * with it, for a different reason — a morph weight is per draw, so thirty instances would wear
+ * one expression between them, which is a wrong picture rather than a refused one.
+ *
+ * What would make it wrong is a twelfth base attribute. The escape hatch is to carry the tint in
+ * the w lanes of these four columns, which an affine matrix leaves unused, at the cost of
+ * narrowing this to affine transforms and making a projective one silently wrong.
+ */
+layout(location = 11) in vec4 aInstanceModel0;
+layout(location = 12) in vec4 aInstanceModel1;
+layout(location = 13) in vec4 aInstanceModel2;
+layout(location = 14) in vec4 aInstanceModel3;
+layout(location = 15) in vec3 aInstanceTint;
+#else
+uniform mat4 uModel;
+/**
+ * Per-draw colour multiplier. White is the identity and the default, so nothing that
+ * does not ask for one changes by a floating-point bit.
+ *
+ * Exists because colour in this engine is *vertex data* — that is what makes the whole
+ * world a single flat-shaded draw call — and vertex data cannot answer a question about
+ * the current frame. A caller that wants a mesh to take on a colour it learns at runtime
+ * had only one option before this: rebuild the geometry, which for anything per-frame is
+ * absurd. One uniform gives that whole class of effect a home without touching the
+ * payload rule: still no textures, still colour from vertices, just scaled.
+ */
+uniform vec3 uTint;
+
+/*
+ * **The per-vertex channel lives in this branch and not above it.** Location 13 is
+ * aInstanceModel2 in the instanced variant and one location cannot hold both, so an instanced
+ * draw compiles no channel at all -- and InstancedMesh refuses a mesh that carries one, so the
+ * absence is a loud error at construction rather than leaves that quietly never move.
+ *
+ * Declared after uModel and uTint and before the morph block, which is what keeps every variant
+ * agreeing about where the shared uniforms sit: the instanced variant drops these five along with
+ * the two above it, and a dropped field moves nothing. flatPass.ts asserts exactly that.
+ */
+${CHANNEL_ATTRIBUTE}
+${CHANNEL_BEND}
+#endif
+
+/*
+ * **After every uniform above it, and the position is the requirement.** A uniform block is packed
+ * in declaration order, so morph's four uniforms declared *before* uViewProj move the offset of
+ * every field the renderer already writes — and the renderer writes them by offset. That does not
+ * fail: it puts the model matrix where the view projection should be and draws a scrambled frame.
+ * Declared last, every shared field keeps the offset it had and all four vertex variants agree
+ * about the block they share.
+ */
+#if MORPHED
+${MORPH_GLSL}
+#endif
+
+out vec3 vNormal;
+out vec3 vColor;
+out vec3 vWorldPos;
+out float vEmissive;
+out float vSpecular;
+out vec4 vLightPos;
+out vec2 vUv;
+out vec3 vEmissiveColor;
+out float vRoughness;
+out float vGrain;
+out float vRelief;
+out vec4 vTangent;
+/**
+ * How much of the directional term this vertex receives, and how opaque it is.
+ *
+ * Declared in every variant, including the instanced one that carries no channel: that variant
+ * writes the neutral 1.0 for both, so the fragment stage reads one shape whatever drew it and
+ * needs no permutation of its own.
+ *
+ * vSkyDirect scales the directional term and never the albedo, which is the whole reason it is a
+ * lane rather than something folded into vColor. A sky factor in the vertex colour multiplies
+ * ambient and sun together, so an enclosed face is darkened twice -- once for having no sky, once
+ * for the ambient it should still have received. See MeshData.channel.
+ */
+out float vSkyDirect;
+out float vAlpha;
+/*
+ * How much medium a refracting surface has behind this vertex, as a multiplier on the thickness
+ * the draw states. The channel's .w lane, which 3.42.0 declared reserved and unread.
+ *
+ * It costs a varying and no attribute, where a fifteenth attribute would have spent one of the
+ * two vertex locations left. Absent means 1.0, so a mesh with no channel refracts at exactly the
+ * thickness its draw asked for.
+ */
+out float vThickness;
+/**
+ * Whether aTangent is a real frame or the absent-attribute constant.
+ *
+ * vertexDefaults.ts hands a mesh without tangents (1, 0, 0, 1) — a usable frame rather than a
+ * sentinel, because a zero tangent normalises to a NaN and a NaN in a fragment takes the pixel
+ * with it. So the attribute cannot report its own absence and the renderer has to.
+ *
+ * flat, because there is nothing to interpolate: it is one value for the whole draw.
+ */
+flat out int vHasTangents;
+
+void main() {
+  /*
+   * **Morph before skin, and the order is the definition.** A morph target deforms the *bind pose*
+   * — an expression on a face the skeleton has not moved yet — and the skeleton then carries that
+   * shape wherever the joint goes. Skinning first would deform the posed vertex, so an expression
+   * would drift as a limb moved.
+   */
+#if MORPHED
+  vec3 basePosition = aPosition + morphOffset();
+#else
+  vec3 basePosition = aPosition;
+#endif
+#if SKINNED
+  /*
+   * The skin matrix is applied in model space, before uModel, because a palette entry already
+   * carries the joint's inverse bind — it takes a vertex from the model's bind pose to where the
+   * joint has moved it, and uModel then places the whole character.
+   *
+   * The normal takes the same upper 3x3. **Uniform joint scale is assumed**: a non-uniformly
+   * scaled joint wants the inverse transpose, and this is not it, so such a joint lights slightly
+   * wrong rather than being wrong in shape. What would make it right is a second palette of
+   * inverse transposes, which doubles the texture — not worth it until a rig that squashes asks.
+   */
+  mat4 skin = skinMatrix();
+  vec4 local = skin * vec4(basePosition, 1.0);
+  vec3 localNormal = mat3(skin) * aNormal;
+#else
+  vec4 local = vec4(basePosition, 1.0);
+  vec3 localNormal = aNormal;
+#endif
+#if INSTANCED
+  mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
+  vec3 tint = aInstanceTint;
+#else
+  mat4 model = uModel;
+  vec3 tint = uTint;
+#endif
+  vec4 world = model * local;
+  /*
+   * **The bend lands here, before vWorldPos, vLightPos and gl_Position read it.** All three have
+   * to see the same displaced vertex: a fragment shaded at one position and shadow-tested at
+   * another self-shadows as the gust changes, which is a defect that only appears in motion.
+   */
+#if INSTANCED
+  vec3 bent = world.xyz;
+#else
+  vec3 bent = channelBend(world.xyz, aChannel.x);
+#endif
+  world = vec4(bent, world.w);
+  vWorldPos = world.xyz;
+  // Rotation/translation-only models (our case): mat3 is a valid normal matrix.
+  vec3 worldNormal = mat3(model) * localNormal;
+  vNormal = worldNormal;
+  vLightPos = uLightViewProj * world;
+  vColor = aColor * tint;
+  vEmissive = aEmissive;
+  vSpecular = aSpecular;
+  vUv = aUv * uUvScale;
+  vEmissiveColor = aEmissiveColor;
+  vRoughness = aRoughness;
+  vGrain = aGrain;
+  vRelief = aRelief;
+  vTangent = aTangent;
+#if INSTANCED
+  /* No channel on this path; the neutral values are what every mesh read before it existed. */
+  vSkyDirect = 1.0;
+  vAlpha = 1.0;
+  vThickness = 1.0;
+#else
+  vSkyDirect = aChannel.y;
+  vAlpha = aChannel.z;
+  vThickness = aChannel.w;
+#endif
+  vHasTangents = uHasTangents;
+  gl_Position = uViewProj * world;
+}
+`;
+/**
+ * The flat vertex shader, built for one variant.
+ *
+ * `resolveConditionals` cuts the skinning prelude and both attribute declarations out entirely
+ * when `skinned` is false, so an unskinned pipeline declares locations 11 and 12 nowhere and a
+ * driver is never handed a palette sampler it cannot reach.
+ */
+export function flatVert(options) {
+    if (options.skinned && options.instanced) {
+        throw new Error('flatVert: a variant cannot be both skinned and instanced — the joint attributes and the ' +
+            'instance matrix want locations 11 and 12, and WebGL2 guarantees only sixteen in all.');
+    }
+    if (options.morphed && options.instanced) {
+        throw new Error('flatVert: a variant cannot be both morphed and instanced — a morph weight is per draw, ' +
+            'so every instance of the batch would wear one expression between them.');
+    }
+    return resolveConditionals(FLAT_VERT_SOURCE, { SKINNED: options.skinned, MORPHED: options.morphed, INSTANCED: options.instanced }, 'flatVert');
+}
+/**
+ * The flat fragment shader, built for one quality profile.
+ *
+ * A permutation rather than a constant, because a profile with shadows off was still
+ * compiling every line of shadow code it could never reach: ten `samplerCube` uniforms, a
+ * ten-way branch chain over them, a 190-line cubemap filter and two PCF loops. GLSL has no
+ * way to prove at compile time that `uPointShadowIndex[k]` is always -1, so none of it is
+ * eliminated — it becomes register pressure and sampler state paid by every fragment of
+ * every frame, in a shader whose author had already switched the feature off.
+ *
+ * That is ordinary waste on most parts and not ordinary on all of them. On a Radeon RX
+ * 9070 XT (RDNA4, Mesa 25.2.8) a dense interior world drawn with the full shader faults the
+ * GPU within seconds — an `SQC (data)` page fault, then a `gfx_0.0.0` ring timeout and a
+ * driver reset that takes the WebGL context with it. The fault scales with fragment count:
+ * a quarter of the pixels bought four times the survival time, and the same scene under
+ * the renderer this replaced never faults at all. A driver should not fault whatever it is
+ * handed, so that half is a driver bug worth reporting — but a shader carrying five times
+ * the work it needs is ours, and this is the half we own.
+ *
+ * `#if` rather than stripping by hand, so the enabled path stays one readable shader and
+ * the disabled one is genuinely absent rather than merely unreachable.
+ */
+/**
+ * The fragment shader, assembled from its sections.
+ *
+ * The sections concatenate in exactly the order they occupied when this was one file, and
+ * `flatSource.test.ts` is what holds that: sixteen permutations pinned by hash and one in
+ * full. A reordering here changes the picture, and the snapshot is what says it has not.
+ */
+export function flatFrag(options) {
+    /*
+     * `??` per field rather than a spread over the defaults, because a spread copies a key whose
+     * value is an explicit `undefined` and destroys the default under it — which is what 3.60.2 was.
+     */
+    const budget = {
+        maxLights: options.maxLights ?? FULL_LIGHT_BUDGET.maxLights,
+        maxAreaLights: options.maxAreaLights ?? FULL_LIGHT_BUDGET.maxAreaLights,
+    };
+    /*
+     * Refused rather than clamped, at the only moment anybody can act on it. A budget of zero
+     * declares `uniform vec3 uLightPos[0]`, which does not compile, and a fractional one interpolates
+     * `[7.5]` into the source — both arrive as a shader compile error naming a line nobody wrote.
+     */
+    for (const [name, value] of [
+        ['maxLights', budget.maxLights],
+        ['maxAreaLights', budget.maxAreaLights],
+    ]) {
+        if (!Number.isInteger(value) || value < 1) {
+            throw new Error(`flatFrag: ${name} must be a whole number of at least 1, not ${String(value)} — it is an ` +
+                `array size interpolated straight into the shader.`);
+        }
+    }
+    return resolveConditionals(
+    /*
+     * Joined with a newline, not concatenated bare. Each section holds the lines it owned
+     * and no trailing break, so a bare `+` would run the last line of one section into the
+     * first line of the next — which is a GLSL syntax error at best and a changed shader at
+     * worst. The snapshot caught it on the first run.
+     */
+    [
+        preambleGlsl(budget),
+        /*
+         * **Before `LOBES_GLSL`, and that position is a correction rather than a preference.**
+         *
+         * This used to sit between `LOBES_GLSL` and `POINTSHADOW_GLSL` under a comment saying it was
+         * "outside every `#if`". It was not: `LOBES_GLSL` opens a conditional that
+         * `DIRECTIONALSHADOW_GLSL` closes, so everything between them is inside it, and `octEncode`
+         * was compiled only into the permutations with point shadows. Nothing noticed, because the
+         * only caller was `pointShadow`, which is inside the same arm.
+         *
+         * A probe grid calls `octInsetUv` from an arm that has nothing to do with shadows, so the
+         * claim had to become true. Here it is: the preamble balances its own conditionals, so this
+         * is at depth zero, and it is still declared before `pointShadow` uses it.
+         */
+        OCTAHEDRAL_GLSL,
+        LOBES_GLSL,
+        POINTSHADOW_GLSL,
+        DIRECTIONALSHADOW_GLSL,
+        SURFACE_GLSL,
+        /*
+         * **Here because this is depth zero, which is what the chunk needs and where it was not.**
+         *
+         * Placed after `OCTAHEDRAL_GLSL` it landed inside the conditional `LOBES_GLSL` opens, so
+         * `gridIrradiance` was compiled out of every permutation without point shadows while `main`
+         * still called it — glslang answering "no matching overloaded function found" for a function
+         * whose definition was in the source, which is the same failure the note below records.
+         * Measured by counting `#if` against `#endif` per chunk rather than by reading them.
+         */
+        PROBEGRID_GLSL,
+        /*
+         * **Immediately before `MAIN_GLSL`, and the position is the requirement.**
+         *
+         * These chunks are not a flat list: several of them open an `#if` that a later one closes,
+         * so a chunk placed between two of them lands *inside* a conditional. Put beside
+         * `OCTAHEDRAL_GLSL` this was inside `#if POINT_SHADOWS` and compiled out of all eight
+         * permutations without them — glslang answering "no matching overloaded function found" for
+         * a function whose definition was there in the source. Here it cannot be: `main` follows,
+         * and `main` is unconditional by construction.
+         */
+        TANGENT_FRAME_GLSL,
+        MAIN_GLSL,
+    ].join('\n'), {
+        POINT_SHADOWS: options.pointShadows,
+        ENVIRONMENT_PROBE: options.environmentProbe,
+        NIGHT_EMISSIVE: options.nightEmissive,
+        DIRECTIONAL_SHADOWS: options.directionalShadows,
+    }, 'flat');
+}

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

@@ -0,0 +1 @@
+export declare const LOBES_GLSL: string;