@woosh/meep-engine 3.14.2 → 3.14.3

package/src/format/texture/basis/uastc/bc7_write_block.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The eight-bit value a stored endpoint component decodes to.
+ *
+ * The parity bit, where the mode has one, sits *below* the stored bits — so a five-bit component
+ * with a parity bit is a six-bit value — and the result is then widened to eight by replicating its
+ * top bits downward.
+ *
+ * @param {number} stored
+ * @param {number} bits including the parity bit
+ * @returns {number}
+ */
+export function bc7_expand_endpoint(stored: number, bits: number): number;
+/**
+ * Quantise an eight-bit value to what a mode can store, optionally forced to a parity.
+ *
+ * @param {number} value
+ * @param {number} bits including the parity bit, where there is one
+ * @param {number} parity `-1` when the mode has none
+ * @returns {number} the value including its parity bit, so `bits` wide
+ */
+export function bc7_quantise_endpoint(value: number, bits: number, parity: number): number;
+/**
+ * Write one BC7 block.
+ *
+ * **One writer for every mode**, because the specification says the fields are always in the same
+ * order and only their widths change. Writing each mode out separately would be the same sequence
+ * five times with different constants, and the constants are already a table.
+ *
+ * Endpoints are ordered as the specification stores them: by channel, then by subset, then by
+ * endpoint — so red for both ends of subset 0, then both ends of subset 1, then green, and so on.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {number} mode
+ * @param {object} block
+ * @param {number} [block.partition] index into BC7's partition table
+ * @param {number} [block.rotation]
+ * @param {Uint8Array} block.endpoints `subsets * 2 * 4` stored fields, low then high RGBA per
+ * subset — already quantised to the mode's width, with any parity bit held separately
+ * @param {Uint8Array} block.indices sixteen
+ * @param {Uint8Array} [block.secondary_indices] sixteen, for a mode with two index sets
+ * @param {Uint8Array} block.anchors one texel index per subset
+ * @param {Int8Array} [block.parity] one bit per endpoint, or per subset for a shared-parity mode
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc7_write_block(out: Uint8Array, byte_offset: number, mode: number, block: {
+    partition?: number;
+    rotation?: number;
+    endpoints: Uint8Array;
+    indices: Uint8Array;
+    secondary_indices?: Uint8Array;
+    anchors: Uint8Array;
+    parity?: Int8Array;
+}): void;
+/**
+ * Bytes one BC7 block occupies.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC7_BLOCK_BYTES: number;
+/**
+ * What one BC7 mode stores, from the specification's mode table.
+ *
+ * The field *order* is the same for every mode — partition, rotation, index selection, colour,
+ * alpha, per-endpoint parity, shared parity, indices — so a mode is entirely described by how many
+ * bits it gives each, which is what makes one writer enough for all of them.
+ *
+ * @typedef {object} Bc7Mode
+ * @property {number} subsets
+ * @property {number} partition_bits
+ * @property {number} rotation_bits
+ * @property {number} color_bits
+ * @property {number} alpha_bits `0` where the mode has no alpha, which then decodes as opaque
+ * @property {number} endpoint_parity_bits one parity bit per endpoint, `0` or `1`
+ * @property {number} shared_parity_bits one parity bit per *subset*, shared by both its endpoints
+ * @property {number} index_bits
+ * @property {number} secondary_index_bits `0` unless the mode has a second index set
+ */
+/**
+ * Every BC7 mode this writes, from Table.M of the specification.
+ *
+ * Modes 0 and 4 are absent: no UASTC mode maps to either, so writing them would be code with no
+ * caller and no test.
+ *
+ * @readonly
+ * @type {Object<number, Bc7Mode>}
+ */
+export const BC7_MODES: {
+    [x: number]: Bc7Mode;
+};
+/**
+ * What one BC7 mode stores, from the specification's mode table.
+ *
+ * The field *order* is the same for every mode — partition, rotation, index selection, colour,
+ * alpha, per-endpoint parity, shared parity, indices — so a mode is entirely described by how many
+ * bits it gives each, which is what makes one writer enough for all of them.
+ */
+export type Bc7Mode = {
+    subsets: number;
+    partition_bits: number;
+    rotation_bits: number;
+    color_bits: number;
+    /**
+     * `0` where the mode has no alpha, which then decodes as opaque
+     */
+    alpha_bits: number;
+    /**
+     * one parity bit per endpoint, `0` or `1`
+     */
+    endpoint_parity_bits: number;
+    /**
+     * one parity bit per *subset*, shared by both its endpoints
+     */
+    shared_parity_bits: number;
+    index_bits: number;
+    /**
+     * `0` unless the mode has a second index set
+     */
+    secondary_index_bits: number;
+};
+//# sourceMappingURL=bc7_write_block.d.ts.map

