@driftengine/core 4.13.2 → 4.13.4

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

@@ -0,0 +1,74 @@
+/**
+ * A material's tiled detail over whatever its maps made: `SurfaceMaterial.detail`, packed into
+ * `uDetail` by `surfaceDetail.ts`.
+ *
+ * **Each texel wears its own region's detail alone.** The region is read exactly from the ORM
+ * array's layer the material names, at the base coordinates, so an index is never blended with its
+ * neighbour's at a region's edge; then that region's normal map is read at its repeat and offset,
+ * turned through a frame built on the normal the base maps made — the construction a layered
+ * material lays its layers over a mesh normal with — and its occlusion multiplied into the
+ * surface's. A strength scales the detail's slopes as a layer's look does.
+ *
+ * **Read with explicit gradients**, the base coordinates' times the region's repeat, because the
+ * region is the pixel's own: a read whose level is implicit is legal only in uniform control flow
+ * (AGENTS.md 2026-08-07), and across a region's edge the repeated coordinates jump, which would
+ * read a level as coarse as the jump. The frame and the gradients are taken first, under the
+ * uniform branch that calls this.
+ *
+ * **A lit switch, `SURFACE_DETAIL`**, off until a material first asks, declared after `LAYERED` and
+ * `LAYER_LOOKS` so each keeps its id. Compiled out, its thirty-three vectors are not declared.
+ */
+export function detailGlsl(on) {
+    if (!on) {
+        return /* glsl */ `
+const bool SURFACE_DETAIL = false;  // wgsl:override
+bool detailed() { return false; }
+void surfaceDetail(inout vec3 n, inout float occlusion, vec2 uv) {}
+`;
+    }
+    return /* glsl */ `
+/* Whether this program lays a material's detail. Off but where one has asked: detail.ts. */
+const bool SURFACE_DETAIL = true;  // wgsl:override
+/*
+ * Thirty-three vectors, as surfaceDetail.ts packs them: the region count (x) and the ORM array's
+ * layer holding the region map, or -1 for none (y); then two a region, the normal map's layer (x),
+ * the occlusion's or -1 (y), the normal strength (z) and the occlusion strength (w); its repeats
+ * across and down (x y) and its offset (z w).
+ */
+uniform vec4 uDetail[33]; // wgsl:material
+
+bool detailed() { return uDetail[0].x > 0.0; }
+
+/* The region a texel of the base maps is in, read exactly, held to the regions there are. */
+int detailRegion(vec2 uv) {
+  int last = int(uDetail[0].x) - 1;
+  if (uDetail[0].y < 0.0) return 0;
+  ivec2 size = textureSize(uOrmMap, 0).xy;
+  ivec2 texel = clamp(ivec2(floor(fract(uv) * vec2(size))), ivec2(0), size - 1);
+  int region = int(texelFetch(uOrmMap, ivec3(texel, int(uDetail[0].y)), 0).r * 255.0 + 0.5);
+  return clamp(region, 0, last);
+}
+
+void surfaceDetail(inout vec3 n, inout float occlusion, vec2 uv) {
+  /* In uniform control flow, before anything that depends on the pixel's region. */
+  mat3 frame = tangentFrame(n, vWorldPos, uv, vTangent, vHasTangents);
+  vec2 dx = dFdx(uv);
+  vec2 dy = dFdy(uv);
+  int region = detailRegion(uv);
+  vec4 picks = uDetail[1 + region * 2];
+  vec4 place = uDetail[2 + region * 2];
+  vec2 at = uv * place.xy + place.zw;
+  vec2 gx = dx * place.xy;
+  vec2 gy = dy * place.xy;
+  vec3 d = textureGrad(uModelMap, vec3(at, picks.x), gx, gy).xyz * 2.0 - 1.0;
+  /* z rebuilt where none is stored, as the base map's is: normalMap.ts. */
+  d.z = d.z > 0.0 ? d.z : sqrt(max(0.0, 1.0 - dot(d.xy, d.xy)));
+  d = normalize(vec3(d.xy * picks.z, max(d.z, 1e-4)));
+  n = normalize(frame * d);
+  if (picks.y >= 0.0) {
+    float held = textureGrad(uModelMap, vec3(at, picks.y), gx, gy).r;
+    occlusion *= mix(1.0, held, picks.w);
+  }
+}
+`;
+}

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

@@ -8,7 +8,7 @@ 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' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED' | 'LAYER_LOOKS';
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED' | 'LAYER_LOOKS' | 'SURFACE_DETAIL';
 /** 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`. */

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

