@driftengine/core 4.13.2 → 4.13.4

package/dist/render/surfaceDetail.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A material's tiled detail: small normal maps, and occlusion, repeated many times over the base
+ * maps, a region map choosing which one each texel wears. `SurfaceMaterial.detail`, packed into
+ * `uDetail` for `shaders/flat/detail.ts`.
+ *
+ * **What it is for.** A surface's finest grain — leather, a weave, brushed metal, a face's pores —
+ * is a map of a few hundred texels repeated tens of times across it. Baked into the base maps it is
+ * lost: a 256-texel detail tiled forty times over a 2048-texel map would want some ten thousand
+ * texels a side. So the base maps carry the shape and a detail map the grain, each garment region
+ * with its own grain at its own repeat, which is how such surfaces are authored.
+ *
+ * **Where the maps are.** The lit stage has no texture binding to spare on either backend, so the
+ * detail maps are layers of the array read where a shading model's map is (`uModelMap`), and the
+ * region map is a layer of the material's own ORM array, one index a texel in its red. What that
+ * gives up, said where each is refused: a material whose shading model has a map must put its
+ * detail layers in that same array; a layered material whose mask is a map cannot have detail; and
+ * the region map shares the ORM array's size and format, which must keep an index exactly, so an
+ * uncompressed one.
+ *
+ * **Sixteen regions, two vectors each**, behind one vector saying how many and where the region
+ * map is: thirty-three in all, which is why WebGL2 compiles them in only when a material first asks
+ * and refuses them on a part with no room for them.
+ */
+/** Regions a material may name. */
+export declare const MAX_DETAIL_REGIONS = 16;
+/** Floats `uDetail` holds: a header vector, then two vectors a region. */
+export declare const DETAIL_FLOATS: number;
+/** One region's detail. */
+export interface SurfaceDetailRegion {
+    /** The layer of the detail array holding this region's tangent-space normal map. */
+    readonly normalLayer: number;
+    /** The layer holding its occlusion, in red; absent, the region adds none. */
+    readonly occlusionLayer?: number;
+    /** Repeats across the base coordinates, the same both ways or across and down apart. */
+    readonly repeat: number | readonly [number, number];
+    /** Added to the repeated coordinates, so neighbouring regions need not line up. Default none. */
+    readonly offset?: readonly [number, number];
+    /** How far the detail turns the normal: 0 lies flat, 1 as drawn, more steeper. Default 1. */
+    readonly normalStrength?: number;
+    /** How much of its occlusion is laid on, from 0 to 1. Default 1. */
+    readonly occlusionStrength?: number;
+}
+/** A material's tiled detail. */
+export interface SurfaceDetail<Texture> {
+    /**
+     * The array whose layers the regions name, read where a shading model's map is. A material with
+     * a `modelMap` puts its detail layers in that array and names it here too.
+     */
+    readonly maps: Texture;
+    /**
+     * The layer of the material's ORM array holding the region map: in its red, each texel's region
+     * as an index from 0, stored as `index / 255`, read exactly at the base coordinates. Absent, every
+     * texel is region 0, which is a surface with one detail all over: a face's pores.
+     */
+    readonly regionLayer?: number;
+    /** Up to sixteen, by index. A texel naming a region past the last wears the last. */
+    readonly regions: readonly SurfaceDetailRegion[];
+}
+/**
+ * Pack a material's detail into `out`, `DETAIL_FLOATS` long; zeros for none, which the shader reads
+ * as no detail. `hasOrm` says whether the material carries the ORM array a region map is a layer
+ * of; without one every texel is region 0. Allocates nothing.
+ */
+export declare function packSurfaceDetail(detail: SurfaceDetail<unknown> | null, hasOrm: boolean, out: Float32Array): void;
+/** Why a material's detail is drawn without, or null where nothing stands in its way. */
+export type DetailRefusal = 'slot' | 'projection';
+/**
+ * Whether a material's detail can be drawn, given what else wants the slot its maps are read
+ * through: a shading model's own map, or a layered material's mask where it is a map. Either must
+ * be the detail's array itself. And a material placed by the world has no base coordinates for a
+ * region map to be read at, so its detail is refused too.
+ */
+export declare function detailRefusal(detail: SurfaceDetail<unknown>, slotTakenBy: unknown, projected: boolean): DetailRefusal | null;
+/** A material's detail, or null where it names none or no region. */
+export declare function detailOf<Texture>(material: {
+    readonly detail?: SurfaceDetail<Texture> | null;
+} | null): SurfaceDetail<Texture> | null;
+/** The sentence each backend says once when it draws a material without its detail. */
+export declare function detailRefusalWarning(refusal: DetailRefusal): string;

