sample_mask input: allow either full coverage mask or (1<<sample_index) (#4671)

This allows the varying behaviour observed on different platforms.

Generalize the "findFailedPixels" utility to allow two reference
"expected" texel views.  A pixel comparison succeeds if the "actual"
texel matches the texel from either of the "expected" or the "alternate
expected" texel views.

See gpuweb/gpuweb#5457

Co-authored-by: alan-baker <alanbaker@google.com>

Author: dneto0

src/webgpu/shader/execution/shader_io/fragment_builtins.spec.ts

@@ -510,17 +510,25 @@ function computeFragmentFrontFacing({ frontFacing }: FragData) {
 }
 
 /**
- * Computes 'builtin(sample_mask)'
+ * Computes the full sample coverage mask.
  */
-function computeSampleMask({ sampleMask }: FragData) {
+function computeFullSampleCoverageMask({ sampleMask }: FragData) {
   return [sampleMask, 0, 0, 0];
 }
 
+/**
+ * Computes (1 << sample_index)
+ */
+function computeSingleSampleMask({ sampleIndex }: FragData) {
+  return [1 << sampleIndex, 0, 0, 0];
+}
+
 /**
  * Renders float32 fragment shader inputs values to 4 rgba8unorm textures that
  * can be multisampled textures. It stores each of the channels, r, g, b, a of
  * the shader input to a separate texture, doing the math required to store the
- * float32 value into an rgba8unorm texel.
+ * float32 value into an rgba8unorm texel (i.e. mapping each 8bit chunk in the
+ * bit representation of a float32 value to a 8-bit norm float value).
  *
  * Note: We could try to store the output to an vec4f storage buffer.
  * Unfortunately, using a storage buffer has the issue that we need to compute
@@ -700,13 +708,15 @@ function checkSampleRectsApproximatelyEqual({
   actual,
   expected,
   maxDiffULPsForFloatFormat,
+  alternativeExpected,
 }: {
   width: number;
   height: number;
   sampleCount: number;
   actual: Float32Array;
   expected: Float32Array;
   maxDiffULPsForFloatFormat: number;
+  alternativeExpected?: Float32Array;
 }) {
   const subrectOrigin = [0, 0, 0];
   const subrectSize = [width * sampleCount, height, 1];
@@ -728,12 +738,19 @@ function checkSampleRectsApproximatelyEqual({
     new Uint8Array(expected.buffer),
     areaDesc
   );
+  const altExpTexelView = alternativeExpected
+    ? TexelView.fromTextureDataByReference(
+        format,
+        new Uint8Array((alternativeExpected ?? new Float32Array()).buffer),
+        areaDesc
+      )
+    : undefined;
 
   const failedPixelsMessage = findFailedPixels(
     format,
     { x: 0, y: 0, z: 0 },
     { width: width * sampleCount, height, depthOrArrayLayers: 1 },
-    { actTexelView, expTexelView },
+    { actTexelView, expTexelView, altExpTexelView },
     { maxDiffULPsForFloatFormat }
   );
 
@@ -742,6 +759,7 @@ function checkSampleRectsApproximatelyEqual({
     return new ErrorWithExtra(msg, () => ({
       expTexelView,
       actTexelView,
+      altExpTexelView,
     }));
   }
 
@@ -1300,10 +1318,14 @@ g.test('inputs,sample_mask')
     Test fragment shader builtin(sample_mask) values.
 
     Draws various triangles that should trigger different sample_mask values.
-    Checks that sample_mask matches what's expected. Note: the triangles
-    are selected so they do not intersect sample points as we don't want
-    to test precision issues on whether or not a sample point is inside
-    or outside the triangle when right on the edge.
+    Checks that sample_mask matches what's expected. The expected sample mask
+    is either:
+    - the full coverage mask for the fragment, or
+    - only has 1 bit at the current sample index.
+
+    Note: the triangles are selected so they do not intersect sample points
+    as we don't want to test precision issues on whether or not a sample point
+    is inside or outside the triangle when right on the edge.
 
     Example: x=-1, y=2, it draws the following triangle
 
@@ -1423,6 +1445,7 @@ g.test('inputs,sample_mask')
       [ x + 0.2,  y, 0, 1],
     ];
 
+    // This is not significant in this test, but is still needed by the helper.
     const interStagePoints = [
       [13, 14, 15, 16],
       [17, 18, 19, 20],
@@ -1444,24 +1467,36 @@ g.test('inputs,sample_mask')
       outputCode: 'vec4f(f32(fin.sample_mask), 0, 0, 0)',
     });
 
-    const expected = generateFragmentInputs({
+    const expectedFullCoverageMask = generateFragmentInputs({
       width,
       height,
       nearFar,
       sampleCount,
       clipSpacePoints,
-      interpolateFn: computeSampleMask,
+      interpolateFn: computeFullSampleCoverageMask,
     });
 
-    showExpected(t, width, height, sampleCount, expected);
+    showExpected(t, width, height, sampleCount, expectedFullCoverageMask);
+
+    const expectedSingleSampleMask = generateFragmentInputs({
+      width,
+      height,
+      nearFar,
+      sampleCount,
+      clipSpacePoints,
+      interpolateFn: computeSingleSampleMask,
+    });
+
+    showExpected(t, width, height, sampleCount, expectedSingleSampleMask);
 
     t.expectOK(
       checkSampleRectsApproximatelyEqual({
         width,
         height,
         sampleCount,
         actual,
-        expected,
+        expected: expectedFullCoverageMask,
+        alternativeExpected: expectedSingleSampleMask,
         maxDiffULPsForFloatFormat: 0,
       })
     );

src/webgpu/util/texture/texture_ok.ts

@@ -46,9 +46,17 @@ type TexelViewComparer = {
   tableRows: (failedCoords: readonly Required<GPUOrigin3DDict>[]) => Iterable<string>[];
 };
 
+// Creates a texel view comparer that compares an actual texel view against
+// an expected texel view and optionally a second, alternate, texel view.
+// The comparison for each texel succeeds if the actual texel is close enough
+// to either
 function makeTexelViewComparer(
   format: EncodableTextureFormat,
-  { actTexelView, expTexelView }: { actTexelView: TexelView; expTexelView: TexelView },
+  {
+    actTexelView,
+    expTexelView,
+    altExpTexelView,
+  }: { actTexelView: TexelView; expTexelView: TexelView; altExpTexelView?: TexelView },
   opts: TexelCompareOptions
 ): TexelViewComparer {
   const {
@@ -76,27 +84,35 @@ function makeTexelViewComparer(
   const tvc = {} as TexelViewComparer;
   if (fmtIsInt) {
     tvc.predicate = coords =>
-      comparePerComponent(actTexelView.color(coords), expTexelView.color(coords), maxIntDiff);
+      comparePerComponent(
+        actTexelView.color(coords),
+        expTexelView.color(coords),
+        maxIntDiff,
+        altExpTexelView?.color(coords)
+      );
   } else if (fmtIsNorm && maxDiffULPsForNormFormat !== undefined) {
     tvc.predicate = coords =>
       comparePerComponent(
         actTexelView.ulpFromZero(coords),
         expTexelView.ulpFromZero(coords),
-        maxDiffULPsForNormFormat
+        maxDiffULPsForNormFormat,
+        altExpTexelView?.ulpFromZero(coords)
       );
   } else if (fmtIsFloat && maxDiffULPsForFloatFormat !== undefined) {
     tvc.predicate = coords =>
       comparePerComponent(
         actTexelView.ulpFromZero(coords),
         expTexelView.ulpFromZero(coords),
-        maxDiffULPsForFloatFormat
+        maxDiffULPsForFloatFormat,
+        altExpTexelView?.ulpFromZero(coords)
       );
   } else if (maxFractionalDiff !== undefined) {
     tvc.predicate = coords =>
       comparePerComponent(
         actTexelView.color(coords),
         expTexelView.color(coords),
-        maxFractionalDiff
+        maxFractionalDiff,
+        altExpTexelView?.color(coords)
       );
   } else {
     if (fmtIsNorm) {
@@ -114,10 +130,17 @@ function makeTexelViewComparer(
       [`tolerance ± ${maxIntDiff}`],
       (function* () {
         yield* [` diff (act - exp)`, '==', ''];
+        if (altExpTexelView) {
+          yield* [` diff (act - alternateExp)`, '==', ''];
+        }
         for (const coords of failedCoords) {
           const act = actTexelView.color(coords);
           const exp = expTexelView.color(coords);
           yield repr.componentOrder.map(ch => act[ch]! - exp[ch]!).join(',');
+          if (altExpTexelView) {
+            const altExp = altExpTexelView.color(coords);
+            yield repr.componentOrder.map(ch => act[ch]! - altExp[ch]!).join(',');
+          }
         }
       })(),
     ];
@@ -130,10 +153,17 @@ function makeTexelViewComparer(
       [`tolerance ± ${toleranceULPs} normal-ULPs`],
       (function* () {
         yield* [` diff (act - exp) in normal-ULPs`, '==', ''];
+        if (altExpTexelView) {
+          yield* [` diff (act - alternateExp) in normal-ULPs`, '==', ''];
+        }
         for (const coords of failedCoords) {
           const act = actTexelView.ulpFromZero(coords);
           const exp = expTexelView.ulpFromZero(coords);
           yield repr.componentOrder.map(ch => act[ch]! - exp[ch]!).join(',');
+          if (altExpTexelView) {
+            const altExp = altExpTexelView.ulpFromZero(coords);
+            yield repr.componentOrder.map(ch => act[ch]! - altExp[ch]!).join(',');
+          }
         }
       })(),
     ];
@@ -143,10 +173,17 @@ function makeTexelViewComparer(
       [`tolerance ± ${maxFractionalDiff}`],
       (function* () {
         yield* [` diff (act - exp)`, '==', ''];
+        if (altExpTexelView) {
+          yield* [` diff (act - alternateExp)`, '==', ''];
+        }
         for (const coords of failedCoords) {
           const act = actTexelView.color(coords);
           const exp = expTexelView.color(coords);
           yield repr.componentOrder.map(ch => (act[ch]! - exp[ch]!).toPrecision(4)).join(',');
+          if (altExpTexelView) {
+            const altExp = altExpTexelView.color(coords);
+            yield repr.componentOrder.map(ch => (act[ch]! - altExp[ch]!).toPrecision(4)).join(',');
+          }
         }
       })(),
     ];
@@ -155,18 +192,32 @@ function makeTexelViewComparer(
   return tvc;
 }
 
+/** Returns true if all components of an "actual" texel compare as
+ * nearly equal (with tolerance) against either a (required) expected
+ * texel or against an optional alternate texel.
+ */
 function comparePerComponent(
   actual: PerTexelComponent<number>,
   expected: PerTexelComponent<number>,
-  maxDiff: number
+  maxDiff: number,
+  alternateExpected?: PerTexelComponent<number>
 ) {
-  return Object.keys(actual).every(key => {
-    const k = key as TexelComponent;
-    const act = actual[k]!;
-    const exp = expected[k];
-    if (exp === undefined) return false;
-    return numbersApproximatelyEqual(act, exp, maxDiff);
-  });
+  const similar = (a: PerTexelComponent<number>, b: PerTexelComponent<number>, maxDiff: number) =>
+    Object.keys(a).every(key => {
+      const k = key as TexelComponent;
+      const act = a[k]!;
+      const exp = b[k];
+      if (exp === undefined) return false;
+      return numbersApproximatelyEqual(act, exp, maxDiff);
+    });
+
+  if (similar(actual, expected, maxDiff)) {
+    return true;
+  }
+  if (alternateExpected) {
+    return similar(actual, alternateExpected, maxDiff);
+  }
+  return false;
 }
 
 /** Create a new mappable GPUBuffer, and copy a subrectangle of GPUTexture data into it. */
@@ -196,13 +247,17 @@ export function findFailedPixels(
   format: EncodableTextureFormat,
   subrectOrigin: Required<GPUOrigin3DDict>,
   subrectSize: Required<GPUExtent3DDict>,
-  { actTexelView, expTexelView }: { actTexelView: TexelView; expTexelView: TexelView },
+  {
+    actTexelView,
+    expTexelView,
+    altExpTexelView,
+  }: { actTexelView: TexelView; expTexelView: TexelView; altExpTexelView?: TexelView },
   texelCompareOptions: TexelCompareOptions,
   coords?: Generator<Required<GPUOrigin3DDict>>
 ) {
   const comparer = makeTexelViewComparer(
     format,
-    { actTexelView, expTexelView },
+    { actTexelView, expTexelView, altExpTexelView },
     texelCompareOptions
   );
 
@@ -260,6 +315,15 @@ export function findFailedPixels(
       yield `${repr.componentOrder.map(ch => numericToString(pixel[ch]!)).join(',')}`;
     }
   })();
+  const printAlternateExpectedColors = (function* () {
+    if (altExpTexelView) {
+      yield* [' alternateExp. colors', '==', componentOrderStr];
+      for (const coords of failedPixels) {
+        const pixel = altExpTexelView.color(coords);
+        yield `${repr.componentOrder.map(ch => numericToString(pixel[ch]!)).join(',')}`;
+      }
+    }
+  })();
   const printActualULPs = (function* () {
     yield* [' act. normal-ULPs-from-zero', '==', componentOrderStr];
     for (const coords of failedPixels) {
@@ -274,6 +338,15 @@ export function findFailedPixels(
       yield `${repr.componentOrder.map(ch => pixel[ch]).join(',')}`;
     }
   })();
+  const printAlternateExpectedULPs = (function* () {
+    if (altExpTexelView) {
+      yield* [` alternateExp. normal-ULPs-from-zero`, '==', componentOrderStr];
+      for (const coords of failedPixels) {
+        const pixel = altExpTexelView.ulpFromZero(coords);
+        yield `${repr.componentOrder.map(ch => pixel[ch]).join(',')}`;
+      }
+    }
+  })();
 
   const opts = {
     fillToWidth: 120,
@@ -286,8 +359,10 @@ ${generatePrettyTable(opts, [
   printActualBytes,
   printActualColors,
   printExpectedColors,
+  printAlternateExpectedColors,
   printActualULPs,
   printExpectedULPs,
+  printAlternateExpectedULPs,
   ...comparer.tableRows(failedPixels),
 ])}`;
 }