@driftengine/core 4.11.1 → 4.12.0

package/src/render/surfaceLayerLooks.ts

@@ -0,0 +1,155 @@
+/**
+ * Which layer of a layered material's arrays each of its layers reads, and how each looks: the
+ * fifteen vectors `shaders/flat/layerLooks.ts` reads, packed from `SurfaceMaterial.layers`.
+ *
+ * **Why a material needs these at all.** Layers read from the material's own arrays in order, so
+ * a texture worn by fifty materials in fifty tints had to be baked fifty times, each with its tint,
+ * its roughness range and its normal strength in the pixels. Picked by index from arrays the
+ * materials share, and given their look as numbers, each texture is held once: a set of layered
+ * materials built from a few textures costs those textures rather than one copy per material.
+ *
+ * **What it gives up**: fifteen fragment uniform vectors, so it is a lit switch of its own,
+ * `LAYER_LOOKS`, which a device short of vectors refuses while still drawing the layers; a layer's
+ * look is a handful of numbers, not a graph; and every layer is still read wherever any shows, as
+ * `surfaceLayers.ts` says, now from arrays that may be large.
+ */
+import type { Vec3 } from '../math/color.ts';
+import type { SurfaceLayers } from './surfaceLayers.ts';
+import { MAX_SURFACE_LAYERS, across } from './surfaceLayers.ts';
+
+/**
+ * One layer's own look, applied to what it reads before the layers are blended. Every field is the
+ * identity where it is absent, so a material names only what differs.
+ */
+export interface SurfaceLayerLook {
+  /** Multiplies the layer's colour, linear. Above 1 brightens it. Absent: `[1, 1, 1]`. */
+  readonly tint?: Vec3;
+  /** The roughness the ORM's green channel is spread over, from its 0 to its 1. Absent: `[0, 1]`. */
+  readonly roughness?: readonly [number, number];
+  /** The metalness the ORM's blue channel is spread over, the same way. Absent: `[0, 1]`. */
+  readonly metalness?: readonly [number, number];
+  /**
+   * How far the layer's normal map bends the surface: its tangent-space x and y times this, before
+   * the layers' normals are blended. 0 is flat, 1 the map as it is. Absent: 1.
+   */
+  readonly normalStrength?: number;
+  /**
+   * The layer's specular, in the units a mesh's vertices carry theirs: how strong a highlight is,
+   * and under `physicalSpecular` the reflectance head-on, `0.08 × specular`. Blended across the
+   * layers as their colours are. Absent: the surface's own, as its vertices give it.
+   */
+  readonly specular?: number;
+}
+
+/** What an occlusion read at the mesh's own coordinates darkens, and how far. */
+export interface SurfaceMeshOcclusion {
+  /** 0 to 1: the surface times `mix(1, occlusion, strength)`. Absent: 1. */
+  readonly strength?: number;
+  /**
+   * `'color'`, the default, darkens the blended colour, and so every light on it, the sun's too.
+   * `'ambient'` darkens the ambient light alone, sky, ground and probe, as an ambient occlusion
+   * does, leaving the sun, the lamps and the reflections as they were.
+   */
+  readonly into?: 'color' | 'ambient';
+  /** The range the occlusion's red is spread over, from its 0 to its 1. Absent: `[0, 1]`. */
+  readonly range?: readonly [number, number];
+}
+
+/** Floats `packLayerLooks` writes: fifteen vectors. */
+export const LOOK_FLOATS = 60;
+
+/** The specular a layer is packed with when it names none: the surface's own, as its vertices give it. */
+const OWN_SPECULAR = -1;
+
+/**
+ * Whether a material asks for anything the `LAYER_LOOKS` switch carries: layers picked by index,
+ * extra maps placed somewhere other than just past the layers, a look, a repeat that is a pair, or
+ * a mesh occlusion.
+ */
+export function asksLayerLooks<Texture>(
+  layers: SurfaceLayers<Texture> | null | undefined,
+): boolean {
+  if (layers === null || layers === undefined) return false;
+  return (
+    layers.arrayLayers !== undefined ||
+    layers.extrasAt !== undefined ||
+    layers.looks !== undefined ||
+    layers.repeats.some((repeat) => typeof repeat !== 'number') ||
+    occlusionOf(layers.meshOcclusion).strength > 0
+  );
+}
+
+/**
+ * `layers` into `out`, fifteen vectors, the identity wherever a material says nothing — which is
+ * also what a layered material that asks for none of this is drawn with once another has switched
+ * `LAYER_LOOKS` on, so it must draw exactly as it did before.
+ *
+ * - **0 to 7**: the array layer each layer reads, base first (layer `i` where not given); where the
+ *   maps beyond the layers start (the layer count where not given); the mesh occlusion's strength,
+ *   and what it darkens, 0 the colour and 1 the ambient light.
+ * - **8 to 47**: two vectors a layer, base first: its tint and its normal strength, then its
+ *   roughness range and its metalness range.
+ * - **48 to 59**: each layer's specular (−1 for the surface's own), each layer's repeat down (its
+ *   repeat across where it gave one number), and the range the occlusion is spread over.
+ *
+ * An array layer that is not a whole number at or above 0 reads layer `i`; a start that is not one
+ * is the count; a strength is held to 0..1; a tint channel, a normal strength or a specular that is
+ * not a number at or above 0 is the identity; a repeat down that is not a positive number is the
+ * repeat across; a range end that is not a number is the identity's end.
+ */
+export function packLayerLooks<Texture>(
+  layers: SurfaceLayers<Texture> | null | undefined,
+  out: Float32Array,
+): void {
+  const count = Math.min(layers?.repeats.length ?? 0, MAX_SURFACE_LAYERS);
+  const picks = layers?.arrayLayers;
+  for (let i = 0; i < MAX_SURFACE_LAYERS; i++) out[i] = arrayLayer(picks?.[i], i);
+  out[5] = arrayLayer(layers?.extrasAt, count);
+  const occlusion = occlusionOf(layers?.meshOcclusion);
+  out[6] = occlusion.strength;
+  out[7] = occlusion.into === 'ambient' ? 1 : 0;
+  for (let i = 0; i < MAX_SURFACE_LAYERS; i++) {
+    const look = layers?.looks?.[i] ?? null;
+    const at = 8 + i * 8;
+    out[at] = atLeastZero(look?.tint?.[0], 1);
+    out[at + 1] = atLeastZero(look?.tint?.[1], 1);
+    out[at + 2] = atLeastZero(look?.tint?.[2], 1);
+    out[at + 3] = atLeastZero(look?.normalStrength, 1);
+    out[at + 4] = finiteOr(look?.roughness?.[0], 0);
+    out[at + 5] = finiteOr(look?.roughness?.[1], 1);
+    out[at + 6] = finiteOr(look?.metalness?.[0], 0);
+    out[at + 7] = finiteOr(look?.metalness?.[1], 1);
+    out[48 + i] = atLeastZero(look?.specular, OWN_SPECULAR);
+    const repeat = layers?.repeats[i];
+    const acrossIt = positiveOr(across(repeat), 1);
+    out[53 + i] = typeof repeat === 'object' ? positiveOr(repeat[1], acrossIt) : acrossIt;
+  }
+  out[58] = finiteOr(occlusion.range?.[0], 0);
+  out[59] = finiteOr(occlusion.range?.[1], 1);
+}
+
+/** The number form of `meshOcclusion` as the object form, the strength held to 0..1. */
+function occlusionOf(
+  occlusion: number | SurfaceMeshOcclusion | undefined,
+): SurfaceMeshOcclusion & { readonly strength: number } {
+  const given =
+    typeof occlusion === 'number' ? { strength: occlusion } : (occlusion ?? { strength: 0 });
+  const strength = given.strength ?? 1;
+  return { ...given, strength: Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 1) : 0 };
+}
+
+function arrayLayer(value: number | undefined, otherwise: number): number {
+  return value !== undefined && Number.isInteger(value) && value >= 0 ? value : otherwise;
+}
+
+function atLeastZero(value: number | undefined, otherwise: number): number {
+  return value !== undefined && Number.isFinite(value) && value >= 0 ? value : otherwise;
+}
+
+function positiveOr(value: number | undefined, otherwise: number): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? value : otherwise;
+}
+
+function finiteOr(value: number | undefined, otherwise: number): number {
+  return value !== undefined && Number.isFinite(value) ? value : otherwise;
+}