package/dist/render/surfaceDetail.js

@@ -0,0 +1,86 @@
+/**
+ * A material's tiled detail: small normal maps, and occlusion, repeated many times over the base
+ * maps, a region map choosing which one each texel wears. `SurfaceMaterial.detail`, packed into
+ * `uDetail` for `shaders/flat/detail.ts`.
+ *
+ * **What it is for.** A surface's finest grain — leather, a weave, brushed metal, a face's pores —
+ * is a map of a few hundred texels repeated tens of times across it. Baked into the base maps it is
+ * lost: a 256-texel detail tiled forty times over a 2048-texel map would want some ten thousand
+ * texels a side. So the base maps carry the shape and a detail map the grain, each garment region
+ * with its own grain at its own repeat, which is how such surfaces are authored.
+ *
+ * **Where the maps are.** The lit stage has no texture binding to spare on either backend, so the
+ * detail maps are layers of the array read where a shading model's map is (`uModelMap`), and the
+ * region map is a layer of the material's own ORM array, one index a texel in its red. What that
+ * gives up, said where each is refused: a material whose shading model has a map must put its
+ * detail layers in that same array; a layered material whose mask is a map cannot have detail; and
+ * the region map shares the ORM array's size and format, which must keep an index exactly, so an
+ * uncompressed one.
+ *
+ * **Sixteen regions, two vectors each**, behind one vector saying how many and where the region
+ * map is: thirty-three in all, which is why WebGL2 compiles them in only when a material first asks
+ * and refuses them on a part with no room for them.
+ */
+/** Regions a material may name. */
+export const MAX_DETAIL_REGIONS = 16;
+/** Floats `uDetail` holds: a header vector, then two vectors a region. */
+export const DETAIL_FLOATS = 4 + MAX_DETAIL_REGIONS * 8;
+/**
+ * Pack a material's detail into `out`, `DETAIL_FLOATS` long; zeros for none, which the shader reads
+ * as no detail. `hasOrm` says whether the material carries the ORM array a region map is a layer
+ * of; without one every texel is region 0. Allocates nothing.
+ */
+export function packSurfaceDetail(detail, hasOrm, out) {
+    out.fill(0);
+    if (detail === null)
+        return;
+    const count = Math.min(MAX_DETAIL_REGIONS, detail.regions.length);
+    out[0] = count;
+    const regionLayer = detail.regionLayer;
+    out[1] = hasOrm && regionLayer !== undefined ? Math.max(0, Math.floor(regionLayer)) : -1;
+    for (let i = 0; i < count; i++) {
+        const region = detail.regions[i];
+        const at = 4 + i * 8;
+        const repeat = region.repeat;
+        const across = typeof repeat === 'number' ? repeat : repeat[0];
+        const down = typeof repeat === 'number' ? repeat : repeat[1];
+        out[at] = Math.max(0, Math.floor(region.normalLayer));
+        out[at + 1] =
+            region.occlusionLayer === undefined ? -1 : Math.max(0, Math.floor(region.occlusionLayer));
+        out[at + 2] = Math.max(0, region.normalStrength ?? 1);
+        out[at + 3] = Math.min(1, Math.max(0, region.occlusionStrength ?? 1));
+        /* A repeat at or below zero has no grain to show, so it is one rather than a mirror or nothing. */
+        out[at + 4] = across > 0 ? across : 1;
+        out[at + 5] = down > 0 ? down : 1;
+        out[at + 6] = region.offset?.[0] ?? 0;
+        out[at + 7] = region.offset?.[1] ?? 0;
+    }
+}
+/**
+ * Whether a material's detail can be drawn, given what else wants the slot its maps are read
+ * through: a shading model's own map, or a layered material's mask where it is a map. Either must
+ * be the detail's array itself. And a material placed by the world has no base coordinates for a
+ * region map to be read at, so its detail is refused too.
+ */
+export function detailRefusal(detail, slotTakenBy, projected) {
+    if (projected)
+        return 'projection';
+    if (slotTakenBy !== null && slotTakenBy !== undefined && slotTakenBy !== detail.maps) {
+        return 'slot';
+    }
+    return null;
+}
+/** A material's detail, or null where it names none or no region. */
+export function detailOf(material) {
+    const detail = material?.detail ?? null;
+    return detail === null || detail.regions.length === 0 ? null : detail;
+}
+/** The sentence each backend says once when it draws a material without its detail. */
+export function detailRefusalWarning(refusal) {
+    return refusal === 'slot'
+        ? "Renderer: a material's detail is drawn without: its maps are read where a shading model's " +
+            "map goes, and this material binds another array there, its `modelMap` or its layers' " +
+            'mask. Put the detail layers in the `modelMap` array and name that array as `detail.maps`.'
+        : "Renderer: a material's detail is drawn without: it is placed by the world (`projection`), " +
+            'so there are no base coordinates for its regions and repeats to be read at.';
+}

