Adds documentation for antialiasing with impeller by gaaclarke · Pull Request #13370 · flutter/website

gaaclarke · 2026-05-06T23:56:04Z

This PR should only be landed after macOS impeller is switched to SDFs by default: flutter/flutter#183045

Description

This explains SDF rendering for macOS and covers antialiasing in general. The main things to communicate is the escape hatch if people want to implement their own SDFs and how to opt-in to SDFs on mobile devices.

Issues fixed by this PR

flutter/flutter#183043

PRs or commits this PR depends on

flutter/flutter#183045

Presubmit checklist

If you are unwilling, or unable, to sign the CLA, even for a tiny, one-word PR, please file an issue instead of a PR.
If this PR is not meant to land until a future stable release, mark it as draft with an explanation.
This PR follows the Google Developer Documentation Style Guidelines—for example, it doesn't use i.e. or e.g., and it avoids I and we (first-person pronouns).
This PR uses semantic line breaks
of 80 characters or fewer.

flutter-website-bot · 2026-05-07T00:02:09Z

Visit the preview URL for this PR (updated for commit 76cc499):

https://flutter-docs-prod--pr13370-antialias-doc-17a96hc6.web.app

andywolff

LGTM. Contents and location of the new doc make sense to me.

sfshaza2

Some smoothing out and one question for @gaaclarke.

flar · 2026-05-14T20:52:24Z

+only one fragment operation is calculated. This limits smoothing to edges.
+Mobile phone GPUs have special hardware to optimize this process (
+[Tiled rendering][]). It comes in varying degrees of how many samples to
+consider.


Not sure how you are defining "fragment operation". If it is "execution of a fragment program" then I don't think this is correct.

For any given pixel I believe it only performs one fragment shader operation on the center of a pixel for any pixel, whether it has all the same MSAA coverage or not. The only thing that MSAA adds is which of the sub-samples it propagates that single result to.

The text above implies that it only runs the fragment shader once for wholly enclosed interior pixels - and??? runs it multiple times for edge pixles? (I don't think it works that way).

flar · 2026-05-14T20:54:56Z

+[Tiled rendering][]). It comes in varying degrees of how many samples to
+consider.
+
+On desktop and mobile 4x MSAA is used for all rendering calls.


Perhaps mention the consequences of the MSAA #, such as "the quantization of the coverage for edge pixels is limited to the number of MSAA samples" (so edge pixels are always only one of 0%, 25%, 50%, 75%, or 100% covered with MSAA 4).

flar · 2026-05-14T20:56:40Z

+### Signed distance fields ([SDFs][])
+
+Typically, hardware accelerated computer graphics define a series of points and
+edges (a [mesh][]) and [shaders][]. Instead, SDF renders shapes in the fragment


"... and the color sample for pixels is either 0% or 100% the result of the fragment shader (color source?) for each pixel depending on whether it falls in the mesh or not"...?

flar · 2026-05-14T20:58:08Z

+edges (a [mesh][]) and [shaders][]. Instead, SDF renders shapes in the fragment
+shader program as signed distance fields. Since the shape is defined in the
+fragment shader the edges can be smoothed at the fragment level instead of
+relying on the rasterization of a mesh.


"smoothed ... by computing the coverage of the shape over each individual pixel at a high resolution (or precision?) and used to proportionally apply the color sample to that pixel"...?

flar · 2026-05-14T20:58:29Z

+fragment shader the edges can be smoothed at the fragment level instead of
+relying on the rasterization of a mesh.
+
+On desktop, rendering with SDFs is enabled. On mobile platforms, SDFs are an


"... enabled by default"?

flar · 2026-05-14T20:59:12Z

+
+This technique is prioritized on desktop because SDF rendering puts more demand
+on the GPU and Flutter supports older mobile phones. Also, the physical pixel
+sizes on desktop computers are typically bigger than those of mobile phones. So


Desktop computers don't have pixels. ;)

"desktop displays"?

Perhaps provide some example statistics?

Also, bigger in terms of field of view. Mobile phones are viewed closer than desktop displays, but their much higher pixel count still wins out in terms of pixel angular viewing angle thingy bopper...

flar · 2026-05-14T21:01:05Z

+
+### SDFs with the FragmentShader API
+
+Standard primitive shapes in Flutter are drawn automatically with SDFs. If a


automatically -> by default unless the developer changes the "?antialiased?" setting in the Paint object...?