package/src/render/surfaceLayers.ts

@@ -2,6 +2,7 @@
  * A material blended from layers by a mask: `SurfaceMaterial.layers`, the four vectors
  * `shaders/flat/layered.ts` reads it from, and the decisions both backends take about it.
  */
+import type { SurfaceLayerLook, SurfaceMeshOcclusion } from './surfaceLayerLooks.ts';
 import type { SurfaceProjection } from './surfaceProjection.ts';
 
 /** The most layers a material blends: a base and one for each of the mask's four channels. */
@@ -10,8 +11,9 @@ 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
+ * **Layer `i` is layer `i` of the material's arrays**, unless `arrayLayers` picks another: `albedo`,
+ * `normal` and `orm` each an array whose layers are the material's layers, 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.
  * Where the material has a `projection`, the layers are read at the world's horizontal position
  * instead, so a repeat is so many a metre (with the projection's own scale at 1). **The mask** is
@@ -23,8 +25,13 @@ export const MAX_SURFACE_LAYERS = 5;
  * **Maps beyond the layers ride the material's own arrays, after its layers**, so they take no
  * texture binding of their own — the lit stage has none to spare: a mask the ORM array carries
  * (`mask: 'orm'`) is the ORM array's layer just past the layers, an `addMask` the one after that,
- * and `meshNormal` the normal array's layer just past the layers. Each shares its array's size and
- * format, so a four-channel mask wants an array that stores four.
+ * a `meshOcclusion` the one after any of those, and `meshNormal` the normal array's layer just past
+ * the layers. `extrasAt` moves where "just past" is, for materials that share arrays. Each shares
+ * its array's size and format, so a four-channel mask wants an array that stores four.
+ *
+ * **Shared arrays and a look of each layer's own** — `arrayLayers`, `extrasAt`, `looks` and
+ * `meshOcclusion` — are a lit switch of their own, `LAYER_LOOKS`, and `surfaceLayerLooks.ts` says
+ * what they cost.
  *
  * **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
@@ -40,8 +47,12 @@ export interface SurfaceLayers<Texture> {
    * vertex colour's red, green and blue, which then weights the layers instead of tinting them.
    */
   readonly mask: Texture | 'orm' | 'vertex';
-  /** Each layer's repeats across the mesh's coordinates, base first: one to five of them. */
-  readonly repeats: readonly number[];
+  /**
+   * Each layer's repeats across the mesh's coordinates, base first: one to five of them. A pair is a
+   * repeat across and a repeat down apart, moss stretched along a trunk; a pair is drawn through the
+   * `LAYER_LOOKS` switch, which a single number does not need.
+   */
+  readonly repeats: readonly (number | readonly [number, number])[];
   /** The layer the emissive map glows on, 0 to 4. Absent: everywhere, as on any material. */
   readonly emissiveLayer?: number;
   /**
@@ -77,6 +88,34 @@ export interface SurfaceLayers<Texture> {
    * layer repeating forty times across it cannot carry.
    */
   readonly meshNormal?: boolean;
+  /**
+   * Which layer of the material's albedo, normal and ORM arrays each layer reads, base first, so
+   * many materials can share one array of each kind and hold every texture once. Absent, or past
+   * its end, layer `i` reads layer `i`. The same index reads all three arrays, so a texture's three
+   * maps sit at the same layer of each.
+   */
+  readonly arrayLayers?: readonly number[];
+  /**
+   * The layer of each array where the maps beyond the layers start: the ORM array's mask, added
+   * mask and mesh occlusion, in that order, and the normal array's mesh normal. Absent: just past
+   * the layers, at the layer count — which is no place for them once materials share arrays.
+   */
+  readonly extrasAt?: number;
+  /**
+   * Each layer's own look, base first: a tint, the ranges its ORM's roughness and metalness are
+   * spread over, and how far its normal map bends the surface. Absent or null for a layer: the map
+   * as it is.
+   */
+  readonly looks?: readonly (SurfaceLayerLook | null | undefined)[];
+  /**
+   * An occlusion read at the mesh's own coordinates — the red of the ORM array's layer after the
+   * layers and any mask or added mask the array carries — darkening the surface by a strength from 0
+   * to 1: the large shading of a cliff that layers repeating across it cannot carry, as
+   * `meshNormal` carries its shape. A number is that strength, darkening the blended colour; the
+   * object form also chooses what it darkens and the range its red is spread over. Absent or 0:
+   * none.
+   */
+  readonly meshOcclusion?: number | SurfaceMeshOcclusion;
 }
 
 /** Floats `packSurfaceLayers` writes: four vectors. */
@@ -104,7 +143,8 @@ export function packSurfaceLayers<Texture>(
   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++) out[i] = positive(i < count ? layers.repeats[i] : 1);
+  for (let i = 0; i < MAX_SURFACE_LAYERS; i++)
+    out[i] = positive(i < count ? across(layers.repeats[i]) : 1);
   out[5] = count;
   const glow = layers.emissiveLayer;
   out[6] = glow !== undefined && Number.isInteger(glow) && glow >= 0 && glow < count ? glow : -1;
@@ -162,6 +202,11 @@ export function layeredProjection<Texture>(
   return { kind: 'planar', scale: projection.scale };
 }
 
+/** A layer's repeat across: the number, or the first of a pair. The second is `LAYER_LOOKS`'. */
+export function across(repeat: number | readonly [number, number] | undefined): number | undefined {
+  return typeof repeat === 'number' || repeat === undefined ? repeat : repeat[0];
+}
+
 /** A layer an added mask or the facing may name: one a channel lays, 1 to `count − 1`, or −1. */
 function laidLayer(layer: number | undefined, count: number): number {
   return layer !== undefined && Number.isInteger(layer) && layer >= 1 && layer < count ? layer : -1;