@@ -38,6 +38,7 @@ export function noLitSwitches() {
         MOVING_SUN: false,
         LAYERED: false,
         LAYER_LOOKS: false,
+        SURFACE_DETAIL: false,
     };
 }
 /**

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

@@ -4,28 +4,34 @@
  * receives, and every term to a finite answer where the geometry degenerates.
  *
  * **The strand is the tangent, root to tip.** The model map's green turns each strand's tilt by up
- * to half of it either way (0.5 is none) and its blue is occlusion, which the sky, DriftLight and
- * the environment's reflection take and the lamps do not — their shadows are theirs to cast. The
- * red is not read: a colour from root to tip is the albedo map's to carry.
+ * to half of it either way (0.5 is none) and its blue is occlusion, which light from every side
+ * takes and the lamps do not — their shadows are theirs to cast. The red is not read: a colour from
+ * root to tip is the albedo map's to carry.
  *
- * **The environment** is the reflected lobe's: mirrored about a normal turned toward the eye across
- * the strand, which is the cone R lies on, at the strand's own Fresnel — the lobe integrates to it
- * over every direction of arrival. **What it gives up** is the two transmitted lobes against the
- * sky, which a head of hair lit from behind by an open sky would show as a rim; the lamps carry
- * them.
+ * **Light from every side** — the sky, the probes, DriftLight — goes through the lobes rather than
+ * past them: they are evaluated once, for a light along the eye flattened across the strand, every
+ * lobe widened by \`HAIR_AREA\` as a source that large would widen it, and their sum taken as the
+ * share of that light the strand returns (\`hairIndirect\`). That is how a real-time hair model
+ * stands one direction in for the sphere: a strand returns most toward the eye what arrives from
+ * the eye's side of it, and the R and TRT lobes are what make a fibre gold rather than a wash of
+ * its scatter. The environment's reflection leaves hair out, because R already took its share.
+ *
+ * **What it gives up**: light from behind. The direction stands for the eye's side only, so there
+ * is no transmitted lobe in it, and a head of hair lit from behind by an open sky shows no rim
+ * from the sky; the lamps carry one. And the share is one direction's, not the sphere's integral,
+ * so it moves with the eye as the lobes do rather than holding still as an average would. **What
+ * would make it wrong** is hair seen mostly against its light, a head against a bright window,
+ * whose sky arrives through the strands rather than off them and wants the transmitted lobe back.
  */
