@driftengine/core 4.8.3 → 4.8.4

package/CHANGELOG.json

@@ -1,4 +1,75 @@
 [
+  {
+    "version": "4.8.4",
+    "date": "2026-10-05",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "A material can name a shading model (anisotropic, hair, skin or eye) with `model`, and carry its own channels in a `modelMap`. A scene that names none compiles none of them.",
+        "text": "`SurfaceMaterial.model` takes a frozen descriptor from `anisotropicModel`, `hairModel`, `skinModel` or `eyeModel`, and `modelMap` an image of that model's own channels, read at the albedo's coordinates. Each model is a pipeline constant of its own, off in every pipeline but the ones a material asks for and compiled the first time a draw does, so the standard lit shader is the one it was: every published scene moves 0 pixels on WebGPU, and the lit shader's instruction count and registers hold on RADV. **`anisotropicModel`** is GGX stretched along the mesh's tangent by a strength and turned by a rotation, after `KHR_materials_anisotropy`, and is the standard highlight exactly at strength 0; the environment is reflected about a normal bent toward the stretch, so a brushed disc shows a streak of sky. Hair, skin and the eye ignore the per-vertex `specular`: their highlights are physical, set by their own index of refraction. The models belong to the forward path; a `GpuDrivenMaterial` names none. The manual's materials chapter says what each map channel means."
+      },
+      {
+        "kind": "added",
+        "short": "`hairModel` shades strands along the mesh's tangent: a white highlight toward the root, a coloured one toward the tip, a glow when lit from behind, and light scattered through the hair.",
+        "text": "`hairModel({ shift, scatter, backlit })` treats each strand as a rough dielectric cylinder along the tangent, running from root to tip, after Marschner et al. in the real-time form Karis gave: the reflection off the surface, white and shifted toward the root by twice the cuticle's tilt; the light through the strand, which is the glow of a backlit head and is nearly nothing with the light in front; and the light reflected once inside, the coloured second highlight. Each is a normalised longitudinal Gaussian times an azimuthal fit, so a lamp's size widens every lobe without brightening it, and a wrapped scatter term carries the light that has passed through many strands, deepening toward the fibre's hue in a penumbra. The sky and DriftLight reach it through that scatter, and the environment through the reflected lobe at the strand's own Fresnel. `shift` is the tilt in radians, 3° by default; a card whose tangents run tip to root takes it negative. Held by tests to the three lobes' tilted peaks, reciprocity, a white strand returning what it receives to within the fit, and finite answers where the geometry degenerates."
+      },
+      {
+        "kind": "added",
+        "short": "`skinModel` lights skin as light that leaves it a little way from where it entered: a softer, redder terminator on curved parts, a red edge to a shadow, light through thin parts.",
+        "text": "`skinModel({ scatterColor, radius, transmission, profile })` gives each colour its own scatter distance, `radius` times its share of `scatterColor`, and on a curved surface lights a point by its neighbours' angle to the light as well as its own: Burley's diffusion profile averaged around a ring of the surface's curvature, after Penner, evaluated as a closed-form fit rather than looked up, so it costs no texture. The fit splits the average into the cosine's first harmonic and a smoothed absolute value carrying the rest, is exactly Lambert on a flat surface, and stays within 0.0105 of the integral done numerically wherever it is used. The curvature is read from the screen or from the model map; light from behind a thin part comes through it, and a shadow's penumbra lets each colour in as far as it travels. The highlight is two normalised GGX lobes at skin's Fresnel. Measured at a person's scale: a lamp behind a six-millimetre fin moves it red by 99 levels and blue by 8, and the standard model by nothing."
+      },
+      {
+        "kind": "added",
+        "short": "`skinScattering: 'screen-space'` adds Burley's blur in the picture: skin's diffuse is spread across the pixels its scatter distance covers before anything blended is drawn.",
+        "text": "A renderer quality option. Each skin draw writes its specular to the frame and its diffuse to a half-float target of its own — drawn a second time to do it — which is spread along each screen axis by Burley's profile integrated across a line, every tap weighted by the profile's mass over its cell in closed form, refusing taps off the skin's depth and counting part-covered ones for their part, and added back before the frame's first blended draw. Under it the per-pixel fit steps back to Lambert's and the blur does the scattering, so light crosses a shadow's edge and a nostril's rim on screen; light through thin parts stays with the fit. The split adds back to the whole: with a blur narrower than half a pixel the two pictures differ only at silhouettes, on both backends, multisampled or not, and under a pane drawn over the skin. It needs the composite (`screenEffects`) and, on WebGL2, `EXT_color_buffer_float`; without either, skin is pre-integrated and the renderer says so once. What it costs: every skin draw twice, two half-float targets the size of the frame and a third under multisampling, and two full-screen passes that leave at once where no skin was drawn. `profile` picks one of eight scatter distances the blur uses."
+      },
+      {
+        "kind": "added",
+        "short": "`eyeModel` moves an iris under its cornea as the eye turns, lights it as the shallow cone it is, and puts the cornea's sharp highlight over the whole eye.",
+        "text": "`eyeModel({ irisRadius, irisDepth, ior, corneaRoughness, axis, joint })` refracts the eye's ray at the cornea and moves the iris's texture coordinate by how far that ray crosses the iris plane before any map is read, so colour, relief and the model's channels move as one. Measured on a flat cornea at 30°: the iris is seen across 1.21 mm of a 3 mm depth, where parallax alone would put it at 1.73, both as predicted. The iris is lit by the surface normal mirrored about the eye's axis, so light pools on the side away from it, the sclera by its own, and the cornea's highlight — normalised GGX at `corneaRoughness`, the Fresnel of index 1.336 — lies over both. `axis` and `joint` say which way the eye looks and which bone it turns with; the renderer turns the axis per draw."
+      },
+      {
+        "kind": "added",
+        "short": "`cutoutMode: 'dithered'` gives a cutout a soft edge for hair, lashes and leaves, resolved over time, as multisampled coverage, or as the hard test where neither can.",
+        "text": "A dithered cutout keeps a pixel by the share of it the texture covers rather than by a line through it. The material asks for the smooth edge and the frame decides how: under a temporal resolve (TAA or DriftTR) the threshold moves every frame and the resolve averages the pattern into coverage; multisampled, the share goes to the GPU as alpha-to-coverage; with neither, the test is hard, since a dither nothing averages is grain. Shadows and coloured glass shadows dither with a pattern that holds still, and a translucent draw tests hard whatever the material says. `'hard'` stays the default, and every cutout before this draws as it did. Measured on both backends: grain under TAA 11.7, DriftTR 13.1, and the hard test's edge unchanged to the pixel."
+      },
+      {
+        "kind": "added",
+        "short": "A vertex may follow up to eight bones: `joints2` and `weights2` carry the second four, the importers keep eight heaviest first, and the container writes them at 1.24.",
+        "text": "`MeshData.joints2` and `weights2` add a second four influences beside `joints` and `weights`. glTF's `JOINTS_1` and `WEIGHTS_1` are read, and FBX skins with more than four bones a vertex keep eight, sorted heaviest first and normalised across all eight. `.drft` 1.24 writes them after every array a 1.23 reader reads; a 1.23 reader refuses such a mesh rather than drawing it with its second four read as indices. A skinned draw with them takes the eight-influence vertex stage on both backends — lit, shadow-casting and DriftTR's motion — under a pipeline constant inside the existing skinned variant, so a four-influence mesh draws exactly as before and the generated shaders do not double."
+      },
+      {
+        "kind": "added",
+        "short": "BC1 to BC5 and BC7 textures upload as their blocks where the device samples them, a byte a texel for BC7 against four, and the asset loader decodes them in a worker where it cannot.",
+        "text": "`createSurfaceTexture` takes a `CompressedTextureSource` — format, size and the stored mip chain — and uploads it as it is where `renderer.compressedFormats` has the format: WebGPU asks for `texture-compression-bc` wherever the adapter offers it, and WebGL2 reads the four extensions BC is spread across. Core ships no decoder and refuses by name a source the device cannot take; `uploadsCompressed` is the question to ask first. The baker keeps a DDS as BC blocks in `.drft` 1.24's `CODEC_BC` payload (`--decode-dds` keeps PNG for an older reader), and `@driftengine/assets` uploads them as blocks or decodes level 0 in a module worker — on the main thread where no worker can be had — so every device gets the image. A two-channel BC5 normal map keeps two channels and the lit stage rebuilds the third, which also repairs every BC5 map baked to PNG before this release with its blue at zero. The decoders are checked against an independent one: BC7 to the byte across every partition."
+      },
+      {
+        "kind": "added",
+        "short": "Cloth on a character: a skinned cloth solved on the GPU (on the CPU under WebGL2), with a finer mesh bound to it in the vertex stage, colliders on bones, limits, wind and resets.",
+        "text": "`SkinnedCloth` in `@driftengine/physics` is XPBD over particles that carry up to eight bone influences: distance, dihedral bending and tether constraints in graph-colour batches, a max distance, a backstop and a frontstop measured from where skinning puts each particle, spheres and tapered capsules on joints, inertia that lets a free particle keep a share of the character's motion, and a teleport that resets, settles and blends back in — whole fixed steps, drawn on `alpha`, with `setWind` taking the frame's sample of the scene's one wind. `createSkinnedCloth(renderer, setup)` solves it as WebGPU compute, its particles never leaving the device, and as `SkinnedCloth` under WebGL2, one schedule over both. A skinned mesh bound to it with `createClothBinding` and `setCloth` is placed by the cloth in its vertex stage — lit, shadow and DriftTR's motion alike — so a garment uploads nothing a frame. On an RX 9070 XT, 4,500 particles and 40,000 bound vertices take 0.65 ms a frame on the device against 20 ms on the CPU. `examples/garment/` builds a cape by hand; the handbook maps a cooked garment onto the two arrays. Self-collision is accepted in a set-up and not simulated."
+      },
+      {
+        "kind": "changed",
+        "short": "`updateMesh` uploads the positions and normals it is given and nothing else on WebGPU: a dynamic mesh no longer keeps a copy of its whole vertex buffer to resend every frame.",
+        "text": "A dynamic mesh kept a CPU copy of its interleaved vertex buffer, patched the positions and normals into it and sent all of it, reported at 2.8 MB a frame for one character's garments. Positions and normals are buffers of their own now, an update is one write of each, and no copy is kept; last frame's positions, for DriftTR's motion, are copied on the device ahead of the write. The picture is identical to the pixel, plain and under DriftTR."
+      },
+      {
+        "kind": "fixed",
+        "short": "A turned, skinned or instanced mesh with tangents lit its normal map from the wrong side: the tangent now leaves the vertex stage in world space, as the normal does.",
+        "text": "The lit vertex stage handed the fragment its tangent in the mesh's own space and the tangent frame crossed it with the world-space normal, so any mesh with stored tangents that was not drawn unturned lit its normal map from a direction that turned with it. The tangent is now turned as the normal is: by the joints, the model or instance matrix, and a cloth. Measured on a mapped panel turned a quarter: 80.4 rms from the derived reference before, 14.8 now — what it is unturned — on both backends. Every published scene is unchanged on WebGPU."
+      },
+      {
+        "kind": "fixed",
+        "short": "On WebGL2 a draw no longer loses the material set before it when a lit shader is compiled in the middle of a frame, as when a feature turns on or a new kind of draw first appears.",
+        "text": "Feeding a lit program compiled mid-frame its pass state also reset the renderer's current material, so the draws after it — until the next `setMaterial` — drew with no maps. The pass's material is reset where the pass begins now, and a program compiled mid-frame is handed the material that is current."
+      },
+      {
+        "kind": "fixed",
+        "short": "The baker no longer bakes a DDS it finds elsewhere in a bundle, rather than beside the model, as a single white pixel.",
+        "text": "A texture the baker found by searching a bundle went through a path that knew PNG, JPEG and WEBP and nothing else, so a DDS there was refused as an image and baked white. Both paths share one now, and a DDS is kept as BC blocks or decoded like any other."
+      }
+    ]
+  },
   {
     "version": "4.8.3",
     "date": "2026-10-04",

package/README.md

@@ -6,7 +6,7 @@ carries the loop, the renderer, cameras, input, the scene graph, geometry, text
 and the whole of [`@driftengine/physics`](https://driftengine.dev/docs/simulation/rigid-bodies),
 which it re-exports. The rest of the engine is separate packages you add when you need them.
 
-**Cost: 710.5 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 777.5 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/geometry/meshConcat.js

@@ -26,6 +26,8 @@ const OPTIONAL = [
     ['channel', 4],
     ['joints', 4],
     ['weights', 4],
+    ['joints2', 4],
+    ['weights2', 4],
     ['layers', 1],
 ];
 /**

package/dist/index.d.ts

@@ -5,7 +5,6 @@ export type { LoopHooks, FrameSource, LoopOptions } from './core/loop.ts';
 export { StepBudget } from './core/stepBudget.ts';
 export type { StepBudgetOptions } from './core/stepBudget.ts';
 export { hashToUnit, mulberry32, pickBySeed, savableMulberry32 } from './core/rng.ts';
-export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './math/exact.ts';
 export type { SavableRandom } from './core/rng.ts';
 export { TickTrace } from './core/tickTrace.ts';
 export type { TickTraceLike } from './core/tickTrace.ts';
@@ -148,7 +147,12 @@ export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './rend
 export type { ColourGradeLut } from './render/colourGrade.ts';
 export { probeDevice } from './render/backend/probe.ts';
 export type { ProbeVerdict } from './render/backend/probe.ts';
-export type { BoltHandle, CausticsHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
+export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
+export type { ClothBindingData } from './render/clothBindingData.ts';
+export { anisotropicModel, eyeModel, hairModel, skinModel } from './render/surfaceModel.ts';
+export type { AnisotropicModel, EyeModel, HairModel, SkinModel, SurfaceModel, SurfaceModelKind, } from './render/surfaceModel.ts';
+export { createSkinnedCloth } from './render/skinnedClothRun.ts';
+export type { SkinnedClothSolver } from './render/skinnedClothRun.ts';
 /**
  * What a frame asked of a backend, against the ceilings that backend imposes.
  *
@@ -157,7 +161,7 @@ export type { BoltHandle, CausticsHandle, FlockHandle, IncrementalMeshHandle, Li
  */
 export type { BudgetLine, FrameBudget } from './render/backend/budget.ts';
 export type { FrameTimer } from './render/backend/timer.ts';
-export type { SceneCasterMaterial, SceneCasters, ShadowCasterSink, ShadowCasters, } from './render/shadowCasters.ts';
+export type { SceneCasterMaterial, SceneCasters, ShadowCasterCloth, ShadowCasterSink, ShadowCasters, } from './render/shadowCasters.ts';
 export type { Atmosphere, UnderwaterAtmosphere } from './render/atmosphere.ts';
 export { createImageTexelDecoder } from './render/imageTexels.ts';
 export type { ImageTexelDecoder, ImageTexels } from './render/imageTexels.ts';
@@ -204,11 +208,13 @@ export type { PrefilterQuality } from './render/prefilterEnvMap.ts';
  * `ProbeBakeOptions`, which is the whole of the reasoning.
  */
 export type { ProbeBakeOptions } from './render/reflectionProbe.ts';
-export type { DirectionalShadowDepthLayers, GlassShadows, OutputTransform, RenderQuality, RenderQualityOptions, ShadowFilterTaps, WaterReflectionFilterTaps, } from './render/renderQuality.ts';
+export type { DirectionalShadowDepthLayers, GlassShadows, OutputTransform, RenderQuality, RenderQualityOptions, ShadowFilterTaps, SkinScattering, WaterReflectionFilterTaps, } from './render/renderQuality.ts';
 export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.ts';
 export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
+export { compressedFormatName, isCompressedSource, uploadsCompressed, } from './render/compressedSource.ts';
+export type { BlockFormat, CompressedTextureFormat, CompressedTextureSource, SurfaceSource, } from './render/compressedSource.ts';
 export { DEFAULT_GOVERNOR_LIMITS, ResolutionGovernor } from './render/resolutionGovernor.ts';
 export type { GovernorLimits } from './render/resolutionGovernor.ts';
 export { isWeakGpuFamily } from './render/gpuCapability.ts';

package/dist/index.js

@@ -3,7 +3,6 @@
 export { startLoop } from './core/loop.js';
 export { StepBudget } from './core/stepBudget.js';
 export { hashToUnit, mulberry32, pickBySeed, savableMulberry32 } from './core/rng.js';
-export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './math/exact.js';
 export { TickTrace } from './core/tickTrace.js';
 export { BrowserStore, MemoryStore, defaultStore } from './core/storage.js';
 /* The same seam over a backend that answers later, with the queue, the retry and the status. */
@@ -211,6 +210,17 @@ export { placeCascade } from './render/gi/globalField.js';
  */
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.js';
 export { probeDevice } from './render/backend/probe.js';
+/*
+ * A material's shading model, for what the standard one is not: brushed metal, hair, skin, an eye.
+ * A frozen descriptor made by a factory and set as `SurfaceMaterial.model`; each is a pipeline of
+ * its own, compiled the first time a draw asks.
+ */
+export { anisotropicModel, eyeModel, hairModel, skinModel } from './render/surfaceModel.js';
+/*
+ * A skinned cloth solved where the renderer can: compute on WebGPU, the CPU under WebGL2. A function
+ * rather than a renderer method so only a game that imports it carries the solver.
+ */
+export { createSkinnedCloth } from './render/skinnedClothRun.js';
 /*
  * Reading an image's texels back exactly, which no canvas and no `VideoFrame` will do.
  *
@@ -260,6 +270,11 @@ export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.js'
 /* The width a light buffer can usefully be with `clusteredLights` on; `createPointLightBuffer`. */
 export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.js';
 export { SurfaceTexture } from './render/surfaceTexture.js';
+/*
+ * BC compressed textures: the source `createSurfaceTexture` takes as blocks, and the one question to
+ * ask before handing one over — whether this device takes its format (`renderer.compressedFormats`).
+ */
+export { compressedFormatName, isCompressedSource, uploadsCompressed, } from './render/compressedSource.js';
 export { DEFAULT_GOVERNOR_LIMITS, ResolutionGovernor } from './render/resolutionGovernor.js';
 export { isWeakGpuFamily } from './render/gpuCapability.js';
 /**

package/dist/math/scalar.js

@@ -26,7 +26,7 @@ export function damp(a, b, lambda, dt) {
      * **What a simulation wants instead**, if it ever wants exponential approach inside the fixed
      * step, is a per-tick factor computed once from `lambda` and the fixed `dt` and passed in as a
      * number: at a constant step the factor is a constant, so nothing has to call `exp` on a tick at
-     * all. `exactExp` in `math/exact.ts` is the other answer, and is the one to reach for when the
+     * all. `exactExp` in `@driftengine/physics`' `exact.ts` is the other answer, and is the one to reach for when the
      * rate itself varies.
      */
     // determinism: build-time — presentation smoothing; see the note above for a simulation

package/dist/render/anisotropicLobe.d.ts

@@ -0,0 +1,7 @@
+/** The two widths, along the direction and across it, into `out` as [alongT, acrossB]. */
+export declare function anisotropicAlphas(roughness: number, strength: number, out: Float64Array): void;
+/**
+ * The lobe at a half vector whose components along the direction, across it and along the normal
+ * are `th`, `bh` and `nh`. 1 at the mirror direction.
+ */
+export declare function anisotropicLobe(th: number, bh: number, nh: number, alphaT: number, alphaB: number): number;

package/dist/render/anisotropicLobe.js

@@ -0,0 +1,33 @@
+/**
+ * The anisotropic model's lobe, as `shaders/flat/anisotropic.ts` computes it: the reference its
+ * tests hold the arithmetic to, and nothing at run time calls it.
+ *
+ * **GGX stretched along a direction in the surface**, after glTF's `KHR_materials_anisotropy`: the
+ * roughness across the direction is the material's, and along it is raised toward 1 by the
+ * strength squared — `alphaT = mix(alpha, 1, strength²)`, `alphaB = alpha` — so a brushed disc's
+ * highlight is a streak across its grooves.
+ *
+ * **Divided by its own peak, as `specularLobe` is**, because this engine's highlights are in those
+ * units: a look control that peaks at 1 whatever its width, rather than an energy-conserving BRDF
+ * (`lobes.ts` says why). So at strength 0 this *is* `specularLobe`, which is the property a material
+ * that turns anisotropy down to nothing must have, and which the tests hold. **What it gives up** is
+ * the Smith masking a physically based anisotropic lobe carries at grazing angles; the standard lobe
+ * carries none either, and the two must agree at strength 0.
+ */
+import { MIN_LOBE_ALPHA } from './shaders/flat/lobes.js';
+/** The two widths, along the direction and across it, into `out` as [alongT, acrossB]. */
+export function anisotropicAlphas(roughness, strength, out) {
+    const alpha = Math.max(roughness * roughness, MIN_LOBE_ALPHA);
+    out[0] = alpha + (1 - alpha) * strength * strength;
+    out[1] = alpha;
+}
+/**
+ * The lobe at a half vector whose components along the direction, across it and along the normal
+ * are `th`, `bh` and `nh`. 1 at the mirror direction.
+ */
+export function anisotropicLobe(th, bh, nh, alphaT, alphaB) {
+    const x = th / alphaT;
+    const y = bh / alphaB;
+    const d = x * x + y * y + nh * nh;
+    return 1 / Math.max(d * d, 1e-8);
+}

package/dist/render/backend/api.d.ts

@@ -6,6 +6,8 @@ import type { ProbeBakeOptions } from '../reflectionProbe.ts';
 import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
 import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
+import type { SurfaceSource } from '../compressedSource.ts';
+import type { ClothBindingData } from '../clothBindingData.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
 import type { SdfTextStyle } from '../sdfTextLayout.ts';
@@ -37,6 +39,15 @@ export interface MeshHandle {
      */
     readonly complete: boolean;
 }
+/**
+ * A mesh's cloth binding on the device, from `createClothBinding`: which simulation triangle each
+ * vertex follows. Opaque, for the reason `MeshHandle` gives.
+ */
+export interface ClothBindingHandle {
+}
+/** One character's cloth particles on the device, from `createClothParticles`. Opaque likewise. */
+export interface ClothParticlesHandle {
+}
 /** A mesh on its way to the device, and the iterator that gets it there. */
 export interface IncrementalMeshHandle {
     /**
@@ -175,9 +186,35 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial'> & {
-    /** Upload a caller's image. See `SurfaceTextureHandle` for the boundary this guards. */
-    createSurfaceTexture(source: TexImageSource, options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+    /**
+     * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
+     * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
+     * between its skinning and the cloth — and is checked against the binding by name.
+     */
+    createClothBinding(mesh: MeshHandle, data: ClothBindingData): ClothBindingHandle;
+    /** One character's particles, `count` of them, updated every frame with `updateClothParticles`. */
+    createClothParticles(count: number): ClothParticlesHandle;
+    /**
+     * This frame's particles, three floats each, world space — a simulation's output as it is.
+     * **Once a frame, before the character's draws**: a second update in one frame reaches every
+     * draw of it on WebGPU, whose texture writes land ahead of the frame's commands. Last frame's
+     * are kept for the motion a temporal resolve needs, and a frame with no update did not move.
+     */
+    updateClothParticles(particles: ClothParticlesHandle, positions: Float32Array): void;
+    /**
+     * Place the skinned draws that follow — lit and cast — by a cloth: the mesh's binding and the
+     * character's particles. Null for none, which every draw is until this is called; per-draw state,
+     * as `setSkinPalette` is.
+     */
+    setCloth(binding: ClothBindingHandle | null, particles?: ClothParticlesHandle | null): void;
+    disposeClothBinding(binding: ClothBindingHandle): void;
+    disposeClothParticles(particles: ClothParticlesHandle): void;
+    /**
+     * Upload a caller's image, or a BC image's blocks with their stored chain where
+     * `compressedFormats` has the format. See `SurfaceTextureHandle` for the boundary this guards.
+     */
+    createSurfaceTexture(source: SurfaceSource, options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
     /**
      * Upload several images of one size as the layers of one array texture.
      *
@@ -191,7 +228,7 @@ export type RendererApi = Omit<{
      * refusal names the first image that differs. A layer past the end reads the last one.
      * `updateSurfaceTexture` refuses an array.
      */
-    createSurfaceTextureArray(sources: readonly TexImageSource[], options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
+    createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
     /**
      * Replace a texture's pixels, keeping the GPU object and its sampler state.
      *

package/dist/render/backend/select.js

@@ -206,6 +206,14 @@ async function acquireWebGpu(gpu, wantsGpuTiming, shaders, stage) {
         if (wantsGpuTiming && adapter.features?.has('timestamp-query') === true) {
             features.push('timestamp-query');
         }
+        /*
+         * BC compressed textures, on the same terms: asked for wherever the adapter offers it, because
+         * a device without it still draws — the loader decodes for it — and one with it samples a BC7
+         * texture at a byte a texel instead of four. See `compressedUpload.ts`.
+         */
+        if (adapter.features?.has('texture-compression-bc') === true) {
+            features.push('texture-compression-bc');
+        }
         const descriptor = {};
         if (Object.keys(required).length > 0)
             descriptor.requiredLimits = required;

package/dist/render/backend/webgl2/clothTextures.d.ts

@@ -0,0 +1,27 @@
+import type { ClothBindingData } from '../../clothBindingData.ts';
+/** A mesh's binding and its particles at rest. Validated by the renderer against the mesh. */
+export declare class GlClothBinding {
+    readonly binding: WebGLTexture;
+    readonly rest: WebGLTexture;
+    /** How many particles the binding names. */
+    readonly particles: number;
+    constructor(gl: WebGL2RenderingContext, data: ClothBindingData);
+    dispose(gl: WebGL2RenderingContext): void;
+}
+/** One character's particles: this frame's and the last, in two textures that swap. */
+export declare class GlClothParticles {
+    readonly count: number;
+    private readonly width;
+    private readonly height;
+    private readonly staging;
+    private readonly textures;
+    private latest;
+    constructor(gl: WebGL2RenderingContext, count: number);
+    /** This frame's particles. */
+    get current(): WebGLTexture;
+    /** Last frame's. */
+    get previous(): WebGLTexture;
+    /** Write `positions` (three floats a particle, world space) as this frame's; last frame's stays. */
+    update(gl: WebGL2RenderingContext, positions: Float32Array): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/backend/webgl2/clothTextures.js

@@ -0,0 +1,93 @@
+/**
+ * A cloth binding's textures on WebGL2: the binding and the rest particles once, a mesh's; the
+ * particles every frame, a character's.
+ *
+ * `RGBA32F`, one storage level and `NEAREST` both ways, as the joint palette is: the vertex stage
+ * reads them with `texelFetch`, so nothing filters and nothing selects a mip. Rows of at most 2048
+ * texels; see `clothBindingData.ts`.
+ *
+ * **Two particle textures that swap on each update**, so last frame's positions are still there for
+ * a motion vector without a copy: an update writes the older of the two and makes it current.
+ */
+import { clothTextureSize, packClothBinding, packClothParticles } from '../../clothBindingData.js';
+function floatTexture(gl, width, height, texels) {
+    const texture = gl.createTexture();
+    if (texture === null)
+        throw new Error('cloth: createTexture failed');
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.RGBA32F, width, height);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    if (texels !== null) {
+        gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, width, height, gl.RGBA, gl.FLOAT, texels);
+    }
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    return texture;
+}
+/** A mesh's binding and its particles at rest. Validated by the renderer against the mesh. */
+export class GlClothBinding {
+    binding;
+    rest;
+    /** How many particles the binding names. */
+    particles;
+    constructor(gl, data) {
+        const vertices = data.weights.length;
+        const size = clothTextureSize(vertices * 2);
+        this.binding = floatTexture(gl, size.width, size.height, packClothBinding(data));
+        this.particles = data.rest.length / 3;
+        const rest = clothTextureSize(this.particles);
+        const texels = new Float32Array(rest.width * rest.height * 4);
+        packClothParticles(data.rest, texels);
+        this.rest = floatTexture(gl, rest.width, rest.height, texels);
+    }
+    dispose(gl) {
+        gl.deleteTexture(this.binding);
+        gl.deleteTexture(this.rest);
+    }
+}
+/** One character's particles: this frame's and the last, in two textures that swap. */
+export class GlClothParticles {
+    count;
+    width;
+    height;
+    staging;
+    textures;
+    latest = 0;
+    constructor(gl, count) {
+        this.count = count;
+        const size = clothTextureSize(count);
+        this.width = size.width;
+        this.height = size.height;
+        this.staging = new Float32Array(size.width * size.height * 4);
+        this.textures = [
+            floatTexture(gl, size.width, size.height, this.staging),
+            floatTexture(gl, size.width, size.height, this.staging),
+        ];
+    }
+    /** This frame's particles. */
+    get current() {
+        return this.textures[this.latest];
+    }
+    /** Last frame's. */
+    get previous() {
+        return this.textures[1 - this.latest];
+    }
+    /** Write `positions` (three floats a particle, world space) as this frame's; last frame's stays. */
+    update(gl, positions) {
+        if (positions.length !== this.count * 3) {
+            throw new Error(`cloth: ${this.count} particles and an update of ${positions.length / 3}; a cloth's ` +
+                'particle count is fixed when its particles are created');
+        }
+        packClothParticles(positions, this.staging);
+        this.latest = 1 - this.latest;
+        gl.bindTexture(gl.TEXTURE_2D, this.current);
+        gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, this.width, this.height, gl.RGBA, gl.FLOAT, this.staging);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    dispose(gl) {
+        gl.deleteTexture(this.textures[0]);
+        gl.deleteTexture(this.textures[1]);
+    }
+}