flar · 2026-05-14T21:02:19Z

+
+| No AA                                       | MSAA 4x                                        | MSAA 4x + SDF                                           |
+| ------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------- |
+| ![No AA](/assets/images/docs/perf/noaa.png) | ![MSAA 4x](/assets/images/docs/perf/msaa4.png) | ![MSAA 4x + SDF](/assets/images/docs/perf/msaa4sdf.png) |


The images are subtle. One other option is to show a very slightly rotated line where the stepping is far more abrupt with MSAA and it is easy to see more steps with SDF.

flutter-website-bot · 2026-07-17T21:07:03Z

Staged preview of the updated docs.flutter.dev site (updated for commit 1a138ad):

https://flutter-docs-prod--docs-pr13370-antialias-doc-el7q81xn.web.app

flutter-website-bot · 2026-07-17T21:12:32Z

Staged preview of the updated flutter.dev site (updated for commit 1a138ad):

https://flutter-dev-230821--www-pr13370-antialias-doc-sg22jgt2.web.app

sfshaza2

I know this is still in draft form, but this looks great, @gaaclarke! LGTM, for when you are ready to land.

parlough · 2026-08-20T17:12:07Z

@gaaclarke @flar Is this relevant as of 3.47? Is it ready to land?

gaaclarke · 2026-08-20T17:51:26Z

@gaaclarke @flar Is this relevant as of 3.47? Is it ready to land?

Yes it's relevant, please land it.

gemini-code-assist

Code Review

This pull request introduces a new documentation page detailing Impeller's anti-aliasing techniques, specifically Multisample Anti-Aliasing (MSAA) and Signed Distance Fields (SDFs), and integrates it into the sidebar and the main Impeller documentation. The review feedback focuses on enhancing the clarity, grammar, and technical accuracy of the new page, including several suggestions for improved phrasing, formatting, and professional tone. Additionally, the reviewer requests clarification on whether the SDF configuration is iOS-only or if there is an equivalent setup for Android.

gemini-code-assist · 2026-08-20T17:52:29Z

+Mobile phone GPUs have special hardware to optimize this process (
+[Tiled rendering][]). It comes in varying degrees of how many samples to
+consider.


The line break inside the parentheses before the link [Tiled rendering][] is awkward. Adjusting the line break improves readability while adhering to the 80-character semantic line break limit.

Suggested change

Mobile phone GPUs have special hardware to optimize this process (

[Tiled rendering][]). It comes in varying degrees of how many samples to

consider.

Mobile phone GPUs have special hardware to optimize this process

([Tiled rendering][]). It comes in varying degrees of how many samples to

consider.

gemini-code-assist · 2026-08-20T17:52:29Z

+[Tiled rendering][]). It comes in varying degrees of how many samples to
+consider.
+
+On desktop and mobile 4x MSAA is used for all rendering calls.


Add a comma after "mobile" for better readability and grammatical correctness.

Suggested change

On desktop and mobile 4x MSAA is used for all rendering calls.

On desktop and mobile, 4x MSAA is used for all rendering calls.

gemini-code-assist · 2026-08-20T17:52:29Z

+Typically, hardware accelerated computer graphics define a series of points and
+edges (a [mesh][]) and [shaders][]. Instead, SDF renders shapes in the fragment
+shader program as signed distance fields. Since the shape is defined in the
+fragment shader the edges can be smoothed at the fragment level instead of
+relying on the rasterization of a mesh.


Improve clarity, grammar, and technical accuracy:

Hyphenate "hardware-accelerated".

Clarify "SDF renders" to "Impeller renders ... using signed distance fields (SDFs)" since SDF is the representation, not the renderer.

Add a comma after the introductory conditional clause ("Since the shape is defined in the fragment shader,").

Suggested change

Typically, hardware accelerated computer graphics define a series of points and

edges (a [mesh][]) and [shaders][]. Instead, SDF renders shapes in the fragment

shader program as signed distance fields. Since the shape is defined in the

fragment shader the edges can be smoothed at the fragment level instead of

relying on the rasterization of a mesh.

Typically, hardware-accelerated computer graphics define a series of points and

edges (a [mesh][]) and [shaders][]. Instead, Impeller renders shapes in the

fragment shader program using signed distance fields (SDFs). Since the shape is

defined in the fragment shader, the edges can be smoothed at the fragment level

instead of relying on the rasterization of a mesh.

gemini-code-assist · 2026-08-20T17:52:29Z

