@driftengine/core 4.8.2 → 4.8.4

package/dist/render/surfaceModel.d.ts

@@ -0,0 +1,129 @@
+/**
+ * A material's shading model: how its surface answers light, when the standard model is not what
+ * it is made of — brushed metal, hair, skin, an eye.
+ *
+ * **A frozen descriptor, made once by a factory, carrying a kind and that model's numbers.** The
+ * standard model is `null`, exactly today's shader, and a scene that never names a model compiles
+ * nothing of any of them: each is a pipeline constant of its own (`MODEL_ANISOTROPIC` and the rest
+ * in `shaders/flat/models.ts`), off in every pipeline but the ones a material asks for.
+ *
+ * **Two vectors of numbers a material, and no more.** The lit stage's eight-light build is 254 of
+ * the 256 uniform vectors an Adreno 740 offers, so a model's numbers are packed into
+ * `uModelParams[2]` — the last component of the second says whether a model map is bound — and
+ * every model fits. See `packModel` for each layout.
+ *
+ * **The eye's axis is the one number that moves.** It is the eye's forward direction in the world,
+ * which a turning head or a glance changes every frame; the lit stage has no room left for another
+ * varying (sixteen, WebGPU's ceiling), so the renderer turns the descriptor's mesh-local axis by
+ * the draw's model matrix and the eye's joint each draw, with `eyeAxisInWorld`.
+ */
+import type { Vec3 } from '../math/color.ts';
+/** Strands of brushed metal, satin or hair-like fibre: a highlight stretched across them. */
+export interface AnisotropicModel {
+    readonly kind: 'anisotropic';
+    /** 0 to 1: how far the highlight is stretched along the tangent. */
+    readonly strength: number;
+    /** Radians, turning the stretch's direction from the tangent toward the bitangent. */
+    readonly rotation: number;
+}
+/**
+ * Hair: three lobes along the strand, which is the mesh's tangent, running from root to tip
+ * (`hairLobes.ts`). A model map's green turns each strand's tilt by up to half of it either way and
+ * its blue is occlusion.
+ */
+export interface HairModel {
+    readonly kind: 'hair';
+    /**
+     * Radians the cuticle's scales tilt the strand's surface: positive moves the white highlight
+     * toward the root and the coloured one toward the tip. A card whose tangent runs tip to root
+     * takes it negative.
+     */
+    readonly shift: number;
+    /** 0 to 1: the light scattered through many strands, tinted by their colour. */
+    readonly scatter: number;
+    /** How strongly light from behind glows through: the transmitted lobe. */
+    readonly backlit: number;
+}
+/** Skin: light scattered beneath the surface, reddening its terminator and its thin parts. */
+export interface SkinModel {
+    readonly kind: 'skin';
+    /** The colour light keeps travelling beneath the surface — the mean free path, as a colour. */
+    readonly scatterColor: Vec3;
+    /** Metres: how far light travels beneath it before it leaves. */
+    readonly radius: number;
+    /** 0 to 1: how much a light behind a thin part shows through it. */
+    readonly transmission: number;
+    /** Which of up to eight profiles the screen-space scattering blurs this skin by. */
+    readonly profile: number;
+}
+/** An eye: an iris seen through a cornea, which refracts it, under a mirror-smooth highlight. */
+export interface EyeModel {
+    readonly kind: 'eye';
+    /** The iris's radius, in texture coordinates from the centre of the eye's map. */
+    readonly irisRadius: number;
+    /** Metres from the cornea down to the iris. */
+    readonly irisDepth: number;
+    /** The cornea's index of refraction. */
+    readonly ior: number;
+    /** How smooth the cornea's highlight is. */
+    readonly corneaRoughness: number;
+    /** The eye's forward direction, in the mesh's own space at its bind pose. */
+    readonly axis: Vec3;
+    /** The joint the eye turns with, or -1 for an eye placed by its model matrix alone. */
+    readonly joint: number;
+}
+/** Every model a material can name, by its `kind`: see `SurfaceMaterial.model`. */
+export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel;
+/** A model's name, which also picks its pipeline switch: `SURFACE_MODEL_SWITCH`. */
+export type SurfaceModelKind = SurfaceModel['kind'];
+/** Every kind, in the order the lit stage declares their switches. */
+export declare const SURFACE_MODEL_KINDS: readonly SurfaceModelKind[];
+/** The lit stage's switch for each kind. */
+export declare const SURFACE_MODEL_SWITCH: Readonly<Record<SurfaceModelKind, string>>;
+/** Floats a material's model takes: `uModelParams[2]`. */
+export declare const MODEL_PARAM_FLOATS = 8;
+/** Brushed metal and the like, after glTF's `KHR_materials_anisotropy`: a strength and a turn. */
+export declare function anisotropicModel(options?: {
+    strength?: number;
+    rotation?: number;
+}): AnisotropicModel;
+/** Hair, along the mesh's tangent from root to tip. A tilt of 3°, within the 2.5° to 5° measured. */
+export declare function hairModel(options?: {
+    shift?: number;
+    scatter?: number;
+    backlit?: number;
+}): HairModel;
+/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+export declare function skinModel(options?: {
+    scatterColor?: Vec3;
+    radius?: number;
+    transmission?: number;
+    profile?: number;
+}): SkinModel;
+/** An eye. The defaults are a human eye's, its axis along the mesh's +Z. */
+export declare function eyeModel(options?: {
+    irisRadius?: number;
+    irisDepth?: number;
+    ior?: number;
+    corneaRoughness?: number;
+    axis?: Vec3;
+    joint?: number;
+}): EyeModel;
+/**
+ * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
+ * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
+ * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ *
+ * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - hair: shift, scatter, backlit, − · −, −, −, map
+ * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ */
+export declare function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void;
+/**
+ * An eye's axis in the world for one draw, into `out[at…at+2]`: the descriptor's mesh-local axis
+ * turned by its joint's palette entry, where it names one and a palette is set, and then by the
+ * draw's model matrix — the turn its vertices take, without the translation. Normalised, because
+ * a palette carries a joint's scale.
+ */
+export declare function eyeAxisInWorld(model: EyeModel, placement: ArrayLike<number>, palette: ArrayLike<number> | null, out: Float32Array, at: number): void;

