[andywolff]

Part of #193689
Pre-requisite for #192937

This PR adds an optional maxDifferentPixelsRate tolerance parameter to matchesReferenceImage in package:flutter_test and configures a small tolerance for Impeller in transform_test.dart.

We did the same thing for engine/src/flutter/testing/dart/goldens.dart's fuzzyCompareImages in #193937. Can't share because that's in the engine code, which can't depend on framework packages, and matchesReferenceImage is in package:flutter_test.

The test 3D transform renders the same with or without needsCompositing was originally added in #61779 to prevent visual jumping regressions (#41654) where layer integer coordinate snapping caused 3D transforms to wiggle when needsCompositing changed. Across a loop of angles, it compares a raster snapshot of the transform rendered with needsCompositing: true against the same transform rendered with needsCompositing: false using matchesReferenceImage.

Under Skia, both composited and non-composited paths render identically with 0 differing pixels through software rasterization.

Under Impeller, they actually don't render identically because they take different paths:
with compositing: the child is drawn into an offscreen texture and composited as a 3D texture quad sampled via bilinear filtering.
Without composition: the canvas renders vector geometry directly under the 3D perspective matrix using MSAA edge coverage.

Because of this difference, there are antialiasing differences along angled polygon boundaries (consistently ~241 to 247 pixels out of 480,000, or ~0.05% of pixels). It's not a full pixel shift like the issue for which this test was added.

But why do these differences only appear with #192937? Because the host buffer wasn't being reset between snapshots, it actually wasn't re-rendering(?).

I previously attempted to mitigate this in #193936 by reducing loop density (increasing the angle step from 0.01 to 0.05), because I thought it was a problem happening towards the end of the loop after too many iterations. But this didn't help. Now that we have a proper diff tolerance, this PR reverts that angle step back to 0.01, restoring the test to its original angular sampling density.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant in-code documentation (doc comments with ///).
• If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in flutter/website (or verified none is needed).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

[gemini-code-assist]

Code Review

This pull request introduces a maxDifferentPixelsRate parameter to matchesReferenceImage to allow a configurable tolerance rate for pixel differences during reference image comparisons, and updates relevant tests. Feedback suggests returning null early when countDifferentPixels is 0 to prevent potential division-by-zero or NaN issues when calculating the pixel difference rate.

[andywolff]

Closing this draft, I found the true root cause of this rendering difference and we can address it without adding a pixel diff tolerance