@driftengine/core 3.61.0

package/dist/render/ssrPass.js

@@ -0,0 +1,196 @@
+import { mat4 } from 'gl-matrix';
+import { decalScissor } from './decalProjector.js';
+import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { SSR_RESOLVE_FRAG } from './shaders/ssrResolve.js';
+import { SSR_TRACE_FRAG } from './shaders/ssrTrace.js';
+/**
+ * Screen-space reflection on WebGL2: a scissored trace per surface, then one composite.
+ *
+ * **The trace writes into a target of its own and that is not an optimisation.** It samples the
+ * finished scene colour to find out what a ray hit, so writing into the scene would be a feedback
+ * loop — `GL_INVALID_OPERATION` once per draw and undefined rasterisation, which `OitPass` records
+ * paying for. One extra full-frame attachment buys the separation, and it also makes several
+ * reflective surfaces accumulate as premultiplied layers rather than as independent guesses.
+ *
+ * **Two passes, and the second is one fetch.** The composite is done by the blend state:
+ * `(ONE, ONE_MINUS_SRC_ALPHA)` against premultiplied texels is `over`, so the resolve never samples
+ * the colour it is compositing onto either.
+ */
+export class SsrPass {
+    gl;
+    floatColor;
+    trace;
+    traceUniforms;
+    resolve;
+    resolveUniforms;
+    vao;
+    reflection = null;
+    framebuffer = null;
+    width = 0;
+    height = 0;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per surface. */
+    depthToWorld = new Float32Array(16);
+    scissor = new Int32Array(4);
+    constructor(gl, 
+    /**
+     * Whether the scene it reflects is a float target.
+     *
+     * The reflection buffer matches it. A half-float scene composited through an eight-bit
+     * reflection would clip every highlight the reflection carries, which is exactly the part of a
+     * scene that shows in a wet floor.
+     */
+    floatColor) {
+        this.gl = gl;
+        this.floatColor = floatColor;
+        this.trace = compileProgram(gl, FULLSCREEN_VERT, SSR_TRACE_FRAG, 'ssrTrace');
+        this.traceUniforms = uniformLocations(gl, this.trace, 'ssrTrace');
+        this.resolve = compileProgram(gl, FULLSCREEN_VERT, SSR_RESOLVE_FRAG, 'ssrResolve');
+        this.resolveUniforms = uniformLocations(gl, this.resolve, 'ssrResolve');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('SsrPass: createVertexArray failed');
+        this.vao = vao;
+    }
+    ensureSize(width, height) {
+        const { gl } = this;
+        if (this.width === width && this.height === height)
+            return;
+        this.width = width;
+        this.height = height;
+        /* Unit 0, chosen rather than inherited: `bindTexture` binds to whichever unit is active, and
+           the renderer leaves that wherever its last pass finished. `OitPass` records what leaving it
+           there cost — a feedback loop reported once per draw. */
+        gl.activeTexture(gl.TEXTURE0);
+        if (this.reflection === null)
+            this.reflection = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.reflection);
+        gl.texImage2D(gl.TEXTURE_2D, 0, this.floatColor ? gl.RGBA16F : gl.RGBA8, width, height, 0, gl.RGBA, this.floatColor ? gl.HALF_FLOAT : gl.UNSIGNED_BYTE, null);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        if (this.framebuffer === null)
+            this.framebuffer = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.reflection, 0);
+        /* No depth: the trace decides everything from the depth it *samples*, and an attachment here
+           would be one more thing to be caught reading. */
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        /* And released, so nothing carries this target into a sampler of another pass. */
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    /**
+     * March every recorded surface into the reflection buffer.
+     *
+     * `viewProjection` is the **raw** camera matrix. `DEPTH_01_TO_CLIP` turns a stored depth back
+     * into the clip space that matrix was built in, and the trace projects its samples back through
+     * the same matrix — pairing either with the clip-corrected one applies the remap twice.
+     */
+    traceReflections(queue, scene, depth, viewProjection, eye, width, height, edgeFade) {
+        if (queue.length === 0)
+            return;
+        const { gl } = this;
+        const u = this.traceUniforms;
+        this.ensureSize(width, height);
+        mat4.invert(this.depthToWorld, viewProjection);
+        mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.viewport(0, 0, width, height);
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        /* Cleared whole, then scissored: the resolve reads every pixel and an uncleared one outside
+           every box would composite last frame's reflection over this frame's scene. */
+        gl.disable(gl.SCISSOR_TEST);
+        gl.clearBufferfv(gl.COLOR, 0, [0, 0, 0, 0]);
+        gl.enable(gl.BLEND);
+        /* Premultiplied `over`, so two overlapping surfaces layer rather than replace. */
+        gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+        gl.enable(gl.SCISSOR_TEST);
+        gl.useProgram(this.trace);
+        gl.bindVertexArray(this.vao);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        gl.uniform1i(u['uSsrDepth'] ?? null, 0);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, scene);
+        gl.uniform1i(u['uSsrScene'] ?? null, 1);
+        gl.uniformMatrix4fv(u['uSsrDepthToWorld'] ?? null, false, this.depthToWorld);
+        /* No Y flip on this backend: `gl.scissor` and the framebuffer both count rows from the bottom,
+           which is the space the raw matrix already emits. See `CLIP_Y_FLIP`. */
+        gl.uniformMatrix4fv(u['uSsrViewProj'] ?? null, false, viewProjection);
+        gl.uniform3f(u['uSsrEye'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
+        gl.uniform1f(u['uSsrEdgeFade'] ?? null, edgeFade);
+        queue.replay((surface) => {
+            if (!decalScissor(viewProjection, surface.surfaceToWorld, width, height, false, this.scissor)) {
+                return;
+            }
+            gl.scissor(this.scissor[0] ?? 0, this.scissor[1] ?? 0, this.scissor[2] ?? 0, this.scissor[3] ?? 0);
+            gl.uniformMatrix4fv(u['uWorldToSurface'] ?? null, false, surface.worldToSurface);
+            gl.uniform3fv(u['uSsrAxis'] ?? null, surface.axis);
+            gl.uniform3fv(u['uSsrTint'] ?? null, surface.tint);
+            gl.uniform1f(u['uSsrStrength'] ?? null, surface.strength);
+            gl.uniform1f(u['uSsrFacingCos'] ?? null, surface.facingCos);
+            gl.uniform1f(u['uSsrReach'] ?? null, surface.reachM);
+            gl.uniform1f(u['uSsrThickness'] ?? null, surface.thicknessM);
+            gl.uniform1f(u['uSsrSteps'] ?? null, surface.steps);
+            gl.drawArrays(gl.TRIANGLES, 0, 3);
+        });
+        gl.disable(gl.SCISSOR_TEST);
+        gl.scissor(0, 0, width, height);
+        gl.bindVertexArray(null);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    }
+    /** Composite what the trace found over whatever framebuffer is bound. */
+    resolveReflections() {
+        const { gl } = this;
+        if (this.reflection === null)
+            return;
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.enable(gl.BLEND);
+        /* Premultiplied `over`: the trace already multiplied its colour by the coverage it found. */
+        gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+        gl.useProgram(this.resolve);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.reflection);
+        gl.uniform1i(this.resolveUniforms['uSsrReflection'] ?? null, 0);
+        gl.bindVertexArray(this.vao);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.bindVertexArray(null);
+        /*
+         * **Released, and `OitPass` says why at length.** A binding outlives the frame it was made in,
+         * so unit 0 would keep the reflection buffer — which the *next* frame then attaches as its own
+         * target while a program still declares a sampler on that unit. That is a feedback loop,
+         * reported once per draw and rasterising something undefined.
+         */
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+    }
+    dispose() {
+        const { gl } = this;
+        if (this.reflection !== null)
+            gl.deleteTexture(this.reflection);
+        if (this.framebuffer !== null)
+            gl.deleteFramebuffer(this.framebuffer);
+        gl.deleteProgram(this.trace);
+        gl.deleteProgram(this.resolve);
+        gl.deleteVertexArray(this.vao);
+        this.reflection = null;
+        this.framebuffer = null;
+        this.width = 0;
+        this.height = 0;
+    }
+}

