Fix inconsistent macOS text stroke weights by supporting light/dark glyph separation in glyph atlas by b-luk · Pull Request #186074 · flutter/flutter

b-luk · 2026-05-05T18:13:00Z

This PR addresses #185790 where text rendered using the Impeller backend on macOS exhibits inconsistent stroke weights, particularly with light text on dark backgrounds.

Cause

Apple's CoreText applies different font smoothing and antialiasing depending on whether text is light or dark. Visually, dark text on a light background looks heavier than light text on a dark background. CoreText tries to account for this and make light/dark text at the same size have a similar visual weight by automatically dilating light text and eroding dark text.

Prior to this PR, our (non-color) glyph atlases are based on drawing a black glyph using Skia, which uses CoreText as its underlying text renderer on macOS. So our glyphs all are eroded by CoreText, based on the incorrect assumption that they are always displayed as dark text. As a result, our light glyphs end up wispy and inconsistently stroked. Light text already appears optically lighter weight, and then CoreText erodes them even further based on incorrectly rendering them with dark-text weighting.

Fix

On macOS, update GlyphProperties to calculate whether a glyph is "light" based on the luminance of its color. This is stored in a new is_light property. This ensures that the same character rendered with a light color and a dark color will result in two separate entries in the glyph atlas.
Render light glyphs as white during atlas generation to trigger the correct CoreText smoothing for light glyphs.
- Dark glyphs retain the existing behavior and are rendered by having Skia render a black glyph on an A8 bitmap.
- Light glyphs must be rendered as white on a full-color bitmap. This is because when Skia renders to an A8 bitmap (like for the dark glyph case), it is hard coded to render the glyph as black on white (from here). So for light glyphs, render them into an RGBA bitmap and then convert it to an A8 bitmap to be copied into the glyph atlas.

Additionally, this PR refactors the usage of std::optional<GlyphProperties> to just be GlyphProperties. A nullopt value was treated exactly the same as a default GlyphProperties: color is black and stroke is null. So the optionality didn't add anything. It required a lot of unnecessary and confusing branching that made the code harder to follow, especially with this added is_light property.

Fixes #185790

This PR makes this change only for macOS. We can also consider whether to do this on iOS. iOS also uses Apple's CoreText, so the same erosion issues with dark text apply on iOS. However, all modern iOS devices are hi-dpi displays which use UI scaling. This mitigates most of the visual inconsistencies that we see on macOS when running apps on a non-UI-upscaled display. We would have to weigh whether the negative performance impact of this change is worth it for iOS. Whether or not to expand this to iOS is out of scope for this PR.

Newly added `AiksTest.CanRenderTextFrameWithThinLightAndDarkColors` golden test

This shows the golden screenshot before this change (top half) and after this change (bottom half). Light text is now heavier weight and more consistently stroked. Dark text is unchanged.

Flutter "New Gallery" app screenshots

All of these screenshots compare:

Top row: Dark mode
Bottom row: Light mode
Left: Before this PR, rendering with Impeller
Middle: After this PR, rendering with Impeller
Right: Rendering with Skia. It is a not a goal to replicate Skia's rendering exactly. But Skia's rendering is provided here for comparison.

Home screen

In both dark and light mode, light text in the "Reply" card is now thicker.
In dark mode, light text like in the "Shrine" card and in the category titles (Material, Cupertino, Styles & Other) are thicker. In light mode, this text is dark and is unaffected.

"About Flutter Gallery" modal

In dark mode, the text is now thicker and more consistently stroked.
Light mode is unaffected.

Settings screen, normal text scaling

In dark mode, the text is now thicker and more consistently stroked.
Light mode is unaffected.

Settings screen, small text scaling

In dark mode, wispy-ness of small text is even more apparent in the old version.
Light mode is unaffected.

Settings screen, large text scaling

In dark mode, large text is very readable even in the old version. In the new version it is noticeably thicker, but whether it looks better is more subjective than in the examples with smaller and thinner text.
Light mode is unaffected.

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

gemini-code-assist

Code Review

