@woosh/meep-engine 3.14.2 → 3.14.3

package/src/shade/renderer/texture/encode/chunk_bc4_encode_block.js

@@ -0,0 +1,348 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_bc4_pack_block } from "./chunk_bc4_pack_block.js";
+
+/**
+ * Encode sixteen values as one BC4 block — unsigned through `bc4_encode_block`, signed through
+ * `bc4_encode_block_snorm`.
+ *
+ * **A fixed budget, spent where it counts.** One invocation owns one block, and everything below is
+ * loops of constant trip count over sixteen registers — no search whose depth depends on the
+ * content, because a compute lane that finishes early only waits for the one that did not.
+ *
+ * Two palettes are fitted and the better one is written, and each fit is the same three steps:
+ *
+ * 1. **The bounding line, refined by least squares.** The extremes are where every real-time encoder
+ *    starts, and where the 2007 real-time DXT work stopped, insetting them by a fraction of the
+ *    range instead. Solving the endpoints properly given the current step assignment — the normal
+ *    equations `fit_endpoints.js` solves — then reassigning, is what `stb_dxt`, `rgbcx` and the
+ *    NVIDIA tools all do, and two rounds are where it stops paying.
+ * 2. **A search of the integer endpoints around it, coarse to fine.** Least squares answers the
+ *    question it was asked — the best line *for the assignment it was given* — and the assignment
+ *    it was given is the one the seed line implied. Where a shorter line would serve most texels
+ *    better and hand the odd one to a neighbouring level, the solution sits in a different basin and
+ *    no rounding of the local answer reaches it. Scoring a candidate pair is sixteen texels' work, so
+ *    the basin is searched outright: five by five pairs at a spacing of eight, then two, then one,
+ *    seventy-five scores per mode, each against the palette the decoder will actually build. On the
+ *    mask fixture this is worth three decibels over the least-squares answer alone; on smooth content
+ *    it changes nothing and costs the same.
+ * 3. **Both modes.** `first > second` gives eight values along the line. `first <= second` gives six
+ *    along it plus the two hard extremes of the domain — so its line is seeded over the texels
+ *    *between* the extremes, and a block holding both extremes and a narrow band of values fits the
+ *    band with all six levels and gets the extremes for nothing. A mask with a soft edge is exactly
+ *    that block, and the eight-value line would spend its levels crossing the whole range.
+ *
+ * Every error is scored against the palette the decoder builds — each entry rounded to a level — and
+ * not against the real line, which is why the nearest step is checked with its two neighbours: the
+ * nearest point on the line is not always the nearest rounded entry.
+ *
+ * **The signed format is the same fit in a different domain**, which is why it is a second entry
+ * point and not a second chunk: its endpoints are two's-complement bytes decoded over `[-127, 127]`
+ * (`-128` reads as `-127`) and its six-value mode's hard entries are `-127` and `127`, so the domain's
+ * bounds are the only thing that changes. The unsigned path fits `[0, 1]` in `[0, 255]`; the signed
+ * one fits `[-1, 1]` in `[-127, 127]`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc4_encode_block = CodeChunk.from(
+    //language=WGSL
+    `
+// the palette's entry at a step along the line from the first endpoint (step 0) to the second
+// (the last step: 7 for the eight-value mode, 5 for the six), rounded as the decoder rounds it
+fn bc4_palette_entry(first: f32, second: f32, steps: f32, step: f32) -> f32 {
+    return round((first * (steps - step) + second * step) / steps);
+}
+
+// the index a step along the line is stored as: the endpoints themselves are indices 0 and 1, and the
+// steps between them count from 2
+fn bc4_step_index(step: u32, last: u32) -> u32 {
+    if (step == 0u) {
+        return 0u;
+    }
+
+    if (step == last) {
+        return 1u;
+    }
+
+    return step + 1u;
+}
+
+// the nearest step on the rounded line to a value, and how far off it is: the analytic step on the
+// real line, checked against its two neighbours
+fn bc4_nearest_step(first: f32, second: f32, steps: f32, value: f32) -> vec2<f32> {
+    let step = clamp(round((value - first) * steps / (second - first)), 0.0, steps);
+
+    let below = max(step - 1.0, 0.0);
+    let above = min(step + 1.0, steps);
+
+    var best = step;
+    var best_distance = abs(bc4_palette_entry(first, second, steps, step) - value);
+
+    let below_distance = abs(bc4_palette_entry(first, second, steps, below) - value);
+
+    if (below_distance < best_distance) {
+        best = below;
+        best_distance = below_distance;
+    }
+
+    let above_distance = abs(bc4_palette_entry(first, second, steps, above) - value);
+
+    if (above_distance < best_distance) {
+        best = above;
+        best_distance = above_distance;
+    }
+
+    return vec2<f32>(best, best_distance);
+}
+
+// the nearest entry of the six-value palette: a step 0 to 5 on the line, or 6 for the domain's low
+// extreme and 7 for its high one
+fn bc4_nearest6(first: f32, second: f32, value: f32, floor_value: f32, ceil_value: f32) -> vec2<f32> {
+    var best = bc4_nearest_step(first, second, 5.0, value);
+
+    if (value - floor_value < best.y) {
+        best = vec2<f32>(6.0, value - floor_value);
+    }
+
+    if (ceil_value - value < best.y) {
+        best = vec2<f32>(7.0, ceil_value - value);
+    }
+
+    return best;
+}
+
+// the block's squared error against a pair of integer endpoints, in the mode their order selects;
+// a pair the mode cannot store scores as unusable
+fn bc4_score(values: array<f32, 16>, first: i32, second: i32, eight: bool, floor_value: f32, ceil_value: f32) -> f32 {
+    if (f32(first) < floor_value || f32(first) > ceil_value || f32(second) < floor_value || f32(second) > ceil_value) {
+        return 1e30;
+    }
+
+    if (eight != (first > second)) {
+        return 1e30;
+    }
+
+    var error = 0.0;
+
+    if (eight) {
+        for (var i = 0u; i < 16u; i++) {
+            let distance = bc4_nearest_step(f32(first), f32(second), 7.0, values[i]).y;
+
+            error += distance * distance;
+        }
+    } else {
+        for (var i = 0u; i < 16u; i++) {
+            let distance = bc4_nearest6(f32(first), f32(second), values[i], floor_value, ceil_value).y;
+
+            error += distance * distance;
+        }
+    }
+
+    return error;
+}
+
+// the endpoints that best reproduce the weighted values at the steps they are nearest to on the given
+// line: the two-by-two normal equations, as fit_endpoints.js solves them. A weight of zero leaves a
+// texel out of the fit, which is how the six-value line ignores the texels its hard entries take
+fn bc4_refine(values: array<f32, 16>, weights: array<f32, 16>, first: f32, second: f32, steps: f32) -> vec2<f32> {
+    let scale = steps / (second - first);
+
+    var aa = 0.0;
+    var ab = 0.0;
+    var bb = 0.0;
+    var ap = 0.0;
+    var bp = 0.0;
+
+    for (var i = 0u; i < 16u; i++) {
+        let v = values[i];
+        let w = weights[i];
+
+        let b = clamp(round((v - first) * scale), 0.0, steps) / steps;
+        let a = 1.0 - b;
+
+        aa += w * a * a;
+        ab += w * a * b;
+        bb += w * b * b;
+        ap += w * a * v;
+        bp += w * b * v;
+    }
+
+    let determinant = aa * bb - ab * ab;
+
+    // singular when every weighted value took the same step; the line is as good as it gets
+    if (abs(determinant) < 1e-6) {
+        return vec2<f32>(first, second);
+    }
+
+    return vec2<f32>(
+        (bb * ap - ab * bp) / determinant,
+        (aa * bp - ab * ap) / determinant
+    );
+}
+
+// a line from its two extremes, refined twice; a refinement that collapses the line is discarded
+fn bc4_fit_line(values: array<f32, 16>, weights: array<f32, 16>, first: f32, second: f32, steps: f32, floor_value: f32, ceil_value: f32) -> vec2<f32> {
+    var line = vec2<f32>(first, second);
+
+    for (var iteration = 0u; iteration < 2u; iteration++) {
+        let refined = clamp(bc4_refine(values, weights, line.x, line.y, steps), vec2<f32>(floor_value), vec2<f32>(ceil_value));
+
+        if (abs(refined.x - refined.y) < 1.0) {
+            break;
+        }
+
+        line = refined;
+    }
+
+    return line;
+}
+
+// the best integer pair near a seed: five by five candidates at a spacing of eight, then two, then
+// one, each level centred on the best so far. Seventy-five scores, whatever the block
+fn bc4_search(values: array<f32, 16>, seed: vec2<f32>, eight: bool, floor_value: f32, ceil_value: f32) -> vec3<f32> {
+    var best_first = i32(round(seed.x));
+    var best_second = i32(round(seed.y));
+    var best = bc4_score(values, best_first, best_second, eight, floor_value, ceil_value);
+
+    for (var level = 0u; level < 3u; level++) {
+        let spacing = select(select(1, 2, level == 1u), 8, level == 0u);
+
+        let centre_first = best_first;
+        let centre_second = best_second;
+
+        for (var di = -2; di <= 2; di++) {
+            for (var dj = -2; dj <= 2; dj++) {
+                let first = centre_first + di * spacing;
+                let second = centre_second + dj * spacing;
+
+                let error = bc4_score(values, first, second, eight, floor_value, ceil_value);
+
+                if (error < best) {
+                    best = error;
+                    best_first = first;
+                    best_second = second;
+                }
+            }
+        }
+    }
+
+    return vec3<f32>(f32(best_first), f32(best_second), best);
+}
+
+// the fit itself, over values already in the domain's integer range: [0, 255] for the unsigned
+// format, [-127, 127] for the signed one
+fn bc4_fit_block(scaled: array<f32, 16>, floor_value: f32, ceil_value: f32) -> vec2<u32> {
+    var everything: array<f32, 16>;
+    var interior: array<f32, 16>;
+
+    var low = ceil_value;
+    var high = floor_value;
+
+    // the extremes of the values a hard entry would not serve better than the line
+    var interior_low = ceil_value;
+    var interior_high = floor_value;
+    var interior_count = 0u;
+
+    for (var i = 0u; i < 16u; i++) {
+        let v = scaled[i];
+
+        everything[i] = 1.0;
+
+        low = min(low, v);
+        high = max(high, v);
+
+        let inside = v > floor_value + 0.5 && v < ceil_value - 0.5;
+
+        interior[i] = select(0.0, 1.0, inside);
+
+        if (inside) {
+            interior_low = min(interior_low, v);
+            interior_high = max(interior_high, v);
+            interior_count += 1u;
+        }
+    }
+
+    var indices: array<u32, 16>;
+
+    for (var i = 0u; i < 16u; i++) {
+        indices[i] = 0u;
+    }
+
+    // a flat block: equal endpoints select the six-value mode, whose index 0 decodes to the endpoint
+    // itself, so the block is exact and no fit is needed
+    if (high - low < 0.5) {
+        let flat = u32(i32(round((low + high) * 0.5))) & 255u;
+
+        return bc4_pack_block(flat, flat, indices);
+    }
+
+    var best_error = 1e30;
+    var best_first = 0u;
+    var best_second = 0u;
+    var best_eight = true;
+
+    // the eight-value line runs from the first endpoint down to the second, over every texel; the
+    // seed is nudged apart so the search starts on a pair the mode can store
+    let seed8 = bc4_fit_line(scaled, everything, high, low, 7.0, floor_value, ceil_value);
+
+    var best = bc4_search(scaled, vec2<f32>(max(seed8.x, seed8.y + 1.0), min(seed8.y, seed8.x - 1.0)), true, floor_value, ceil_value);
+    var best_eight_mode = true;
+
+    // the six-value line runs upwards over the interior alone; a block with no interior is the two
+    // extremes, which the eight-value line already holds exactly
+    if (interior_count > 0u) {
+        var seed6 = vec2<f32>(interior_low, interior_high);
+
+        if (interior_high - interior_low >= 1.0) {
+            seed6 = bc4_fit_line(scaled, interior, interior_low, interior_high, 5.0, floor_value, ceil_value);
+        }
+
+        let found = bc4_search(scaled, vec2<f32>(min(seed6.x, seed6.y - 1.0), max(seed6.y, seed6.x + 1.0)), false, floor_value, ceil_value);
+
+        if (found.z < best.z) {
+            best = found;
+            best_eight_mode = false;
+        }
+    }
+
+    let first = best.x;
+    let second = best.y;
+
+    if (best_eight_mode) {
+        for (var i = 0u; i < 16u; i++) {
+            indices[i] = bc4_step_index(u32(bc4_nearest_step(first, second, 7.0, scaled[i]).x), 7u);
+        }
+    } else {
+        for (var i = 0u; i < 16u; i++) {
+            let step = u32(bc4_nearest6(first, second, scaled[i], floor_value, ceil_value).x);
+
+            // steps 6 and 7 are the hard extremes, stored as those indices directly
+            indices[i] = select(bc4_step_index(step, 5u), step, step >= 6u);
+        }
+    }
+
+    // two's complement for the signed domain, the identity for the unsigned one
+    return bc4_pack_block(u32(i32(first)) & 255u, u32(i32(second)) & 255u, indices);
+}
+
+fn bc4_encode_block(values: array<f32, 16>) -> vec2<u32> {
+    var scaled: array<f32, 16>;
+
+    for (var i = 0u; i < 16u; i++) {
+        scaled[i] = clamp(values[i], 0.0, 1.0) * 255.0;
+    }
+
+    return bc4_fit_block(scaled, 0.0, 255.0);
+}
+
+fn bc4_encode_block_snorm(values: array<f32, 16>) -> vec2<u32> {
+    var scaled: array<f32, 16>;
+
+    for (var i = 0u; i < 16u; i++) {
+        scaled[i] = clamp(values[i], -1.0, 1.0) * 127.0;
+    }
+
+    return bc4_fit_block(scaled, -127.0, 127.0);
+}
+`, [
+        chunk_bc4_pack_block,
+    ]);

package/src/shade/renderer/texture/encode/chunk_bc4_pack_block.d.ts

@@ -0,0 +1,16 @@
+/**
+ * One BC4 block from its endpoints and indices, as two little-endian words.
+ *
+ * The same layout `bc4_write_block` states in JavaScript: the first endpoint in the low byte, the
+ * second above it, then forty-eight bits of three-bit indices with texel 0 lowest. The sixteen
+ * indices split into two runs of eight, twenty-four bits each; the first run straddles the two
+ * words, which is the one place the arithmetic is not just a shift.
+ *
+ * Kept apart from the fitting so the layout can be checked on its own: the emulator spec hands the
+ * same endpoints and indices to this and to the JavaScript writer and requires the same eight bytes.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc4_pack_block: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bc4_pack_block.d.ts.map

package/src/shade/renderer/texture/encode/chunk_bc4_pack_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bc4_pack_block.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_bc4_pack_block.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,mCAFU,SAAS,CAmBhB;0BAhCuB,oCAAoC"}

package/src/shade/renderer/texture/encode/chunk_bc4_pack_block.js

@@ -0,0 +1,33 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * One BC4 block from its endpoints and indices, as two little-endian words.
+ *
+ * The same layout `bc4_write_block` states in JavaScript: the first endpoint in the low byte, the
+ * second above it, then forty-eight bits of three-bit indices with texel 0 lowest. The sixteen
+ * indices split into two runs of eight, twenty-four bits each; the first run straddles the two
+ * words, which is the one place the arithmetic is not just a shift.
+ *
+ * Kept apart from the fitting so the layout can be checked on its own: the emulator spec hands the
+ * same endpoints and indices to this and to the JavaScript writer and requires the same eight bytes.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc4_pack_block = CodeChunk.from(
+    //language=WGSL
+    `
+fn bc4_pack_block(first: u32, second: u32, indices: array<u32, 16>) -> vec2<u32> {
+    var low = 0u;
+    var high = 0u;
+
+    for (var i = 0u; i < 8u; i++) {
+        low |= (indices[i] & 7u) << (3u * i);
+        high |= (indices[i + 8u] & 7u) << (3u * i);
+    }
+
+    return vec2<u32>(
+        (first & 255u) | ((second & 255u) << 8u) | ((low & 0xFFFFu) << 16u),
+        (low >> 16u) | (high << 8u)
+    );
+}
+`);

package/src/shade/renderer/texture/encode/chunk_bc6h_encode_block_mode11.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Encode sixteen HDR RGB texels as one BC6H block in mode 11, the unsigned format.
+ *
+ * **The line is fitted in the half-float bit domain, because that is the domain the decoder
+ * interpolates in.** A BC6H endpoint is a half-float bit pattern quantised to ten bits; the decoder
+ * unquantises it to a sixteen-bit integer, interpolates the two ends linearly with BC7's four-bit
+ * weights, scales the result by 31/64 and reinterprets the integer *as a half*. So the palette is
+ * linear in bit patterns, not in values — which is a log-like scale, sixteen steps between two
+ * ends a few octaves apart being spaced by ratio rather than by difference. Fitting in that domain
+ * is what Narkowicz's real-time BC6H does with `f32tof16` before anything else, and it is why an
+ * error measured there is a relative error, which is what an HDR image wants judged.
+ *
+ * The fit is {@link chunk_bc1_encode_block}'s line in that domain: the principal axis, the extreme
+ * projections, two rounds of least squares with the sixteen decode weights, then quantisation to
+ * ten bits and one round of coordinate descent over the six stored components, every candidate
+ * scored against the palette the decoder builds. The anchor is honoured by writing the block the
+ * other way up when texel 0 lands in the upper half.
+ *
+ * **Mode 11 only.** It has the finest endpoints of the one-region modes and no delta to fit; the
+ * two-region modes are where a hard edge inside a block would gain, and they are a later chunk. On
+ * the environment maps the format exists for, Narkowicz measured his mode-11-only fast path within
+ * reach of offline encoders' fast presets.
+ *
+ * Half floats hold no infinity or NaN here and no sign: a negative texel clamps to zero, and
+ * anything over the largest finite half to that. The conversion to half bits is written out rather
+ * than taken from `pack2x16float`, so that the emulator and every device round the same way.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc6h_encode_block_mode11: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bc6h_encode_block_mode11.d.ts.map

package/src/shade/renderer/texture/encode/chunk_bc6h_encode_block_mode11.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bc6h_encode_block_mode11.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_bc6h_encode_block_mode11.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,6CAFU,SAAS,CA2TZ;0BAzVmB,oCAAoC"}