package/dist/render/surfaceSheet.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A bounded, roughly horizontal sheet, described by the cross-sections it is
+ * swept through, and the triangles that cover it.
+ *
+ * Cross-sections rather than rectangles, because the things this describes
+ * follow a route: a channel of water beside a path, the underside of a bridge
+ * over it. A chain of independent rectangles laid along a curve leaves a notch
+ * at every joint — small, and exactly the kind of small that reads as broken
+ * once light is crawling across it. Consecutive spans share their edge, so a
+ * curving sheet is closed by construction.
+ *
+ * Nothing here knows what a sheet is *for*. It takes numbers.
+ */
+/** One cross-section: the two ends of a straight edge across the sheet. */
+export interface SheetSpan {
+    x0: number;
+    z0: number;
+    x1: number;
+    z1: number;
+    /** Resting height of the sheet at this cross-section. */
+    y: number;
+}
+export interface SheetMesh {
+    /** Resting position, 3 floats per vertex. A shader may displace it. */
+    positions: Float32Array;
+    /**
+     * Where the vertex sits inside its own sheet, 0..1 along and across.
+     *
+     * So a shader can dissolve its own boundary. It reaches 0 and 1 exactly at the
+     * outermost vertices rather than approaching them, which is the lesson the
+     * ocean's rim already paid for: a fade that only nearly closes leaves a hard
+     * edge, and a hard edge reads as geometry rather than as water.
+     */
+    locals: Float32Array;
+    /** Two numbers carried from each sheet onto every one of its vertices. */
+    params: Float32Array;
+    vertexCount: number;
+}
+/**
+ * Cover each sheet in cells no coarser than `cellM`.
+ *
+ * Vertices are duplicated at cell boundaries rather than shared. That is safe
+ * here in a way it would not be in general: every displacement applied to this
+ * mesh is a pure function of the resting position, so two vertices at the same
+ * place move to the same place and the seam cannot open.
+ *
+ * `params` is called once per sheet at build time — never per frame — and writes
+ * the two floats each of that sheet's vertices carries.
+ */
+export declare function buildSheets<T extends {
+    spans: readonly SheetSpan[];
+}>(sheets: readonly T[], cellM: number, params: (sheet: T, out: Float32Array) => void): SheetMesh;

