[WebParagraph] Fix text pixelation, glyph clipping, and snapping offsets to avoid subpixel raster caching by Rusino · Pull Request #191736 · flutter/flutter

Rusino · 2026-08-25T15:49:53Z

Summary of Changes

This PR improves WebParagraph text rendering quality and caching on CanvasKit:

Fixes text blurriness / fractional distortion: Snaps physical screen offsets to whole integer device pixels and aligns the Canvas2D context translation to integer coordinates. This guarantees a 1:1 physical device pixel blit with FilterQuality.none.
Eliminates glyph clipping: Adds 2 physical pixels of safety antialiasing padding so glyph descenders/ascenders (e.g. g, j, y, _) are no longer clipped at the paint boundary.
Preserves fractional font sizes: Removes .floor() when generating CSS font strings (cssFontSize.toStringAsFixed(2)), allowing fractional font sizes to render accurately.
Simplifies caching (100% cache hit during scrolling): By snapping physical offsets to integer coordinates, text rendered on Canvas2D is always at phase (0.0, 0.0). As a result, the cached bitmap is valid across all translations and scrolling movements. All complex motion heuristics, frame sequence tracking, settle redraws, and 4-bin quantization state machines have been removed in favor of pure scale-based cache invalidation.

to make sure we have fractional number for anti aliasing correctly. Also, make target rect physical size equal to source rect, not logical.

gemini-code-assist

Code Review

This pull request introduces subpixel alignment for web paragraphs to render 1:1 in physical pixels and avoid pixelation, updating the caching mechanism to include scale and canvas translation shifts. Feedback highlights a mathematical bug in the physical offset and target rect calculations when handling non-unity scales and translations. Additionally, a performance regression was identified where the paragraph cache is invalidated on every frame during translation animations due to changes in the canvas shift.

flutter-dashboard · 2026-08-25T20:32:17Z

Golden file changes have been found for this pull request. Click here to view and triage (e.g. because this is an intentional change).

If you are still iterating on this change and are not ready to resolve the images on the Flutter Gold dashboard, consider marking this PR as a draft pull request above. You will still be able to view image results on the dashboard, commenting will be silenced, and the check will not try to resolve itself until marked ready for review.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

Changes reported for pull request #191736 at sha 1dcb1b0

