Assorted helpers used for texture checking

src/unittests/conversion.spec.ts

@@ -1,7 +1,15 @@
 export const description = `Unit tests for conversion`;
 
 import { makeTestGroup } from '../common/internal/test_group.js';
-import { float16BitsToFloat32, float32ToFloat16Bits } from '../webgpu/util/conversion.js';
+import {
+  float16BitsToFloat32,
+  float32ToFloat16Bits,
+  float32ToFloatBits,
+  floatBitsToNormalULPFromZero,
+  floatBitsToNumber,
+  kFloat16Format,
+  kFloat32Format,
+} from '../webgpu/util/conversion.js';
 
 import { UnitTest } from './unit_test.js';
 
@@ -21,17 +29,114 @@ const cases = [
   [0b1_10101_1001000000, -100],
 ];
 
-g.test('conversion,float16BitsToFloat32').fn(t => {
+g.test('float16BitsToFloat32').fn(t => {
   cases.forEach(value => {
     // some loose check
     t.expect(Math.abs(float16BitsToFloat32(value[0]) - value[1]) <= 0.00001, value[0].toString(2));
   });
 });
 
-g.test('conversion,float32ToFloat16Bits').fn(t => {
+g.test('float32ToFloat16Bits').fn(t => {
   cases.forEach(value => {
     // some loose check
     // Does not handle clamping, underflow, overflow, or denormalized numbers.
     t.expect(Math.abs(float32ToFloat16Bits(value[1]) - value[0]) <= 1, value[1].toString());
   });
 });
+
+g.test('float32ToFloatBits_floatBitsToNumber')
+  .paramsSubcasesOnly(u =>
+    u
+      .combine('signed', [0, 1] as const)
+      .combine('exponentBits', [5, 8])
+      .combine('mantissaBits', [10, 23])
+  )
+  .fn(t => {
+    const { signed, exponentBits, mantissaBits } = t.params;
+    const bias = (1 << (exponentBits - 1)) - 1;
+
+    for (const [, value] of cases) {
+      if (value < 0 && signed === 0) continue;
+      const bits = float32ToFloatBits(value, signed, exponentBits, mantissaBits, bias);
+      const reconstituted = floatBitsToNumber(bits, { signed, exponentBits, mantissaBits, bias });
+      t.expect(Math.abs(reconstituted - value) <= 0.0000001, `${reconstituted} vs ${value}`);
+    }
+  });
+
+g.test('floatBitsToULPFromZero,16').fn(t => {
+  const test = (bits: number, ulpFromZero: number) =>
+    t.expect(floatBitsToNormalULPFromZero(bits, kFloat16Format) === ulpFromZero, bits.toString(2));
+  // Zero
+  test(0b0_00000_0000000000, 0);
+  // Subnormal
+  test(0b0_00000_0000000001, 0);
+  test(0b1_00000_0000000001, 0);
+  test(0b0_00000_1111111111, 0);
+  test(0b1_00000_1111111111, 0);
+  // Normal
+  test(0b0_00001_0000000000, 1); // 0 + 1ULP
+  test(0b1_00001_0000000000, -1); // 0 - 1ULP
+  test(0b0_00001_0000000001, 2); // 0 + 2ULP
+  test(0b1_00001_0000000001, -2); // 0 - 2ULP
+  test(0b0_01110_0000000000, 0b01101_0000000001); // 0.5
+  test(0b1_01110_0000000000, -0b01101_0000000001); // -0.5
+  test(0b0_01110_1111111110, 0b01101_1111111111); // 1.0 - 2ULP
+  test(0b1_01110_1111111110, -0b01101_1111111111); // -(1.0 - 2ULP)
+  test(0b0_01110_1111111111, 0b01110_0000000000); // 1.0 - 1ULP
+  test(0b1_01110_1111111111, -0b01110_0000000000); // -(1.0 - 1ULP)
+  test(0b0_01111_0000000000, 0b01110_0000000001); // 1.0
+  test(0b1_01111_0000000000, -0b01110_0000000001); // -1.0
+  test(0b0_01111_0000000001, 0b01110_0000000010); // 1.0 + 1ULP
+  test(0b1_01111_0000000001, -0b01110_0000000010); // -(1.0 + 1ULP)
+  test(0b0_10000_0000000000, 0b01111_0000000001); // 2.0
+  test(0b1_10000_0000000000, -0b01111_0000000001); // -2.0
+
+  const testThrows = (b: number) =>
+    t.shouldThrow('Error', () => floatBitsToNormalULPFromZero(b, kFloat16Format));
+  // Infinity
+  testThrows(0b0_11111_0000000000);
+  testThrows(0b1_11111_0000000000);
+  // NaN
+  testThrows(0b0_11111_1111111111);
+  testThrows(0b1_11111_1111111111);
+});
+
+g.test('floatBitsToULPFromZero,32').fn(t => {
+  const test = (bits: number, ulpFromZero: number) =>
+    t.expect(floatBitsToNormalULPFromZero(bits, kFloat32Format) === ulpFromZero, bits.toString(2));
+  // Zero
+  test(0b0_00000000_00000000000000000000000, 0);
+  // Subnormal
+  test(0b0_00000000_00000000000000000000001, 0);
+  test(0b1_00000000_00000000000000000000001, 0);
+  test(0b0_00000000_11111111111111111111111, 0);
+  test(0b1_00000000_11111111111111111111111, 0);
+  // Normal
+  test(0b0_00000001_00000000000000000000000, 1); // 0 + 1ULP
+  test(0b1_00000001_00000000000000000000000, -1); // 0 - 1ULP
+  test(0b0_00000001_00000000000000000000001, 2); // 0 + 2ULP
+  test(0b1_00000001_00000000000000000000001, -2); // 0 - 2ULP
+  test(0b0_01111110_00000000000000000000000, 0b01111101_00000000000000000000001); // 0.5
+  test(0b1_01111110_00000000000000000000000, -0b01111101_00000000000000000000001); // -0.5
+  test(0b0_01111110_11111111111111111111110, 0b01111101_11111111111111111111111); // 1.0 - 2ULP
+  test(0b1_01111110_11111111111111111111110, -0b01111101_11111111111111111111111); // -(1.0 - 2ULP)
+  test(0b0_01111110_11111111111111111111111, 0b01111110_00000000000000000000000); // 1.0 - 1ULP
+  test(0b1_01111110_11111111111111111111111, -0b01111110_00000000000000000000000); // -(1.0 - 1ULP)
+  test(0b0_01111111_00000000000000000000000, 0b01111110_00000000000000000000001); // 1.0
+  test(0b1_01111111_00000000000000000000000, -0b01111110_00000000000000000000001); // -1.0
+  test(0b0_01111111_00000000000000000000001, 0b01111110_00000000000000000000010); // 1.0 + 1ULP
+  test(0b1_01111111_00000000000000000000001, -0b01111110_00000000000000000000010); // -(1.0 + 1ULP)
+  test(0b0_11110000_00000000000000000000000, 0b11101111_00000000000000000000001); // 2.0
+  test(0b1_11110000_00000000000000000000000, -0b11101111_00000000000000000000001); // -2.0
+
+  const testThrows = (b: number) =>
+    t.shouldThrow('Error', () => floatBitsToNormalULPFromZero(b, kFloat32Format));
+  // Infinity
+  testThrows(0b0_11111111_00000000000000000000000);
+  testThrows(0b1_11111111_00000000000000000000000);
+  // NaN
+  testThrows(0b0_11111111_11111111111111111111111);
+  testThrows(0b0_11111111_00000000000000000000001);
+  testThrows(0b1_11111111_11111111111111111111111);
+  testThrows(0b1_11111111_00000000000000000000001);
+});

src/webgpu/util/check_contents.ts

@@ -8,6 +8,7 @@ import {
 } from '../../common/util/util.js';
 
 import { float16BitsToFloat32 } from './conversion.js';
+import { generatePrettyTable } from './pretty_diff_tables.js';
 
 /** Generate an expected value at `index`, to test for equality with the actual value. */
 export type CheckElementsGenerator = (index: number) => number;
@@ -236,53 +237,3 @@ function intToPaddedHex(number: number, { byteLength }: { byteLength: number })
   if (number < 0) s = '-' + s;
   return s;
 }
-
-/**
- * Pretty-prints a "table" of cell values (each being `number | string`), right-aligned.
- * Each row may be any iterator, including lazily-generated (potentially infinite) rows.
- *
- * The first argument is the printing options:
- *  - fillToWidth: Keep printing columns (as long as there is data) until this width is passed.
- *    If there is more data, "..." is appended.
- *  - numberToString: if a cell value is a number, this is used to stringify it.
- *
- * Each remaining argument provides one row for the table.
- */
-function generatePrettyTable(
-  { fillToWidth, numberToString }: { fillToWidth: number; numberToString: (n: number) => string },
-  rows: ReadonlyArray<Iterable<string | number>>
-): string {
-  const rowStrings = range(rows.length, () => '');
-  let totalTableWidth = 0;
-  const iters = rows.map(row => row[Symbol.iterator]());
-
-  // Loop over columns
-  for (;;) {
-    const cellsForColumn = iters.map(iter => {
-      const r = iter.next(); // Advance the iterator for each row, in lock-step.
-      return r.done ? undefined : typeof r.value === 'number' ? numberToString(r.value) : r.value;
-    });
-    if (cellsForColumn.every(cell => cell === undefined)) break;
-
-    // Maximum width of any cell in this column, plus one for space between columns
-    // (also inserts a space at the left of the first column).
-    const colWidth = Math.max(...cellsForColumn.map(c => (c === undefined ? 0 : c.length))) + 1;
-    for (let row = 0; row < rowStrings.length; ++row) {
-      const cell = cellsForColumn[row];
-      if (cell !== undefined) {
-        rowStrings[row] += cell.padStart(colWidth);
-      }
-    }
-
-    totalTableWidth += colWidth;
-    if (totalTableWidth >= fillToWidth) {
-      for (let row = 0; row < rowStrings.length; ++row) {
-        if (cellsForColumn[row] !== undefined) {
-          rowStrings[row] += ' ...';
-        }
-      }
-      break;
-    }
-  }
-  return rowStrings.join('\n');
-}

src/webgpu/util/conversion.ts

@@ -101,11 +101,76 @@ export function float32ToFloat16Bits(n: number) {
  * Decodes an IEEE754 16 bit floating point number into a JS `number` and returns.
  */
 export function float16BitsToFloat32(float16Bits: number): number {
-  const buf = new DataView(new ArrayBuffer(Float32Array.BYTES_PER_ELEMENT));
-  // shift exponent and mantissa bits and fill with 0 on right, shift sign bit
-  buf.setUint32(0, ((float16Bits & 0x7fff) << 13) | ((float16Bits & 0x8000) << 16), true);
-  // shifting for bias different: f16 uses a bias of 15, f32 uses a bias of 127
-  return buf.getFloat32(0, true) * 2 ** (127 - 15);
+  return floatBitsToNumber(float16Bits, kFloat16Format);
+}
+
+type FloatFormat = { signed: 0 | 1; exponentBits: number; mantissaBits: number; bias: number };
+
+/** FloatFormat defining IEEE754 32-bit float. */
+export const kFloat32Format = { signed: 1, exponentBits: 8, mantissaBits: 23, bias: 127 } as const;
+/** FloatFormat defining IEEE754 16-bit float. */
+export const kFloat16Format = { signed: 1, exponentBits: 5, mantissaBits: 10, bias: 15 } as const;
+
+const workingData = new ArrayBuffer(4);
+const workingDataU32 = new Uint32Array(workingData);
+const workingDataF32 = new Float32Array(workingData);
+/** Bitcast u32 (represented as integer Number) to f32 (represented as floating-point Number). */
+export function float32BitsToNumber(bits: number): number {
+  workingDataU32[0] = bits;
+  return workingDataF32[0];
+}
+/** Bitcast f32 (represented as floating-point Number) to u32 (represented as integer Number). */
+export function numberToFloat32Bits(number: number): number {
+  workingDataF32[0] = number;
+  return workingDataU32[0];
+}
+
+/**
+ * Decodes an IEEE754 float with the supplied format specification into a JS number.
+ *
+ * The format MUST be no larger than a 32-bit float.
+ */
+export function floatBitsToNumber(bits: number, fmt: FloatFormat): number {
+  // Pad the provided bits out to f32, then convert to a `number` with the wrong bias.
+  // E.g. for f16 to f32:
+  // - f16: S    EEEEE MMMMMMMMMM
+  //        ^ 000^^^^^ ^^^^^^^^^^0000000000000
+  // - f32: S eeeEEEEE MMMMMMMMMMmmmmmmmmmmmmm
+
+  const kNonSignBits = fmt.exponentBits + fmt.mantissaBits;
+  const kNonSignBitsMask = (1 << kNonSignBits) - 1;
+  const expAndMantBits = bits & kNonSignBitsMask;
+  let f32BitsWithWrongBias = expAndMantBits << (kFloat32Format.mantissaBits - fmt.mantissaBits);
+  f32BitsWithWrongBias |= (bits << (31 - kNonSignBits)) & 0x8000_0000;
+  const numberWithWrongBias = float32BitsToNumber(f32BitsWithWrongBias);
+  return numberWithWrongBias * 2 ** (kFloat32Format.bias - fmt.bias);
+}
+
+/**
+ * Given a floating point number (as an integer representing its bits), computes how many ULPs it is
+ * from zero.
+ *
+ * Subnormal numbers are skipped, so that 0 is one ULP from the minimum normal number.
+ * Subnormal values are flushed to 0.
+ * Positive and negative 0 are both considered to be 0 ULPs from 0.
+ */
+export function floatBitsToNormalULPFromZero(bits: number, fmt: FloatFormat): number {
+  const mask_sign = fmt.signed << (fmt.exponentBits + fmt.mantissaBits);
+  const mask_expt = ((1 << fmt.exponentBits) - 1) << fmt.mantissaBits;
+  const mask_mant = (1 << fmt.mantissaBits) - 1;
+  const mask_rest = mask_expt | mask_mant;
+
+  assert(fmt.exponentBits + fmt.mantissaBits <= 31);
+
+  const sign = bits & mask_sign ? -1 : 1;
+  const rest = bits & mask_rest;
+  const subnormal_or_zero = (bits & mask_expt) === 0;
+  const infinity_or_nan = (bits & mask_expt) === mask_expt;
+  assert(!infinity_or_nan, 'no ulp representation for infinity/nan');
+
+  // The first normal number is mask_mant+1, so subtract mask_mant to make min_normal - zero = 1ULP.
+  const abs_ulp_from_zero = subnormal_or_zero ? 0 : rest - mask_mant;
+  return sign * abs_ulp_from_zero;
 }
 
 /**

src/webgpu/util/math.ts

@@ -34,8 +34,11 @@ export function clamp(n: number, { min, max }: { min: number; max: number }): nu
 }
 
 /**
- * @returns the Units of Last Place difference between the numbers a and b.
- * If either `a` or `b` are not finite numbers, then diffULP() returns Infinity.
+ * @returns the (absolute) Units of Last Place difference between the float32 numbers a and b, taken
+ * as JS doubles. If either `a` or `b` are not finite numbers, then diffULP() returns Infinity.
+ *
+ * Subnormal numbers are skipped, so 0 is one ULP from the minimum normal number.
+ * Subnormal values are rounded to 0.
  */
 export function diffULP(a: number, b: number): number {
   if (!Number.isFinite(a) || !Number.isFinite(b)) {
@@ -317,3 +320,9 @@ export function multiplyMatrices(
 
   return product;
 }
+
+/** Sign-extend the `bits`-bit number `n` to a 32-bit signed integer. */
+export function signExtend(n: number, bits: number): number {
+  const shift = 32 - bits;
+  return (n << shift) >> shift;
+}

src/webgpu/util/pretty_diff_tables.ts

@@ -0,0 +1,51 @@
+import { range } from '../../common/util/util.js';
+
+/**
+ * Pretty-prints a "table" of cell values (each being `number | string`), right-aligned.
+ * Each row may be any iterator, including lazily-generated (potentially infinite) rows.
+ *
+ * The first argument is the printing options:
+ *  - fillToWidth: Keep printing columns (as long as there is data) until this width is passed.
+ *    If there is more data, "..." is appended.
+ *  - numberToString: if a cell value is a number, this is used to stringify it.
+ *
+ * Each remaining argument provides one row for the table.
+ */
+export function generatePrettyTable(
+  { fillToWidth, numberToString }: { fillToWidth: number; numberToString: (n: number) => string },
+  rows: ReadonlyArray<Iterable<string | number>>
+): string {
+  const rowStrings = range(rows.length, () => '');
+  let totalTableWidth = 0;
+  const iters = rows.map(row => row[Symbol.iterator]());
+
+  // Loop over columns
+  for (;;) {
+    const cellsForColumn = iters.map(iter => {
+      const r = iter.next(); // Advance the iterator for each row, in lock-step.
+      return r.done ? undefined : typeof r.value === 'number' ? numberToString(r.value) : r.value;
+    });
+    if (cellsForColumn.every(cell => cell === undefined)) break;
+
+    // Maximum width of any cell in this column, plus one for space between columns
+    // (also inserts a space at the left of the first column).
+    const colWidth = Math.max(...cellsForColumn.map(c => (c === undefined ? 0 : c.length))) + 1;
+    for (let row = 0; row < rowStrings.length; ++row) {
+      const cell = cellsForColumn[row];
+      if (cell !== undefined) {
+        rowStrings[row] += cell.padStart(colWidth);
+      }
+    }
+
+    totalTableWidth += colWidth;
+    if (totalTableWidth >= fillToWidth) {
+      for (let row = 0; row < rowStrings.length; ++row) {
+        if (cellsForColumn[row] !== undefined) {
+          rowStrings[row] += ' ...';
+        }
+      }
+      break;
+    }
+  }
+  return rowStrings.join('\n');
+}