package/dist/render/surfaceSheet.js

@@ -0,0 +1,99 @@
+/**
+ * A bounded, roughly horizontal sheet, described by the cross-sections it is
+ * swept through, and the triangles that cover it.
+ *
+ * Cross-sections rather than rectangles, because the things this describes
+ * follow a route: a channel of water beside a path, the underside of a bridge
+ * over it. A chain of independent rectangles laid along a curve leaves a notch
+ * at every joint — small, and exactly the kind of small that reads as broken
+ * once light is crawling across it. Consecutive spans share their edge, so a
+ * curving sheet is closed by construction.
+ *
+ * Nothing here knows what a sheet is *for*. It takes numbers.
+ */
+/**
+ * One vertex, bilinearly placed between two cross-sections.
+ *
+ * @param along 0 at span `a`, 1 at span `b`.
+ * @param across 0 at the spans' first end, 1 at their second.
+ * @param joint index of `a` within the sheet, and how many joints it has, so the
+ *   local coordinate measures the whole sheet rather than this piece of it.
+ */
+function emitVertex(into, a, b, along, across, joint, joints) {
+    const ax = a.x0 + (a.x1 - a.x0) * across;
+    const az = a.z0 + (a.z1 - a.z0) * across;
+    const bx = b.x0 + (b.x1 - b.x0) * across;
+    const bz = b.z0 + (b.z1 - b.z0) * across;
+    into.positions.push(ax + (bx - ax) * along, a.y + (b.y - a.y) * along, az + (bz - az) * along);
+    into.locals.push((joint + along) / joints, across);
+    into.params.push(into.param0, into.param1);
+}
+/**
+ * Cover each sheet in cells no coarser than `cellM`.
+ *
+ * Vertices are duplicated at cell boundaries rather than shared. That is safe
+ * here in a way it would not be in general: every displacement applied to this
+ * mesh is a pure function of the resting position, so two vertices at the same
+ * place move to the same place and the seam cannot open.
+ *
+ * `params` is called once per sheet at build time — never per frame — and writes
+ * the two floats each of that sheet's vertices carries.
+ */
+export function buildSheets(sheets, cellM, params) {
+    const into = {
+        positions: [],
+        locals: [],
+        params: [],
+        param0: 0,
+        param1: 0,
+    };
+    const scratch = new Float32Array(2);
+    const cell = cellM > 0 ? cellM : 0;
+    for (const sheet of sheets) {
+        const spans = sheet.spans;
+        if (cell <= 0 || spans.length < 2)
+            continue;
+        scratch[0] = 0;
+        scratch[1] = 0;
+        params(sheet, scratch);
+        into.param0 = scratch[0] ?? 0;
+        into.param1 = scratch[1] ?? 0;
+        const joints = spans.length - 1;
+        for (let s = 0; s < joints; s++) {
+            const a = spans[s];
+            const b = spans[s + 1];
+            /*
+             * How finely this piece has to be cut: the longest edge on each axis, so a
+             * widening channel is sampled by its wide end rather than its narrow one.
+             */
+            const alongLength = Math.max(Math.hypot(b.x0 - a.x0, b.z0 - a.z0), Math.hypot(b.x1 - a.x1, b.z1 - a.z1));
+            const acrossLength = Math.max(Math.hypot(a.x1 - a.x0, a.z1 - a.z0), Math.hypot(b.x1 - b.x0, b.z1 - b.z0));
+            if (!(alongLength > 0) || !(acrossLength > 0))
+                continue;
+            const alongCells = Math.max(1, Math.ceil(alongLength / cell));
+            const acrossCells = Math.max(1, Math.ceil(acrossLength / cell));
+            for (let i = 0; i < alongCells; i++) {
+                const t0 = i / alongCells;
+                const t1 = (i + 1) / alongCells;
+                for (let j = 0; j < acrossCells; j++) {
+                    const s0 = j / acrossCells;
+                    const s1 = (j + 1) / acrossCells;
+                    // Two triangles per cell, wound counter-clockwise from above so the
+                    // sheet's front face is its top.
+                    emitVertex(into, a, b, t0, s0, s, joints);
+                    emitVertex(into, a, b, t1, s0, s, joints);
+                    emitVertex(into, a, b, t1, s1, s, joints);
+                    emitVertex(into, a, b, t0, s0, s, joints);
+                    emitVertex(into, a, b, t1, s1, s, joints);
+                    emitVertex(into, a, b, t0, s1, s, joints);
+                }
+            }
+        }
+    }
+    return {
+        positions: new Float32Array(into.positions),
+        locals: new Float32Array(into.locals),
+        params: new Float32Array(into.params),
+        vertexCount: into.positions.length / 3,
+    };
+}