mdebbar · 2026-08-26T20:18:33Z

    ui.Rect sourceRect,
    ui.Rect targetRect, {
    required ParagraphImageGenerator generateParagraphImage,
+    required ui.Offset canvas2dShift,


This is not used.

mdebbar · 2026-08-26T20:33:12Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the web paragraph painting logic to support subpixel alignment and scale transforms, introducing a paragraph cache key and updating calculation logic for the source and target rectangles. The review feedback points out a copy-paste typo in the vertical target rectangle calculation and suggests including the subpixel shift (canvas2dShift) in the cache key to prevent stale cache reuse and text jittering.

* **Unified Cache Entry ()**: * Consolidated the paragraph cache image and its scale metrics into a single class, eliminating separate image and cache key fields in . * Replaced individual , , and properties with and . * Added an epsilon tolerance () to to avoid unnecessary cache invalidation due to minor floating-point precision fluctuations. * **Cleaned Up Signature**: * Removed the unused parameter from and . * **Upfront Transform & Scale Computation**: * Extracted and calculations directly within and passed them down to and . * Streamlined 's return signature to return . * Renamed / to / across canvas sizing and layout calculations. * **Fixed Vertical Target Rect Translation**: * Corrected the calculation in to properly divide by when canvas transforms are present. * **Unit Testing & Test Maintenance**: * Updated existing subpixel alignment tests to reflect the simplified 3-tuple return signature of . * Added test coverage verifying behavior with combined scaling and translation matrices.

Rusino · 2026-08-27T15:04:49Z

/gemini review

Rusino · 2026-08-27T15:05:41Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the web paragraph painter to account for the canvas transform matrix when calculating paragraph dimensions and scaling, ensuring subpixel phase alignment. It also introduces a _ParagraphCacheKey to cache paragraphs based on device pixel ratio and scale. Feedback highlights a typo in the vertical position calculation of the target rectangle where scaleY was used instead of transformY / scaleY. Additionally, it is recommended to include canvas2dShift in _ParagraphCacheKey to prevent stale bitmap reuse when the subpixel phase changes.

gemini-code-assist

Code Review

This pull request improves web paragraph rendering by incorporating canvas matrix scaling and translation into the subpixel alignment and caching logic. It introduces a _ParagraphCacheEntry to cache rasterized paragraph images at their effective scale and updates the paragraph layout calculations to match physical subpixel phases. Feedback on these changes suggests simplifying the mathematical formula for calculating targetRect, refactoring _resizePaintCanvas to accept pre-calculated effective scales directly, and avoiding null assertions on _cacheEntry by using a local variable.

- Dual-Mode Caching Strategy (CanvasKitPainter): - Updated to include for subpixel phase tracking. - Implemented dynamic motion detection () by tracking frame-to-frame position deltas. - Active Scrolling: Uses loose scale-only cache matching () to eliminate readbacks and guarantee 60/120 FPS jank-free scrolling. - Stationary / Settled: Uses strict cache matching () including so static text is always rasterized with exact subpixel alignment and crispness. - Target Rect & Canvas Resize Simplification (painter.dart): - Simplified and calculation in to , canceling out redundant terms and avoiding potential division-by-zero precision issues. - Updated to accept pre-calculated and directly. - Code Health & Type Safety: - Added unit test in verifying static text subpixel invalidation and scroll cache preservation.

flutter-dashboard · 2026-08-27T17:06:26Z

Golden file changes are available for triage from new commit, Click here to view.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

Changes reported for pull request #191736 at sha fa91671

mdebbar

Let's update the PR title since we aren't doing "dual-mode caching" anymore.

mdebbar · 2026-09-08T21:40:41Z


    if (!hasCache) {
+      debugRasterizeCount++;
+      debugTotalRasterizeCount++;


Add a test that uses it to justify its existence.

mdebbar · 2026-09-08T21:51:05Z

    final TextLayout layout = _paragraph.getLayout();
+    final Float64List canvasTransform = canvas.getTransform();
+    final double dpr = ui.window.devicePixelRatio;
+    final transform = _ParagraphTransform.from(canvasTransform, dpr);


There's no need to create a wrapper class. You can use extension methods to attach methods to Float64List. Something like this:

extension MatrixOperations on Float64List { (double scaleX, double scaleY) getScale() { return ... } }

An extension would work if we only needed the scale, but ParagraphTransform also merges in the DPR, handles null transforms, and owns the coordinate snapping (snapOffset, snapRect). It also gives us a nice bundle to pass into the background/block painting methods instead of passing 5 loose arguments around.

flutter-dashboard · 2026-09-11T03:34:45Z

Golden file changes are available for triage from new commit, Click here to view.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

Changes reported for pull request #191736 at sha 0c11d0c

flutter-dashboard · 2026-09-11T14:39:52Z

Golden file changes are available for triage from new commit, Click here to view.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

Changes reported for pull request #191736 at sha c72c9a2

Roll Flutter from 63b9518f16bc to 2553f89be1ef (62 revisions) flutter/flutter@63b9518...2553f89 2026-09-12 [email protected] Roll clang to 07d67299a15ce03b053736e2d31a668ee0576987 (flutter/flutter#192607) 2026-09-12 [email protected] Roll Dart SDK from b24b352c29db to 7863887acbfb (3 revisions) (flutter/flutter#192665) 2026-09-12 [email protected] fix(tree): et format --all (flutter/flutter#192669) 2026-09-12 [email protected] Support activity-alias in Android launcher activity detection (flutter/flutter#187251) 2026-09-12 [email protected] fix: regenerate gradle lockfiles for external_textures integration test (flutter/flutter#192657) 2026-09-12 [email protected] Roll Skia from 51aa02b2c195 to e5e96533b732 (4 revisions) (flutter/flutter#192646) 2026-09-12 [email protected] [WebParagraph] Fix text pixelation, glyph clipping, and snapping offsets to avoid subpixel raster caching (flutter/flutter#191736) 2026-09-12 [email protected] fix(tests): Add ruby dep to Mac windowing_test (flutter/flutter#192656) 2026-09-12 [email protected] Remove some `unawaited_futures` outdated ignores (flutter/flutter#192026) 2026-09-11 [email protected] Bump Dart to 3.13, reformat, re-enable formatting check (flutter/flutter#192649) 2026-09-11 [email protected] [android] Isolate API-34 high contrast listener in AccessibilityBridge behind Api34Impl (flutter/flutter#192502) 2026-09-11 [email protected] Update style guide for Dart 3.13 (flutter/flutter#192639) 2026-09-11 [email protected] ci(bringups): remove bringup from these tests (flutter/flutter#192637) 2026-09-11 [email protected] Unmark new_gallery_windows_impeller__transition_perf as bringup (flutter/flutter#192633) 2026-09-11 [email protected] Unmark new_gallery_windows_skia__transition_perf as bringup (flutter/flutter#192635) 2026-09-11 [email protected] Roll Skia from f446aec4ce9e to 51aa02b2c195 (2 revisions) (flutter/flutter#192631) 2026-09-11 [email protected] fix(ci): mac verify binaries still racing (flutter/flutter#192634) 2026-09-11 [email protected] Roll Packages from 8a35b16 to 9caa77c (8 revisions) (flutter/flutter#192630) 2026-09-11 [email protected] Roll Dart SDK from a76fee2722e0 to b24b352c29db (2 revisions) (flutter/flutter#192627) 2026-09-11 [email protected] [tool] Migrate PackagesCommand and Pub to modular dependency injection (flutter/flutter#192460) 2026-09-11 [email protected] [tool] Migrate Darwin framework commands to modular dependency injection (flutter/flutter#192252) 2026-09-11 [email protected] [tool] Migrate Upgrade, Downgrade, and UpdatePackages commands to modular dependency injection (flutter/flutter#190787) 2026-09-11 [email protected] Roll Skia from b3fa80a0e168 to f446aec4ce9e (55 revisions) (flutter/flutter#192620) 2026-09-11 [email protected] Roll Dart SDK from d20d59cfa664 to a76fee2722e0 (2 revisions) (flutter/flutter#192616) 2026-09-11 [email protected] remove deeplink integration tests from bringup (flutter/flutter#192459) 2026-09-11 [email protected] Revert: [devicelab] Clean up Chrome profile directories and trap abort signals in web benchmarks (flutter/flutter#192615) 2026-09-11 [email protected] Roll Fuchsia Linux SDK from C0j8F-_Iy-OQZ6YyI... to m69nfK-wnHaMTe8P9... (flutter/flutter#192608) 2026-09-11 [email protected] Fix Wasm build cache mismatch in ResidentWebRunner and browser 404 fallbacks (flutter/flutter#190786) 2026-09-11 [email protected] Roll Dart SDK from 3ce3116bc9ec to d20d59cfa664 (1 revision) (flutter/flutter#192588) 2026-09-11 [email protected] [Linux] Keep the frame at the top of a resizing subsurface (flutter/flutter#192408) 2026-09-10 [email protected] [devicelab] Clean up Chrome profile directories and trap abort signals in web benchmarks (flutter/flutter#192584) 2026-09-10 [email protected] [web] Keep ImageSource alive until Picture disposal (flutter/flutter#192516) 2026-09-10 [email protected] Remove the accessibility evaluations feature flag (flutter/flutter#192266) 2026-09-10 [email protected] Promote Windows gradient benchmark tests to non-bringup (flutter/flutter#192581) 2026-09-10 [email protected] Remove commented out export in `text_input.dart` since the dart compiler has the correct behavior now (flutter/flutter#191539) 2026-09-10 [email protected] [flutter_tools] Do not mistake server-initiated requests for responses to client requests in AnalysisServer (flutter/flutter#192546) 2026-09-10 [email protected] Roll Packages from 36e088a to 8a35b16 (12 revisions) (flutter/flutter#192550) 2026-09-10 [email protected] Roll pub packages (flutter/flutter#192517) 2026-09-10 [email protected] feat(web): support --web-content-hash for entrypoint files (flutter/flutter#190153) 2026-09-10 [email protected] [web] Stop iOS auto-zoom by sizing semantic inputs at 16px (flutter/flutter#192328) 2026-09-10 [email protected] Roll Dart SDK from 0d55b7a6a9ee to 3ce3116bc9ec (2 revisions) (flutter/flutter#192534) 2026-09-10 [email protected] Update more enum instances comparison to use equality == since dart has the correct behavior now (flutter/flutter#191788) 2026-09-10 [email protected] Fix specify_nonobvious_local_variable_types lints in luci_resultdb_test.dart (flutter/flutter#192543) 2026-09-10 [email protected] Roll ICU from 8cc91d9b6ab9 to 6ebb40c59477 (1 revision) (flutter/flutter#192527) 2026-09-10 [email protected] [Linux] Make the framebuffer depth/stencil buffer optional (flutter/flutter#192156) 2026-09-10 [email protected] [Linux] Cancel input when events stop being delivered (flutter/flutter#192277) ...

Rusino added 4 commits August 24, 2026 11:05

drawImageRect 1:1 and deal with fractional

6811e12

Correcting Y-axis too

f57a4c0

Fixing chopped text (by adding antialias padding)

dcb3f0a

Keeping track of all transform/scale factors

3f7c60b

to make sure we have fractional number for anti aliasing correctly. Also, make target rect physical size equal to source rect, not logical.

flutter-dashboard Bot added the CICD Run CI/CD label Aug 25, 2026

Rusino self-assigned this Aug 25, 2026

Rusino requested a review from mdebbar August 25, 2026 15:50

github-actions Bot added engine flutter/engine related. See also e: labels. platform-web Web applications specifically team-web Owned by Web platform team labels Aug 25, 2026

gemini-code-assist Bot reviewed Aug 25, 2026

View reviewed changes

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/web_paragraph/painter.dart Outdated

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/canvaskit/web_paragraph_painter.dart Outdated

Rusino and others added 3 commits August 25, 2026 14:03

Fixing the font size (not flooring it anymore)

96efc09

Fixing problems found by Gemini

5cec607

Merge branch 'master' into fraction

1dcb1b0

flutter-dashboard Bot added the will affect goldens Changes to golden files label Aug 25, 2026

mdebbar reviewed Aug 26, 2026

View reviewed changes

gemini-code-assist Bot reviewed Aug 26, 2026

View reviewed changes

gemini-code-assist Bot reviewed Aug 27, 2026

View reviewed changes

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/web_paragraph/painter.dart

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/canvaskit/web_paragraph_painter.dart

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/canvaskit/web_paragraph_painter.dart Outdated

gemini-code-assist Bot reviewed Aug 27, 2026

View reviewed changes

Rusino requested a review from mdebbar August 27, 2026 15:53

Rusino changed the title ~~[WebParagraph] Fixes text pixelation and cutting off glyphs vertically~~ [WebParagraph] Fix text pixelation, glyph clipping, and implement dual-mode subpixel raster caching Sep 1, 2026

Rusino marked this pull request as draft September 1, 2026 17:24

Dealing with image cache more accurately

4a73311

github-actions Bot added the d: examples Sample code and demos label Sep 8, 2026

Rusino and others added 2 commits September 8, 2026 11:09

Merge branch 'master' into fraction

937133b

Removing the example app

ae44697

Rusino force-pushed the fraction branch from 937133b to 48fd25c Compare September 8, 2026 15:28

github-actions Bot removed the d: examples Sample code and demos label Sep 8, 2026

mdebbar reviewed Sep 8, 2026

View reviewed changes

Reacting to Mouad's comments

81d69ba

Rusino requested a review from mdebbar September 9, 2026 14:56

Rusino changed the title ~~[WebParagraph] Fix text pixelation, glyph clipping, and implement dual-mode subpixel raster caching~~ [WebParagraph] Fix text pixelation, glyph clipping, and snapping offsets to avoid subpixel raster caching Sep 9, 2026

mdebbar reviewed Sep 9, 2026

View reviewed changes

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/canvaskit/web_paragraph_painter.dart Outdated

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/web_paragraph/painter.dart Outdated

Comment thread engine/src/flutter/lib/web_ui/lib/src/engine/web_paragraph/painter.dart Outdated

Another round of code review

8306329

Rusino requested a review from mdebbar September 10, 2026 15:14

mdebbar reviewed Sep 10, 2026

View reviewed changes

Comment thread engine/src/flutter/lib/web_ui/test/webparagraph/paragraph_cache_test.dart Outdated

Comment thread engine/src/flutter/lib/web_ui/test/webparagraph/paragraph_cache_test.dart Outdated

One more round of code review

14e364d

Rusino requested a review from mdebbar September 10, 2026 17:23

Merge branch 'master' into fraction

7b5eb32

mdebbar approved these changes Sep 10, 2026

View reviewed changes

Merge branch 'master' into fraction

0c11d0c

Merge branch 'master' into fraction

c72c9a2

mdebbar added the autosubmit Merge PR when tree becomes green via auto submit App label Sep 11, 2026

auto-submit Bot added this pull request to the merge queue Sep 12, 2026

Merged via the queue into flutter:master with commit be32f06 Sep 12, 2026
23 checks passed

flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Sep 12, 2026

This was referenced Sep 12, 2026

Roll Flutter from 63b9518f16bc to 2553f89be1ef (62 revisions) flutter/packages#12853

Closed

Roll Flutter from 63b9518f16bc to 2553f89be1ef (62 revisions) flutter/packages#12855

Merged

justinmc mentioned this pull request Sep 25, 2026

Flutter Notable Commits - 2026 #181433

Open

Conversation

Rusino commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of Changes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

flutter-dashboard Bot commented Aug 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mdebbar Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mdebbar commented Aug 26, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rusino commented Aug 27, 2026

Uh oh!

Rusino commented Aug 27, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flutter-dashboard Bot commented Aug 27, 2026

Uh oh!

mdebbar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mdebbar Sep 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mdebbar Sep 8, 2026

Choose a reason for hiding this comment

Uh oh!

Rusino Sep 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flutter-dashboard Bot commented Sep 11, 2026

Uh oh!

flutter-dashboard Bot commented Sep 11, 2026

Uh oh!

Uh oh!

Reviewers

Rusino commented Aug 25, 2026 •

edited

Loading