package/dist/render/surfaceModel.js

@@ -0,0 +1,152 @@
+/** Every kind, in the order the lit stage declares their switches. */
+export const SURFACE_MODEL_KINDS = [
+    'anisotropic',
+    'hair',
+    'skin',
+    'eye',
+];
+/** The lit stage's switch for each kind. */
+export const SURFACE_MODEL_SWITCH = {
+    anisotropic: 'MODEL_ANISOTROPIC',
+    hair: 'MODEL_HAIR',
+    skin: 'MODEL_SKIN',
+    eye: 'MODEL_EYE',
+};
+/** Floats a material's model takes: `uModelParams[2]`. */
+export const MODEL_PARAM_FLOATS = 8;
+function check(model, name, value, low, high) {
+    if (!Number.isFinite(value) || value < low || value > high) {
+        throw new Error(`${model}: ${name} must be from ${low} to ${high}, not ${String(value)}`);
+    }
+    return value;
+}
+function unit(model, name, v) {
+    const length = Math.hypot(v[0], v[1], v[2]);
+    if (!(length > 1e-6))
+        throw new Error(`${model}: ${name} must be a direction, not [${v.join(', ')}]`);
+    return [v[0] / length, v[1] / length, v[2] / length];
+}
+/** Brushed metal and the like, after glTF's `KHR_materials_anisotropy`: a strength and a turn. */
+export function anisotropicModel(options = {}) {
+    return Object.freeze({
+        kind: 'anisotropic',
+        strength: check('anisotropicModel', 'strength', options.strength ?? 1, 0, 1),
+        rotation: check('anisotropicModel', 'rotation', options.rotation ?? 0, -2 * Math.PI, 2 * Math.PI),
+    });
+}
+/** Hair, along the mesh's tangent from root to tip. A tilt of 3°, within the 2.5° to 5° measured. */
+export function hairModel(options = {}) {
+    return Object.freeze({
+        kind: 'hair',
+        shift: check('hairModel', 'shift', options.shift ?? (3 * Math.PI) / 180, -0.5, 0.5),
+        scatter: check('hairModel', 'scatter', options.scatter ?? 0.7, 0, 1),
+        backlit: check('hairModel', 'backlit', options.backlit ?? 1, 0, 4),
+    });
+}
+/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+export function skinModel(options = {}) {
+    const color = options.scatterColor ?? [0.85, 0.35, 0.22];
+    for (let c = 0; c < 3; c++)
+        check('skinModel', 'scatterColor', color[c], 0, 1);
+    const profile = check('skinModel', 'profile', options.profile ?? 0, 0, 7);
+    if (!Number.isInteger(profile))
+        throw new Error(`skinModel: profile must be a whole number, not ${profile}`);
+    return Object.freeze({
+        kind: 'skin',
+        scatterColor: Object.freeze([color[0], color[1], color[2]]),
+        radius: check('skinModel', 'radius', options.radius ?? 0.012, 0, 0.1),
+        transmission: check('skinModel', 'transmission', options.transmission ?? 0.5, 0, 1),
+        profile,
+    });
+}
+/** An eye. The defaults are a human eye's, its axis along the mesh's +Z. */
+export function eyeModel(options = {}) {
+    const joint = options.joint ?? -1;
+    if (!Number.isInteger(joint) || joint < -1) {
+        throw new Error(`eyeModel: joint must be a joint index or -1, not ${String(joint)}`);
+    }
+    return Object.freeze({
+        kind: 'eye',
+        irisRadius: check('eyeModel', 'irisRadius', options.irisRadius ?? 0.15, 0.001, 0.5),
+        irisDepth: check('eyeModel', 'irisDepth', options.irisDepth ?? 0.003, 0, 0.02),
+        ior: check('eyeModel', 'ior', options.ior ?? 1.336, 1, 2),
+        corneaRoughness: check('eyeModel', 'corneaRoughness', options.corneaRoughness ?? 0.02, 0, 1),
+        axis: Object.freeze(unit('eyeModel', 'axis', options.axis ?? [0, 0, 1])),
+        joint,
+    });
+}
+/**
+ * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
+ * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
+ * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ *
+ * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - hair: shift, scatter, backlit, − · −, −, −, map
+ * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ */
+export function packModel(model, mapped, out) {
+    out.fill(0);
+    if (model === null)
+        return;
+    out[7] = mapped ? 1 : 0;
+    switch (model.kind) {
+        case 'anisotropic':
+            out[0] = model.strength;
+            out[1] = Math.cos(model.rotation);
+            out[2] = Math.sin(model.rotation);
+            return;
+        case 'hair':
+            out[0] = model.shift;
+            out[1] = model.scatter;
+            out[2] = model.backlit;
+            return;
+        case 'skin':
+            out[0] = model.scatterColor[0];
+            out[1] = model.scatterColor[1];
+            out[2] = model.scatterColor[2];
+            out[3] = model.radius;
+            out[4] = model.transmission;
+            out[5] = model.profile;
+            return;
+        case 'eye':
+            out[0] = model.irisRadius;
+            out[1] = model.irisDepth;
+            out[2] = model.ior;
+            out[3] = model.corneaRoughness;
+            out[4] = model.axis[0];
+            out[5] = model.axis[1];
+            out[6] = model.axis[2];
+            return;
+    }
+}
+/**
+ * An eye's axis in the world for one draw, into `out[at…at+2]`: the descriptor's mesh-local axis
+ * turned by its joint's palette entry, where it names one and a palette is set, and then by the
+ * draw's model matrix — the turn its vertices take, without the translation. Normalised, because
+ * a palette carries a joint's scale.
+ */
+export function eyeAxisInWorld(model, placement, palette, out, at) {
+    let [x, y, z] = model.axis;
+    const j = model.joint * 16;
+    if (palette !== null && model.joint >= 0 && j + 16 <= palette.length) {
+        const px = palette[j] * x + palette[j + 4] * y + palette[j + 8] * z;
+        const py = palette[j + 1] * x +
+            palette[j + 5] * y +
+            palette[j + 9] * z;
+        const pz = palette[j + 2] * x +
+            palette[j + 6] * y +
+            palette[j + 10] * z;
+        x = px;
+        y = py;
+        z = pz;
+    }
+    const m = placement;
+    const wx = m[0] * x + m[4] * y + m[8] * z;
+    const wy = m[1] * x + m[5] * y + m[9] * z;
+    const wz = m[2] * x + m[6] * y + m[10] * z;
+    const length = Math.hypot(wx, wy, wz) || 1;
+    out[at] = wx / length;
+    out[at + 1] = wy / length;
+    out[at + 2] = wz / length;
+}