-import { HAIR_F0, HAIR_MIN_BETA, HAIR_SCATTER_SPHERE } from '../../hairLobes.js';
+import { HAIR_AREA, HAIR_F0, HAIR_MIN_BETA } from '../../hairLobes.js';
 export const HAIR_GLSL = /* glsl */ `
 const float HAIR_F0 = ${HAIR_F0.toFixed(9)};
 const float HAIR_MIN_BETA = ${HAIR_MIN_BETA.toFixed(3)};
-const float HAIR_SCATTER_SPHERE = ${HAIR_SCATTER_SPHERE.toFixed(3)};
+const float HAIR_AREA = ${HAIR_AREA.toFixed(3)};
 
-/* This texel's tilt, gathered once with the surface. */
+/* This texel's tilt, and the share of light from every side it returns: gathered with the surface. */
 float hShift;
-
-void hairSurface() {
-  hShift = uModelParams[0].x * (0.5 + mMap.g);
-}
+vec3 hAround;
 
 /** A longitudinal lobe: a normalised Gaussian of width \`beta\` at \`x\` from its centre. */
 float hairLongitudinal(float beta, float x) {
@@ -37,14 +43,18 @@ float hairFresnel(float cosine) {
   return HAIR_F0 + (1.0 - HAIR_F0) * c * c * c * c * c;
 }
 
-/** The normal turned toward the eye across the strand: the scatter's and the environment's. */
+/** The normal turned toward the eye across the strand: the scatter's, and light from every side's. */
 vec3 hairAcross() {
   vec3 across = mToEye - mTangent * dot(mTangent, mToEye);
   float length2 = dot(across, across);
   return length2 > 1e-8 ? across * inversesqrt(length2) : mNormal;
 }
 
-void hairLight(vec3 l, float sourceRadius, float dist) {
+/**
+ * The lobes for light arriving along \`l\`, into \`mSpecular\` and \`mDiffuse\`: every lobe widened by
+ * \`grow\` radians, and the transmitted one scaled by \`backlit\`.
+ */
+void hairLobes(vec3 l, float grow, float backlit) {
   vec3 t = mTangent;
   float sinI = clamp(dot(t, l), -1.0, 1.0);
   float sinO = clamp(dot(t, mToEye), -1.0, 1.0);
@@ -55,7 +65,6 @@ void hairLight(vec3 l, float sourceRadius, float dist) {
   float cosPhi = dot(lp, vp) * inversesqrt(dot(lp, lp) * dot(vp, vp) + 1e-4);
   float cosHalfPhi = sqrt(clamp(0.5 + 0.5 * cosPhi, 0.0, 1.0));
   float beta = max(mRoughness * mRoughness, HAIR_MIN_BETA);
-  float grow = sourceRadius / max(2.0 * dist, 1e-3);
   float x = sinI + sinO;
 
   float r = hairLongitudinal(beta + grow, x + 2.0 * hShift) * 0.25 * cosHalfPhi
@@ -65,7 +74,7 @@ void hairLight(vec3 l, float sourceRadius, float dist) {
   float h = cosHalfPhi * (1.0 + a * (0.6 - 0.8 * cosPhi));
   float fTT = hairFresnel(cosD * sqrt(clamp(1.0 - h * h, 0.0, 1.0)));
   float tt = hairLongitudinal(0.5 * beta + grow, x - hShift) * exp(-3.65 * cosPhi - 3.98)
-    * (1.0 - fTT) * (1.0 - fTT) * uModelParams[0].z;
+    * (1.0 - fTT) * (1.0 - fTT) * backlit;
   float ttPower = 0.5 * sqrt(clamp(1.0 - h * h * a * a, 0.0, 1.0)) / cosD;
 
   float fTRT = hairFresnel(0.5 * cosD);
@@ -80,6 +89,11 @@ void hairLight(vec3 l, float sourceRadius, float dist) {
   mDiffuse = sqrt(mAlbedo) * uModelParams[0].y * mix(wrapped, 1.0 - abs(sinI), 0.33);
 }
 
+/** A lamp, or the sun at no size: widened by the angle it subtends, as \`sphereLobe\` takes it. */
+void hairLight(vec3 l, float sourceRadius, float dist) {
+  hairLobes(l, sourceRadius / max(2.0 * dist, 1e-3), uModelParams[0].z);
+}
+
 /**
  * A shadow on the scatter: light that reaches a strand in another's shadow has passed through
  * hair to get there, so a penumbra deepens toward the fibre's own hue.
@@ -89,13 +103,25 @@ vec3 hairShade(float shadow) {
   return shadow * pow(max(hue, vec3(1e-4)), vec3(1.0 - shadow));
 }
 
-/** Light from every side, through the scatter term: \`HAIR_SCATTER_SPHERE\` says why that number. */
-vec3 hairAround(vec3 light) {
-  return sqrt(mAlbedo) * (uModelParams[0].y * HAIR_SCATTER_SPHERE * mMap.b) * light;
+/**
+ * The share of light from every side a strand returns: the lobes for a light along the eye
+ * flattened across the strand, unshadowed, with nothing from behind and every lobe widened by
+ * \`HAIR_AREA\`, twice their sum and at most all of it. Twice, in this engine's units, because the
+ * lobes are per unit irradiance and the scatter's half is then exactly \`HAIR_SCATTER_SPHERE\`, its
+ * own average over the sphere: \`hairLobes.ts\` says why, and holds the arithmetic to it.
+ */
+vec3 hairIndirect() {
+  hairLobes(hairAcross(), HAIR_AREA, 0.0);
+  return min(vec3(1.0), 2.0 * (mSpecular + mDiffuse));
 }
 
-/** The reflected lobe's share of the environment: its Fresnel, which is what it integrates to. */
-float hairReflectance() {
-  return hairFresnel(dot(hairAcross(), mToEye)) * mMap.b;
+void hairSurface() {
+  hShift = uModelParams[0].x * (0.5 + mMap.g);
+  hAround = hairIndirect();
+}
+
+/** Light from every side, through the lobes, under the map's occlusion. */
+vec3 hairAround(vec3 light) {
+  return hAround * (mMap.b * light);
 }
 `;

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

@@ -145,6 +145,11 @@ export interface FlatShaderOptions {
      * \`uLayerLooks\` and all. True when absent; nothing without \`layered\`. See \`layerLooksGlsl\`.
      */
     readonly layerLooks?: boolean;
+    /**
+     * Whether it lays a material's tiled detail over its maps, \`uDetail\` and all
+     * (\`SurfaceMaterial.detail\`). True when absent. See \`detailGlsl\`.
+     */
+    readonly surfaceDetail?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

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

@@ -24,6 +24,7 @@ import { overlayGlsl } from './overlay.js';
 import { reflectionSurfaceGlsl } from './reflectionSurface.js';
 import { worldUvGlsl } from './worldUv.js';
 import { movingSunGlsl } from './movingSun.js';
+import { detailGlsl } from './detail.js';
 import { layeredGlsl } from './layered.js';
 import { MAP_READS_GLSL } from './mapReads.js';
 import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.js';
@@ -514,6 +515,8 @@ export function flatFrag(options) {
         worldUvGlsl(options.worldUvs ?? true),
         /* After the projection, so its switch takes the next id; the normal map below calls it. */
         layeredGlsl(options.layered ?? true, options.layerLooks ?? true),
+        /* After the layers, so its switch takes the next id; main calls it. See detail.ts. */
+        detailGlsl(options.surfaceDetail ?? true),
         /* Where each map is read, after both of the ways it can be read otherwise. See mapReads.ts. */
         MAP_READS_GLSL,
         /* After the frame and the projection it calls, unconditional for the same reason as the