@driftengine/core 4.9.0 → 4.11.0

package/src/render/surfaceTexture.ts

@@ -8,9 +8,16 @@
  * 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 { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSource.ts';
+import {
+  compressedLayers,
+  isCompressedSource,
+  planBlocks,
+  refuseBlockUpdate,
+} from './compressedSource.ts';
 import type {
   BlockFormat,
   CompressedTextureFormat,
@@ -119,7 +126,7 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * which is every light's default too, so a scene that names no channel is lit as it always was.
    *
    * A point or spot light shades this surface only where its `PointLightSet.lightChannels` and this
-   * share a bit — Unreal's lighting channels. A character's own key and rim lights on channel 2,
+   * share a bit — lighting channels. A character's own key and rim lights on channel 2,
    * and the character's materials on 3, light the character and leave the floor around it as the
    * stage's lights alone have it. **What it does not reach**: the sun, the sky and the probes, area
    * lights, DriftLight's volume and the GPU-driven pipeline light every surface whatever its mask.
@@ -153,6 +160,22 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * which is the opposite of what the caller asked for.
    */
   occlusionStrength?: number;
+  /**
+   * How much of the environment this material's draws mirror, 0 to 1: the number
+   * `setSurfaceReflectivity` sets for every draw, stated by the material for its own. Absent, its
+   * draws wear the setter's, as every material's did before this existed.
+   *
+   * **Here so a static list can carry it.** A list keeps each entry's material and none of the
+   * renderer's state between draws (`createStaticDraws`), so a stage whose batches each mirror their
+   * own share of a baked reflection says so in the material it records. What it gives up is nothing a
+   * setter could do: one called after this material is set is ignored for the material's draws.
+   */
+  reflectivity?: number;
+  /**
+   * How bright the environment this material's draws reflect is: `setEnvironmentGain`'s number,
+   * stated by the material for its own, and absent the setter's. Held non-negative.
+   */
+  environmentGain?: number;
   /**
    * Scales the emissive map, per channel. Default 1.
    *
@@ -176,14 +199,14 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
   modelMap?: Texture | null;
   /**
    * Whether a lamp's and the sun's highlight on this surface is GGX's own, `π · D · Vis · F · N·L`,
-   * as Unreal and this engine's skin and eye shade it, rather than the engine's lobe scaled to a
-   * peak of one. **False by default**, every surface as it was.
+   * as physically based renderers and this engine's skin and eye shade it, rather than the engine's
+   * lobe scaled to a peak of one. **False by default**, every surface as it was.
    *
    * The peak-normalised lobe is a look control: the specular attribute says how strong a highlight
    * is and roughness how wide, apart. Physical, they are entangled as they are in a real surface —
    * the peak is `1 / (4 α²)` of the light head-on, so a polished surface's highlight is many times
    * the look's and a rough one's lower and broader — and the specular attribute is read as the
-   * reflectance at normal incidence, F0: Unreal's `0.08 × Specular`, 0.04 at its default. Fresnel
+   * reflectance at normal incidence, F0: `0.08 × Specular`, 0.04 at its default. Fresnel
    * then brightens every surface toward grazing, not only a metal. A rectangle's highlight is the
    * lobe integrated over it with the attribute as F0 already, so it is unchanged either way.
    *
@@ -192,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 {
@@ -292,7 +343,9 @@ export class SurfaceTexture {
   /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
   private effectsTable: WebGLTexture | null = null;
   /** The block format a compressed texture holds, or null for one uploaded from images. */
-  private readonly blockFormat: BlockFormat | null;
+  private blockFormat: BlockFormat | null;
+  /** How the texture is sampled, kept so blocks swapped in by `update` are sampled the same way. */
+  private readonly sampling: { wrap: number; nearest: boolean; anisotropy: number };
   /** Level 0's size, which `flatLayer` copies; kept as `update` changes it. */
   private width = 0;
   private height = 0;
@@ -404,27 +457,13 @@ export class SurfaceTexture {
       this.storage = this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA8;
       uploadImages(gl, sources, this.srgb);
     }
-    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
-    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, wrap);
-    /* Nearest where the caller said their pixels are the subject; see `filter`. The mip chain is
-       still blended between levels, because that is minification and this option is about
-       magnification. */
-    const nearest = options.filter === 'nearest';
-    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
-    gl.texParameteri(
-      gl.TEXTURE_2D_ARRAY,
-      gl.TEXTURE_MIN_FILTER,
-      this.mipmapped
-        ? nearest
-          ? gl.NEAREST_MIPMAP_LINEAR
-          : gl.LINEAR_MIPMAP_LINEAR
-        : nearest
-          ? gl.NEAREST
-          : gl.LINEAR,
-    );
-
+    this.sampling = {
+      wrap,
+      nearest: options.filter === 'nearest',
+      anisotropy: options.anisotropy ?? DEFAULT_ANISOTROPY,
+    };
+    this.applySampling(gl);
     if (this.mipmapped && this.blockFormat === null) gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
-    applyAnisotropy(gl, options.anisotropy ?? DEFAULT_ANISOTROPY);
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
 
     /* Half floats, nearest, clamped: a table read by texelFetch, whose every whole number is under
@@ -475,9 +514,17 @@ export class SurfaceTexture {
    * Not a hot path: it re-uploads the whole image and regenerates the chain. A caller
    * doing this every frame at any size wants to know that it costs what it costs.
    */
-  update(gl: WebGL2RenderingContext, source: TexImageSource): void {
+  update(
+    gl: WebGL2RenderingContext,
+    source: TexImageSource | CompressedTextureSource,
+    compressed: readonly CompressedTextureFormat[] = [],
+  ): void {
     if (this.texture === null) return;
     refuseArrayUpdate(this.layers);
+    if (isCompressedSource(source)) {
+      this.swapToBlocks(gl, source, compressed);
+      return;
+    }
     refuseBlockUpdate(this.blockFormat);
     const { width, height } = sourceSize(source);
     this.width = width;
@@ -501,6 +548,56 @@ export class SurfaceTexture {
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
   }
 
+  /**
+   * Blocks in place of the image, behind the same handle: **a new GL object** rather than the
+   * image's levels respecified, because a chain shorter than the image's would leave the levels
+   * past it allocated, and immutable storage could not be respecified at all. Sampled as the image
+   * was, and refused before anything changes where the context does not take the format.
+   */
+  private swapToBlocks(
+    gl: WebGL2RenderingContext,
+    source: CompressedTextureSource,
+    compressed: readonly CompressedTextureFormat[],
+  ): void {
+    const plan = planBlocks([source], this.srgb, compressed);
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('SurfaceTexture: createTexture failed');
+    this.dropFlat(gl);
+    if (this.texture !== null) gl.deleteTexture(this.texture);
+    this.texture = texture;
+    this.blockFormat = source.format;
+    this.width = source.width;
+    this.height = source.height;
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+    uploadCompressedArray(gl, plan.name, [source], this.mipmapped ? plan.levels : 1);
+    this.applySampling(gl);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+  }
+
+  /**
+   * Wrap, filters and anisotropy on the bound texture. Nearest where the caller said their pixels
+   * are the subject; see `filter`. The mip chain is still blended between levels, because that is
+   * minification and this option is about magnification.
+   */
+  private applySampling(gl: WebGL2RenderingContext): void {
+    const { wrap, nearest, anisotropy } = this.sampling;
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, wrap);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
+    gl.texParameteri(
+      gl.TEXTURE_2D_ARRAY,
+      gl.TEXTURE_MIN_FILTER,
+      this.mipmapped
+        ? nearest
+          ? gl.NEAREST_MIPMAP_LINEAR
+          : gl.LINEAR_MIPMAP_LINEAR
+        : nearest
+          ? gl.NEAREST
+          : gl.LINEAR,
+    );
+    applyAnisotropy(gl, anisotropy);
+  }
+
   /**
    * Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into
    * by `captureScene`. Engine-internal, as `bind` is.

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;
-}