package/dist/render/surfaceTexture.d.ts

@@ -1,4 +1,17 @@
+/**
+ * A GPU image the caller supplies, sampled by the flat shader as surface colour — or several, as
+ * the layers of one array.
+ *
+ * **Every surface texture is an array; a plain image is an array of one.** The lit pass has three of
+ * WebGL2's guaranteed sixteen texture units free, so a second set of array samplers beside the 2D
+ * ones was never affordable. Making the one set of samplers arrays costs no unit, and a one-layer
+ * 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 { SurfaceModel } from './surfaceModel.ts';
+import type { CompressedTextureFormat, SurfaceSource } from './compressedSource.ts';
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
+import type { CutoutMode } from './cutoutDither.ts';
 /**
  * How a texture behaves past its edges and between its texels.
  *
@@ -57,8 +70,31 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
     /** Repeats across the mesh's own UV range, per axis. Applies to every map the material holds. */
     uScale?: number;
     vScale?: number;
-    /** Alpha below which a fragment is discarded. See `uAlbedoCutout`. */
+    /**
+     * Where the texture starts, per axis, added after the scale: a surface samples
+     * `uv · scale + offset`. Applies to every map, and to a cutout's shadow and depth as well.
+     *
+     * **What picks a cell of a flipbook or an atlas through the material**, so one quad draws any
+     * cell: a strip of four frames is `uScale: 0.25` and `uOffset: frame * 0.25`. Without it a
+     * consumer built one quad mesh per cell — 106 meshes for four strips — because the only way to
+     * move a texture was to move the geometry's own coordinates.
+     */
+    uOffset?: number;
+    vOffset?: number;
+    /** Alpha below which a fragment is discarded. See `uCutout`. */
     cutout?: number;
