@driftengine/core 4.10.0 → 4.11.0

package/src/render/surfaceLayers.ts

@@ -0,0 +1,57 @@
+/**
+ * A material blended from layers by a mask: `SurfaceMaterial.layers`, and the two vectors
+ * `shaders/flat/layered.ts` reads it from.
+ */
+
+/** The most layers a material blends: a base and one for each of the mask's four channels. */
+export const MAX_SURFACE_LAYERS = 5;
+
+/**
+ * Up to five layers, each its own colour, normal and roughness at its own repeat, blended by a mask.
+ *
+ * **Layer `i` is layer `i` of the material's arrays**: `albedo`, `normal` and `orm` each an array
+ * whose layers are the material's layers in order, read at the mesh's coordinates times
+ * `repeats[i]`, so rock can repeat forty times across a cliff while the moss on it repeats three.
+ * **The mask** is read at the mesh's own coordinates and lays each layer over those before it: red
+ * lays layer 1 over the base, green layer 2 over that, blue layer 3, alpha layer 4. Its layer 0 is
+ * read, from where a shading model's map goes, which is why a layered material carries no
+ * `modelMap`. `emissiveLayer` gives the material's emissive map to one layer, glowing where that
+ * layer shows and nowhere it is covered; absent, the map glows as on any material.
+ *
+ * **What it gives up**: every layer's maps are read wherever any shows, three reads a layer, so five
+ * layers are fifteen reads where one material is three; layers share an array's size and format; a
+ * cutout reads the base layer's alpha; and the mask is sampled linear, so it is uploaded as data
+ * (`colorSpace: 'linear'`).
+ */
+export interface SurfaceLayers<Texture> {
+  /** The weights, red to alpha laying layers 1 to 4, read at the mesh's coordinates. */
+  readonly mask: Texture;
+  /** Each layer's repeats across the mesh's coordinates, base first: one to five of them. */
+  readonly repeats: readonly number[];
+  /** The layer the emissive map glows on, 0 to 4. Absent: everywhere, as on any material. */
+  readonly emissiveLayer?: number;
+}
+
+/** Floats `packSurfaceLayers` writes: two vectors. */
+export const LAYER_FLOATS = 8;
+
+/**
+ * `layers` into `out`: the five repeats (1 for a layer not given), then how many layers there are
+ * and which one glows (−1 for none); zeros, no layers, where there are none. A repeat that is not a
+ * positive number is 1, so a layer is never laid at a scale that collapses it to a point.
+ */
+export function packSurfaceLayers<Texture>(
+  layers: SurfaceLayers<Texture> | null | undefined,
+  out: Float32Array,
+): void {
+  out.fill(0);
+  if (layers === null || layers === undefined || layers.repeats.length === 0) return;
+  const count = Math.min(layers.repeats.length, MAX_SURFACE_LAYERS);
+  for (let i = 0; i < MAX_SURFACE_LAYERS; i++) {
+    const repeat = i < count ? (layers.repeats[i] as number) : 1;
+    out[i] = Number.isFinite(repeat) && repeat > 0 ? repeat : 1;
+  }
+  out[5] = count;
+  const glow = layers.emissiveLayer;
+  out[6] = glow !== undefined && Number.isInteger(glow) && glow >= 0 && glow < count ? glow : -1;
+}

package/src/render/surfaceOverlay.ts