package/src/format/texture/basis/uastc/bc7_write_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bc7_write_block.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/uastc/bc7_write_block.js"],"names":[],"mappings":"AA+DA;;;;;;;;;;GAUG;AACH,4CAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAQlB;AAED;;;;;;;GAOG;AACH,6CALW,MAAM,QACN,MAAM,UACN,MAAM,GACJ,MAAM,CAyBlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qCAhBW,UAAU,eACV,MAAM,QACN,MAAM;IAES,SAAS,GAAxB,MAAM;IACS,QAAQ,GAAvB,MAAM;IACY,SAAS,EAA3B,UAAU;IAEQ,OAAO,EAAzB,UAAU;IACS,iBAAiB,GAApC,UAAU;IACQ,OAAO,EAAzB,UAAU;IACQ,MAAM,GAAxB,SAAS;SAmEnB;AA3MD;;;;;GAKG;AACH,8BAFU,MAAM,CAEkB;AAElC;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;GAQG;AACH;QAFiB,MAAM,GAAE,OAAO;EA2B9B;;;;;;;;;aA7CY,MAAM;oBACN,MAAM;mBACN,MAAM;gBACN,MAAM;;;;gBACN,MAAM;;;;0BACN,MAAM;;;;wBACN,MAAM;gBACN,MAAM;;;;0BACN,MAAM"}

package/src/format/texture/basis/uastc/bc7_write_block.js

