@driftengine/core 4.13.1 → 4.13.3

package/src/render/mesh.ts

@@ -115,6 +115,12 @@ export class Mesh {
    * this — two references, and only where a consumer asked.
    */
   private readonly deformable: { positions: WebGLBuffer; normals: WebGLBuffer } | null = null;
+  /** A dynamic mesh's position and normal buffers, for a pose written on the device; else null. */
+  get streams(): { readonly positions: WebGLBuffer; readonly normals: WebGLBuffer } | null {
+    return this.deformable;
+  }
+  /** The colour buffer, kept so `updateColors` can rewrite it. Null unless `dynamicColors`. */
+  private readonly recolourable: WebGLBuffer | null = null;
   /** How many floats the position buffer holds, so an update of the wrong size is refused. */
   private readonly positionFloats: number;
   /**
@@ -222,8 +228,15 @@ export class Mesh {
    * and the default is the fast path: filling a buffer with `bufferData` in one call skips the
    * zero-fill that `bufferData(size)` then `bufferSubData` pays for, and every mesh in the
    * engine that does not need to be spread should keep skipping it.
+   * @param dynamicColors Colours as floats in a buffer kept for `updateColors`.
    */
-  constructor(gl: WebGL2RenderingContext, data: MeshData, dynamic = false, spread = false) {
+  constructor(
+    gl: WebGL2RenderingContext,
+    data: MeshData,
+    dynamic = false,
+    spread = false,
+    dynamicColors = false,
+  ) {
     validateMeshData(data);
     this.spread = spread;
     this.hasUvs = data.uvs !== undefined;
@@ -243,11 +256,15 @@ export class Mesh {
      */
     const usage = dynamic ? gl.DYNAMIC_DRAW : gl.STATIC_DRAW;
     /* How each attribute travels: sixteen-bit fixed point, or one value as a constant. */
-    const packing = vertexPackingOf(data, dynamic);
+    const packing = vertexPackingOf(data, dynamic, dynamicColors);
     const positions = this.attachAttribute(gl, ATTR_POSITION, data.positions, 3, usage);
     const normals = this.attachAttribute(gl, ATTR_NORMAL, data.normals, 3, usage, packing.normals);
     if (dynamic) this.deformable = { positions, normals };
-    this.attachShared(gl, ATTR_COLOR, data.colors, 3, packing.colors);
+    if (packing.colors === 'stream') {
+      this.recolourable = this.attachAttribute(gl, ATTR_COLOR, data.colors, 3, gl.DYNAMIC_DRAW);
+    } else {
+      this.attachShared(gl, ATTR_COLOR, data.colors, 3, packing.colors);
+    }
     this.attachShared(gl, ATTR_EMISSIVE, data.emissive, 1, packing.emissive);
     /*
      * Absent means "not shiny", supplied as a constant rather than as a buffer of
@@ -463,9 +480,9 @@ export class Mesh {
   /**
    * Rewrite this mesh's positions, and its normals where the caller has them.
    *
-   * **Only the two attributes that move.** Colour, emissive and the rest describe what a surface
-   * *is* and do not change because it bent; rewriting them would be uploading unchanged bytes
-   * every frame. A caller with genuinely changing colour wants a second mesh or a tint.
+   * **Only the two attributes that move.** Emissive and the rest describe what a surface *is* and
+   * do not change because it bent; rewriting them would be uploading unchanged bytes every frame.
+   * A caller whose colours change has `updateColors`, on a mesh made `dynamicColors`.
    *
    * **The bounds are recomputed**, because everything that decides whether this is on screen
    * starts from them — a cloth that blew sideways out of its original box would be culled while
@@ -495,6 +512,30 @@ export class Mesh {
     }
   }
 
+  /**
+   * Rewrite this mesh's colours, three floats a vertex, into the buffer they have to themselves.
+   *
+   * Nothing else moves, the bounds included: a colour does not change where a vertex is.
+   */
+  updateColors(gl: WebGL2RenderingContext, colors: Float32Array): void {
+    if (this.recolourable === null) {
+      throw new Error(
+        'this mesh was not created with { dynamicColors: true }, so its colours are packed or are ' +
+          'one value with no buffer at all, and cannot be rewritten. Say so at `createMesh`: the ' +
+          'flag gives the colours a buffer of their own.',
+      );
+    }
+    if (colors.length !== this.positionFloats) {
+      throw new Error(
+        `this mesh has ${this.positionFloats / 3} vertices and the colours have ` +
+          `${colors.length / 3}. A mesh's vertex count is fixed at creation: the index buffer, ` +
+          'the pipeline and every other attribute are sized against it.',
+      );
+    }
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.recolourable);
+    gl.bufferSubData(gl.ARRAY_BUFFER, 0, colors);
+  }
+
   /**
    * One attribute's buffer, as floats or in its sixteen-bit fixed point (`vertexPacking.ts`), which
    * WebGL2 reads back through a normalised `SHORT` or `UNSIGNED_SHORT`: three lanes wide where
@@ -638,8 +679,9 @@ export function createMeshIncremental(
   gl: WebGL2RenderingContext,
   data: MeshData,
   dynamic = false,
+  dynamicColors = false,
 ): IncrementalMesh {
-  const mesh = new Mesh(gl, data, dynamic, true);
+  const mesh = new Mesh(gl, data, dynamic, true, dynamicColors);
   return { mesh, upload: mesh.uploads(gl) };
 }
 

package/src/render/pointSkin.ts

@@ -0,0 +1,178 @@
+/**
+ * A mesh posed on the device from weighted points in its joints' own spaces: the data, its checks,
+ * and the bounds a pose is culled by. Each backend's binding poses the vertices.
+ *
+ * **What it is for.** Some formats store a vertex as up to four points, each in the space of a
+ * joint, with a weight each and a normal in the space of the first: posed, the vertex is the
+ * weighted sum of each point moved by its joint. That is not ordinary skinning, which moves one
+ * bind-pose position by a blend of joints, so a rig of that kind had to be posed on the main thread
+ * and its positions uploaded every frame. Reported at 38% of the main thread's drawing time.
+ * Posed on the device into a dynamic mesh's own buffers, the main thread hands over the joints.
+ *
+ * **Into a dynamic mesh rather than in the vertex stage**, because a skinned vertex stage has no
+ * attribute left for four more points, and every pass that draws a mesh would need a variant that
+ * reads them: lit, cast, glass, motion. Posed once into the mesh's positions and normals, it is an
+ * ordinary dynamic mesh to every one of them, motion vectors included. What it costs is the mesh's
+ * two buffers, written a pose, and a pass that runs before the draws.
+ *
+ * **The bounds are a box of spheres, not the posed vertices**, which the CPU never sees. Each joint
+ * reaches as far as the farthest point a weighted influence holds in its space, scaled by its
+ * largest axis; a weighted sum of points inside those spheres lies inside their box, scaled by the
+ * least and greatest sums of a vertex's weights. Conservative, so it culls nothing visible; loose
+ * by the joints' reach where a mesh is long and thin, which culls a little less than it could.
+ */
+import type { Bounds } from '../math/bounds.ts';
+import { MAX_JOINTS } from './skinPalette.ts';
+
+/** A point skin, one entry a vertex unless said otherwise. */
+export interface PointSkinData {
+  /** Four joint indices a vertex, as floats, as `MeshData.joints` is. */
+  readonly joints: Float32Array;
+  /** Four weights a vertex. An influence of weight 0 is skipped, whatever its joint and point. */
+  readonly weights: Float32Array;
+  /** Four points a vertex, three floats each: influence `k`'s point in joint `k`'s own space. */
+  readonly points: Float32Array;
+  /** One normal a vertex, in the space of its first joint. */
+  readonly normals: Float32Array;
+}
+
+/** How far a skin reaches from each joint, and what its weights sum to: what a pose's bounds need. */
+export interface PointSkinReach {
+  /** Joints a pose must hand over: one past the highest any vertex names and uses. */
+  readonly joints: number;
+  /** For each joint, the farthest point a weighted influence holds in its space; -1 where none. */
+  readonly reach: Float32Array;
+  /** The least and the greatest sum of one vertex's weights. */
+  readonly sums: readonly [number, number];
+}
+
+/** Refuse a skin whose arrays disagree with a mesh of `vertices`, or that names a joint past the rest. */
+export function validatePointSkin(data: PointSkinData, vertices: number): void {
+  const fail = (what: string): never => {
+    throw new Error(`point skin: ${what}`);
+  };
+  for (const [name, values, width] of [
+    ['joints', data.joints, 4],
+    ['weights', data.weights, 4],
+    ['points', data.points, 12],
+    ['normals', data.normals, 3],
+  ] as const) {
+    if (values.length !== vertices * width) {
+      fail(`${name} holds ${values.length / width} vertices and the mesh has ${vertices}`);
+    }
+  }
+  for (let at = 0; at < data.joints.length; at++) {
+    const joint = data.joints[at] as number;
+    if (!(Number.isInteger(joint) && joint >= 0 && joint < MAX_JOINTS)) {
+      fail(`vertex ${Math.floor(at / 4)} names joint ${joint}; a joint is 0 to ${MAX_JOINTS - 1}`);
+    }
+  }
+}
+
+/** Measure a skin's reach once, at creation. */
+export function reachOf(data: PointSkinData): PointSkinReach {
+  const reach = new Float32Array(MAX_JOINTS).fill(-1);
+  let joints = 0;
+  let least = Infinity;
+  let most = -Infinity;
+  const vertices = data.weights.length / 4;
+  for (let v = 0; v < vertices; v++) {
+    /* The first joint carries the normal, so it is named whatever its weight. */
+    joints = Math.max(joints, (data.joints[v * 4] as number) + 1);
+    let sum = 0;
+    for (let k = 0; k < 4; k++) {
+      const weight = data.weights[v * 4 + k] as number;
+      if (weight === 0) continue;
+      sum += weight;
+      const joint = data.joints[v * 4 + k] as number;
+      joints = Math.max(joints, joint + 1);
+      const at = (v * 4 + k) * 3;
+      const x = data.points[at] as number;
+      const y = data.points[at + 1] as number;
+      const z = data.points[at + 2] as number;
+      reach[joint] = Math.max(reach[joint] as number, Math.sqrt(x * x + y * y + z * z));
+    }
+    least = Math.min(least, sum);
+    most = Math.max(most, sum);
+  }
+  return {
+    joints,
+    reach: reach.slice(0, joints),
+    sums: vertices === 0 ? [1, 1] : [least, most],
+  };
+}
+
+/**
+ * The bounds of a pose, into the mesh's own: `matrices` holds each joint's transform into the
+ * mesh's model space, sixteen floats, column-major. Allocates nothing.
+ */
+export function poseBounds(matrices: Float32Array, skin: PointSkinReach, out: Bounds): void {
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (let j = 0; j < skin.joints; j++) {
+    const reach = skin.reach[j] as number;
+    if (reach < 0) continue;
+    const m = j * 16;
+    const scale = Math.sqrt(
+      Math.max(
+        columnLength2(matrices, m),
+        columnLength2(matrices, m + 4),
+        columnLength2(matrices, m + 8),
+      ),
+    );
+    const r = reach * scale;
+    const x = matrices[m + 12] as number;
+    const y = matrices[m + 13] as number;
+    const z = matrices[m + 14] as number;
+    minX = Math.min(minX, x - r);
+    minY = Math.min(minY, y - r);
+    minZ = Math.min(minZ, z - r);
+    maxX = Math.max(maxX, x + r);
+    maxY = Math.max(maxY, y + r);
+    maxZ = Math.max(maxZ, z + r);
+  }
+  if (minX > maxX) {
+    out.min.fill(0);
+    out.max.fill(0);
+    out.centre.fill(0);
+    out.radius = 0;
+    return;
+  }
+  /* A sum of weights other than one scales the box about the origin, by the least and the most. */
+  const [least, most] = skin.sums;
+  out.min[0] = Math.min(least * minX, most * minX);
+  out.min[1] = Math.min(least * minY, most * minY);
+  out.min[2] = Math.min(least * minZ, most * minZ);
+  out.max[0] = Math.max(least * maxX, most * maxX);
+  out.max[1] = Math.max(least * maxY, most * maxY);
+  out.max[2] = Math.max(least * maxZ, most * maxZ);
+  let radius2 = 0;
+  for (let axis = 0; axis < 3; axis++) {
+    const centre = ((out.min[axis] as number) + (out.max[axis] as number)) / 2;
+    out.centre[axis] = centre;
+    const half = (out.max[axis] as number) - centre;
+    radius2 += half * half;
+  }
+  out.radius = Math.sqrt(radius2);
+}
+
+/** The squared length of one column's first three components. */
+function columnLength2(m: Float32Array, at: number): number {
+  const x = m[at] as number;
+  const y = m[at + 1] as number;
+  const z = m[at + 2] as number;
+  return x * x + y * y + z * z;
+}
+
+/** Refuse a pose that hands over fewer joints than the skin names. */
+export function validatePose(matrices: Float32Array, skin: PointSkinReach): void {
+  if (matrices.length % 16 !== 0 || matrices.length / 16 < skin.joints) {
+    throw new Error(
+      `point skin: a pose of ${matrices.length / 16} joints for a skin that names ${skin.joints}`,
+    );
+  }
+}

package/src/render/rendererHarness.ts

@@ -125,6 +125,12 @@ export function recordingGl(
     ONE: 1,
     ONE_MINUS_SRC_ALPHA: 0x0303,
     TRIANGLES: 0x0004,
+    /* Transform feedback's, so a point skin's pose can be seen to discard, capture and undo both. */
+    POINTS: 0x0000,
+    RASTERIZER_DISCARD: 0x8c89,
+    TRANSFORM_FEEDBACK: 0x8e22,
+    TRANSFORM_FEEDBACK_BUFFER: 0x8c8e,
+    SEPARATE_ATTRIBS: 0x8c8d,
     /* The winding a pass names, so a test can tell which one it chose. */
     CW: 0x0900,
     CCW: 0x0901,

package/src/render/shader.ts

@@ -5,6 +5,8 @@ export function compileProgram(
   vertexSource: string,
   fragmentSource: string,
   label: string,
+  /** Vertex outputs captured by transform feedback, one buffer each; named before the link. */
+  feedback?: readonly string[],
 ): WebGLProgram {
   const vs = compileStage(gl, gl.VERTEX_SHADER, vertexSource, `${label}.vert`);
   const fs = compileStage(gl, gl.FRAGMENT_SHADER, fragmentSource, `${label}.frag`);
@@ -14,6 +16,9 @@ export function compileProgram(
 
   gl.attachShader(program, vs);
   gl.attachShader(program, fs);
+  if (feedback !== undefined) {
+    gl.transformFeedbackVaryings(program, feedback as string[], gl.SEPARATE_ATTRIBS);
+  }
   gl.linkProgram(program);
   gl.deleteShader(vs);
   gl.deleteShader(fs);

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/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