@driftengine/core 4.13.2 → 4.13.4

package/src/render/shaders/flat/detail.ts

@@ -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: boolean): string {
+  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/src/render/shaders/flat/glassTint.ts

@@ -40,7 +40,8 @@ export type LitSwitch =
   | 'WORLD_UVS'
   | 'MOVING_SUN'
   | 'LAYERED'
-  | 'LAYER_LOOKS';
+  | 'LAYER_LOOKS'
+  | 'SURFACE_DETAIL';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -57,6 +58,7 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     MOVING_SUN: false,
     LAYERED: false,
     LAYER_LOOKS: false,
+    SURFACE_DETAIL: false,
   };
 }
 

package/src/render/shaders/flat/hair.ts

@@ -4,29 +4,35 @@
  * 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.ts';
+import { HAIR_AREA, HAIR_F0, HAIR_MIN_BETA } from '../../hairLobes.ts';
 
 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) {
@@ -38,14 +44,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);
@@ -56,7 +66,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
@@ -66,7 +75,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);
@@ -81,6 +90,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.
@@ -90,13 +104,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/src/render/shaders/flat/index.ts

@@ -24,6 +24,7 @@ import { overlayGlsl } from './overlay.ts';
 import { reflectionSurfaceGlsl } from './reflectionSurface.ts';
 import { worldUvGlsl } from './worldUv.ts';
 import { movingSunGlsl } from './movingSun.ts';
+import { detailGlsl } from './detail.ts';
 import { layeredGlsl } from './layered.ts';
 import { MAP_READS_GLSL } from './mapReads.ts';
 import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.ts';
@@ -539,6 +540,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.
    *
@@ -692,6 +698,8 @@ export function flatFrag(options: FlatShaderOptions): string {
       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

package/src/render/shaders/flat/main.ts

@@ -227,6 +227,8 @@ export const MAIN_GLSL = `void main() {
     if (uNormalStrength > 0.0) n = normalMapped(n, surfaceAt, frameAt, frameTangents);
     /* A draw's wrinkles, by region, over whatever the map made: overlay.ts. */
     if (SURFACE_OVERLAY) n = overlayWrinkle(n, unmapped, surfaceAt.xy);
+    /* The material's tiled detail over whatever the maps made, and its occlusion: detail.ts. */
+    if (SURFACE_DETAIL && detailed()) surfaceDetail(n, ormOcclusion, surfaceAt.xy);
 
     /*
      * Microscopic relief: the surface's own texture, as a turn of the normal rather than a change
@@ -693,8 +695,9 @@ export const MAIN_GLSL = `void main() {
      * branch it did not take before.
      */
     /* A model reflects its environment whatever the pass asked of the standard model: see
-       modelReflectance. On the switches alone, so the derivatives below stay in uniform flow. */
-    if (uEnvironmentDials.y > 0.0 || uMaterialFlags.y != 0 || modelled) {
+       modelReflectance. Hair takes none: modelReflects. On the switches alone, so the derivatives
+       below stay in uniform flow. */
+    if ((uEnvironmentDials.y > 0.0 || uMaterialFlags.y != 0 || modelled) && modelReflects()) {
       vec3 toEye = normalize(uCameraPos - vWorldPos);
       vec3 mirrored = reflect(-toEye, modelled ? modelReflectNormal(n) : n);
       vec3 environment = mix(uAmbientGround, uAmbient, mirrored.y * 0.5 + 0.5);

package/src/render/shaders/flat/models.ts

@@ -12,8 +12,8 @@
  * **Where the models plug in.** `main` gathers the surface once (`modelSurface`), then asks at each
  * place light arrives: `modelLight` for the sun, each lamp and each rectangle, `modelAmbient` for
  * the sky and the probe's irradiance, `modelIrradiance` for DriftLight, `modelReflectNormal` and
- * `modelReflectance` for the environment's reflection. Each returns today's term for the standard
- * model, and each model's file is where its own answers are.
+ * `modelReflectance` for the environment's reflection, which `modelReflects` keeps from hair. Each
+ * returns today's term for the standard model, and each model's file is where its own answers are.
  *
  * **What a model returns from a light** is the two halves the standard terms are: a diffuse already
  * weighted by the angle of arrival, and a specular lobe in the engine's peak-normalised units (see
@@ -95,6 +95,15 @@ bool modelSeesBehind() {
   return false;
 }
 
+/**
+ * Whether the environment's reflection reaches this surface: every model's but hair's, whose share
+ * of it is in its light from every side (hair.ts).
+ */
+bool modelReflects() {
+  if (MODEL_HAIR) return false;
+  return true;
+}
+
 /* The surface a model shades, gathered once in main before any light reaches it. */
 vec3 mNormal;
 vec3 mToEye;
@@ -285,7 +294,6 @@ vec3 modelIrradiance(vec3 irradiance) {
 /** The normal the environment is reflected about: the surface's own, but for a stretched lobe. */
 vec3 modelReflectNormal(vec3 n) {
   if (MODEL_ANISOTROPIC) return anisotropicReflectNormal(n);
-  if (MODEL_HAIR) return hairAcross();
   return n;
 }
 
@@ -361,7 +369,6 @@ vec3 modelDiffuseOut(vec3 diffuse, float fog) {
  * what the standard model would.
  */
 float modelReflectance(float standard) {
-  if (MODEL_HAIR) return hairReflectance();
   if (MODEL_SKIN) return skinReflectance();
   if (MODEL_EYE) return eyeReflectance();
   return standard;