+This technique is prioritized on desktop because SDF rendering puts more demand
+on the GPU and Flutter supports older mobile phones. Also, the physical pixel
+sizes on desktop computers are typically bigger than those of mobile phones. So
+any imperfection will be more evident there.


Refine the phrasing for a more professional and technical tone:

Use "places higher demands on" instead of "puts more demand on".

Use "larger" instead of "bigger" for pixel sizes.

Avoid starting a sentence with "So" in technical documentation; combine the clauses to improve flow.

Suggested change

This technique is prioritized on desktop because SDF rendering puts more demand

on the GPU and Flutter supports older mobile phones. Also, the physical pixel

sizes on desktop computers are typically bigger than those of mobile phones. So

any imperfection will be more evident there.

This technique is prioritized on desktop because SDF rendering places higher

demands on the GPU, and Flutter supports older mobile phones. Also, the physical

pixel sizes on desktop computers are typically larger than those of mobile

phones, making any imperfections more noticeable.

gemini-code-assist · 2026-08-20T17:52:30Z

+do so with the [FragmentShader API][]. Using the [drawPath()][] is sufficient
+for most use cases without resorting to high quality SDF rendering. Not all
+drawn paths are guaranteed to result in SDF rendering though.


Improve phrasing and grammar:

Remove the unnecessary article "the" before [drawPath()][].

Hyphenate "high-quality" when used as a compound adjective.

Avoid ending the sentence with "though" to maintain a professional tone.

Suggested change

do so with the [FragmentShader API][]. Using the [drawPath()][] is sufficient

for most use cases without resorting to high quality SDF rendering. Not all

drawn paths are guaranteed to result in SDF rendering though.

do so with the [FragmentShader API][]. Using [drawPath()][] is sufficient

for most use cases without resorting to high-quality SDF rendering. However,

not all drawn paths are guaranteed to result in SDF rendering.

gemini-code-assist · 2026-08-20T17:52:30Z

+### Enabling SDFs on iOS
+
+SDFs can be enabled on iOS by adding a new field to the `Info.plist` for the
+project.


The section only describes how to enable SDFs on iOS. Since the PR description mentions opting in to SDFs on "mobile devices" (plural), please clarify if there is an equivalent configuration for Android (e.g., in AndroidManifest.xml), or explicitly state if this feature is currently iOS-only.

Adds documentation for antialiasing with impeller

68e69c5

gaaclarke added 2 commits May 7, 2026 09:35

added links

bb96228

added internal links

7581f25

gaaclarke requested a review from andywolff May 7, 2026 16:45

andywolff reviewed May 7, 2026

View reviewed changes

Comment thread sites/docs/src/content/perf/antialiasing.md

andywolff approved these changes May 7, 2026

View reviewed changes

adds some images

0e74068

sfshaza2 reviewed May 7, 2026

View reviewed changes

sfshaza2 added the review.await-update Awaiting Updates after Edits label May 7, 2026

shams feedback

76cc499

gaaclarke requested a review from sfshaza2 May 7, 2026 22:59

sfshaza2 removed the review.await-update Awaiting Updates after Edits label May 11, 2026

flar reviewed May 14, 2026

View reviewed changes

Merge branch 'main' into antialias-doc

1a138ad

sfshaza2 approved these changes Jul 20, 2026

View reviewed changes

gaaclarke marked this pull request as ready for review August 20, 2026 17:51

gaaclarke requested a review from a team as a code owner August 20, 2026 17:51

gemini-code-assist Bot reviewed Aug 20, 2026

View reviewed changes


		### SDFs with the FragmentShader API

		Standard primitive shapes in Flutter are drawn automatically with SDFs. If a

	On desktop and mobile 4x MSAA is used for all rendering calls.
	On desktop and mobile, 4x MSAA is used for all rendering calls.

Uh oh!

Conversation

gaaclarke commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issues fixed by this PR

PRs or commits this PR depends on

Presubmit checklist

Uh oh!

flutter-website-bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

andywolff left a comment

Choose a reason for hiding this comment

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flutter-website-bot commented Jul 17, 2026

Uh oh!

flutter-website-bot commented Jul 17, 2026

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

gaaclarke commented Aug 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

gaaclarke commented May 6, 2026 •

edited

Loading

flutter-website-bot commented May 7, 2026 •

edited

Loading

parlough commented Aug 20, 2026 •

edited

Loading