@@ -0,0 +1,227 @@
+/**
+ * Bytes one BC7 block occupies.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const BC7_BLOCK_BYTES = 16;
+
+/**
+ * What one BC7 mode stores, from the specification's mode table.
+ *
+ * The field *order* is the same for every mode — partition, rotation, index selection, colour,
+ * alpha, per-endpoint parity, shared parity, indices — so a mode is entirely described by how many
+ * bits it gives each, which is what makes one writer enough for all of them.
+ *
+ * @typedef {object} Bc7Mode
+ * @property {number} subsets
+ * @property {number} partition_bits
+ * @property {number} rotation_bits
+ * @property {number} color_bits
+ * @property {number} alpha_bits `0` where the mode has no alpha, which then decodes as opaque
+ * @property {number} endpoint_parity_bits one parity bit per endpoint, `0` or `1`
+ * @property {number} shared_parity_bits one parity bit per *subset*, shared by both its endpoints
+ * @property {number} index_bits
+ * @property {number} secondary_index_bits `0` unless the mode has a second index set
+ */
+
+/**
+ * Every BC7 mode this writes, from Table.M of the specification.
+ *
+ * Modes 0 and 4 are absent: no UASTC mode maps to either, so writing them would be code with no
+ * caller and no test.
+ *
+ * @readonly
+ * @type {Object<number, Bc7Mode>}
+ */
+export const BC7_MODES = {
+    1: {
+        subsets: 2, partition_bits: 6, rotation_bits: 0, color_bits: 6, alpha_bits: 0,
+        endpoint_parity_bits: 0, shared_parity_bits: 1, index_bits: 3, secondary_index_bits: 0,
+    },
+    2: {
+        subsets: 3, partition_bits: 6, rotation_bits: 0, color_bits: 5, alpha_bits: 0,
+        endpoint_parity_bits: 0, shared_parity_bits: 0, index_bits: 2, secondary_index_bits: 0,
+    },
+    3: {
+        subsets: 2, partition_bits: 6, rotation_bits: 0, color_bits: 7, alpha_bits: 0,
+        endpoint_parity_bits: 1, shared_parity_bits: 0, index_bits: 2, secondary_index_bits: 0,
+    },
+    5: {
+        subsets: 1, partition_bits: 0, rotation_bits: 2, color_bits: 7, alpha_bits: 8,
+        endpoint_parity_bits: 0, shared_parity_bits: 0, index_bits: 2, secondary_index_bits: 2,
+    },
+    6: {
+        subsets: 1, partition_bits: 0, rotation_bits: 0, color_bits: 7, alpha_bits: 7,
+        endpoint_parity_bits: 1, shared_parity_bits: 0, index_bits: 4, secondary_index_bits: 0,
+    },
+    7: {
+        subsets: 2, partition_bits: 6, rotation_bits: 0, color_bits: 5, alpha_bits: 5,
+        endpoint_parity_bits: 1, shared_parity_bits: 0, index_bits: 2, secondary_index_bits: 0,
+    },
+};
+
+/**
+ * The eight-bit value a stored endpoint component decodes to.
+ *
+ * The parity bit, where the mode has one, sits *below* the stored bits — so a five-bit component
+ * with a parity bit is a six-bit value — and the result is then widened to eight by replicating its
+ * top bits downward.
+ *
+ * @param {number} stored
+ * @param {number} bits including the parity bit
+ * @returns {number}
+ */
+export function bc7_expand_endpoint(stored, bits) {
+    if (bits >= 8) {
+        return stored & 255;
+    }
+
+    return ((stored << (8 - bits)) | (stored >>> (2 * bits - 8))) & 255;
+}
+
+/**
+ * Quantise an eight-bit value to what a mode can store, optionally forced to a parity.
+ *
+ * @param {number} value
+ * @param {number} bits including the parity bit, where there is one
+ * @param {number} parity `-1` when the mode has none
+ * @returns {number} the value including its parity bit, so `bits` wide
+ */
+export function bc7_quantise_endpoint(value, bits, parity) {
+    const max = (1 << bits) - 1;
+
+    let quantised = Math.round((value * max) / 255);
+
+    if (parity >= 0 && (quantised & 1) !== parity) {
+        /*
+         Both neighbours are equally far, so the one that stays inside the range wins and otherwise
+         the one nearer the original value does.
+        */
+        const lower = quantised - 1;
+        const upper = quantised + 1;
+
+        const ideal = (value * max) / 255;
+
+        quantised = lower < 0 ? upper
+            : upper > max ? lower
+                : (Math.abs(ideal - lower) <= Math.abs(ideal - upper) ? lower : upper);
+    }
+
+    return quantised < 0 ? (parity < 0 ? 0 : parity)
+        : quantised > max ? (max - ((max & 1) === parity || parity < 0 ? 0 : 1))
+            : quantised;
+}
+
+/**
+ * Write one BC7 block.
+ *
+ * **One writer for every mode**, because the specification says the fields are always in the same
+ * order and only their widths change. Writing each mode out separately would be the same sequence
+ * five times with different constants, and the constants are already a table.
+ *
+ * Endpoints are ordered as the specification stores them: by channel, then by subset, then by
+ * endpoint — so red for both ends of subset 0, then both ends of subset 1, then green, and so on.
+ *
+ * @param {Uint8Array} out
+ * @param {number} byte_offset of the block
+ * @param {number} mode
+ * @param {object} block
+ * @param {number} [block.partition] index into BC7's partition table
+ * @param {number} [block.rotation]
+ * @param {Uint8Array} block.endpoints `subsets * 2 * 4` stored fields, low then high RGBA per
+ * subset — already quantised to the mode's width, with any parity bit held separately
+ * @param {Uint8Array} block.indices sixteen
+ * @param {Uint8Array} [block.secondary_indices] sixteen, for a mode with two index sets
+ * @param {Uint8Array} block.anchors one texel index per subset
+ * @param {Int8Array} [block.parity] one bit per endpoint, or per subset for a shared-parity mode
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bc7_write_block(out, byte_offset, mode, block) {
+    const spec = BC7_MODES[mode];
+
+    let bit = byte_offset * 8;
+
+    /**
+     * @param {number} value
+     * @param {number} count
+     */
+    const write = (value, count) => {
+        for (let i = 0; i < count; i++) {
+            if (((value >> i) & 1) !== 0) {
+                out[(bit + i) >> 3] |= 1 << ((bit + i) & 7);
+            }
+        }
+
+        bit += count;
+    };
+
+    // a mode is signalled by that many zero bits followed by a one
+    write(1 << mode, mode + 1);
+
+    write(block.partition ?? 0, spec.partition_bits);
+    write(block.rotation ?? 0, spec.rotation_bits);
+
+    for (let channel = 0; channel < 3; channel++) {
+        for (let subset = 0; subset < spec.subsets; subset++) {
+            for (let end = 0; end < 2; end++) {
+                write(block.endpoints[(subset * 2 + end) * 4 + channel], spec.color_bits);
+            }
+        }
+    }
+
+    if (spec.alpha_bits > 0) {
+        for (let subset = 0; subset < spec.subsets; subset++) {
+            for (let end = 0; end < 2; end++) {
+                write(block.endpoints[(subset * 2 + end) * 4 + 3], spec.alpha_bits);
+            }
+        }
+    }
+
+    if (spec.endpoint_parity_bits > 0) {
+        for (let subset = 0; subset < spec.subsets; subset++) {
+            for (let end = 0; end < 2; end++) {
+                write(block.parity[subset * 2 + end], 1);
+            }
+        }
+    }
+
+    if (spec.shared_parity_bits > 0) {
+        for (let subset = 0; subset < spec.subsets; subset++) {
+            write(block.parity[subset], 1);
+        }
+    }
+
+    write_indices(write, block.indices, block.anchors, spec.subsets, spec.index_bits);
+
+    if (spec.secondary_index_bits > 0) {
+        write_indices(
+            write, block.secondary_indices, block.anchors, spec.subsets, spec.secondary_index_bits
+        );
+    }
+}
+
+/**
+ * @param {function(number, number): void} write
+ * @param {Uint8Array} indices
+ * @param {Uint8Array} anchors one texel per subset
+ * @param {number} subsets
+ * @param {number} bits
+ */
+function write_indices(write, indices, anchors, subsets, bits) {
+    for (let texel = 0; texel < 16; texel++) {
+        let anchor = false;
+
+        for (let subset = 0; subset < subsets; subset++) {
+            if (anchors[subset] === texel) {
+                anchor = true;
+
+                break;
+            }
+        }
+
+        write(indices[texel], anchor ? bits - 1 : bits);
+    }
+}

