gputex 0.2.0 → 0.3.0

package/dist/testing.d.ts

@@ -0,0 +1,120 @@
+/** 48-value input: 16 RGB triplets, channel-interleaved, each in [0, 1]. */
+type BC1Pixels = Readonly<ArrayLike<number>>;
+/** Exactly 8 bytes of BC1 block data. */
+type BC1Block = Uint8Array;
+type BC1Quality = 'fast' | 'high';
+/**
+ * Encode a 4×4 RGB block (48 floats in [0, 1]) into an 8-byte BC1 block.
+ * Always emits 4-colour (opaque) mode.
+ */
+declare function encodeBC1Block(pixels: BC1Pixels, { quality }?: {
+    quality?: BC1Quality;
+}): BC1Block;
+/**
+ * Decode an 8-byte BC1 block to 48 normalised [0, 1] values (16 RGB triplets).
+ * Handles both 4-colour and 3-colour modes; the 3-colour transparent index
+ * decodes to black (this library samples BC1 as opaque RGB).
+ */
+declare function decodeBC1Block(block: BC1Block): Float32Array;
+
+/** 16-value input: accepts both real arrays and typed arrays. */
+type BC4Values = Readonly<ArrayLike<number>>;
+/** Exactly 8 bytes, indexed numerically. */
+type BC4Block = Uint8Array;
+/**
+ * Encode 16 single-channel values in [0, 1] into an 8-byte BC4 block.
+ *
+ * Always produces a 6-interpolation-mode block (red0 > red1). This is
+ * the right choice for the BC5 normal-map use case; see file comment.
+ */
+declare function encodeBC4Block(values: BC4Values): BC4Block;
+/**
+ * Decode an 8-byte BC4 block to 16 normalized [0, 1] values.
+ *
+ * Handles both 6-interpolation and 4-interpolation modes so we can
+ * round-trip blocks produced externally (hardware, other encoders).
+ */
+declare function decodeBC4Block(block: BC4Block): Float32Array;
+
+/** Exactly 16 bytes of BC5 block data. */
+type BC5Block = Uint8Array;
+interface BC5Decoded {
+    r: Float32Array;
+    g: Float32Array;
+}
+declare function encodeBC5Block(r: BC4Values, g: BC4Values): BC5Block;
+declare function decodeBC5Block(block: BC5Block): BC5Decoded;
+
+/** 16 pixels × 4 channels = 64 normalized floats, interleaved RGBA. */
+type BC7Pixels = Readonly<ArrayLike<number>>;
+/** 16 bytes of BC7 block data. */
+type BC7Block = Uint8Array;
+/** Read the variable-width unary-coded mode field. Returns the mode number. */
+declare function readBC7Mode(block: BC7Block): number;
+/**
+ * Encode 16 RGBA pixels (64 floats in [0,1]) as a BC7 mode 6 block.
+ *
+ * Algorithm:
+ *   1. Convert to 8-bit per channel.
+ *   2. Farthest-pair in 4D → initial 8-bit endpoints. (See farthestPair
+ *      for why bbox corners aren't safe when channels vary in different
+ *      directions along the data line.)
+ *   3. For each p-bit combo {(0,0),(0,1),(1,0),(1,1)}:
+ *      quantize each endpoint to 7-bit under its chosen p-bit,
+ *      rebuild palette, reassign indices, measure total error.
+ *   4. Keep the best p-bit combo.
+ *   5. One-pass least-squares refinement on the surviving indices,
+ *      re-quantize with p-bit search, accept if error decreases.
+ *   6. Anchor fix: if pixel 0's index has MSB=1, swap endpoints and
+ *      invert all indices.
+ *   7. Pack.
+ */
+declare function encodeBC7Mode6Block(pixels: BC7Pixels): BC7Block;
+/**
+ * Decode a BC7 mode 6 block to 16 normalized [0, 1] RGBA pixels (64 floats).
+ * Throws if the block doesn't start with the mode 6 field.
+ */
+declare function decodeBC7Mode6Block(block: BC7Block): Float32Array;
+/**
+ * Encode a BC7 block. Currently this always produces a mode 6 block —
+ * see the file header for why other modes are deliberately out of scope.
+ */
+declare function encodeBC7Block(pixels: BC7Pixels): BC7Block;
+/**
+ * Decode a BC7 block, dispatching on the mode field. This reference
+ * supports mode 6 only; other modes throw. Encoders outside this
+ * project (AMD Compressonator, bc7enc, ...) routinely pick other modes,
+ * so this decoder is mainly for round-tripping our own output.
+ */
+declare function decodeBC7Block(block: BC7Block): Float32Array;
+
+/** 16 pixels × 4 channels = 64 normalised floats, interleaved RGBA. */
+type ASTC4x4Pixels = Readonly<ArrayLike<number>>;
+/** 16 bytes of ASTC 4×4 block data. */
+type ASTC4x4Block = Uint8Array;
+/**
+ * Encode 16 RGBA pixels (64 floats in [0, 1]) as a single ASTC 4×4 LDR
+ * block using the narrow subset described at the top of this file.
+ *
+ * Algorithm:
+ *   1. Quantise input to 8-bit.
+ *   2. Farthest-pair in 4D → initial (e0, e1).
+ *   3. Assign per-texel 2-bit indices by nearest palette entry.
+ *   4. One LSQ refit pass; accept only if total error strictly decreases.
+ *   5. Flip endpoints (and invert indices) if sum(e0.rgb) > sum(e1.rgb)
+ *      so the decoder doesn't apply blue contraction.
+ *   6. Pack block mode, CEM, endpoints, weights into 128 bits.
+ */
+declare function encodeASTC4x4Block(pixels: ASTC4x4Pixels): ASTC4x4Block;
+/**
+ * Decode an ASTC 4×4 block produced by this encoder (or by any other
+ * encoder that respects our narrow subset: block mode 0x042, single
+ * partition, CEM 12). Handles the blue-contraction branch even though
+ * our encoder doesn't produce it, so externally-supplied blocks round-
+ * trip predictably.
+ *
+ * Output: 16 RGBA pixels as 64 floats in [0, 1].
+ */
+declare function decodeASTC4x4Block(block: ASTC4x4Block): Float32Array;
+
+export { type ASTC4x4Block, type ASTC4x4Pixels, type BC1Block, type BC1Pixels, type BC1Quality, type BC4Block, type BC4Values, type BC5Block, type BC5Decoded, type BC7Block, type BC7Pixels, decodeASTC4x4Block, decodeBC1Block, decodeBC4Block, decodeBC5Block, decodeBC7Block, decodeBC7Mode6Block, encodeASTC4x4Block, encodeBC1Block, encodeBC4Block, encodeBC5Block, encodeBC7Block, encodeBC7Mode6Block, readBC7Mode };