@woosh/meep-engine 3.0.2 → 3.2.0

package/src/engine/ecs/fow/FogOfWar.js

@@ -1,707 +1,707 @@
-import { assert } from "../../../core/assert.js";
-import { BinaryDataType } from "../../../core/binary/type/BinaryDataType.js";
-import { RowFirstTable } from "../../../core/collection/table/RowFirstTable.js";
-import { RowFirstTableSpec } from "../../../core/collection/table/RowFirstTableSpec.js";
-import Signal from "../../../core/events/signal/Signal.js";
-import Vector1 from "../../../core/geom/Vector1.js";
-import Vector2 from "../../../core/geom/Vector2.js";
-import Vector4 from "../../../core/geom/Vector4.js";
-import { clamp } from "../../../core/math/clamp.js";
-import { max2 } from "../../../core/math/max2.js";
-import { min2 } from "../../../core/math/min2.js";
-import { computeUnsignedDistanceField } from "../../graphics/texture/sampler/distance/computeUnsignedDistanceField.js";
-import { Sampler2D } from "../../graphics/texture/sampler/Sampler2D.js";
-import { FogOfWarEdgeMode } from "./FogOfWarEdgeMode.js";
-
-const samplePosition = [];
-
-const corners2d = new Float64Array(8);
-
-/**
- * Measured in Uint8 channel value per second.
- * @example 255 would mean complete fade happens in 1s, 25.5 would mean fade happens over 10 seconds
- * @readonly
- * @type {number}
- */
-const FADE_SPEED = 255;
-
-/**
- * pre-fade to enable correct distance field calculation
- * @readonly
- * @type {number}
- */
-const INITIAL_FADE_VALUE = 254;
-
-/**
- *
- * @type {RowFirstTableSpec}
- */
-const revealMaskTableSpec = new RowFirstTableSpec([
-    BinaryDataType.Int32, // Index
-    BinaryDataType.Float32, // Precise current value
-    BinaryDataType.Float32 // Fade speed
-]);
-
-const fadeRow = [];
-
-/**
- * @class
- */
-export class FogOfWar {
-
-    /**
-     *
-     * @type {boolean}
-     */
-    textureNeedsUpdate = true;
-    /**
-     *
-     * @type {boolean}
-     */
-    distanceFieldNeedsUpdate = false;
-
-    /**
-     * Resolution scale of FoW versus terrain resolution, higher number makes FoW more detailed
-     * @type {Vector1}
-     */
-    scale = new Vector1(1);
-
-    /**
-     * Size of the fog area
-     * @type {Vector2}
-     */
-    size = new Vector2(0, 0);
-
-    color = new Vector4(0.1, 0.1, 0.1, 1);
-
-    /**
-     * What the fog does outside the fogged area — see {@link FogOfWarEdgeMode}.
-     *
-     * NOT serialized: it is configuration the owner sets when it builds the
-     * component, not accumulated reveal state, and adding it to the binary format
-     * would cost a version bump plus an updater for every existing save. A
-     * deserialized FogOfWar therefore comes back as Conceal; a consumer that
-     * wants Extend sets it after loading, in the same place it sets {@link color}.
-     *
-     * @type {FogOfWarEdgeMode}
-     */
-    edge_mode = FogOfWarEdgeMode.Conceal;
-
-    /**
-     * Contains indices of pixes that are currently being updated
-     * @type {RowFirstTable}
-     */
-    fadeMask = new RowFirstTable(revealMaskTableSpec);
-
-    /**
-     * Maps a sampler cell index to the row index of its in-progress fade in
-     * {@link fadeMask}. Enforces at most one fade row per cell, so that the
-     * latest reveal/conceal command for a cell re-aims its existing fade
-     * instead of stacking a second, opposing row.
-     * @type {Map<number, number>}
-     */
-    #fadeRowByCell = new Map();
-
-    on = {
-        textureChanged: new Signal()
-    };
-
-    /**
-     *
-     * @type {Sampler2D}
-     */
-    sampler = Sampler2D.uint8(1, 0, 0);
-
-    /**
-     *
-     * @type {Sampler2D}
-     */
-    distanceSampler = Sampler2D.uint8(1, 0, 0);
-
-    /**
-     *
-     * @param {number} timeDelta
-     */
-    updateFade(timeDelta) {
-        const samplerData = this.sampler.data;
-
-        const fadeMask = this.fadeMask;
-
-        const rowByCell = this.#fadeRowByCell;
-
-        let numRows = fadeMask.length;
-
-        let i = 0;
-
-        for (; i < numRows; i++) {
-            //read row
-            fadeMask.readRow(i, fadeRow);
-
-            //decode row
-            const index = fadeRow[0];
-            const oldValue = fadeRow[1];
-            const speed = fadeRow[2];
-
-            //compute new value
-            const value = oldValue + (speed * timeDelta);
-
-            let writeValue = value | 0;
-
-            //store the advanced precise value
-            fadeMask.writeCellValue(i, 1, value);
-
-            let completed = false;
-
-            if (value <= 0) {
-                writeValue = 0;
-
-                if (speed < 0) {
-                    //revealing fade reached the bottom
-                    completed = true;
-                }
-            } else if (value >= 255) {
-                writeValue = 255;
-
-                if (speed > 0) {
-                    //concealing fade reached the top
-                    completed = true;
-                }
-            }
-
-            if ((oldValue | 0) !== writeValue) {
-                //value has changed
-                samplerData[index] = writeValue;
-                this.textureNeedsUpdate = true;
-            }
-
-            if (completed) {
-                //Drop the finished row while keeping the cell->row index
-                //consistent. Swap the last row into this slot (O(1)) instead of
-                //shifting the whole tail forward, so only one other row's index
-                //needs to be patched in the map.
-                rowByCell.delete(index);
-
-                const lastRow = numRows - 1;
-
-                if (i !== lastRow) {
-                    const movedCell = fadeMask.readCellValue(lastRow, 0);
-
-                    fadeMask.copyRow(lastRow, i);
-
-                    rowByCell.set(movedCell, i);
-                }
-
-                fadeMask.removeRows(lastRow, 1);
-
-                i--;
-                numRows--;
-            }
-        }
-    }
-
-    /**
-     * Schedule (or re-aim) a fade for a single sampler cell so that it converges
-     * to `target`. Guarantees at most one fade row per cell: if the cell already
-     * has an in-progress fade its direction is updated in place, so the latest
-     * command wins instead of stacking a second, opposing row.
-     * @param {number} index sampler cell index
-     * @param {number} target target sampler value, either 0 (revealed) or 255 (concealed)
-     * @returns {boolean} whether the visible sampler value was changed (i.e. the distance field may need a rebuild)
-     */
-    #scheduleCellFade(index, target) {
-        const fadeMask = this.fadeMask;
-        const rowByCell = this.#fadeRowByCell;
-
-        const speed = target === 0 ? -FADE_SPEED : FADE_SPEED;
-
-        const existingRow = rowByCell.get(index);
-
-        if (existingRow !== undefined) {
-            //A fade is already in progress for this cell, re-aim it in place.
-            //The precise value column is left untouched so the fade resumes from
-            //its current progress and never snaps back through the far end.
-            fadeMask.writeCellValue(existingRow, 2, speed);
-
-            return false;
-        }
-
-        const samplerData = this.sampler.data;
-
-        const current = samplerData[index];
-
-        if (current === target) {
-            //already fully at the target, nothing to fade
-            return false;
-        }
-
-        let seedValue = current;
-        let visibleChanged = false;
-
-        if (target === 0 && current === 255) {
-            //pre-fade off the fully-concealed value so the distance field
-            //immediately treats this cell as being revealed
-            seedValue = INITIAL_FADE_VALUE;
-            samplerData[index] = INITIAL_FADE_VALUE;
-            visibleChanged = true;
-        }
-
-        //add record to fade mask
-        fadeRow[0] = index;
-        fadeRow[1] = seedValue;
-        fadeRow[2] = speed;
-
-        const rowIndex = fadeMask.addRow(fadeRow);
-
-        rowByCell.set(index, rowIndex);
-
-        return visibleChanged;
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     */
-    revealPoint(x, y) {
-        const samplerWidth = this.sampler.width;
-
-        const index = (y + 1) * samplerWidth + (x + 1);
-
-        if (this.#scheduleCellFade(index, 0)) {
-            this.distanceFieldNeedsUpdate = true;
-        }
-    }
-
-    clear() {
-        this.fadeMask.clear();
-        this.#fadeRowByCell.clear();
-
-        this.sampler.data.fill(255);
-
-        this.distanceFieldNeedsUpdate = true;
-        this.textureNeedsUpdate = true;
-    }
-
-    revealAll() {
-        this.fadeMask.clear();
-        this.#fadeRowByCell.clear();
-
-        this.sampler.data.fill(0);
-
-        this.distanceFieldNeedsUpdate = true;
-        this.textureNeedsUpdate = true;
-    }
-
-    concealAll() {
-        this.clear();
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} radius
-     */
-    reveal(x, y, radius) {
-        assert.isNumber(x, 'x');
-        assert.isNumber(y, 'y');
-        assert.isNumber(radius, 'radius');
-
-        const sampler = this.sampler;
-        const samplerWidth = sampler.width;
-
-        const lastPixelY = sampler.height - 1;
-        const lastPixelX = samplerWidth - 1;
-
-        let changeFlag = false;
-
-        sampler.traverseCircle(x + 1, y + 1, radius, (x, y) => {
-
-            if (x <= 0 || x >= lastPixelX || y <= 0 || y >= lastPixelY) {
-                //edges are reserved to preserve cover outside of the working area
-                return;
-            }
-
-            const index = y * samplerWidth + x;
-
-            if (this.#scheduleCellFade(index, 0)) {
-                changeFlag = true;
-            }
-
-        });
-
-        if (changeFlag) {
-
-            this.rebuildDistanceField();
-
-        }
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {number} radius
-     */
-    conceal(x, y, radius) {
-        assert.isNumber(x, 'x');
-        assert.isNumber(y, 'y');
-        assert.isNumber(radius, 'radius');
-
-        const sampler = this.sampler;
-        const samplerWidth = sampler.width;
-
-        const lastPixelY = sampler.height - 1;
-        const lastPixelX = samplerWidth - 1;
-
-        let changeFlag = false;
-
-        sampler.traverseCircle(x + 1, y + 1, radius, (x, y) => {
-
-            if (x <= 0 || x >= lastPixelX || y <= 0 || y >= lastPixelY) {
-                //edges are reserved to preserve cover outside of the working area
-                return;
-            }
-
-            const index = y * samplerWidth + x;
-
-            if (this.#scheduleCellFade(index, 255)) {
-                changeFlag = true;
-            }
-
-        });
-
-        if (changeFlag) {
-
-            this.rebuildDistanceField();
-
-        }
-    }
-
-    /**
-     * Rebuild the cell -> fade row index from the current {@link fadeMask}
-     * contents. Must be invoked whenever the fade mask is populated without
-     * going through {@link reveal}/{@link conceal}/{@link revealPoint} (e.g.
-     * after deserialization), otherwise those methods could stack duplicate
-     * fade rows for a cell.
-     */
-    rebuildFadeIndex() {
-        const rowByCell = this.#fadeRowByCell;
-
-        rowByCell.clear();
-
-        const fadeMask = this.fadeMask;
-
-        const numRows = fadeMask.length;
-
-        for (let i = 0; i < numRows; i++) {
-            const index = fadeMask.readCellValue(i, 0);
-
-            rowByCell.set(index, i);
-        }
-    }
-
-    /**
-     * Copy the sampler's outermost REAL cells out into the 1-cell ring that
-     * {@link rebuildSampler} pads it with.
-     *
-     * That ring is padding — it exists so the shader's 5x5 blur and the distance
-     * field have something to read past the edge — and it is filled with full
-     * concealment. The blur then drags that concealment ~2 cells back INTO the
-     * fogged area, so the outermost cells of the world can never read as fully
-     * revealed however thoroughly they are explored; and every lookup from outside
-     * the area clamps onto it, which is what paints the void. Mirroring makes the
-     * padding agree with the edge it pads, on both counts.
-     *
-     * O(perimeter), and only on frames that upload a new texture.
-     *
-     * @private
-     */
-    #mirrorBorderRing() {
-        const s = this.sampler;
-
-        const w = s.width;
-        const h = s.height;
-
-        if (w < 3 || h < 3) {
-            // no interior to mirror from
-            return;
-        }
-
-        const data = s.data;
-
-        const last_row = (h - 1) * w;
-        const second_last_row = (h - 2) * w;
-
-        // top and bottom edges, corners excluded — those come from the sides below
-        for (let x = 1; x < w - 1; x++) {
-            data[x] = data[w + x];
-            data[last_row + x] = data[second_last_row + x];
-        }
-
-        // left and right edges, corners INCLUDED: the row above and below have
-        // already been mirrored, so a corner ends up with its diagonal neighbour's
-        // value rather than an arbitrary one
-        for (let y = 0; y < h; y++) {
-            const row = y * w;
-
-            data[row] = data[row + 1];
-            data[row + w - 1] = data[row + w - 2];
-        }
-    }
-
-    updateTexture() {
-        if (this.edge_mode === FogOfWarEdgeMode.Extend) {
-            // do this HERE, at the single point every reveal path funnels through
-            // on its way to the GPU, rather than in each of them
-            this.#mirrorBorderRing();
-        }
-
-        this.on.textureChanged.send0();
-
-        //clear flag
-        this.textureNeedsUpdate = false;
-    }
-
-    /**
-     *
-     * @param {number} timeDelta
-     */
-    update(timeDelta) {
-        this.updateFade(timeDelta);
-
-        if (this.textureNeedsUpdate) {
-            this.updateTexture();
-        }
-
-        if (this.distanceFieldNeedsUpdate) {
-            this.rebuildDistanceField();
-        }
-    }
-
-    /**
-     * Compute bounding box of revealed area in grid space, where coordinate system maps to discrete texels of the fog
-     * @param {AABB2} result
-     */
-    computeRevealedGridBoundingRectangle(result) {
-        const sampler = this.sampler;
-        const data = sampler.data;
-
-        const l = data.length;
-
-        const width = sampler.width;
-
-        let i = 0;
-
-        let x0 = width - 1, y0 = sampler.height - 1, x1 = 0, y1 = 0;
-
-        let x, y;
-
-        for (; i < l; i++) {
-            const value = data[i];
-
-            if (value !== 255) {
-                //revealed
-                x = i % width;
-                y = Math.floor(i / width);
-
-                x0 = min2(x, x0);
-                y0 = min2(y, y0);
-
-                x1 = max2(x, x1);
-                y1 = max2(y, y1);
-            }
-        }
-
-        result.set(x0, y0, x1, y1);
-    }
-
-    /**
-     *
-     * @param {number} x
-     * @param {number} y
-     * @param {number[]} result
-     */
-    worldToSamplePosition(x, y, result) {
-        const scale = this.scale.getValue();
-
-        const size = this.size;
-
-        const sizeX = size.x;
-        const sizeY = size.y;
-
-        const scaleX = (sizeX - 1) / (scale * sizeX);
-        const scaleY = (sizeY - 1) / (scale * sizeY);
-
-        result[0] = x * scaleX + 1;
-        result[1] = y * scaleY + 1;
-    }
-
-    /**
-     *
-     * @param {AABB3} aabb
-     * @param {Vector3} cameraFocalPoint
-     * @param {number} clearance distance to nearest non-occluding cell
-     */
-    computeAABBVisibility(aabb, cameraFocalPoint, clearance) {
-        assert.isNumber(clearance, 'clearance');
-
-        let sx0 = this.size.x - 1;
-        let sy0 = this.size.y - 1;
-        let sx1 = 0;
-        let sy1 = 0;
-
-        let i;
-
-        //cast ray from object's position along inverted view plane normal
-        corners2d[0] = aabb.x0;
-        corners2d[1] = aabb.z0;
-
-        corners2d[2] = aabb.x0;
-        corners2d[3] = aabb.z1;
-
-        corners2d[4] = aabb.x1;
-        corners2d[5] = aabb.z0;
-
-        corners2d[6] = aabb.x1;
-        corners2d[7] = aabb.z1;
-
-        const distanceSampler = this.distanceSampler;
-
-        //check corners, this is fast compared to checking each cell of fog overlapping bounding box
-        for (i = 0; i < 8; i += 2) {
-
-            const x = corners2d[i];
-            const z = corners2d[i + 1];
-
-            //scale down position to obtain sample position
-            this.worldToSamplePosition(x, z, samplePosition);
-            const sampleX = samplePosition[0];
-            const sampleY = samplePosition[1];
-
-            const sX = clamp(sampleX, 0, this.size.x - 1);
-            const sY = clamp(sampleY, 0, this.size.y - 1);
-
-            const distance = distanceSampler.readChannel(sX | 0, sY | 0, 0);
-
-            //Check if cell is visible
-            if (distance <= clearance) {
-                //if fog is not 100% opaque - return as visible
-                return true;
-            }
-
-            sx0 = min2(sx0, sX);
-            sy0 = min2(sy0, sY);
-
-            sx1 = max2(sx1, sX);
-            sy1 = max2(sy1, sY);
-        }
-
-        sx0 = Math.floor(sx0);
-        sy0 = Math.floor(sy0);
-        sx1 = Math.ceil(sx1);
-        sy1 = Math.ceil(sy1);
-
-        const shExtX = Math.ceil((sx1 - sx0) / 2);
-        const shExtY = Math.ceil((sy1 - sy0) / 2);
-
-        const sMidX = sx0 + shExtX;
-        const sMidY = sy0 + shExtY;
-
-        const centerOcclusionDistance = distanceSampler.readChannel(sMidX | 0, sMidY | 0, 0);
-
-        const maxDistanceFromCenter = max2(shExtX, shExtY);
-
-        const distanceToNearestClearance = centerOcclusionDistance - maxDistanceFromCenter;
-
-        if (distanceToNearestClearance > clearance) {
-            //distance from center of the rectangle to nearest non-occluded region is too great,  treat as fully occluded
-            return false;
-        } else {
-            return true;
-        }
-    }
-
-    /**
-     * Returns fog clearance from a set of world coordinates
-     * @param {number} x world X coordinate
-     * @param {number} y world Y coordinate
-     * @returns {number} clearance value
-     */
-    getWorldClearance(x, y) {
-        this.worldToSamplePosition(x, y, samplePosition);
-
-        const sampleX = samplePosition[0];
-        const sampleY = samplePosition[1];
-
-        return this.distanceSampler.readChannel(sampleX | 0, sampleY | 0, 0);
-    }
-
-    rebuildDistanceField() {
-        // console.time('computeSignedDistanceField');
-        computeUnsignedDistanceField(this.sampler, this.distanceSampler, 255);
-        // console.timeEnd('computeSignedDistanceField');
-        this.distanceFieldNeedsUpdate = false;
-    }
-
-    rebuildDistanceSampler() {
-        const array = new Uint8Array(this.sampler.width * this.sampler.height);
-        array.fill(0);
-
-        this.distanceSampler.data = array;
-        this.distanceSampler.width = this.sampler.width;
-        this.distanceSampler.height = this.sampler.height;
-
-        this.rebuildDistanceField();
-    }
-
-    rebuildSampler() {
-
-        //resize the sampler
-        const samplerWidth = this.size.x + 2;
-        const samplerHeight = this.size.y + 2;
-        const uint8Array = new Uint8Array(samplerWidth * samplerHeight);
-
-        uint8Array.fill(255);
-
-        const sampler = new Sampler2D(uint8Array, 1, samplerWidth, samplerHeight);
-
-        sampler.copy(this.sampler, 0, 0, 0, 0, this.sampler.width, this.sampler.height);
-
-        //rewrite sampler
-        this.sampler.data = sampler.data;
-        this.sampler.width = sampler.width;
-        this.sampler.height = sampler.height;
-
-        //rebuild distance sampler
-        this.rebuildDistanceSampler();
-
-
-        //Mark texture for update
-        this.textureNeedsUpdate = true;
-
-    }
-
-
-    /**
-     *
-     * @param {number} w
-     * @param {number} h
-     * @param scale
-     */
-    resize(w, h, scale) {
-        this.size.set(w, h);
-        this.scale.set(scale);
-
-        //TODO update fade mask as necessary - the sampler indices change with the
-        //new width, so any in-progress fade rows (and the #fadeRowByCell index that
-        //mirrors them) would need remapping or clearing. Only reachable at link time
-        //today, when both are empty.
-
-        this.rebuildSampler();
-    }
-}
-
-FogOfWar.typeName = 'FogOfWar';
-
-
+import { assert } from "../../../core/assert.js";
+import { BinaryDataType } from "../../../core/binary/type/BinaryDataType.js";
+import { RowFirstTable } from "../../../core/collection/table/RowFirstTable.js";
+import { RowFirstTableSpec } from "../../../core/collection/table/RowFirstTableSpec.js";
+import Signal from "../../../core/events/signal/Signal.js";
+import Vector1 from "../../../core/geom/Vector1.js";
+import Vector2 from "../../../core/geom/Vector2.js";
+import Vector4 from "../../../core/geom/Vector4.js";
+import { clamp } from "../../../core/math/clamp.js";
+import { max2 } from "../../../core/math/max2.js";
+import { min2 } from "../../../core/math/min2.js";
+import { computeUnsignedDistanceField } from "../../graphics/texture/sampler/distance/computeUnsignedDistanceField.js";
+import { Sampler2D } from "../../graphics/texture/sampler/Sampler2D.js";
+import { FogOfWarEdgeMode } from "./FogOfWarEdgeMode.js";
+
+const samplePosition = [];
+
+const corners2d = new Float64Array(8);
+
+/**
+ * Measured in Uint8 channel value per second.
+ * @example 255 would mean complete fade happens in 1s, 25.5 would mean fade happens over 10 seconds
+ * @readonly
+ * @type {number}
+ */
+const FADE_SPEED = 255;
+
+/**
+ * pre-fade to enable correct distance field calculation
+ * @readonly
+ * @type {number}
+ */
+const INITIAL_FADE_VALUE = 254;
+
+/**
+ *
+ * @type {RowFirstTableSpec}
+ */
+const revealMaskTableSpec = new RowFirstTableSpec([
+    BinaryDataType.Int32, // Index
+    BinaryDataType.Float32, // Precise current value
+    BinaryDataType.Float32 // Fade speed
+]);
+
+const fadeRow = [];
+
+/**
+ * @class
+ */
+export class FogOfWar {
+
+    /**
+     *
+     * @type {boolean}
+     */
+    textureNeedsUpdate = true;
+    /**
+     *
+     * @type {boolean}
+     */
+    distanceFieldNeedsUpdate = false;
+
+    /**
+     * Resolution scale of FoW versus terrain resolution, higher number makes FoW more detailed
+     * @type {Vector1}
+     */
+    scale = new Vector1(1);
+
+    /**
+     * Size of the fog area
+     * @type {Vector2}
+     */
+    size = new Vector2(0, 0);
+
+    color = new Vector4(0.1, 0.1, 0.1, 1);
+
+    /**
+     * What the fog does outside the fogged area — see {@link FogOfWarEdgeMode}.
+     *
+     * NOT serialized: it is configuration the owner sets when it builds the
+     * component, not accumulated reveal state, and adding it to the binary format
+     * would cost a version bump plus an updater for every existing save. A
+     * deserialized FogOfWar therefore comes back as Conceal; a consumer that
+     * wants Extend sets it after loading, in the same place it sets {@link color}.
+     *
+     * @type {FogOfWarEdgeMode}
+     */
+    edge_mode = FogOfWarEdgeMode.Conceal;
+
+    /**
+     * Contains indices of pixes that are currently being updated
+     * @type {RowFirstTable}
+     */
+    fadeMask = new RowFirstTable(revealMaskTableSpec);
+
+    /**
+     * Maps a sampler cell index to the row index of its in-progress fade in
+     * {@link fadeMask}. Enforces at most one fade row per cell, so that the
+     * latest reveal/conceal command for a cell re-aims its existing fade
+     * instead of stacking a second, opposing row.
+     * @type {Map<number, number>}
+     */
+    #fadeRowByCell = new Map();
+
+    on = {
+        textureChanged: new Signal()
+    };
+
+    /**
+     *
+     * @type {Sampler2D}
+     */
+    sampler = Sampler2D.uint8(1, 0, 0);
+
+    /**
+     *
+     * @type {Sampler2D}
+     */
+    distanceSampler = Sampler2D.uint8(1, 0, 0);
+
+    /**
+     *
+     * @param {number} timeDelta
+     */
+    updateFade(timeDelta) {
+        const samplerData = this.sampler.data;
+
+        const fadeMask = this.fadeMask;
+
+        const rowByCell = this.#fadeRowByCell;
+
+        let numRows = fadeMask.length;
+
+        let i = 0;
+
+        for (; i < numRows; i++) {
+            //read row
+            fadeMask.readRow(i, fadeRow);
+
+            //decode row
+            const index = fadeRow[0];
+            const oldValue = fadeRow[1];
+            const speed = fadeRow[2];
+
+            //compute new value
+            const value = oldValue + (speed * timeDelta);
+
+            let writeValue = value | 0;
+
+            //store the advanced precise value
+            fadeMask.writeCellValue(i, 1, value);
+
+            let completed = false;
+
+            if (value <= 0) {
+                writeValue = 0;
+
+                if (speed < 0) {
+                    //revealing fade reached the bottom
+                    completed = true;
+                }
+            } else if (value >= 255) {
+                writeValue = 255;
+
+                if (speed > 0) {
+                    //concealing fade reached the top
+                    completed = true;
+                }
+            }
+
+            if ((oldValue | 0) !== writeValue) {
+                //value has changed
+                samplerData[index] = writeValue;
+                this.textureNeedsUpdate = true;
+            }
+
+            if (completed) {
+                //Drop the finished row while keeping the cell->row index
+                //consistent. Swap the last row into this slot (O(1)) instead of
+                //shifting the whole tail forward, so only one other row's index
+                //needs to be patched in the map.
+                rowByCell.delete(index);
+
+                const lastRow = numRows - 1;
+
+                if (i !== lastRow) {
+                    const movedCell = fadeMask.readCellValue(lastRow, 0);
+
+                    fadeMask.copyRow(lastRow, i);
+
+                    rowByCell.set(movedCell, i);
+                }
+
+                fadeMask.removeRows(lastRow, 1);
+
+                i--;
+                numRows--;
+            }
+        }
+    }
+
+    /**
+     * Schedule (or re-aim) a fade for a single sampler cell so that it converges
+     * to `target`. Guarantees at most one fade row per cell: if the cell already
+     * has an in-progress fade its direction is updated in place, so the latest
+     * command wins instead of stacking a second, opposing row.
+     * @param {number} index sampler cell index
+     * @param {number} target target sampler value, either 0 (revealed) or 255 (concealed)
+     * @returns {boolean} whether the visible sampler value was changed (i.e. the distance field may need a rebuild)
+     */
+    #scheduleCellFade(index, target) {
+        const fadeMask = this.fadeMask;
+        const rowByCell = this.#fadeRowByCell;
+
+        const speed = target === 0 ? -FADE_SPEED : FADE_SPEED;
+
+        const existingRow = rowByCell.get(index);
+
+        if (existingRow !== undefined) {
+            //A fade is already in progress for this cell, re-aim it in place.
+            //The precise value column is left untouched so the fade resumes from
+            //its current progress and never snaps back through the far end.
+            fadeMask.writeCellValue(existingRow, 2, speed);
+
+            return false;
+        }
+
+        const samplerData = this.sampler.data;
+
+        const current = samplerData[index];
+
+        if (current === target) {
+            //already fully at the target, nothing to fade
+            return false;
+        }
+
+        let seedValue = current;
+        let visibleChanged = false;
+
+        if (target === 0 && current === 255) {
+            //pre-fade off the fully-concealed value so the distance field
+            //immediately treats this cell as being revealed
+            seedValue = INITIAL_FADE_VALUE;
+            samplerData[index] = INITIAL_FADE_VALUE;
+            visibleChanged = true;
+        }
+
+        //add record to fade mask
+        fadeRow[0] = index;
+        fadeRow[1] = seedValue;
+        fadeRow[2] = speed;
+
+        const rowIndex = fadeMask.addRow(fadeRow);
+
+        rowByCell.set(index, rowIndex);
+
+        return visibleChanged;
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     */
+    revealPoint(x, y) {
+        const samplerWidth = this.sampler.width;
+
+        const index = (y + 1) * samplerWidth + (x + 1);
+
+        if (this.#scheduleCellFade(index, 0)) {
+            this.distanceFieldNeedsUpdate = true;
+        }
+    }
+
+    clear() {
+        this.fadeMask.clear();
+        this.#fadeRowByCell.clear();
+
+        this.sampler.data.fill(255);
+
+        this.distanceFieldNeedsUpdate = true;
+        this.textureNeedsUpdate = true;
+    }
+
+    revealAll() {
+        this.fadeMask.clear();
+        this.#fadeRowByCell.clear();
+
+        this.sampler.data.fill(0);
+
+        this.distanceFieldNeedsUpdate = true;
+        this.textureNeedsUpdate = true;
+    }
+
+    concealAll() {
+        this.clear();
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} radius
+     */
+    reveal(x, y, radius) {
+        assert.isNumber(x, 'x');
+        assert.isNumber(y, 'y');
+        assert.isNumber(radius, 'radius');
+
+        const sampler = this.sampler;
+        const samplerWidth = sampler.width;
+
+        const lastPixelY = sampler.height - 1;
+        const lastPixelX = samplerWidth - 1;
+
+        let changeFlag = false;
+
+        sampler.traverseCircle(x + 1, y + 1, radius, (x, y) => {
+
+            if (x <= 0 || x >= lastPixelX || y <= 0 || y >= lastPixelY) {
+                //edges are reserved to preserve cover outside of the working area
+                return;
+            }
+
+            const index = y * samplerWidth + x;
+
+            if (this.#scheduleCellFade(index, 0)) {
+                changeFlag = true;
+            }
+
+        });
+
+        if (changeFlag) {
+
+            this.rebuildDistanceField();
+
+        }
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number} radius
+     */
+    conceal(x, y, radius) {
+        assert.isNumber(x, 'x');
+        assert.isNumber(y, 'y');
+        assert.isNumber(radius, 'radius');
+
+        const sampler = this.sampler;
+        const samplerWidth = sampler.width;
+
+        const lastPixelY = sampler.height - 1;
+        const lastPixelX = samplerWidth - 1;
+
+        let changeFlag = false;
+
+        sampler.traverseCircle(x + 1, y + 1, radius, (x, y) => {
+
+            if (x <= 0 || x >= lastPixelX || y <= 0 || y >= lastPixelY) {
+                //edges are reserved to preserve cover outside of the working area
+                return;
+            }
+
+            const index = y * samplerWidth + x;
+
+            if (this.#scheduleCellFade(index, 255)) {
+                changeFlag = true;
+            }
+
+        });
+
+        if (changeFlag) {
+
+            this.rebuildDistanceField();
+
+        }
+    }
+
+    /**
+     * Rebuild the cell -> fade row index from the current {@link fadeMask}
+     * contents. Must be invoked whenever the fade mask is populated without
+     * going through {@link reveal}/{@link conceal}/{@link revealPoint} (e.g.
+     * after deserialization), otherwise those methods could stack duplicate
+     * fade rows for a cell.
+     */
+    rebuildFadeIndex() {
+        const rowByCell = this.#fadeRowByCell;
+
+        rowByCell.clear();
+
+        const fadeMask = this.fadeMask;
+
+        const numRows = fadeMask.length;
+
+        for (let i = 0; i < numRows; i++) {
+            const index = fadeMask.readCellValue(i, 0);
+
+            rowByCell.set(index, i);
+        }
+    }
+
+    /**
+     * Copy the sampler's outermost REAL cells out into the 1-cell ring that
+     * {@link rebuildSampler} pads it with.
+     *
+     * That ring is padding — it exists so the shader's 5x5 blur and the distance
+     * field have something to read past the edge — and it is filled with full
+     * concealment. The blur then drags that concealment ~2 cells back INTO the
+     * fogged area, so the outermost cells of the world can never read as fully
+     * revealed however thoroughly they are explored; and every lookup from outside
+     * the area clamps onto it, which is what paints the void. Mirroring makes the
+     * padding agree with the edge it pads, on both counts.
+     *
+     * O(perimeter), and only on frames that upload a new texture.
+     *
+     * @private
+     */
+    #mirrorBorderRing() {
+        const s = this.sampler;
+
+        const w = s.width;
+        const h = s.height;
+
+        if (w < 3 || h < 3) {
+            // no interior to mirror from
+            return;
+        }
+
+        const data = s.data;
+
+        const last_row = (h - 1) * w;
+        const second_last_row = (h - 2) * w;
+
+        // top and bottom edges, corners excluded — those come from the sides below
+        for (let x = 1; x < w - 1; x++) {
+            data[x] = data[w + x];
+            data[last_row + x] = data[second_last_row + x];
+        }
+
+        // left and right edges, corners INCLUDED: the row above and below have
+        // already been mirrored, so a corner ends up with its diagonal neighbour's
+        // value rather than an arbitrary one
+        for (let y = 0; y < h; y++) {
+            const row = y * w;
+
+            data[row] = data[row + 1];
+            data[row + w - 1] = data[row + w - 2];
+        }
+    }
+
+    updateTexture() {
+        if (this.edge_mode === FogOfWarEdgeMode.Extend) {
+            // do this HERE, at the single point every reveal path funnels through
+            // on its way to the GPU, rather than in each of them
+            this.#mirrorBorderRing();
+        }
+
+        this.on.textureChanged.send0();
+
+        //clear flag
+        this.textureNeedsUpdate = false;
+    }
+
+    /**
+     *
+     * @param {number} timeDelta
+     */
+    update(timeDelta) {
+        this.updateFade(timeDelta);
+
+        if (this.textureNeedsUpdate) {
+            this.updateTexture();
+        }
+
+        if (this.distanceFieldNeedsUpdate) {
+            this.rebuildDistanceField();
+        }
+    }
+
+    /**
+     * Compute bounding box of revealed area in grid space, where coordinate system maps to discrete texels of the fog
+     * @param {AABB2} result
+     */
+    computeRevealedGridBoundingRectangle(result) {
+        const sampler = this.sampler;
+        const data = sampler.data;
+
+        const l = data.length;
+
+        const width = sampler.width;
+
+        let i = 0;
+
+        let x0 = width - 1, y0 = sampler.height - 1, x1 = 0, y1 = 0;
+
+        let x, y;
+
+        for (; i < l; i++) {
+            const value = data[i];
+
+            if (value !== 255) {
+                //revealed
+                x = i % width;
+                y = Math.floor(i / width);
+
+                x0 = min2(x, x0);
+                y0 = min2(y, y0);
+
+                x1 = max2(x, x1);
+                y1 = max2(y, y1);
+            }
+        }
+
+        result.set(x0, y0, x1, y1);
+    }
+
+    /**
+     *
+     * @param {number} x
+     * @param {number} y
+     * @param {number[]} result
+     */
+    worldToSamplePosition(x, y, result) {
+        const scale = this.scale.getValue();
+
+        const size = this.size;
+
+        const sizeX = size.x;
+        const sizeY = size.y;
+
+        const scaleX = (sizeX - 1) / (scale * sizeX);
+        const scaleY = (sizeY - 1) / (scale * sizeY);
+
+        result[0] = x * scaleX + 1;
+        result[1] = y * scaleY + 1;
+    }
+
+    /**
+     *
+     * @param {AABB3} aabb
+     * @param {Vector3} cameraFocalPoint
+     * @param {number} clearance distance to nearest non-occluding cell
+     */
+    computeAABBVisibility(aabb, cameraFocalPoint, clearance) {
+        assert.isNumber(clearance, 'clearance');
+
+        let sx0 = this.size.x - 1;
+        let sy0 = this.size.y - 1;
+        let sx1 = 0;
+        let sy1 = 0;
+
+        let i;
+
+        //cast ray from object's position along inverted view plane normal
+        corners2d[0] = aabb.x0;
+        corners2d[1] = aabb.z0;
+
+        corners2d[2] = aabb.x0;
+        corners2d[3] = aabb.z1;
+
+        corners2d[4] = aabb.x1;
+        corners2d[5] = aabb.z0;
+
+        corners2d[6] = aabb.x1;
+        corners2d[7] = aabb.z1;
+
+        const distanceSampler = this.distanceSampler;
+
+        //check corners, this is fast compared to checking each cell of fog overlapping bounding box
+        for (i = 0; i < 8; i += 2) {
+
+            const x = corners2d[i];
+            const z = corners2d[i + 1];
+
+            //scale down position to obtain sample position
+            this.worldToSamplePosition(x, z, samplePosition);
+            const sampleX = samplePosition[0];
+            const sampleY = samplePosition[1];
+
+            const sX = clamp(sampleX, 0, this.size.x - 1);
+            const sY = clamp(sampleY, 0, this.size.y - 1);
+
+            const distance = distanceSampler.readChannel(sX | 0, sY | 0, 0);
+
+            //Check if cell is visible
+            if (distance <= clearance) {
+                //if fog is not 100% opaque - return as visible
+                return true;
+            }
+
+            sx0 = min2(sx0, sX);
+            sy0 = min2(sy0, sY);
+
+            sx1 = max2(sx1, sX);
+            sy1 = max2(sy1, sY);
+        }
+
+        sx0 = Math.floor(sx0);
+        sy0 = Math.floor(sy0);
+        sx1 = Math.ceil(sx1);
+        sy1 = Math.ceil(sy1);
+
+        const shExtX = Math.ceil((sx1 - sx0) / 2);
+        const shExtY = Math.ceil((sy1 - sy0) / 2);
+
+        const sMidX = sx0 + shExtX;
+        const sMidY = sy0 + shExtY;
+
+        const centerOcclusionDistance = distanceSampler.readChannel(sMidX | 0, sMidY | 0, 0);
+
+        const maxDistanceFromCenter = max2(shExtX, shExtY);
+
+        const distanceToNearestClearance = centerOcclusionDistance - maxDistanceFromCenter;
+
+        if (distanceToNearestClearance > clearance) {
+            //distance from center of the rectangle to nearest non-occluded region is too great,  treat as fully occluded
+            return false;
+        } else {
+            return true;
+        }
+    }
+
+    /**
+     * Returns fog clearance from a set of world coordinates
+     * @param {number} x world X coordinate
+     * @param {number} y world Y coordinate
+     * @returns {number} clearance value
+     */
+    getWorldClearance(x, y) {
+        this.worldToSamplePosition(x, y, samplePosition);
+
+        const sampleX = samplePosition[0];
+        const sampleY = samplePosition[1];
+
+        return this.distanceSampler.readChannel(sampleX | 0, sampleY | 0, 0);
+    }
+
+    rebuildDistanceField() {
+        // console.time('computeSignedDistanceField');
+        computeUnsignedDistanceField(this.sampler, this.distanceSampler, 255);
+        // console.timeEnd('computeSignedDistanceField');
+        this.distanceFieldNeedsUpdate = false;
+    }
+
+    rebuildDistanceSampler() {
+        const array = new Uint8Array(this.sampler.width * this.sampler.height);
+        array.fill(0);
+
+        this.distanceSampler.data = array;
+        this.distanceSampler.width = this.sampler.width;
+        this.distanceSampler.height = this.sampler.height;
+
+        this.rebuildDistanceField();
+    }
+
+    rebuildSampler() {
+
+        //resize the sampler
+        const samplerWidth = this.size.x + 2;
+        const samplerHeight = this.size.y + 2;
+        const uint8Array = new Uint8Array(samplerWidth * samplerHeight);
+
+        uint8Array.fill(255);
+
+        const sampler = new Sampler2D(uint8Array, 1, samplerWidth, samplerHeight);
+
+        sampler.copy(this.sampler, 0, 0, 0, 0, this.sampler.width, this.sampler.height);
+
+        //rewrite sampler
+        this.sampler.data = sampler.data;
+        this.sampler.width = sampler.width;
+        this.sampler.height = sampler.height;
+
+        //rebuild distance sampler
+        this.rebuildDistanceSampler();
+
+
+        //Mark texture for update
+        this.textureNeedsUpdate = true;
+
+    }
+
+
+    /**
+     *
+     * @param {number} w
+     * @param {number} h
+     * @param scale
+     */
+    resize(w, h, scale) {
+        this.size.set(w, h);
+        this.scale.set(scale);
+
+        //TODO update fade mask as necessary - the sampler indices change with the
+        //new width, so any in-progress fade rows (and the #fadeRowByCell index that
+        //mirrors them) would need remapping or clearing. Only reachable at link time
+        //today, when both are empty.
+
+        this.rebuildSampler();
+    }
+}
+
+FogOfWar.typeName = 'FogOfWar';
+
+