package/dist/render/surfaceTexture.d.ts

@@ -8,6 +8,7 @@
  * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
  * so a merged block wearing forty facades is one draw.
  */
+import type { SurfaceDetail } from './surfaceDetail.ts';
 import type { SurfaceLayers } from './surfaceLayers.ts';
 import type { SurfaceProjection } from './surfaceProjection.ts';
 import type { SurfaceModel } from './surfaceModel.ts';
@@ -235,6 +236,14 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * vertices. See `surfaceLayers.ts` for the rest and what it gives up.
      */
     layers?: SurfaceLayers<Texture> | null;
+    /**
+     * Fine grain tiled over the base maps: up to sixteen regions, each a detail normal map, and an
+     * occlusion, at its own repeat and strength, a region map in the ORM array choosing which one each
+     * texel wears. The detail maps are layers of an array read where `modelMap` goes, so a material
+     * with a shading model's map puts them in that array. **A lit switch**, compiled in the first time
+     * a material asks. See `surfaceDetail.ts` for the rest and what it gives up.
+     */
+    detail?: SurfaceDetail<Texture> | null;
 }
 export interface SurfaceTextureOptions {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.13.2",
+  "version": "4.13.4",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.13.2",
-    "@driftengine/physics": "4.13.2",
+    "@driftengine/drft": "4.13.4",
+    "@driftengine/physics": "4.13.4",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.13.2",
-    "@driftengine/network": "4.13.2",
-    "@driftengine/texture": "4.13.2"
+    "@driftengine/nav": "4.13.4",
+    "@driftengine/network": "4.13.4",
+    "@driftengine/texture": "4.13.4"
   }
 }

package/src/index.ts

@@ -677,6 +677,8 @@ export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
 export type { SurfaceProjection } from './render/surfaceProjection.ts';
 export type { SurfaceLayers } from './render/surfaceLayers.ts';