package/dist/render/surfaceTexture.d.ts

@@ -0,0 +1,197 @@
+/** A GPU image the caller supplies, sampled by the flat shader as surface colour. */
+/**
+ * How a texture behaves past its edges and between its texels.
+ *
+ * Deliberately small. Every knob here is one a tiling world actually needs; anything
+ * beyond it — swizzles, borders, compressed formats — is a format decision that
+ * belongs to whoever is generating the pixels, not to the surface that shows them.
+ */
+/**
+ * Everything the flat pass needs to know about a surface, in one call.
+ *
+ * **Shaped for what comes after it.** ORM is the next map and emissive the one after; both are a
+ * field here rather than a fourth and fifth setter, which is the whole reason this replaced
+ * `setSurfaceTexture` rather than sitting beside it. A consumer setting four maps in four calls is
+ * four chances to forget one, and four resets `bindMeshPass` has to reason about.
+ *
+ * **Every field is independent.** A material with a `normal` and no `albedo` is a legitimate one —
+ * vertex colour with authored normals — and shades as such rather than as no material at all.
+ *
+ * **Generic over the texture, for the reason `SurfaceTextureHandle` exists.** The two backends have
+ * different texture classes and the public API speaks in an opaque handle; parameterising here lets
+ * each renderer take its own concrete type while a consumer sees one shape. Defaulted to the
+ * WebGL2 class so the common spelling stays `SurfaceMaterial`.
+ */
+export interface SurfaceMaterial<Texture = SurfaceTexture> {
+    albedo?: Texture | null;
+    /**
+     * Surface-space directions, turned into world space through the mesh's tangent frame.
+     *
+     * Read by the flat pass since 2026-08-22, from the attribute at location 10 where the mesh has
+     * one and from a per-fragment cotangent frame where it does not. `normalStrength` gates it.
+     * See `docs/RENDERING.md` for the normal-map path.
+     */
+    normal?: Texture | null;
+    /**
+     * Occlusion in R, roughness in G, metallic in B, in one image.
+     *
+     * glTF's packing, because that is what an import carries, and one unit for three channels rather
+     * than three units for three maps. Sampled linear and never sRGB: these numbers *are* the data.
+     */
+    orm?: Texture | null;
+    /**
+     * Where a surface glows, and in what colour.
+     *
+     * **It modulates the surface's own emission rather than creating it**, which is glTF's rule
+     * — emitted colour is `emissiveFactor * emissiveTexture` — and is the one thing about this map
+     * that surprises people. A mesh whose `emissive` attribute is 0 emits nothing however bright
+     * the image it binds, because there is nothing for the image to scale. An import carries the
+     * factor for you: `gltf.ts` puts `max(emissiveFactor)` in the attribute and the factor itself
+     * in `emissiveColor`. A procedurally built mesh has to say so the same way it says its colour,
+     * which is in vertex data, because that is what makes a whole world one draw call here.
+     *
+     * Sampled **sRGB**, unlike `normal` and `orm`: this one is a colour a person picked, where
+     * those two are numbers. glTF says the same.
+     */
+    emissive?: Texture | null;
+    /** 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`. */
+    cutout?: number;
+    /**
+     * How hard the normal map turns the shading normal.
+     *
+     * **Defaults to 1 when a `normal` is supplied and 0 when it is not**, because binding a map and
+     * saying nothing about strength means "use it" rather than "use it at nothing".
+     */
+    normalStrength?: number;
+    /**
+     * Scales the ORM map's G channel. glTF's `roughnessFactor`. Default 1.
+     *
+     * The map *replaces* the mesh's own roughness attribute rather than scaling it, and this is what
+     * gives back the scaling. Scaling the attribute was the alternative and it is wrong outside an
+     * import: `vertexDefaults.ts` hands an absent roughness **0.4277**, not 1, so every procedurally
+     * built mesh would read far glossier than the image it was handed, with nothing in the API to
+     * say it would.
+     */
+    roughnessScale?: number;
+    /** Scales the ORM map's B channel. glTF's `metallicFactor`. Default 1. */
+    metallicScale?: number;
+    /**
+     * How much of the ORM map's R channel to apply. glTF's `occlusionTexture.strength`. Default 1.
+     *
+     * **0 is no occlusion, not full occlusion.** glTF defines it as `1 + strength * (texel - 1)`, so
+     * the shader mixes from 1 rather than multiplying — a multiply at 0 would black the surface out,
+     * which is the opposite of what the caller asked for.
+     */
+    occlusionStrength?: number;
+    /**
+     * Scales the emissive map, per channel. Default 1.
+     *
+     * The counterpart of `roughnessScale` and `metallicScale`: a factor that multiplies a texture is
+     * not a value, and this is where the multiplier lives once an image supplies the shape. A
+     * consumer who wants a bound map twice as bright asks here rather than rebuilding the mesh.
+     */
+    emissiveScale?: readonly [number, number, number];
+}
+export interface SurfaceTextureOptions {
+    /**
+     * `repeat` tiles the image, `clamp` stretches its edge texels.
+     *
+     * Repeat is the default because the case this exists for is a wall: one small image
+     * covering a large surface, with `uvScale` deciding how often it lands. Clamp is for
+     * an image that is a *picture* — a portrait, a sign — where a second copy of it
+     * appearing past the edge is a bug rather than a pattern.
+     */
+    wrap?: 'repeat' | 'clamp';
+    /**
+     * How the image's values are encoded, so the shader can sample light rather than pixels.
+     *
+     * `linear` is the default and the old behaviour: the bytes are handed to the shader as
+     * they are. That is right for a mask, a height field, anything whose numbers *are* the
+     * data.
+     *
+     * `srgb` is right for anything that was authored to be looked at — a photo, a painted
+     * canvas, a biome tile. Those bytes are display values, and shading maths is linear, so
+     * multiplying a light into them without decoding first is a category error: mid-greys
+     * come out roughly twice as bright as they should, and the mistake is invisible until an
+     * output transform is applied and everything blows out at once. The GPU decodes
+     * `SRGB8_ALPHA8` in the sampler, so this costs nothing per fetch and, unlike decoding in
+     * the shader, it happens *before* filtering — which is the only place it is correct.
+     */
+    colorSpace?: 'linear' | 'srgb';
+    /**
+     * How a texel is chosen when the image is magnified: smoothed between texels, or taken whole.
+     *
+     * **`linear` is the default and is every surface that shipped before this**, which is right for
+     * anything photographic: a wall, a painted canvas, a biome tile, where the texel grid is an
+     * artefact of resolution rather than the subject.
+     *
+     * `nearest` is for an image whose *pixels are the subject* — pixel art, an icon atlas, a
+     * hand-authored tile. **Reported by a consumer whose block atlas is exactly that**: linear
+     * magnification turns an authored tile into a smear as the camera approaches, and there was no
+     * way to ask for anything else. They composed their atlas with `imageSmoothingEnabled = false`
+     * and kept tiles at twice the resolution they wanted, and neither touches magnification — the
+     * smoothing happens in the sampler, after everything a caller controls.
+     *
+     * **Minification still blends between mip levels**, and that is not the option being ignored. A
+     * tiled floor at a grazing angle minifies far past one texel per pixel, which is what mips exist
+     * for; taking the nearest *level* as well would trade a smear for a visible pop as the camera
+     * pulls back. So the choice applies where it was asked about, and within a level either way.
+     *
+     * `@driftengine/ui2d` takes the same option and defaults it the other way, because a sprite sheet
+     * is usually pixel art and a world surface usually is not.
+     */
+    filter?: 'linear' | 'nearest';
+    /**
+     * Build a mip chain. On by default, and it is not a quality preference.
+     *
+     * A tiled surface seen at a grazing angle — which is every floor and every corridor
+     * wall — minifies far past one texel per pixel, and without mips that undersampling
+     * is aliasing that *crawls* as the camera moves. It is the single most visible
+     * artefact a textured world can have. Off is for a texture drawn at roughly its own
+     * size, where the chain is memory spent on levels nothing will sample.
+     */
+    mipmap?: boolean;
+    /**
+     * Anisotropic samples, when the extension is present. 1 disables it.
+     *
+     * Mips fix the crawling and cost sharpness: a floor stretching to the horizon picks
+     * its mip from the *worse* of the two axes, so it blurs along the one that was still
+     * well sampled. Anisotropy is the standard repair, it is cheap at these sizes, and
+     * on a machine without the extension the clamp below silently leaves it at 1.
+     */
+    anisotropy?: number;
+}
+/**
+ * An image uploaded once and bound per draw.
+ *
+ * The engine ships no image assets and fetches nothing — that payload rule is intact
+ * and this does not weaken it. What it takes is a `TexImageSource` the *consumer*
+ * already has: a canvas it generated procedurally at runtime, an `ImageBitmap` it
+ * decoded, a video frame. The engine owns the GPU object and the sampler state; where
+ * the pixels came from is the caller's business and stays that way.
+ */
+export declare class SurfaceTexture {
+    private texture;
+    private readonly mipmapped;
+    /** Whether the sampler decodes sRGB on fetch. See `colorSpace`. */
+    private readonly srgb;
+    constructor(gl: WebGL2RenderingContext, source: TexImageSource, options?: SurfaceTextureOptions);
+    /**
+     * Replace the pixels, keeping the GPU object and its sampler state.
+     *
+     * For a source that changes — a canvas being redrawn, a decoded frame. Re-uploading
+     * beats constructing a second texture because the binding the caller already handed
+     * to a draw stays valid, and because a texture created per frame is a leak in every
+     * case where the caller forgets the matching dispose.
+     *
+     * 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;
+    /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
+    bind(gl: WebGL2RenderingContext, unit: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/surfaceTexture.js

@@ -0,0 +1,116 @@
+/** A GPU image the caller supplies, sampled by the flat shader as surface colour. */
+const DEFAULT_ANISOTROPY = 4;
+/**
+ * An image uploaded once and bound per draw.
+ *
+ * The engine ships no image assets and fetches nothing — that payload rule is intact
+ * and this does not weaken it. What it takes is a `TexImageSource` the *consumer*
+ * already has: a canvas it generated procedurally at runtime, an `ImageBitmap` it
+ * decoded, a video frame. The engine owns the GPU object and the sampler state; where
+ * the pixels came from is the caller's business and stays that way.
+ */
+export class SurfaceTexture {
+    texture;
+    mipmapped;
+    /** Whether the sampler decodes sRGB on fetch. See `colorSpace`. */
+    srgb;
+    constructor(gl, source, options = {}) {
+        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, 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.
+         */
+        gl.texImage2D(gl.TEXTURE_2D, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);
+        gl.texParameteri(gl.TEXTURE_2D, 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, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, this.mipmapped
+            ? nearest
+                ? gl.NEAREST_MIPMAP_LINEAR
+                : gl.LINEAR_MIPMAP_LINEAR
+            : nearest
+                ? gl.NEAREST
+                : gl.LINEAR);
+        if (this.mipmapped)
+            gl.generateMipmap(gl.TEXTURE_2D);
+        applyAnisotropy(gl, options.anisotropy ?? DEFAULT_ANISOTROPY);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    /**
+     * Replace the pixels, keeping the GPU object and its sampler state.
+     *
+     * For a source that changes — a canvas being redrawn, a decoded frame. Re-uploading
+     * beats constructing a second texture because the binding the caller already handed
+     * to a draw stays valid, and because a texture created per frame is a leak in every
+     * case where the caller forgets the matching dispose.
+     *
+     * 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, source) {
+        if (this.texture === null)
+            return;
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        /* Unflipped, matching the constructor. See it for why, and for what it cost. */
+        gl.texImage2D(gl.TEXTURE_2D, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+        if (this.mipmapped)
+            gl.generateMipmap(gl.TEXTURE_2D);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
+    bind(gl, unit) {
+        gl.activeTexture(gl.TEXTURE0 + unit);
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    }
+    dispose(gl) {
+        if (this.texture === null)
+            return;
+        gl.deleteTexture(this.texture);
+        this.texture = null;
+    }
+}
+/**
+ * Set anisotropic filtering when the driver offers it, and stay silent when it does not.
+ *
+ * Silent because the extension is an enhancement with an exact fallback — the same
+ * texture, filtered isotropically — so a machine without it renders a slightly softer
+ * floor rather than a broken one. Nothing here should fail init over that.
+ */
+function applyAnisotropy(gl, requested) {
+    if (requested <= 1)
+        return;
+    const ext = gl.getExtension('EXT_texture_filter_anisotropic') ??
+        gl.getExtension('WEBKIT_EXT_texture_filter_anisotropic');
+    if (ext === null)
+        return;
+    const max = gl.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
+    gl.texParameterf(gl.TEXTURE_2D, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(requested, max));
+}