+    /**
+     * How the cutout's edge is drawn: `'hard'`, the default and every cutout before 4.8.4, or
+     * `'dithered'`, which keeps a pixel by the share of it the texture covers so a strand of hair, a
+     * lash or a fringe of leaves has a soft edge instead of a stair of pixels.
+     *
+     * **The frame decides how a dithered edge is resolved**, because the material cannot know: under a
+     * temporal resolve (TAA or DriftTR) the pattern moves every frame and the resolve averages it;
+     * multisampled, the share goes to the GPU as alpha-to-coverage; with neither, the test is hard,
+     * since a dither nothing averages is grain. A translucent draw tests hard whatever this says. See
+     * `cutoutDither.ts`.
+     */
+    cutoutMode?: CutoutMode;
     /**
      * Whether both faces are seen: glTF's `doubleSided`, what a curtain or a leaf card is. Drawn
      * without culling, and a back face is lit as its front, with the normal turned to the viewer.
@@ -99,6 +135,19 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * consumer who wants a bound map twice as bright asks here rather than rebuilding the mesh.
      */
     emissiveScale?: readonly [number, number, number];
+    /**
+     * How the surface answers light, when the standard model is not what it is made of: brushed
+     * metal, hair, skin, an eye — `anisotropicModel`, `hairModel`, `skinModel`, `eyeModel`. Null or
+     * absent is the standard model, exactly as before. **A pipeline of its own**, compiled the first
+     * time a draw asks, so a scene that names no model pays for none. See `surfaceModel.ts`.
+     */
+    model?: SurfaceModel | null;
+    /**
+     * The model's own channels, in the albedo's coordinates and layers; what each channel means is
+     * the model's to say. Absent, each model takes its own neutral. Sampled linear, like any map
+     * that is not a colour.
+     */
+    modelMap?: Texture | null;
 }
 export interface SurfaceTextureOptions {
     /**
@@ -193,12 +242,14 @@ export declare class SurfaceTexture {
     readonly layers: number;
     /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
     private effectsTable;
+    /** The block format a compressed texture holds, or null for one uploaded from images. */
+    private readonly blockFormat;
     /**
      * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
-     * Uploaded unflipped either way; see the constructor body for why.
+     * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
+     * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
      */
-    constructor(gl: WebGL2RenderingContext, source: TexImageSource | readonly TexImageSource[], options?: SurfaceTextureOptions);
-    /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
+    constructor(gl: WebGL2RenderingContext, source: SurfaceSource | readonly SurfaceSource[], options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
     get hasEffects(): boolean;
     bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void;

package/dist/render/surfaceTexture.js

@@ -1,14 +1,6 @@
-/**
- * A GPU image the caller supplies, sampled by the flat shader as surface colour — or several, as
- * the layers of one array.
- *
- * **Every surface texture is an array; a plain image is an array of one.** The lit pass has three of
- * WebGL2's guaranteed sixteen texture units free, so a second set of array samplers beside the 2D
- * ones was never affordable. Making the one set of samplers arrays costs no unit, and a one-layer
- * 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 { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from './textureSource.js';
+import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.js';
+import { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSource.js';
+import { uploadCompressedArray } from './glCompressed.js';
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './surfaceEffects.js';
 const DEFAULT_ANISOTROPY = 4;
 /**
@@ -29,48 +21,39 @@ export class SurfaceTexture {
     layers;
     /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
     effectsTable = null;
+    /** The block format a compressed texture holds, or null for one uploaded from images. */
+    blockFormat;
     /**
      * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
-     * Uploaded unflipped either way; see the constructor body for why.
+     * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
+     * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
      */
-    constructor(gl, source, options = {}) {
-        const sources = isSourceList(source) ? source : [source];
-        const { width, height } = layerSize(sources);
-        this.layers = sources.length;
+    constructor(gl, source, options = {}, compressed = []) {
+        const listed = (Array.isArray(source) ? source : [source]);
+        const blocks = compressedLayers(listed);
+        this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
+        /* Refused before anything is allocated, so a refusal leaves no texture behind. */
+        const plan = blocks === null ? null : planBlocks(blocks, this.srgb, compressed);
         const texture = gl.createTexture();
         if (texture === null)
             throw new Error('SurfaceTexture: createTexture failed');
         this.texture = texture;
-        this.mipmapped = options.mipmap ?? true;
-        this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
         const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
-        /*
-         * **Not flipped, and this used to be, which is the bug it is written down for.**
-         *
-         * The flip was here with a comment saying every source is a 2D drawing surface whose Y
-         * runs down from the top-left, so without it "every texture arrives mirrored". That is
-         * true of a canvas and **WebGL ignores `UNPACK_FLIP_Y_WEBGL` entirely for an
-         * `ImageBitmap`**, which carries its own orientation. So the two source types the same
-         * method accepts arrived the opposite way up from each other, and nothing caught it
-         * because every canvas-sourced texture in this repository was symmetric under a vertical
-         * flip: eroded noise, a radial halo, a sleeve blurred to 24 pixels and back. One consumer
-         * painted lettering to a canvas beside a sleeve decoded as a bitmap and the text was
-         * upside down.
-         *
-         * **Made to agree by dropping the flip rather than by extending it**, and the direction
-         * is a deliberate choice about blast radius rather than a coin toss: `drftLoader` builds
-         * every model texture from an `ImageBitmap`, so flipping bitmaps to match canvases would
-         * turn over every painted surface on every loaded model. Dropping it changes only
-         * canvas-sourced textures, and every one of those that exists today is symmetric.
-         *
-         * A caller that was mirroring its own canvas to cancel this must stop.
-         */
-        /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
-           new size, as texImage2D always could. Each layer is then written in place. */
-        gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, width, height, sources.length, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
-        for (let layer = 0; layer < sources.length; layer++) {
-            gl.texSubImage3D(gl.TEXTURE_2D_ARRAY, 0, 0, 0, layer, width, height, 1, gl.RGBA, gl.UNSIGNED_BYTE, sources[layer]);
+        if (blocks !== null && plan !== null) {
+            /* The stored chain, or level 0 alone where no chain was asked for. Nothing is generated:
+               `generateMipmap` cannot write a compressed format. */
+            this.layers = blocks.length;
+            this.blockFormat = blocks[0].format;
+            this.mipmapped = (options.mipmap ?? true) && plan.levels > 1;
+            uploadCompressedArray(gl, plan.name, blocks, this.mipmapped ? plan.levels : 1);
+        }
+        else {
+            const sources = listed;
+            this.layers = sources.length;
+            this.blockFormat = null;
+            this.mipmapped = options.mipmap ?? true;
+            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);
@@ -86,7 +69,7 @@ export class SurfaceTexture {
             : nearest
                 ? gl.NEAREST
                 : gl.LINEAR);
-        if (this.mipmapped)
+        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);
@@ -107,7 +90,6 @@ export class SurfaceTexture {
             this.effectsTable = table;
         }
     }
-    /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
     /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
     get hasEffects() {
         return this.effectsTable !== null;
@@ -131,6 +113,7 @@ export class SurfaceTexture {
         if (this.texture === null)
             return;
         refuseArrayUpdate(this.layers);
+        refuseBlockUpdate(this.blockFormat);
         const { width, height } = sourceSize(source);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
         /* Unflipped, matching the constructor. See it for why, and for what it cost. */
@@ -154,6 +137,37 @@ export class SurfaceTexture {
         this.effectsTable = null;
     }
 }
+/** Images into the bound array, level 0 of each layer; the chain, if any, is generated after. */
+function uploadImages(gl, sources, srgb) {
+    const { width, height } = layerSize(sources);
+    /*
+     * **Not flipped, and this used to be, which is the bug it is written down for.**
+     *
+     * The flip was here with a comment saying every source is a 2D drawing surface whose Y
+     * runs down from the top-left, so without it "every texture arrives mirrored". That is
+     * true of a canvas and **WebGL ignores `UNPACK_FLIP_Y_WEBGL` entirely for an
+     * `ImageBitmap`**, which carries its own orientation. So the two source types the same
+     * method accepts arrived the opposite way up from each other, and nothing caught it
+     * because every canvas-sourced texture in this repository was symmetric under a vertical
+     * flip: eroded noise, a radial halo, a sleeve blurred to 24 pixels and back. One consumer
+     * painted lettering to a canvas beside a sleeve decoded as a bitmap and the text was
+     * upside down.
+     *
+     * **Made to agree by dropping the flip rather than by extending it**, and the direction
+     * is a deliberate choice about blast radius rather than a coin toss: `drftLoader` builds
+     * every model texture from an `ImageBitmap`, so flipping bitmaps to match canvases would
+     * turn over every painted surface on every loaded model. Dropping it changes only
+     * canvas-sourced textures, and every one of those that exists today is symmetric.
+     *
+     * A caller that was mirroring its own canvas to cancel this must stop.
+     */
+    /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
+         new size, as texImage2D always could. Each layer is then written in place. */
+    gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, width, height, sources.length, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+    for (let layer = 0; layer < sources.length; layer++) {
+        gl.texSubImage3D(gl.TEXTURE_2D_ARRAY, 0, 0, 0, layer, width, height, 1, gl.RGBA, gl.UNSIGNED_BYTE, sources[layer]);
+    }
+}
 /**
  * Set anisotropic filtering when the driver offers it, and stay silent when it does not.
  *

package/dist/render/textRenderer.js

@@ -1,6 +1,7 @@
 import { MAX_CELLS, TEXT_CUBE, TextLayout, deviceSnappedOrigin } from './textLayout.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { TEXT_FRAG, TEXT_VERT } from './shaders/text.js';
+import { blendCovering } from './sceneCoverage.js';
 /**
  * Text as geometry, on WebGL2.
  *
@@ -98,7 +99,7 @@ export class TextRenderer {
         const reversed = current === gl.GREATER || current === gl.GEQUAL;
         gl.depthFunc(reversed ? gl.GEQUAL : gl.LEQUAL);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         setVec2(gl, this.uniforms['uViewport'], viewportWidth, viewportHeight);
         /* Snapped with the cell below: a whole pitch on a fractional origin still splits a stroke.
            See `deviceSnappedOrigin`. */

package/dist/render/vertexDefaults.js

@@ -65,6 +65,13 @@ export const ABSENT_ATTRIBUTE = {
      */
     joints: [0, 0, 0, 0],
     weights: [1, 0, 0, 0],
+    /**
+     * The second four influences, absent: all zero, so a four-influence mesh drawn through a pipeline
+     * built for eight adds nothing. **Not the first set's trap**: there a zero sum collapses the
+     * vertex, here the first set already sums to one and zero is exactly "no more influences".
+     */
+    joints2: [0, 0, 0, 0],
+    weights2: [0, 0, 0, 0],
     /**
      * The four-lane channel: planted, fully sunlit, opaque, and a reserved lane.
      *
@@ -102,6 +109,7 @@ export const OUTPUT_TRANSFORM_CODE = {
     none: 0,
     srgb: 1,
     aces: 2,
+    shoulder: 3,
 };
 /**
  * How far the speed rush reaches, and how far a motion-blurred pixel may travel, both in UV.

package/dist/render/waterRenderer.js

@@ -5,6 +5,7 @@ import { bindAtmosphere } from './atmosphere.js';
 import { bindPointLights } from './lightBudget.js';
 import { DEFAULT_RENDER_QUALITY } from './renderQuality.js';
 import { createResolvedWater, resolveWater, waterAppearance } from './waterDraw.js';
+import { blendCovering } from './sceneCoverage.js';
 /** Vertices per side of a bounded body's sheet. A pool is not an ocean. */
 export class WaterRenderer {
     program;
@@ -145,7 +146,7 @@ export class WaterRenderer {
         gl.uniform2f(u['uReflectionTexelSize'] ?? null, reflectionReady && reflection !== null ? 1 / reflection.textureWidth : 1, reflectionReady && reflection !== null ? 1 / reflection.textureHeight : 1);
         gl.uniform1i(u['uReflectionFilterTaps'] ?? null, this.reflectionFilterTaps);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         // Waves are displaced far enough that back faces show at grazing angles.
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(w.bounded ? this.patchVao : this.vao);

package/dist/render/windStreakRenderer.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { WIND_STREAK_FRAG, WIND_STREAK_VERT } from './shaders/windStreaks.js';
 import { WIND_STREAK_DEFAULTS, buildWindStreakLattice, createResolvedWindStreaks, resolveWindStreaks, windStreakStrength, } from './windStreakDraw.js';
+import { blendCovering } from './sceneCoverage.js';
 export class WindStreakRenderer {
     program;
     uniforms;
@@ -68,7 +69,7 @@ export class WindStreakRenderer {
         gl.uniform1f(u['uTime'] ?? null, timeSeconds);
         gl.uniform3fv(u['uTint'] ?? null, tint);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(this.vao);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.8.2",
+  "version": "4.8.4",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.8.2",
-    "@driftengine/physics": "4.8.2",
+    "@driftengine/drft": "4.8.4",
+    "@driftengine/physics": "4.8.4",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.8.2",
-    "@driftengine/network": "4.8.2",
-    "@driftengine/texture": "4.8.2"
+    "@driftengine/nav": "4.8.4",
+    "@driftengine/network": "4.8.4",
+    "@driftengine/texture": "4.8.4"
   }
 }

package/src/geometry/meshConcat.ts

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