lecodes-cli 2.4.9 → 2.5.0

package/runtime/materials/foliage-impostor.mat

@@ -0,0 +1,485 @@
+// foliage-impostor: a FAR TREE as one camera-facing quad, textured from an ATLAS of views of the tree that lecodes-assets
+// bakes at import into the tree's own GLB as its last LOD level (`<root>_LOD<k>`; creator-gl lod.cpp shows it like any
+// other level). The atlas holds only what does not depend on the light; this material lights it at runtime with the
+// crown cards' model (foliage-cards.mat), per pixel instead of per vertex.
+//
+// THE ATLAS (the baker's half of the contract; both halves must agree bit for bit). Two frame LAYOUTS, told apart by
+// `impostorGrid` = (A, E) with E > 0 for the GRID, (N, 0) for the OCTAHEDRON; both cover only the upper hemisphere (+Y)
+// of the GLB's object space — a tree is never seen from below.
+//   • THE GRID (the default, 12 × 3): A azimuths × E elevation rows (A ≥ 3, E ≥ 1). Frame (i, k), i ∈ [0, A), k ∈ [0, E)
+//     looks at the tree from az_i = i·2π/A, el_k = k·(π/2)/E (E = 3 → 0°, 30°, 60°; 90° is never a row, the top row is
+//     reused above it), the direction d = (cos el·sin az, sin el, cos el·cos az) — az = 0 looks from +Z, 90° from +X.
+//     Encode: az = atan(d.x, d.z) wrapped into [0, 2π) (0 when d.x = d.z = 0, the zenith), el = asin(clamp(d.y, 0, 1));
+//     fa = az/2π·A (frame A ≡ frame 0), fe = clamp(el·E/(π/2), 0, E-1). Packed frame index i·E + k.
+//     Atlas A·P × E·P texels (P a frame), frame (i, k) at x ∈ [i·P, (i+1)·P), y ∈ [k·P, (k+1)·P): ROW 0 = elevation 0
+//     at the TOP of the image.
+//   • THE OCTAHEDRON: N×N frames on a HEMI-octahedron. Frame (i, j) looks from the direction decode((i, j) / (N-1)):
+//         decode(uv): u = 2uv.x-1, v = 2uv.y-1, x = (u+v)/2, z = (u-v)/2, y = 1-|x|-|z|, normalised
+//         encode(d):  s = |x|+|y|+|z|, u = (x+z)/s, v = (x-z)/s, back to [0,1]
+//     the zenith is the map's centre, every point of its border the horizon. Packed frame index i·N + j. Atlas N·P
+//     square, frame (i, j) at x ∈ [i·P, (i+1)·P), y ∈ [j·P, (j+1)·P).
+//   • each frame is an orthographic view of the square [-r, r]² around the level-0 bounding sphere's centre c
+//     (`impostor` = (c.xyz, r), object space), with the basis of its direction d (the same for both layouts):
+//         ref = |d.y| < 0.999 ? +Y : -Z, right = normalize(cross(ref, d)), up = cross(d, right)
+//     A point p seen in a frame at a = ½ + ½·dot(p - c, right)/r, b = ½ + ½·dot(p - c, up)/r (a right, b UP) lands at
+//     the atlas uv ((i + a)/A, (k + 1 - b)/E) on the grid, ((i + a)/N, (j + 1 - b)/N) on the octahedron — image row 0
+//     at the top, the glTF convention (flipUV false, getUV0() raw).
+//   • baseColorMap: rgb = albedo (sRGB), a = coverage. metallicRoughnessMap (linear): rg = the crown's HULL normal
+//     (what the cards shade by: from 0.6 of the plant's height over its origin to the surface, foliage-wind.vs f.hull)
+//     in OBJECT space, packed with the FULL-sphere octahedral map ×½+½ (normalDecode below, the baker's normalEncode —
+//     not the frame layout's hemi impEncode/impDecode; its seam pole at the corners is object −Y): a far-side leaf keeps a normal that looks away, which is the
+//     crown's shading; b = the DEPTH along the frame's view axis, z = dot(p - c, d)/r stored z·½+½ (1 = the point
+//     nearest this frame's viewer, ½ = the quad plane, 0 = the farthest); a = the baked sky visibility (vertexAo.ts'
+//     COLOR_0.r). An uncovered texel carries its nearest covered neighbour's data (the dilation): a depth read just
+//     outside a silhouette continues the surface, while the coverage there stays under the cutoff.
+//
+// THE QUAD: 4 vertices whose POSITION is ignored (the baker writes the sphere's box corners there only so gltfio's
+// culling box is right); TEXCOORD_0 is the corner id, corner = uv·2-1 (x right, y up). The vertex shader takes the
+// direction from the sphere's centre to the eye into object space (uniform scale assumed), clamps it to the upper
+// hemisphere, builds that direction's frame basis and spans the quad over [-r, r]² in it — the quad faces the eye from
+// wherever it is looked at. Then the FRAME PICK: the direction falls in a cell of the frame lattice — (fa, fe) on the
+// grid, encode(d)·(N-1) on the octahedron; with (i, k) = its floor and t = its fract, the cell's lower triangle
+// (t.x + t.y < 1) names the frames (i,k) (i+1,k) (i,k+1) with the weights (1-t.x-t.y, t.x, t.y), the upper one
+// (i+1,k+1) (i,k+1) (i+1,k) with (t.x+t.y-1, 1-t.x, 1-t.y), so the picture morphs between neighbouring views instead of
+// popping. On the grid i+1 wraps mod A and k+1 stops at the top row (min(k+1, E-1)); on the octahedron both stop at N-1.
+//
+// THE VARYINGS (Filament caps custom variables at 5; four used):
+//   impFrames = (frame0, frame1, frame2, hash) — a frame packed as i·E + k (grid) / i·N + j (octahedron); hash = the
+//               cards' per-instance tint hash
+//   impPos    = (p.xyz, w0)                     — p = the fragment's offset from c in object space (linear over the quad)
+//   impW      = (w1, alive, 0, 0)               — w2 = 1 - w0 - w1; alive = the distance fade (`fade`, as the cards)
+//   impRot    = the model's rotation as a quaternion (its columns normalised): getWorldFromModelMatrix() exists in the
+//               vertex stage only, and the fragment needs it to take the atlas' object-space normal to the world
+// The frame choice and the weights depend on the CENTRE's direction alone, so they are the same at the four corners:
+// the interpolation hands them over unchanged.
+//
+// THE FRAGMENT: per frame, unpack its index (grid: i = floor(packed/E), k = packed - i·E; octahedron: by N), decode its
+// direction (the grid's d(az_i, el_k) / the octahedron's decode), build its basis, project p onto it (no parallax — see the note at the
+// sample) and read both atlases; blend by the weights. Alpha = Σ w·a (× the distance fade): the glTF cutoff's mask
+// threshold cuts it, alphaToCoverage softens it as on the cards. The normal: normalDecode(data.rg) per frame — already
+// in object space, no basis —, blended, normalised, turned to the world by the quaternion. THE LIGHT is
+// foliage-cards.mat's, per pixel: the ambient = the sky's SH on that normal × the exposure × the baked AO (by leaf.w) as
+// emissive (Filament's IBL off), the sun = a wrapped Lambert (sway.w) + the back-lit translucency (leaf.z) in one scalar
+// (gSun) that surfaceShading() multiplies by the light, its attenuation and its SHADOW (by leaf.y). The per-pixel normal
+// also becomes Filament's shading normal, the one its lights loop tests (dot(n, l) > 0) before it reads the shadow map.
+//
+// THE SELF-SHADOW: a flat quad never shades itself through the shadow map, and at these distances the mesh's own
+// self-shading IS the shadow map (upper branches over the lower ones) — so the impostor shadows itself from its OWN
+// ATLAS: the frames around the sun are its shadow map. The pixel's surface point (offset from c, object space): per view
+// frame k, p's point on that frame's plane (dot(p, right_k)·right_k + dot(p, up_k)·up_k) plus its depth z_k·r·d_k,
+// blended by the weights. The sun in object space (the quaternion's inverse on frameUniforms.lightDirection, which
+// points TOWARD the light) names the sun frames. A sun frame's occluder (impOccl): the point projected onto its basis
+// gives (a_s, b_s) and its depth z_p; the frame's coverage and depth there (2 fetches, the view frames' half-texel
+// inset) give occl = coverage · smoothstep(0, bias, z_o - z_p - bias) with bias = 6/P (P = a frame's texels across:
+// ≈ 3 texels, ≥ 2 depth steps at P = 256), 0 where the point falls outside that frame's square. On the GRID the sun
+// takes the nearest azimuth, i = round(az/2π·A) mod A, and BLENDS the two elevation rows around it: k0 = floor(fe),
+// k1 = min(k0 + 1, E-1), occl = mix(occl(i, k0), occl(i, k1), fract(fe)) — 4 fetches. The nearest row alone was
+// measured against the mesh: a sun between two rows (the Forest's 48.7°) took the 60° row, which throws the top tier's
+// shadow straight down and over-darkens the upper-middle crown; the blend weighs both rows' shadows. The OCTAHEDRON
+// keeps the NEAREST single frame, round(encode(sun)·(N-1)) (its second call names the same frame with a blend of 0,
+// so its fetches stay unconditional). gSun — the whole sun scalar, Lambert and translucency, as the cards' is under the shadow map — is
+// multiplied by 1 - occl. The term is 1 with the sun under the horizon; `impostorSelfShadow` mixes it in (1 = on;
+// glb.cpp writes the 1, CREATOR_IMPOSTOR_SELFSHADOW=0 a 0). The depth variants (the shadow map, the prepass) skip it.
+//
+// The engine treats it as foliage (it declares `benders`) and writes the whole foliage block; the wind is not applied
+// (a far tree's sway is below a pixel). `Material.foliageImpostor` in the SDK; Model.load({ foliage: 'tree' }) arms it
+// with the bark and the cards, and the GLB provider picks it for a material whose extras carry `lecodes.impostor`
+// ([A, cx, cy, cz, r, E] → impostorGrid = (A, E) / impostor; E = 0 or missing = the octahedron, N = the first number).
+
+material {
+    name : foliage_impostor,
+    shadingModel : lit,
+    customSurfaceShading : true,
+    specularAmbientOcclusion : simple,
+    doubleSided : true,
+    culling : none,
+    blending : masked,
+    alphaToCoverage : true,
+    flipUV : false,
+    requires : [ uv0 ],
+    variables : [
+        { name : impFrames, precision : high },
+        { name : impPos, precision : high },
+        { name : impW, precision : high },
+        impRot
+    ],
+    parameters : [
+        { type : float4,    name : baseColorFactor },
+        { type : sampler2d, name : baseColorMap },
+        { type : float,     name : metallicFactor },
+        { type : float,     name : roughnessFactor },
+        { type : float3,    name : emissiveFactor },
+        { type : float,     name : normalScale },
+        { type : float,     name : aoStrength },
+        { type : sampler2d, name : normalMap },
+        { type : float,     name : hasNormalMap },
+        { type : sampler2d, name : metallicRoughnessMap },
+        { type : sampler2d, name : occlusionMap },
+        { type : sampler2d, name : emissiveMap },
+        // ---- foliage (foliage.mat has every comment; the engine writes the block to any material with `benders`) ----
+        { type : float4,    name : wind },
+        { type : float4,    name : sway },
+        { type : float4,    name : fade },
+        { type : float4,    name : leaf },
+        { type : float4,    name : profile },
+        { type : float,     name : shiverDir },
+        { type : float4,    name : look },
+        { type : sampler2d, name : windNoise },
+        { type : float4,    name : plant },
+        { type : float4[8], name : benders },
+        { type : float4[8], name : benderMotion },
+        // ---- the impostor (the GLB material's extras `lecodes.impostor` = [A, cx, cy, cz, r, E]) ----
+        { type : float4,    name : impostor, precision : high },      // (c.xyz, r): the level-0 bounding sphere, object space
+        { type : float2,    name : impostorGrid, precision : high },  // (A, E): A azimuths × E rows; (N, 0): N×N octahedron
+        { type : float,     name : impostorSelfShadow }               // the self-shadow from the atlas: 1 on, 0 off (glb.cpp writes 1)
+    ]
+}
+
+vertex {
+    // the hemi-octahedral map, [0,1]² <-> a unit direction with y ≥ 0 (the baker's TS is the same formula)
+    highp vec3 impDecode(highp vec2 uv) {
+        highp float u = uv.x * 2.0 - 1.0;
+        highp float v = uv.y * 2.0 - 1.0;
+        highp float x = (u + v) * 0.5;
+        highp float z = (u - v) * 0.5;
+        return normalize(vec3(x, 1.0 - abs(x) - abs(z), z));
+    }
+
+    highp vec2 impEncode(highp vec3 d) {
+        highp float s = abs(d.x) + abs(d.y) + abs(d.z);
+        highp float px = d.x / s;
+        highp float pz = d.z / s;
+        return vec2(px + pz, px - pz) * 0.5 + 0.5;
+    }
+
+    // the rotation part of the model matrix (its columns normalised) as a unit quaternion (x, y, z, w); R[c][r] = m_rc
+    vec4 impQuat(mat3 R) {
+        float tr = R[0][0] + R[1][1] + R[2][2];
+        vec4 q;
+        if (tr > 0.0) {
+            float s = sqrt(tr + 1.0) * 2.0;
+            q = vec4(R[1][2] - R[2][1], R[2][0] - R[0][2], R[0][1] - R[1][0], 0.25 * s * s) / s;
+        } else if (R[0][0] > R[1][1] && R[0][0] > R[2][2]) {
+            float s = sqrt(1.0 + R[0][0] - R[1][1] - R[2][2]) * 2.0;
+            q = vec4(0.25 * s * s, R[1][0] + R[0][1], R[2][0] + R[0][2], R[1][2] - R[2][1]) / s;
+        } else if (R[1][1] > R[2][2]) {
+            float s = sqrt(1.0 + R[1][1] - R[0][0] - R[2][2]) * 2.0;
+            q = vec4(R[1][0] + R[0][1], 0.25 * s * s, R[2][1] + R[1][2], R[2][0] - R[0][2]) / s;
+        } else {
+            float s = sqrt(1.0 + R[2][2] - R[0][0] - R[1][1]) * 2.0;
+            q = vec4(R[2][0] + R[0][2], R[2][1] + R[1][2], 0.25 * s * s, R[0][1] - R[1][0]) / s;
+        }
+        return normalize(q);
+    }
+
+    void materialVertex(inout MaterialVertexInputs material) {
+        highp mat4 model = getWorldFromModelMatrix();
+        highp vec4 imp = materialParams.impostor;
+        highp vec2 G = materialParams.impostorGrid;
+        bool isGrid = G.y > 0.0;
+        highp float N = max(floor(G.x + 0.5), 1.0);                      // the grid's A, or the octahedron's N
+        highp float E = isGrid ? max(floor(G.y + 0.5), 1.0) : N;         // the grid's rows (the octahedron: N again)
+        highp float r = imp.w;
+        highp vec3 c = imp.xyz;
+        highp vec2 corner = material.uv0 * 2.0 - 1.0;
+
+        // THE VIEW DIRECTION, from the sphere's centre to the eye, in object space (the transpose undoes the rotation; a
+        // uniform scale only stretches it) and clamped to the upper hemisphere the atlas covers
+        highp vec3 cW = (model * vec4(c, 1.0)).xyz;
+        highp vec3 dW = getWorldCameraPosition() - cW;
+        highp vec3 d = transpose(mat3(model)) * dW;
+        d.y = max(d.y, 0.0);
+        highp float dl = length(d);
+        d = dl > 1e-6 ? d / dl : vec3(0.0, 1.0, 0.0);
+
+        // the quad spans [-r, r]² in that direction's frame basis
+        highp vec3 ref = abs(d.y) < 0.999 ? vec3(0.0, 1.0, 0.0) : vec3(0.0, 0.0, -1.0);
+        highp vec3 right = normalize(cross(ref, d));
+        highp vec3 up = cross(d, right);
+        highp vec3 p = (corner.x * right + corner.y * up) * r;
+        material.worldPosition.xyz = (model * vec4(c + p, 1.0)).xyz;
+#if defined(HAS_ATTRIBUTE_TANGENTS)
+        // the quad's geometric normal faces the eye (the shadow lookup's normal bias reads it; the mesh's NORMAL is a dummy)
+        highp float dwl = length(dW);
+        material.worldNormal = dwl > 1e-6 ? dW / dwl : vec3(0.0, 1.0, 0.0);
+#endif
+
+        // THE FRAME PICK: the cell of the frame lattice the direction falls in, its lower or upper triangle, barycentric
+        // weights. The grid: (fa, fe) = (azimuth / 2π · A, elevation / (π/2) · E clamped to the top row); the octahedron:
+        // encode(d)·(N-1).
+        highp vec2 f;
+        if (isGrid) {
+            highp float az = abs(d.x) + abs(d.z) > 1e-7 ? atan(d.x, d.z) : 0.0;   // the zenith has no azimuth: 0
+            if (az < 0.0) az += 2.0 * PI;
+            highp float el = asin(clamp(d.y, 0.0, 1.0));
+            f = vec2(az / (2.0 * PI) * N, clamp(el * E / (0.5 * PI), 0.0, E - 1.0));
+        } else {
+            f = impEncode(d) * (N - 1.0);
+        }
+        highp vec2 i = floor(f);
+        highp vec2 t = f - i;
+        highp vec2 f0, f1, f2;
+        highp vec3 w;
+        if (t.x + t.y < 1.0) {
+            f0 = i; f1 = i + vec2(1.0, 0.0); f2 = i + vec2(0.0, 1.0);
+            w = vec3(1.0 - t.x - t.y, t.x, t.y);
+        } else {
+            f0 = i + vec2(1.0, 1.0); f1 = i + vec2(0.0, 1.0); f2 = i + vec2(1.0, 0.0);
+            w = vec3(t.x + t.y - 1.0, 1.0 - t.x, 1.0 - t.y);
+        }
+        if (isGrid) {
+            // the azimuth wraps (frame A ≡ frame 0; i itself is A when az rounds up to 2π), the rows stop at the top one
+            f0.x = f0.x >= N ? f0.x - N : f0.x; f1.x = f1.x >= N ? f1.x - N : f1.x; f2.x = f2.x >= N ? f2.x - N : f2.x;
+            highp float top = E - 1.0;
+            f0.y = min(f0.y, top); f1.y = min(f1.y, top); f2.y = min(f2.y, top);
+        } else {
+            highp float last = N - 1.0;
+            f0 = min(f0, vec2(last)); f1 = min(f1, vec2(last)); f2 = min(f2, vec2(last));
+        }
+
+        // the cards' per-instance tint hash, bit for bit (foliage-wind.vs: the USER world origin of the instance)
+        highp vec3 uOrigin = (getUserWorldFromWorldMatrix() * vec4(model[3].xyz, 1.0)).xyz;
+        float hash = fract(sin(dot(uOrigin.xz, vec2(12.9898, 78.233))) * 43758.5453);
+        // the distance fade (foliage-wind.vs `alive`, measured to the sphere's centre)
+        float fadeEnd = materialParams.fade.y;
+        float alive = fadeEnd > 0.0 ? 1.0 - smoothstep(materialParams.fade.x, fadeEnd, length(dW)) : 1.0;
+
+        // packed i·E + k (grid) / i·N + j (octahedron: E = N)
+        material.impFrames = vec4(f0.x * E + f0.y, f1.x * E + f1.y, f2.x * E + f2.y, hash);
+        material.impPos = vec4(p, w.x);
+        material.impW = vec4(w.y, alive, 0.0, 0.0);
+        mat3 R = mat3(normalize(model[0].xyz), normalize(model[1].xyz), normalize(model[2].xyz));
+        material.impRot = impQuat(R);
+    }
+}
+
+fragment {
+    // from material() for surfaceShading(): the sun's scalar at this pixel — the wrapped Lambert + the translucency
+    float gSun = 0.0;
+
+    highp vec3 impDecode(highp vec2 uv) {
+        highp float u = uv.x * 2.0 - 1.0;
+        highp float v = uv.y * 2.0 - 1.0;
+        highp float x = (u + v) * 0.5;
+        highp float z = (u - v) * 0.5;
+        return normalize(vec3(x, 1.0 - abs(x) - abs(z), z));
+    }
+
+    // the hemi-octahedral frame map's encode (the vertex stage's): the octahedron's frame nearest the sun
+    highp vec2 impEncode(highp vec3 d) {
+        highp float s = abs(d.x) + abs(d.y) + abs(d.z);
+        highp float px = d.x / s;
+        highp float pz = d.z / s;
+        return vec2(px + pz, px - pz) * 0.5 + 0.5;
+    }
+
+    // the data map's normal (rg): the FULL-sphere octahedral map, [0,1]² -> a unit object-space vector; the baker's
+    // normalEncode is its inverse. Not impEncode/impDecode — those are the frame layout's hemi map.
+    // THE SEAM POLE IS OBJECT −Y: the baker encodes the swapped vector (n.x, n.z, n.y), so the mapping's "z" (the fold
+    // test, the pole at the four corners) is object y, and the decode swaps y and z back. A view frame never looks from
+    // straight below, so no frame's normals straddle the corners, where bilinear and mips average (1,1) with (-1,1)
+    // into garbage (with the pole at −Z they did: every near-side normal of the az-180° frame). Anchors: (½,½) = +Y,
+    // the corners = −Y, (½,1) = +Z, (½,0) = −Z, (1,½) = +X.
+    highp vec3 normalDecode(highp vec2 e) {
+        highp vec2 p = e * 2.0 - 1.0;
+        highp vec3 n = vec3(p.x, p.y, 1.0 - abs(p.x) - abs(p.y));
+        highp float t = clamp(-n.z, 0.0, 1.0);
+        n.x += n.x >= 0.0 ? -t : t;
+        n.y += n.y >= 0.0 ? -t : t;
+        return normalize(n.xzy);
+    }
+
+    // Frame (i, k) of either layout: its direction d and basis (right, up). `cells` = the atlas' frames across and
+    // down: (A, E) on the grid, (N, N) on the octahedron.
+    void impBasis(highp float fi, highp float fk, bool isGrid, highp vec2 cells,
+                  out highp vec3 dk, out highp vec3 rk, out highp vec3 uk) {
+        if (isGrid) {
+            // the grid's frame (i, k): az = i·2π/A, el = k·(π/2)/E
+            highp float az = fi * (2.0 * PI) / cells.x;
+            highp float el = fk * (0.5 * PI) / cells.y;
+            highp float ce = cos(el);
+            dk = vec3(ce * sin(az), sin(el), ce * cos(az));
+        } else {
+            dk = impDecode(vec2(fi, fk) / max(cells.x - 1.0, 1.0));
+        }
+        highp vec3 ref = abs(dk.y) < 0.999 ? vec3(0.0, 1.0, 0.0) : vec3(0.0, 0.0, -1.0);
+        rk = normalize(cross(ref, dk));
+        uk = cross(dk, rk);
+    }
+
+    // The atlas uv of the frame-local point (a, b) ∈ [-1, 1]² (a right, b up) in frame (i, k), clamped half a texel
+    // inside the frame, so a point the frame's square does not reach (p projected onto ANOTHER view's basis can leave
+    // it) never reads the neighbouring frame.
+    highp vec2 impUv(highp float fi, highp float fk, highp vec2 cells, highp float a, highp float b, highp vec2 inset) {
+        highp float ua = clamp(0.5 + 0.5 * a, inset.x, 1.0 - inset.x);
+        highp float ub = clamp(0.5 + 0.5 * b, inset.y, 1.0 - inset.y);
+        return vec2((fi + ua) / cells.x, (fk + 1.0 - ub) / cells.y);
+    }
+
+    // One frame of the atlas at the object-space offset p: the albedo + coverage, the data texel, and the frame's
+    // direction and basis. The packed index is a whole number (rounded by the caller); the +½ cell bias only guards the
+    // division against a GPU's approximate one.
+    // PARALLAX (the next step, not built): the data map's depth (b) exists now — the self-shadow reads it; offsetting p
+    // along the view by it before the projection would line the three frames up and cut the ghosting between them.
+    void impFrame(highp float packed, bool isGrid, highp vec2 cells, highp float r, highp vec3 p, highp vec2 inset,
+                  out vec4 base, out vec4 data, out highp vec3 dk, out highp vec3 rk, out highp vec3 uk) {
+        highp float fi = floor(packed / cells.y + 0.5 / cells.y);
+        highp float fk = packed - fi * cells.y;
+        impBasis(fi, fk, isGrid, cells, dk, rk, uk);
+        highp vec2 uv = impUv(fi, fk, cells, dot(p, rk) / r, dot(p, uk) / r, inset);
+        base = texture(materialParams_baseColorMap, uv);
+        data = texture(materialParams_metallicRoughnessMap, uv);
+    }
+
+    // the sky's SH irradiance on n (foliage-cards.mat's shIrradianceV; Filament's own is not in every variant's fragment)
+    vec3 impSky(const vec3 n) {
+        return max(
+            frameUniforms.iblSH[0].xyz
+            + frameUniforms.iblSH[1].xyz * n.y + frameUniforms.iblSH[2].xyz * n.z + frameUniforms.iblSH[3].xyz * n.x
+            + frameUniforms.iblSH[4].xyz * (n.y * n.x) + frameUniforms.iblSH[5].xyz * (n.y * n.z)
+            + frameUniforms.iblSH[6].xyz * (3.0 * n.z * n.z - 1.0) + frameUniforms.iblSH[7].xyz * (n.z * n.x)
+            + frameUniforms.iblSH[8].xyz * (n.x * n.x - n.y * n.y), 0.0);
+    }
+
+    // a frame's hull normal, object space (the data map's rg)
+    highp vec3 impNormal(vec4 data) {
+        return normalDecode(data.rg);
+    }
+
+    // a frame's surface point, as an offset from c in object space: p's point on the frame's plane plus the data map's
+    // depth (b) along its direction
+    highp vec3 impSurface(highp vec3 p, vec4 data, highp float r, highp vec3 dk, highp vec3 rk, highp vec3 uk) {
+        return dot(p, rk) * rk + dot(p, uk) * uk + (data.b * 2.0 - 1.0) * r * dk;
+    }
+
+    // The self-shadow's occluder from ONE sun frame (si, sk): the surface point P (offset from c, object space)
+    // projected onto the frame's basis, the frame's coverage and depth there (2 fetches, always taken — no flow control
+    // around them, so the derivatives stay defined), occl = coverage · smoothstep(0, bias, z_o - z_p - bias),
+    // bias = 6 / P (P = a frame's texels across; inset = ½ / P). 0 where P falls outside the frame's square.
+    float impOccl(highp vec3 P, highp float si, highp float sk, bool isGrid, highp vec2 cells, highp float r,
+                  highp vec2 inset) {
+        highp vec3 ds, rs, us;
+        impBasis(si, sk, isGrid, cells, ds, rs, us);
+        highp float sa = dot(P, rs) / r;
+        highp float sb = dot(P, us) / r;
+        highp float zp = dot(P, ds) / r;
+        highp vec2 suv = impUv(si, sk, cells, sa, sb, inset);
+        float cov = texture(materialParams_baseColorMap, suv).a;
+        float zo = texture(materialParams_metallicRoughnessMap, suv).b * 2.0 - 1.0;
+        float bias = 12.0 * inset.x;
+        float occl = cov * smoothstep(0.0, bias, zo - zp - bias);
+        return abs(sa) <= 1.0 && abs(sb) <= 1.0 ? occl : 0.0;
+    }
+
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        highp vec2 G = materialParams.impostorGrid;
+        bool isGrid = G.y > 0.0;
+        highp float N = max(floor(G.x + 0.5), 1.0);                                      // A, or the octahedron's N
+        highp vec2 cells = vec2(N, isGrid ? max(floor(G.y + 0.5), 1.0) : N);             // frames across, down
+        highp float r = max(materialParams.impostor.w, 1e-4);
+        highp vec3 p = variable_impPos.xyz;
+        highp vec3 fr = floor(variable_impFrames.xyz + 0.5);
+        highp vec3 w = vec3(variable_impPos.w, variable_impW.x, 1.0 - variable_impPos.w - variable_impW.x);
+        // half a texel, in frame-local units, per axis (a frame is width/A texels wide and height/E tall)
+        highp vec2 inset = 0.5 * cells / max(vec2(textureSize(materialParams_baseColorMap, 0)), vec2(1.0));
+
+        vec4 b0, b1, b2, t0, t1, t2;
+        highp vec3 d0, d1, d2, r0, r1, r2, u0, u1, u2;
+        impFrame(fr.x, isGrid, cells, r, p, inset, b0, t0, d0, r0, u0);
+        impFrame(fr.y, isGrid, cells, r, p, inset, b1, t1, d1, r1, u1);
+        impFrame(fr.z, isGrid, cells, r, p, inset, b2, t2, d2, r2, u2);
+        vec4 base = (b0 * w.x + b1 * w.y + b2 * w.z) * materialParams.baseColorFactor;
+        // the distance fade thins the tree like the cards (the mask threshold does the cutting)
+        base.a *= variable_impW.y;
+#if defined(VARIANT_DEPTH)
+        // the shadow map / prepass: the cards' rule — a texel near the cutoff casts (no coverage boost here)
+        float cut = getMaskThreshold();
+        if (base.a >= 0.5 * cut) base.a = max(base.a, cut);
+        material.baseColor = base;
+#else
+        vec4 data = t0 * w.x + t1 * w.y + t2 * w.z;
+        highp vec3 nObj = impNormal(t0) * w.x + impNormal(t1) * w.y + impNormal(t2) * w.z;
+        highp float nl = length(nObj);
+        nObj = nl > 1e-5 ? nObj / nl : d0;
+        // object → world by the model's rotation (the quaternion of the vertex stage)
+        highp vec4 q = variable_impRot;
+        highp vec3 n = normalize(nObj + 2.0 * cross(q.xyz, cross(q.xyz, nObj) + q.w * nObj));
+#if defined(HAS_ATTRIBUTE_TANGENTS)
+        shading_normal = n;   // Filament's lights loop reads the shadow map only where dot(shading_normal, l) > 0
+#endif
+
+        // the per-instance tint (foliage-cards.mat)
+        float hash = variable_impFrames.w;
+        vec3 tint = mix(vec3(0.86, 0.94, 0.72), vec3(1.06, 1.02, 1.12), hash);
+        base.rgb *= mix(vec3(1.0), tint, materialParams.sway.z);
+
+        // THE LIGHT, foliage-cards.mat's per-vertex model at the pixel: the sky's SH on the crown's normal darkened by the
+        // baked sky visibility (leaf.w), and the sun's wrapped Lambert + translucency for surfaceShading()
+        float vao = data.a;
+        float ao = mix(1.0, vao, clamp(materialParams.leaf.w, 0.0, 1.0));
+        vec3 ambient = impSky(n) * frameUniforms.iblLuminance * ao;
+        highp vec3 l = frameUniforms.lightDirection;
+        highp vec3 v = getWorldViewVector();
+        float wrap = clamp(materialParams.sway.w, 0.0, 1.0);
+        float NoL = max((dot(n, l) + wrap) / (1.0 + wrap), 0.0);
+        float back = max(-dot(n, l), 0.0);
+        float vl = pow(max(dot(-v, l), 0.0), 4.0);
+        float through = clamp(materialParams.leaf.z, 0.0, 1.0) * back * (0.5 + 0.5 * vl) * mix(1.0, vao, 0.5);
+        gSun = NoL + through;
+
+        // THE SELF-SHADOW from the atlas: the frames around the sun are the tree's own shadow map (the header). The
+        // pixel's surface point (offset from c, object space), the three view frames' points blended by their weights:
+        highp vec3 P = impSurface(p, t0, r, d0, r0, u0) * w.x + impSurface(p, t1, r, d1, r1, u1) * w.y
+                     + impSurface(p, t2, r, d2, r2, u2) * w.z;
+        // the sun in object space: the inverse of the model's rotation (the conjugate quaternion) on the world direction
+        // toward the light — transpose(mat3(model))·l, normalised
+        highp vec3 qi = -q.xyz;
+        highp vec3 lo = normalize(l + 2.0 * cross(qi, cross(qi, l) + q.w * l));
+        // the sun frames: the grid takes the nearest azimuth and the TWO elevation rows around the sun, blended by the
+        // elevation's fraction (the nearest row alone over-darkens the crown when the sun falls between rows); the
+        // octahedron keeps the NEAREST single frame (its second frame is the same one, blended by 0)
+        highp float si, sk0, sk1;
+        float st;
+        if (isGrid) {
+            highp float saz = abs(lo.x) + abs(lo.z) > 1e-7 ? atan(lo.x, lo.z) : 0.0;
+            if (saz < 0.0) saz += 2.0 * PI;
+            si = floor(saz / (2.0 * PI) * cells.x + 0.5);
+            si = si >= cells.x ? si - cells.x : si;
+            highp float sel = asin(clamp(lo.y, 0.0, 1.0));
+            highp float fe = clamp(sel * cells.y / (0.5 * PI), 0.0, cells.y - 1.0);
+            sk0 = floor(fe);
+            sk1 = min(sk0 + 1.0, cells.y - 1.0);
+            st = fe - sk0;
+        } else {
+            highp vec2 sf = clamp(floor(impEncode(lo) * (cells.x - 1.0) + 0.5), vec2(0.0), vec2(cells.x - 1.0));
+            si = sf.x; sk0 = sf.y; sk1 = sf.y;
+            st = 0.0;
+        }
+        // both frames' occluders (4 fetches, unconditional: the derivatives stay defined)
+        float occl0 = impOccl(P, si, sk0, isGrid, cells, r, inset);
+        float occl1 = impOccl(P, si, sk1, isGrid, cells, r, inset);
+        float occl = mix(occl0, occl1, st);
+        bool inSun = lo.y >= 0.0;   // the sun above the horizon
+        float selfShadow = inSun ? 1.0 - occl : 1.0;
+        // by the cards' share of the shadow map (leaf.y, foliage-cards.mat surfaceShading: a crown never goes black under its
+        // own shadow), and the knob
+        selfShadow = mix(1.0, selfShadow, materialParams.impostorSelfShadow * clamp(materialParams.leaf.y, 0.0, 1.0));
+        gSun *= selfShadow;
+
+        material.baseColor = base;
+        material.metallic = 0.0;
+        material.roughness = 1.0;
+        material.reflectance = 0.0;
+        material.ambientOcclusion = 0.0;   // Filament's IBL off: the ambient is ours, as emissive
+        material.emissive = vec4(base.rgb * ambient, 0.0);
+#endif
+    }
+
+    // PER LIGHT (the sun first): the pixel's sun scalar times the light and its SHADOW, by leaf.y — foliage-cards.mat's rule
+    vec3 surfaceShading(const MaterialInputs materialInputs, const ShadingData shadingData, const LightData lightData) {
+        float lit = mix(1.0, lightData.visibility, clamp(materialParams.leaf.y, 0.0, 1.0));
+        float reach = lightData.colorIntensity.w * lightData.attenuation * lit;
+        return shadingData.diffuseColor * lightData.colorIntensity.rgb * (reach * gSun / PI);
+    }
+}