@@ -29,12 +29,24 @@ export interface OverlayRegion {
  * raised to a contrast, times a noise laid in screen space, a slow pulse and a mask, in a colour.
  * Added to what the surface emits, and not gated on the night as emission is: it is a glow the
  * surface wears, not light it gives off.
+ *
+ * **Or, with `mode: 'blend'`, a colour the surface is pulled toward**, lit like the rest of it: the
+ * base colour mixed toward the rim's by the edge times `alpha`, before any light reads it, so the
+ * rim is bright where light falls and dark where none does. The colour is `colour` times
+ * `intensity`, each channel held at 1 as a base colour is, so a colour of 8 red is a red of 1 and
+ * not a glow; `alpha` is the weight, which may pass 1 to saturate the edge sooner.
  */
 export interface SurfaceRim {
   readonly colour: Vec3;
-  /** How bright, 0 for none. Multiplied with `alpha`. */
+  /**
+   * How bright, 0 for none, multiplied with `alpha`. Where the rim blends it scales `colour`
+   * instead, so 0 there is a rim of black, and `alpha` alone says how much: 0 for none.
+   */
   readonly intensity: number;
+  /** The rim's weight, 1 unless given. */
   readonly alpha?: number;
+  /** `'add'`, the default, lays the rim on as glow; `'blend'` pulls the base colour toward it, lit. */
+  readonly mode?: 'add' | 'blend';
   /** The edge's exponent: larger keeps the rim nearer the silhouette. 1.5 unless given. */
   readonly falloff?: number;
   /**
@@ -122,10 +134,11 @@ function region(out: Float32Array, at: number, r: OverlayRegion | undefined | nu
  * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
  * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
  *
- * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim). A blending rim: the colour
+ *   times intensity, each channel held at 1, and the alpha alone
  * - 1: falloff, upward lean, contrast, mask weight
  * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
- * - 4: the pulse's low and high (1 and 1 where none)
+ * - 4: the pulse's low and high (1 and 1 where none), and the mode: 0 adds, 1 blends
  * - 5: the rim's mask region
  * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
  * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
@@ -138,10 +151,14 @@ export function packSurfaceOverlay(overlay: SurfaceOverlay | null, out: Float32A
   const images = overlay.maps !== undefined;
   const rim = overlay.rim;
   if (rim !== undefined) {
-    out[0] = finite(rim.colour[0], 0);
-    out[1] = finite(rim.colour[1], 0);
-    out[2] = finite(rim.colour[2], 0);
-    out[3] = Math.max(0, finite(rim.intensity, 0) * finite(rim.alpha, 1));
+    const blend = rim.mode === 'blend';
+    const scale = blend ? finite(rim.intensity, 0) : 1;
+    for (let c = 0; c < 3; c++) {
+      const channel = finite(rim.colour[c], 0) * scale;
+      out[c] = blend ? Math.min(Math.max(channel, 0), 1) : channel;
+    }
+    out[3] = Math.max(0, (blend ? 1 : finite(rim.intensity, 0)) * finite(rim.alpha, 1));
+    out[18] = blend ? 1 : 0;
     out[4] = Math.max(0, finite(rim.falloff, 1.5));
     out[5] = Math.max(0, finite(rim.upward, 0.4));
     out[6] = Math.max(0, finite(rim.contrast, 1));

package/src/render/surfaceProjection.ts

@@ -0,0 +1,57 @@
+/**
+ * A material's maps placed by where a point is in the world: `SurfaceMaterial.projection`, and the
+ * one vector `shaders/flat/worldUv.ts` reads it from.
+ */
+
+/**
+ * Texture coordinates from the world rather than from the mesh.
+ *
+ * **`'planar'`** lays the maps across the two horizontal axes, `x` and `z`: ground whose mesh
+ * carries flat coordinates, or none worth reading, shows its texture at `scale` repeats a metre.
+ * **`'triplanar'`** reads each map on the three planes across `x`, `y` and `z` and blends them by
+ * how squarely the surface faces each, the normal's components raised to `sharpness`, so walls and
+ * rock wear a texture without stretching. See `worldUv.ts` for the normal map's blend.
+ *
+ * **What it gives up**: the world's coordinates do not move with a mesh, so a moving mesh slides
+ * under its texture; triplanar reads every map three times; and the material's `uScale`, `vScale`
+ * and offsets, which are the mesh's coordinates', do not apply.
+ */
+export interface SurfaceProjection {
+  readonly kind: 'planar' | 'triplanar';
+  /** Repeats a metre: 2 lays a texture every half metre. */
+  readonly scale: number;
+  /** How sharply triplanar's planes meet: the exponent on the normal. 4 unless given. */
+  readonly sharpness?: number;
+}
+
+/** Floats `packSurfaceProjection` writes: one vector. */
+export const PROJECTION_FLOATS = 4;
+
+/**
+ * `projection` into `out`: its kind (0 none, 1 planar, 2 triplanar), its repeats a metre and its
+ * sharpness; zeros for none. A scale that is not finite and above zero projects nothing, so a
+ * material is never drawn at a scale that collapses its texture to a point.
+ */
+export function packSurfaceProjection(
+  projection: SurfaceProjection | null | undefined,
+  out: Float32Array,
+): void {
+  out.fill(0);
+  if (projection === null || projection === undefined) return;
+  const scale = projection.scale;
+  if (!Number.isFinite(scale) || scale <= 0) return;
+  out[0] = projection.kind === 'triplanar' ? 2 : 1;
+  out[1] = scale;
+  const sharpness = projection.sharpness ?? 4;
+  out[2] = Number.isFinite(sharpness) ? Math.min(Math.max(sharpness, 1), 64) : 4;
+}
+
+/** Whether a material projects its maps at all. */
+export function projects(projection: SurfaceProjection | null | undefined): boolean {
+  return (
+    projection !== null &&
+    projection !== undefined &&
+    Number.isFinite(projection.scale) &&
+    projection.scale > 0
+  );
+}

package/src/render/surfaceTexture.ts

@@ -8,6 +8,8 @@
  * 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 { SurfaceLayers } from './surfaceLayers.ts';
+import type { SurfaceProjection } from './surfaceProjection.ts';
 import type { SurfaceModel } from './surfaceModel.ts';
 import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
 import {
@@ -213,6 +215,34 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * and an 8-bit frame clips the brighter peak without `hdrScene`.
    */
   physicalSpecular?: boolean;
+  /**
+   * Texture coordinates from where a point is in the world rather than from the mesh: `'planar'`
+   * across the horizontal axes for ground, `'triplanar'` on three planes for walls and rock, at so
+   * many repeats a metre. Absent, the mesh's, as every material's were. **A lit switch**, compiled in
+   * the first time a material asks, so a scene that never asks pays nothing. See
+   * `surfaceProjection.ts` for what it gives up.
+   */
+  projection?: SurfaceProjection | null;
+  /**
+   * How much light from behind a thin surface lets through, 0 to 1: a banner lit from behind, a
+   * leaf against the sun, a lampshade. The light falling on the far side — the sun, lamps, area
+   * lights, DriftLight — reaches the eye through the surface, coloured by its own colour; a metal
+   * lets none through. 0, the default, is every material as it was. Two-sided or not: a one-sided
+   * surface seen from its front shows the light behind it as well.
+   *
+   * **What it gives up**: a thin surface, not a volume, so a thick one lets through as much as a
+   * sheet; the light behind is not blurred by the surface; and none of it on glass, which lets
+   * light through by its own rule (`TranslucentMeshOptions.glass`).
+   */
+  diffuseTransmission?: number;
+  /**
+   * Up to five layers blended by a mask, each at its own repeat: `albedo`, `normal` and `orm` arrays
+   * whose layers are the material's, and a mask laying each over the ones before it. Absent, the
+   * material is one layer, as every material was. **A lit switch**, compiled in the first time a
+   * material asks. The mask is read where `modelMap` goes, so a material carries one or the other.
+   * See `surfaceLayers.ts` for what it gives up.
+   */
+  layers?: SurfaceLayers<Texture> | null;
 }
 
 export interface SurfaceTextureOptions {

package/src/render/vertexPacking.ts

@@ -0,0 +1,109 @@
+import type { MeshData } from '@driftengine/drft';
+
+/**
+ * How each of a mesh's vertex attributes travels to the device, decided once from its data and
+ * bound by each backend: as floats, as sixteen-bit fixed point, or as one value every vertex
+ * shares.
+ *
+ * **Only what reads back as it went, or near enough that no picture can tell.** One value every
+ * vertex shares is exact, and is a constant rather than a stream: a colour or an emissive naming
+ * no difference between vertices costs nothing a vertex, where both were always stored per vertex.
+ * A unit direction — a normal, a tangent and its handedness — in sixteen-bit signed fixed point is
+ * within 1/32767 a component, a few thousandths of a degree: measured against floats, 12 pixels of
+ * 921,600 moved in one published scene, by 2 of 255 on average, and none in the other eight.
+ * Colours and skin weights inside [0, 1] in sixteen-bit unsigned fixed point are within 1/65535. A
+ * textured vertex with a tangent frame, white and not glowing, goes from 64 bytes to 36 on WebGPU.
+ *
+ * **What it gives up.** Eight-bit normals would save four bytes more and are not taken: a normal in
+ * steps of 1/127 can band a highlight. **Texture coordinates stay floats**, in any range: a
+ * coordinate on a tile's far edge rounds past it in sixteen-bit fixed point, by 1/131,070, and a
+ * pixel there samples the neighbouring tile of an atlas — measured as 29 pixels moved by 62 of 255
+ * in the voxel scene, every one at a face's edge — and a half float, which steps by a 2048th near
+ * 1.0, is worse. A dynamic mesh's normals stay floats, because each rewrite would have to be packed
+ * on the CPU. What would make this wrong is a value outside its range, which the range check sends
+ * to floats rather than clamping, or a shader reading an attribute as something other than the
+ * value it carries.
+ */
+
+/** Floats; sixteen-bit fixed point, signed or not; or one value for every vertex. */
+export type AttributePacking = 'float' | 'snorm16' | 'unorm16' | 'constant';
+
+/** The attributes this decides for. Every other one travels as floats. */
+export const PACKED_ATTRIBUTES = [
+  'normals',
+  'tangents',
+  'colors',
+  'emissive',
+  'weights',
+  'weights2',
+] as const;
+
+export type PackedAttribute = (typeof PACKED_ATTRIBUTES)[number];
+
+export type VertexPacking = Readonly<Record<PackedAttribute, AttributePacking>>;
+
+/** The choice for this mesh. `dynamic` is a mesh whose positions and normals are rewritten. */
+export function vertexPackingOf(data: MeshData, dynamic: boolean): VertexPacking {
+  return {
+    normals: dynamic ? 'float' : fixedOrFloat(data.normals, -1),
+    tangents: fixedOrFloat(data.tangents, -1),
+    colors: shared(data.colors, 3) ? 'constant' : fixedOrFloat(data.colors, 0),
+    emissive: shared(data.emissive, 1) ? 'constant' : 'float',
+    weights: fixedOrFloat(data.weights, 0),
+    weights2: fixedOrFloat(data.weights2, 0),
+  };
+}
+
+/**
+ * What 1 is in each fixed point, the values WebGPU's `snorm16` and `unorm16` and WebGL2's
+ * normalised `SHORT` and `UNSIGNED_SHORT` divide by. A value is stored rounded to nearest, so 1, 0
+ * and -1 come back exactly.
+ */
+export const SNORM16_ONE = 32767;
+export const UNORM16_ONE = 65535;
+
+/** One value in the fixed point whose 1 is `one`, rounded to nearest: the only place it is. */
+export function toFixed16(value: number, one: number): number {
+  return Math.round(value * one);
+}
+
+/** An attribute's values in its fixed point, tightly, for a backend reading separate arrays. */
+export function fixedArray(
+  values: Float32Array,
+  packing: 'snorm16' | 'unorm16',
+): Int16Array | Uint16Array {
+  const out =
+    packing === 'snorm16' ? new Int16Array(values.length) : new Uint16Array(values.length);
+  const one = packing === 'snorm16' ? SNORM16_ONE : UNORM16_ONE;
+  for (let at = 0; at < values.length; at++) out[at] = toFixed16(values[at] as number, one);
+  return out;
+}
+
+/** How `name` travels under this packing: floats for an attribute it does not decide for. */
+export function packingFor(packing: VertexPacking, name: string): AttributePacking {
+  return (packing as Readonly<Record<string, AttributePacking>>)[name] ?? 'float';
+}
+
+/** The value every vertex shares, for an attribute packed as `'constant'`. */
+export function sharedValue(values: Float32Array, width: number): number[] {
+  return Array.from(values.subarray(0, width));
+}
+
+/** Fixed point where every value lies in [low, 1]; floats otherwise, and for a NaN. */
+function fixedOrFloat(values: Float32Array | undefined, low: -1 | 0): AttributePacking {
+  if (values === undefined) return 'float';
+  for (let at = 0; at < values.length; at++) {
+    const value = values[at] as number;
+    if (!(value >= low && value <= 1)) return 'float';
+  }
+  return low < 0 ? 'snorm16' : 'unorm16';
+}
+
+/** Whether every vertex holds the first vertex's value. Not for a mesh of none. */
+function shared(values: Float32Array, width: number): boolean {
+  if (values.length < width) return false;
+  for (let at = width; at < values.length; at++) {
+    if (values[at] !== values[at % width]) return false;
+  }
+  return true;
+}

package/dist/render/backend/webgpu/gpuSkinnedCloth.d.ts

@@ -1,74 +0,0 @@
-import type { SkinnedClothSetup } from '@driftengine/physics';
-import { GpuClothParticles } from './clothTextures.ts';
-/** One garment's solver on the device, and the particle textures it publishes into. */
-export declare class GpuSkinnedCloth {
-    private readonly device;
-    /** The particles a bound mesh draws by: see `RendererApi.setCloth`. */
-    readonly particles: GpuClothParticles;
-    readonly count: number;
-    private readonly control;
-    private readonly packed;
-    private readonly kernels;
-    private readonly buffers;
-    private readonly state;
-    private readonly frameData;
-    private readonly stepSlots;
-    private readonly group;
-    private readonly outputs;
-    private readonly frameStaging;
-    private readonly stepStaging;
-    private readonly stepFloats;
-    private readonly stepWords;
-    /** Each batch's slot, by kind and by whether it opens a substep's iterations. */
-    private readonly batchSlot;
-    /** The air the steps drag toward: the set-up's until `setWind`, written into every step. */
-    private readonly wind;
-    private readonly groups;
-    private readonly substeps;
-    private readonly iterations;
-    private encoder;
-    private pass;
-    private slot;
-    /** Where the pose a step starts from and the one it moves toward sit in `pose`, in floats. */
-    private fromAt;
-    private toAt;
-    constructor(device: GPUDevice, setup: SkinnedClothSetup);
-    /**
-     * One frame: the rig's pose, `dt` of the caller's time in whole fixed steps, and the particles at
-     * the frame's `alpha` published for the draws that follow, as the particles of `frame`.
-     */
-    advance(globals: Float32Array, model: Float32Array, dt: number, frame: number): void;
-    /** The frame's sample of the scene's wind, for the steps to come. See `SkinnedCloth.setWind`. */
-    setWind(x: number, y: number, z: number): void;
-    /** Back to the skinned pose, settled; the next `advance` publishes it. */
-    reset(): void;
-    /**
-     * The particles where the last step left them, read back: for the parity check, which compares
-     * them with the CPU solver's. Not for a frame — it waits on the device.
-     */
-    read(): Promise<Float32Array>;
-    /** Its buffers; the particle textures are the renderer's to retire with the frame. */
-    dispose(): void;
-    private targetsChanged;
-    private rest;
-    private step;
-    /** Every batch of one kind, in colour order, each a dispatch over its range. */
-    private batches;
-    private dispatch;
-    private passFor;
-    /** Send what has been recorded: every slot it reads was written ahead of it on the queue. */
-    private flush;
-    /**
-     * A step's slot: its fraction, blend and alpha, the poses it reads, and — where `targets` is
-     * given — the share of the character's motion the cloth is carried by, as `carryParticles` takes
-     * it. Returns the slot's byte offset.
-     */
-    private takeSlot;
-    /** `carryParticles`' rotation, origin and move, into the step's slot; carry 0 where none. */
-    private writeCarry;
-    /** The pose's skin matrices — or the model, for a cloth with no rig — and its colliders. */
-    private writeFrameData;
-    private constants;
-    /** Each batch's range, twice — opening a substep's iterations and not — at a slot each. */
-    private writeBatches;
-}