package/src/format/texture/basis/uastc/uastc_decode_block.d.ts

@@ -0,0 +1,105 @@
+/**
+ * One decoded UASTC block, in the terms the format states it rather than as texels.
+ *
+ * Kept in this form because a transcoder wants it: the partition and the per-subset endpoints are
+ * what map onto BC7's and ASTC's own, and going through RGBA would throw away the structure that
+ * makes those mappings cheap and nearly lossless.
+ *
+ * @typedef {object} UastcBlock
+ * @property {number} mode
+ * @property {number} subsets
+ * @property {boolean} has_alpha whether the source carried an alpha channel, as opposed to the
+ * opaque one an RGB colour endpoint mode implies
+ * @property {number} pattern index into the mode's partition pattern table, `0` for one subset
+ * @property {Uint8Array} partition one subset index per texel, all zero for a single subset
+ * @property {Uint8Array} endpoints `subsets * 2 * 4` bytes: low then high RGBA, per subset
+ * @property {Uint8Array} weights one `[0, 64]` interpolant per texel per plane, plane 0 first
+ * @property {Uint8Array} weight_indices the same, before unquantisation — what a transcoder maps to
+ * its own index space, since going via the interpolant would round twice
+ * @property {number} weight_range index into `UASTC_WEIGHT_VALUE`
+ * @property {boolean} dual_plane
+ * @property {number} component_selector which channel reads plane 1, when `dual_plane`
+ */
+/**
+ * Decode one UASTC LDR 4x4 block.
+ *
+ * **The whole of the format's complexity is here**, and it is why UASTC is a second bitstream rather
+ * than a variation on ETC1S: nineteen modes differing in subset count, endpoint precision, weight
+ * precision and whether one channel is interpolated separately, with the endpoints trit- or
+ * quint-coded in most modes and the weights packed a bit short at each subset's anchor texel.
+ *
+ * @param {Uint8Array} bytes
+ * @param {number} base byte offset of the block
+ * @returns {UastcBlock}
+ * @throws {Error} for the reserved mode, which no encoder emits
+ *
+ * @see the UASTC LDR 4x4 specification
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function uastc_decode_block(bytes: Uint8Array, base: number): UastcBlock;
+/**
+ * Turn a decoded block into its sixteen RGBA texels.
+ *
+ * @param {UastcBlock} block
+ * @param {Uint8Array} out at least 64 bytes
+ * @param {number} [out_offset]
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function uastc_block_texels(block: UastcBlock, out: Uint8Array, out_offset?: number): void;
+/**
+ * Bytes one UASTC block occupies.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const UASTC_BLOCK_BYTES: number;
+/**
+ * One decoded UASTC block, in the terms the format states it rather than as texels.
+ *
+ * Kept in this form because a transcoder wants it: the partition and the per-subset endpoints are
+ * what map onto BC7's and ASTC's own, and going through RGBA would throw away the structure that
+ * makes those mappings cheap and nearly lossless.
+ */
+export type UastcBlock = {
+    mode: number;
+    subsets: number;
+    /**
+     * whether the source carried an alpha channel, as opposed to the
+     * opaque one an RGB colour endpoint mode implies
+     */
+    has_alpha: boolean;
+    /**
+     * index into the mode's partition pattern table, `0` for one subset
+     */
+    pattern: number;
+    /**
+     * one subset index per texel, all zero for a single subset
+     */
+    partition: Uint8Array;
+    /**
+     * `subsets * 2 * 4` bytes: low then high RGBA, per subset
+     */
+    endpoints: Uint8Array;
+    /**
+     * one `[0, 64]` interpolant per texel per plane, plane 0 first
+     */
+    weights: Uint8Array;
+    /**
+     * the same, before unquantisation — what a transcoder maps to
+     * its own index space, since going via the interpolant would round twice
+     */
+    weight_indices: Uint8Array;
+    /**
+     * index into `UASTC_WEIGHT_VALUE`
+     */
+    weight_range: number;
+    dual_plane: boolean;
+    /**
+     * which channel reads plane 1, when `dual_plane`
+     */
+    component_selector: number;
+};
+//# sourceMappingURL=uastc_decode_block.d.ts.map

package/src/format/texture/basis/uastc/uastc_decode_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uastc_decode_block.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/uastc/uastc_decode_block.js"],"names":[],"mappings":"AAiJA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,0CATW,UAAU,QACV,MAAM,GACJ,UAAU,CAmEtB;AAwMD;;;;;;;;;GASG;AACH,0CAPW,UAAU,OACV,UAAU,eACV,MAAM,QA6BhB;AAhdD;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB;;;;;;;;;UAoItB,MAAM;aACN,MAAM;;;;;eACN,OAAO;;;;aAEP,MAAM;;;;eACN,UAAU;;;;eACV,UAAU;;;;aACV,UAAU;;;;;oBACV,UAAU;;;;kBAEV,MAAM;gBACN,OAAO;;;;wBACP,MAAM"}