This pull request implements support for light and dark glyph variations in the Impeller text renderer by adding an is_light property to GlyphProperties. This property is determined by color luminance and is now part of the glyph atlas cache key. The implementation includes a manual RGBA to A8 conversion in the Skia backend and refactors several interfaces to treat GlyphProperties as a required rather than optional parameter. Review feedback recommends using SkBitmap::extractAlpha for more robust alpha channel extraction, expanding the macOS-specific logic to all Apple platforms, and addressing the accuracy of the linear luminance calculation.

b-luk · 2026-05-05T19:17:40Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the Impeller text rendering pipeline to distinguish between light and dark text glyphs, specifically for macOS compatibility. It replaces optional glyph properties with a mandatory struct and introduces an is_light flag based on luminance. The Skia backend now supports RGBA8888 alpha atlases when light glyphs are present. Review feedback suggests ensuring the is_light property is set for all non-color frames, including stroked text, to prevent rendering issues on macOS.

gaaclarke

Awesome work. Testing looks good, approach looks good. I have some feedback and questions about the layout of the code.

gaaclarke · 2026-05-05T20:37:19Z

@@ -70,6 +70,8 @@ void TextContents::SetTextProperties(
    // Alpha is always applied when rendering, remove it here so
    // we do not double-apply the alpha.
    properties_.color = color.WithAlpha(1.0);
+  } else {
+    properties_.SetIsLight(color);


This is kind of weird that this one concept is stored across 2 fields. Would it make more sense to store color as a std::variant<DlColor, Tone>, so it's either a color or light/dark?

I also like the idea of using a std::variant to indicate that the color is not used if is_light mode is selected.

Done. This was a pretty involved change, so PTAL

flutter-dashboard · 2026-05-05T22:12:16Z

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 #186074 at sha 0351205

b-luk · 2026-05-05T22:16:21Z

Two problems I noticed from the Google testing and golden results:

The check to apply this only for macos is incorrect. FML_OS_MACOSX is defined and set for both macos and iOS. I'll need to use #if FML_OS_MACOSX && !FML_OS_IOS to only apply this to iOS.
There's something funky going on when light text is scaled. I'm looking into this.

b-luk · 2026-05-05T23:29:37Z

Two problems I noticed from the Google testing and golden results:

The check to apply this only for macos is incorrect. FML_OS_MACOSX is defined and set for both macos and iOS. I'll need to use #if FML_OS_MACOSX && !FML_OS_IOS to only apply this to iOS.

There's something funky going on when light text is scaled. I'm looking into this.

I updated the macOS check.
It turns out that I can't use extractAlpha (which was based on an earlier Gemini suggestion). SkBitmap::extractAlpha does not guarantee that the pixels are contiguous, and in many cases will end up with padding at the end of each row. I changed this to SkBitmap::readPixels instead, which lets us allocate its memory beforehand to not have row padding. The logic is more than 1 line now, so I put it in a helper function.

jason-simmons

Overall LGTM

jason-simmons · 2026-05-05T23:30:21Z

@@ -70,6 +70,8 @@ void TextContents::SetTextProperties(
    // Alpha is always applied when rendering, remove it here so
    // we do not double-apply the alpha.
    properties_.color = color.WithAlpha(1.0);
+  } else {
+    properties_.SetIsLight(color);


I also like the idea of using a std::variant to indicate that the color is not used if is_light mode is selected.

flutter-dashboard · 2026-05-06T02:19:17Z

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 #186074 at sha f54a853

auto-submit · 2026-05-06T20:57:58Z

autosubmit label was removed for flutter/flutter/186074, because - The status or check suite Google testing has failed. Please fix the issues identified (or deflake) before re-applying this label.

…ter#186262) Fix `EmbedderTest.CanRenderTextWithImpellerMetal` test breakage. This broke due to flutter#186074. That PR modified how light text is rendered on macOS, but did not update this test's golden image. This updates the image. It also changes the test to explicitly render dark text on a light background and light text on a dark background. Previously it rendered white text on a transparent background. ## 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 documentation (doc comments with `///`). - [ ] 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. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Co-authored-by: Jason Simmons <jsimmons@google.com>

fix things

dd4f2d8

flutter-dashboard Bot added the CICD Run CI/CD label May 5, 2026

github-actions Bot added a: text input Entering text in a text field or keyboard related problems engine flutter/engine related. See also e: labels. e: impeller Impeller rendering backend issues and features requests labels May 5, 2026

gemini-code-assist Bot reviewed May 5, 2026

View reviewed changes

Comment thread engine/src/flutter/impeller/typographer/backends/skia/typographer_context_skia.cc Outdated

Comment thread engine/src/flutter/impeller/typographer/font_glyph_pair.h Outdated

Comment thread engine/src/flutter/impeller/typographer/font_glyph_pair.h Outdated

gemini comments

3708a89

github-actions Bot removed the CICD Run CI/CD label May 5, 2026

gemini-code-assist Bot reviewed May 5, 2026

View reviewed changes

Comment thread engine/src/flutter/impeller/display_list/dl_dispatcher.cc

Comment thread engine/src/flutter/impeller/entity/contents/text_contents.cc

Add false check for bitmap.extractAlpha

0351205

flutter-dashboard Bot added the CICD Run CI/CD label May 5, 2026

b-luk requested review from gaaclarke and jason-simmons May 5, 2026 19:26

b-luk mentioned this pull request May 5, 2026

MacOS text on Impeller has inconsistent looking stroke weights #185790

Closed

gaaclarke reviewed May 5, 2026

View reviewed changes

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

b-luk added 2 commits May 5, 2026 15:59

Fix A8 bitmap conversion, fix macOS vs iOS check

bddd008

gaaclarke comments

6cefe9a

github-actions Bot removed the CICD Run CI/CD label May 5, 2026

jason-simmons reviewed May 5, 2026

View reviewed changes

GlyphProperties tone_or_color

f54a853

flutter-dashboard Bot added the CICD Run CI/CD label May 6, 2026

b-luk requested review from gaaclarke and jason-simmons May 6, 2026 00:28

jason-simmons previously approved these changes May 6, 2026

View reviewed changes

b-luk added the autosubmit Merge PR when tree becomes green via auto submit App label May 6, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label May 6, 2026

b-luk added the autosubmit Merge PR when tree becomes green via auto submit App label May 7, 2026

auto-submit Bot added this pull request to the merge queue May 7, 2026

Merged via the queue into flutter:master with commit 3da669f May 7, 2026
207 of 208 checks passed

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

b-luk deleted the lightglyphs branch May 7, 2026 18:58

b-luk mentioned this pull request May 8, 2026

Fix EmbedderTest.CanRenderTextWithImpellerMetal test breakage #186262

Merged

10 tasks

Piinks mentioned this pull request May 8, 2026

Flutter Notable Commits - 2026 #181433

Open

b-luk mentioned this pull request May 11, 2026

Regression in post_backdrop_filter_perf_ios__timeline_summary 90th percentile time #186362

Closed

Uh oh!

Conversation

b-luk commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Cause

Fix

Newly added AiksTest.CanRenderTextFrameWithThinLightAndDarkColors golden test

Flutter "New Gallery" app screenshots

Home screen

"About Flutter Gallery" modal

Settings screen, normal text scaling

Settings screen, small text scaling

Settings screen, large text scaling

Pre-launch Checklist

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!

b-luk commented May 5, 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!

gaaclarke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gaaclarke May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jason-simmons May 5, 2026

Choose a reason for hiding this comment

Uh oh!

b-luk May 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flutter-dashboard Bot commented May 5, 2026

Uh oh!

b-luk commented May 5, 2026

Uh oh!

b-luk commented May 5, 2026

Uh oh!

jason-simmons left a comment

Choose a reason for hiding this comment

Uh oh!

jason-simmons May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

flutter-dashboard Bot commented May 6, 2026

Uh oh!

auto-submit Bot commented May 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

b-luk commented May 5, 2026 •

edited

Loading

Newly added `AiksTest.CanRenderTextFrameWithThinLightAndDarkColors` golden test