+export type { SurfaceDetail, SurfaceDetailRegion } from './render/surfaceDetail.ts';
+export { MAX_DETAIL_REGIONS } from './render/surfaceDetail.ts';
 export type { SurfaceLayerLook } from './render/surfaceLayerLooks.ts';
 /*
  * Compressed textures — BC, ETC2 and EAC, ASTC: the source `createSurfaceTexture` takes as blocks,

package/src/render/backend/webgl2/renderer.ts

@@ -117,6 +117,15 @@ import {
   packSurfaceLayers,
 } from '../../surfaceLayers.ts';
 import type { SurfaceLayers } from '../../surfaceLayers.ts';
+import {
+  DETAIL_FLOATS,
+  detailOf,
+  detailRefusal,
+  detailRefusalWarning,
+  packSurfaceDetail,
+  type DetailRefusal,
+  type SurfaceDetail,
+} from '../../surfaceDetail.ts';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
 import type { SurfaceProjection } from '../../surfaceProjection.ts';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.ts';
@@ -1801,6 +1810,13 @@ export class WebGL2Renderer implements RendererApi {
   /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
   private looksRoom: boolean | null = null;
   private warnedLooksRoom = false;
+  /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+  private readonly detailFloats = new Float32Array(DETAIL_FLOATS);
+  /** Whether the lit stage has room for detail on this part, asked once. See `detailOfMaterial`. */
+  private detailRoom: boolean | null = null;
+  private warnedDetailRoom = false;
+  /** The refusals already said, each once. */
+  private readonly warnedDetail = new Set<DetailRefusal>();
   private warnedLayersModelMap = false;
   private warnedLayersTriplanar = false;
   private warnedOverlayRoom = false;
@@ -4462,10 +4478,16 @@ export class WebGL2Renderer implements RendererApi {
     const modelMap = material?.modelMap ?? null;
     /* A layered material's mask, where it is a map, goes where a model's would: surfaceLayers.ts. */
     const layers = this.layersOf(material);
-    const boundMap = modelMap ?? layerMaskMap(layers);
+    const taken = modelMap ?? layerMaskMap(layers);
+    /* And its detail's array, where nothing else is read there: surfaceDetail.ts. */
+    const detail = this.detailOfMaterial(material, taken);
+    const boundMap = taken ?? detail?.maps ?? null;
     gl.activeTexture(gl.TEXTURE0 + MODEL_MAP_TEXTURE_UNIT);
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
     if (boundMap !== null) boundMap.bind(gl, MODEL_MAP_TEXTURE_UNIT);
+    packSurfaceDetail(detail, (material?.orm ?? null) !== null, this.detailFloats);
+    if (detail !== null) this.askLit('SURFACE_DETAIL');
+    gl.uniform4fv(u['uDetail'] ?? null, this.detailFloats);
     packSurfaceLayers(layers, this.layerFloats);
     if (layers !== null) this.askLit('LAYERED');
     gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
@@ -4771,6 +4793,37 @@ export class WebGL2Renderer implements RendererApi {
    * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
    * the sentence names the way out.
    */
+  /**
+   * A material's detail, or null where it is refused: its slot holds another array, it is placed by
+   * the world, or the lit stage has no room for its thirty-three vectors. Each said once.
+   */
+  private detailOfMaterial(
+    material: SurfaceMaterial | null,
+    taken: SurfaceTexture | null,
+  ): SurfaceDetail<SurfaceTexture> | null {
+    const detail = detailOf(material) as SurfaceDetail<SurfaceTexture> | null;
+    if (detail === null) return null;
+    const refusal = detailRefusal(detail, taken, (material?.projection ?? null) !== null);
+    if (refusal !== null) {
+      if (!this.warnedDetail.has(refusal)) {
+        this.warnedDetail.add(refusal);
+        console.warn(detailRefusalWarning(refusal));
+      }
+      return null;
+    }
+    this.detailRoom ??= this.switchFits('SURFACE_DETAIL');
+    if (this.detailRoom) return detail;
+    if (!this.warnedDetailRoom) {
+      this.warnedDetailRoom = true;
+      console.warn(
+        "Renderer: a material's detail is refused on this device. It takes thirty-three fragment " +
+          'uniform vectors the lit shader does not have, so the material is drawn without it. A ' +
+          'lower `maxLights` makes the room, or WebGPU has it.',
+      );
+    }
+    return null;
+  }
+
   private looksFit(layers: SurfaceLayers<SurfaceTexture> | null): boolean {
     if (!asksLayerLooks(layers)) return false;
     this.looksRoom ??= this.switchFits('LAYER_LOOKS', 'LAYERED');
@@ -7121,6 +7174,7 @@ export class WebGL2Renderer implements RendererApi {
       movingSun: asIf.MOVING_SUN ?? this.litOn.MOVING_SUN,
       layered: asIf.LAYERED ?? this.litOn.LAYERED,
       layerLooks: asIf.LAYER_LOOKS ?? this.litOn.LAYER_LOOKS,
+      surfaceDetail: asIf.SURFACE_DETAIL ?? this.litOn.SURFACE_DETAIL,
       maxLights: budget.maxLights,
       maxAreaLights: budget.maxAreaLights,
     });
@@ -9287,9 +9341,10 @@ export class WebGL2Renderer implements RendererApi {
     this.projection.fill(0);
     /* Nor light through from behind. See `SurfaceMaterial.diffuseTransmission`. */
     resolveTransmission(null, this.transmission);
-    /* Nor layers: one layer until a material asks for more. */
+    /* Nor layers: one layer until a material asks for more. Nor detail. */
     this.layerFloats.fill(0);
     this.lookFloats.fill(0);
+    this.detailFloats.fill(0);
     this.overlayMaps = null;
     this.overlayTexture = null;
     /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
@@ -9465,6 +9520,7 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
     gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
     gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
+    gl.uniform4fv(u['uDetail'] ?? null, this.detailFloats);
     /* Neither refracting nor glass, which is every draw that does not say otherwise. See
        `bindSeeThrough` for the four numbers in the one vector. */
     gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);

package/src/render/backend/webgpu/clothSetPack.ts

@@ -34,6 +34,7 @@ const SECTIONS: readonly (readonly [number, number])[] = [
   [7, 3],
   [10, 3],
   [13, 16],
+  [29, 1],
 ];
 /** Where the influences start, and where the garment's index sits, in particle counts. */
 const INFLUENCES = 13;

package/src/render/backend/webgpu/clothSolvePack.ts

@@ -20,7 +20,7 @@ import { batchesOf } from '@driftengine/physics';
 import type { ClothBatches, SkinnedClothSetup } from '@driftengine/physics';
 
 /** Floats of statics a particle, across its sections. */
-export const CLOTH_STATIC_FLOATS = 29;
+export const CLOTH_STATIC_FLOATS = 30;
 
 /** Bit flags of the limits a set-up has: a max distance, a backstop, a frontstop. */
 export const CLOTH_LIMIT_MAX = 1;
@@ -29,7 +29,10 @@ export const CLOTH_LIMIT_FRONT = 4;
 
 export interface PackedCloth {
   readonly count: number;
-  /** inverse mass, max distance, backstop ×2, frontstop ×2, thickness, rest ×3, normal ×3, influences ×16. */
+  /**
+   * inverse mass, max distance, backstop ×2, frontstop ×2, thickness, rest ×3, normal ×3,
+   * influences ×16, pull weight.
+   */
   readonly statics: Float32Array;
   /** Distance records (a, b, rest, compliance), bending (four ids, rest, compliance), tethers (particle, anchor, length). */
   readonly constraints: Uint32Array;
@@ -77,6 +80,7 @@ export function packCloth(setup: SkinnedClothSetup): PackedCloth {
       statics[at + i * 2 + 1] = real ? radius : 0;
     }
     statics[6 * n + i] = limits.thickness?.[i] ?? 0;
+    statics[29 * n + i] = setup.pullWeights?.[i] ?? 1;
     for (let k = 0; k < 3; k++) {
       statics[7 * n + i * 3 + k] = setup.positions[i * 3 + k] as number;
       statics[10 * n + i * 3 + k] = setup.normals?.[i * 3 + k] ?? (k === 2 ? 1 : 0);

package/src/render/backend/webgpu/gpuClothSet.ts

@@ -338,7 +338,7 @@ export class GpuClothSet {
     u[base + 32] = garment.range.colliderBase;
     u[base + 33] = garment.range.colliders;
     u[base + 34] = garment.particles.width;
-    f[base + 35] = 1 / (1 + p.pull * h * h);
+    f[base + 35] = p.pull * h * h;
     f[base + 36] = exactExp(p.damping * h);
     f[base + 37] = exactExp(p.drag * h);
     f[base + 38] = p.maxDistanceScale;

package/src/render/backend/webgpu/renderer.ts

@@ -216,6 +216,15 @@ import {
   packSurfaceLayers,
 } from '../../surfaceLayers.ts';
 import type { SurfaceLayers } from '../../surfaceLayers.ts';
+import {
+  DETAIL_FLOATS,
+  detailOf,
+  detailRefusal,
+  detailRefusalWarning,
+  packSurfaceDetail,
+  type DetailRefusal,
+  type SurfaceDetail,
+} from '../../surfaceDetail.ts';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
 import {
   frameReflectionsRefused,
@@ -3038,6 +3047,10 @@ export class WebGPURenderer implements RendererApi {
    */
   private readonly transmission = new Float32Array([-1, -1, -1, 0]);
   private warnedLayersModelMap = false;
+  /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+  private readonly detailFloats = new Float32Array(DETAIL_FLOATS);
+  /** The detail refusals already said, each once. See `detailOfMaterial`. */
+  private readonly warnedDetail = new Set<DetailRefusal>();
   private warnedLayersTriplanar = false;
   /** Its numbers, `uModelParams`, packed by `packModel`. */
   private readonly modelParams = new Float32Array(MODEL_PARAM_FLOATS);
@@ -3516,7 +3529,10 @@ export class WebGPURenderer implements RendererApi {
     const ownModelMap = (material?.modelMap ?? null) as GpuSurfaceTexture | null;
     /* A layered material's mask, where it is a map, goes where a model's would: surfaceLayers.ts. */
     const layers = this.layersOf(material);
-    const modelMap = ownModelMap ?? layerMaskMap(layers);
+    const taken = ownModelMap ?? layerMaskMap(layers);
+    /* And its detail's array, where nothing else is read there: surfaceDetail.ts. */
+    const detail = this.detailOfMaterial(material, taken);
+    const modelMap = taken ?? detail?.maps ?? null;
     this.materialModel = material?.model ?? null;
     const reflectivity = material?.reflectivity;
     const environmentGain = material?.environmentGain;
@@ -3609,6 +3625,10 @@ export class WebGPURenderer implements RendererApi {
       packLayerLooks(layers, this.lookFloats);
       f.set(this.lookFloats, this.materialField('uLayerLooks'));
       if (asksLayerLooks(layers)) this.enableLit('LAYER_LOOKS');
+      /* And its tiled detail, the first time a material lays any: detail.ts. */
+      packSurfaceDetail(detail, orm !== null, this.detailFloats);
+      f.set(this.detailFloats, this.materialField('uDetail'));
+      if (detail !== null) this.enableLit('SURFACE_DETAIL');
       f.set(this.modelParams, this.materialField('uModelParams'));
     });
     /*
@@ -6395,6 +6415,25 @@ export class WebGPURenderer implements RendererApi {
    * A material's layers where they can be drawn: none asked, or a model's map in the mask's place,
    * said once, leave one layer.
    */
+  /**
+   * A material's detail, or null where it is refused: its slot holds another array, or it is placed
+   * by the world. Each said once. This backend has room for its vectors wherever it runs.
+   */
+  private detailOfMaterial(
+    material: SurfaceMaterial<GpuSurfaceTexture> | null,
+    taken: GpuSurfaceTexture | null,
+  ): SurfaceDetail<GpuSurfaceTexture> | null {
+    const detail = detailOf(material);
+    if (detail === null) return null;
+    const refusal = detailRefusal(detail, taken, (material?.projection ?? null) !== null);
+    if (refusal === null) return detail;
+    if (!this.warnedDetail.has(refusal)) {
+      this.warnedDetail.add(refusal);
+      console.warn(detailRefusalWarning(refusal));
+    }
+    return null;
+  }
+
   private layersOf(
     material: SurfaceMaterial<GpuSurfaceTexture> | null,
   ): SurfaceLayers<GpuSurfaceTexture> | null {
@@ -9110,6 +9149,8 @@ export class WebGPURenderer implements RendererApi {
     /* Nor layers: one layer until a material asks for more. */
     f.fill(0, at('uLayers'), at('uLayers') + LAYER_FLOATS);
     f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
+    /* Nor detail. */
+    f.fill(0, at('uDetail'), at('uDetail') + DETAIL_FLOATS);
     f[at('uCutout')] = 0;
     f[at('uCutout') + 1] = 0;
     this.cutoutResolveStaged = 'hard';

package/src/render/backend/webgpu/shaders/clothSolve.wgsl.ts

@@ -88,8 +88,9 @@ struct Pace {
   colliderBase: u32,
   colliders: u32,
   width: u32,
-  /* The share of its offset from its skinned position a particle keeps a substep: the pull's. */
-  pullKeep: f32,
+  /* The garment's pull as a substep's stiffness, pull · h²: a particle weighted w keeps
+     1 / (1 + w · pullStep) of its offset from its skinned position. */
+  pullStep: f32,
   keep: f32,
   dragKeep: f32,
   maxDistanceScale: f32,
@@ -119,7 +120,7 @@ struct Batch {
 
 /* The record of particle i's garment this round: which garment a particle is, in statics. */
 fn paceAt(i: u32) -> u32 {
-  return round.at + u32(statics[29u * c.count + i]);
+  return round.at + u32(statics[30u * c.count + i]);
 }
 
 fn stateAt(section: u32, i: u32) -> u32 {
@@ -446,8 +447,9 @@ fn clothLimit(@builtin(global_invocation_id) id: vec3<u32>) {
   var p = load(at);
   let t = skinnedAt(i, g);
   /* Only where there is a pull, as on the CPU: t + (p - t) is not p in floats. */
-  if (paces[g].pullKeep < 1.0) {
-    p = t + (p - t) * paces[g].pullKeep;
+  let pull = statics[29u * n + i] * paces[g].pullStep;
+  if (pull > 0.0) {
+    p = t + (p - t) * (1.0 / (1.0 + pull));
   }
   /* A max distance below zero is none: the CPU's Infinity, which a device may not be handed. */
   let maxDistance = statics[n + i];

package/src/render/hairLobes.ts

@@ -50,6 +50,17 @@ export const HAIR_MIN_BETA = 0.05;
  */
 export const HAIR_SCATTER_SPHERE = 1.33;
 
+/**
+ * How far every lobe is widened for light from every side, in radians: the angle a source would
+ * subtend to widen them as much, `sourceRadius / 2·dist` in `hairLight`'s terms.
+ *
+ * **0.2, the real-time form's own value**, which stands one direction in for the sphere: a lobe as
+ * narrow as a lamp's would put the whole sky's light into one highlight wherever the eye's
+ * direction happens to meet it. What it gives up is the sky's shape: a sun low in a clear sky and
+ * an even overcast light hair through the same widened lobes.
+ */
+export const HAIR_AREA = 0.2;
+
 /** How much the scatter term leans toward the strand's own direction rather than the pseudo-normal. */
 const KAJIYA_SHARE = 0.33;
 
@@ -98,6 +109,71 @@ export function hairLight(
   sourceRadius: number,
   dist: number,
   out: Float64Array,
+): void {
+  const grow = sourceRadius / Math.max(2 * dist, 1e-3);
+  hairLobes(tangent, toLight, toEye, fibre, roughness, shift, scatter, backlit, grow, out);
+}
+
+/** The flattened eye `hairIndirect` lights a strand along, as the shader finds it. */
+const flattened = new Float64Array(3);
+
+/**
+ * The share of light from every side a strand returns, a colour into `out`, with the one
+ * direction's lobes it is made of into `lobes` (`HAIR_OUT`'s layout). `normal` is the surface's,
+ * which stands in for the flattened eye where the eye runs along the strand and there is none.
+ *
+ * **One direction for the sphere**: the eye flattened across the strand, `V − T(V·T)`, unshadowed,
+ * with no light from behind and so no transmitted lobe, every lobe widened by `HAIR_AREA`. Twice
+ * the sum, and at most all of what arrives. **Why twice**: the scatter's half is then
+ * `HAIR_SCATTER_SPHERE`, its own answer to an even sky — along the flattened eye its shape is
+ * `mix(1/2, 1, 0.33)`, 0.665, which doubled is that constant's 1.33 — so the lobes ride on a
+ * scatter the sphere's quadrature already holds to, and R and TRT are what the direction adds.
+ */
+export function hairIndirect(
+  tangent: ArrayLike<number>,
+  toEye: ArrayLike<number>,
+  normal: ArrayLike<number>,
+  fibre: Vec3,
+  roughness: number,
+  shift: number,
+  scatter: number,
+  lobes: Float64Array,
+  out: Float64Array,
+): void {
+  const along = dot(tangent, toEye);
+  let length2 = 0;
+  for (let c = 0; c < 3; c++) {
+    const across = (toEye[c] as number) - (tangent[c] as number) * along;
+    flattened[c] = across;
+    length2 += across * across;
+  }
+  for (let c = 0; c < 3; c++) {
+    flattened[c] =
+      length2 > 1e-8 ? (flattened[c] as number) / Math.sqrt(length2) : (normal[c] as number);
+  }
+  hairLobes(tangent, flattened, toEye, fibre, roughness, shift, scatter, 0, HAIR_AREA, lobes);
+  for (let c = 0; c < 3; c++) {
+    const sum =
+      (lobes[HAIR_OUT.r] as number) +
+      (lobes[HAIR_OUT.tt + c] as number) +
+      (lobes[HAIR_OUT.trt + c] as number) +
+      (lobes[HAIR_OUT.scatter + c] as number);
+    out[c] = Math.min(1, 2 * sum);
+  }
+}
+
+/** `hairLight`'s arithmetic, every lobe widened by `grow` radians. */
+function hairLobes(
+  tangent: ArrayLike<number>,
+  toLight: ArrayLike<number>,
+  toEye: ArrayLike<number>,
+  fibre: Vec3,
+  roughness: number,
+  shift: number,
+  scatter: number,
+  backlit: number,
+  grow: number,
+  out: Float64Array,
 ): void {
   const sinI = clamp(dot(tangent, toLight), -1, 1);
   const sinO = clamp(dot(tangent, toEye), -1, 1);
@@ -124,7 +200,6 @@ export function hairLight(
   const cosPhi = lpvp / Math.sqrt(lp2 * vp2 + 1e-4);
   const cosHalfPhi = Math.sqrt(clamp(0.5 + 0.5 * cosPhi, 0, 1));
   const beta = Math.max(roughness * roughness, HAIR_MIN_BETA);
-  const grow = sourceRadius / Math.max(2 * dist, 1e-3);
   const x = sinI + sinO;
 
   const r =