From 68e69c5b9e49d7e6bfb81cc0dd92871858630b2a Mon Sep 17 00:00:00 2001 From: gaaclarke <30870216+gaaclarke@users.noreply.github.com> Date: Wed, 6 May 2026 16:53:00 -0700 Subject: [PATCH 1/5] Adds documentation for antialiasing with impeller --- sites/docs/src/content/perf/antialiasing.md | 66 +++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 sites/docs/src/content/perf/antialiasing.md diff --git a/sites/docs/src/content/perf/antialiasing.md b/sites/docs/src/content/perf/antialiasing.md new file mode 100644 index 00000000000..5057aca49d0 --- /dev/null +++ b/sites/docs/src/content/perf/antialiasing.md @@ -0,0 +1,66 @@ +--- +title: Impeller anti-aliasing +description: How does Impeller perform anti-aliasing? +--- + +Aliasing is the visual artifacts that result from drawing geometry to a grid of +pixels (rasterization). Impeller employs a couple of techniques to smooth out +the mapping to raster graphics (anti-aliasing). + +## Techniques + +### Multisample anti-aliasing (MSAA) + +MSAA is a global anti-aliasing technique that operates on the whole contents of +the screen. It is an optimization over rendering the whole screen at a larger +scale and shrinking it down (SSAA). Instead of doing the fragment operation for +each fragment in a region, if it is determined they have the same coverage, only +one fragment operation is calculated. This limits smoothing to edges. Mobile +phone GPU's have special hardware to optimize this process (tiling). It comes in +varying degrees of how many samples to consider. + +On desktop and mobile 4x resolution is used for all rendering calls. + +### Signed distance fields (SDFs) + +Typically, hardware accelerated computer graphics is done by defining a series +of points and edges (a mesh) and shaders. SDF rendering instead renders the +shape of things in the fragment shader program using SDFs to define the shape of +the object being drawn. Since the shape is defined in the fragment shader there +is an opportunity to smooth out edges at the fragment level instead of relying +on the rasterization of a mesh. + +On desktop, rendering with SDF's is enabled. On mobile platforms SDF's is an +option whose default value is false. + +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. + +## Working with anti-aliasing + +### SDFs with the FragmentShader API + +Standard primitive shapes in Flutter will be drawn automatically with SDFs. If +a Flutter developer wants to define their own custom graphics with SDFs they can +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. + +An example of rendering SDFs with the FragmentShader API can be found at +[`simple_sdf`][]. + +### Enabling SDFs on iOS + +SDFs can be enabled on iOS by adding a new field to the `Info.plist` for the +project. + +```xml + FLTEnableSDFs + +``` + +[FragmentShader API]: /ui/design/graphics/fragment-shaders +[drawPath()]: {{site.api}}/flutter/dart-ui/Canvas/drawPath.html +[`simple_sdf`]: {{site.github}}/flutter/samples/tree/main/simple_sdf From bb962282d64709ca947eac71f3d7abb92a3cab66 Mon Sep 17 00:00:00 2001 From: gaaclarke <30870216+gaaclarke@users.noreply.github.com> Date: Thu, 7 May 2026 09:35:41 -0700 Subject: [PATCH 2/5] added links --- sites/docs/src/content/perf/antialiasing.md | 41 ++++++++++++--------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/sites/docs/src/content/perf/antialiasing.md b/sites/docs/src/content/perf/antialiasing.md index 5057aca49d0..7106e892d26 100644 --- a/sites/docs/src/content/perf/antialiasing.md +++ b/sites/docs/src/content/perf/antialiasing.md @@ -11,32 +11,33 @@ the mapping to raster graphics (anti-aliasing). ### Multisample anti-aliasing (MSAA) -MSAA is a global anti-aliasing technique that operates on the whole contents of -the screen. It is an optimization over rendering the whole screen at a larger -scale and shrinking it down (SSAA). Instead of doing the fragment operation for -each fragment in a region, if it is determined they have the same coverage, only -one fragment operation is calculated. This limits smoothing to edges. Mobile -phone GPU's have special hardware to optimize this process (tiling). It comes in -varying degrees of how many samples to consider. +[MSAA][] is a global anti-aliasing technique that operates on the whole contents +of the screen. It is an optimization over rendering the whole screen at a larger +scale and shrinking it down ([SSAA][]). Instead of doing the fragment operation +for each fragment in a region, if it is determined they have the same coverage, +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. -On desktop and mobile 4x resolution is used for all rendering calls. +On desktop and mobile 4x MSAA is used for all rendering calls. -### Signed distance fields (SDFs) +### Signed distance fields ([SDFs][]) Typically, hardware accelerated computer graphics is done by defining a series -of points and edges (a mesh) and shaders. SDF rendering instead renders the -shape of things in the fragment shader program using SDFs to define the shape of -the object being drawn. Since the shape is defined in the fragment shader there -is an opportunity to smooth out edges at the fragment level instead of relying -on the rasterization of a mesh. +of points and edges (a [mesh][]) and [shaders][]. SDF rendering instead renders +the shape of things in the fragment shader program using SDFs to define the +shape of the object being drawn. Since the shape is defined in the fragment +shader there is an opportunity to smooth out edges at the fragment level instead +of relying on the rasterization of a mesh. -On desktop, rendering with SDF's is enabled. On mobile platforms SDF's is an +On desktop, rendering with SDFs is enabled. On mobile platforms SDFs is an option whose default value is false. 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. +sizes on desktop computers are typically bigger than those of mobile phones. So +any imperfection will be more evident there. ## Working with anti-aliasing @@ -61,6 +62,12 @@ project. ``` +[MSAA]: https://en.wikipedia.org/wiki/Multisample_anti-aliasing +[SSAA]: https://en.wikipedia.org/wiki/Supersampling +[Tiled rendering]: https://en.wikipedia.org/wiki/Tiled_rendering +[SDFs]: https://en.wikipedia.org/wiki/Signed_distance_function +[mesh]: https://en.wikipedia.org/wiki/Polygon_mesh +[shaders]: https://en.wikipedia.org/wiki/Shader [FragmentShader API]: /ui/design/graphics/fragment-shaders [drawPath()]: {{site.api}}/flutter/dart-ui/Canvas/drawPath.html [`simple_sdf`]: {{site.github}}/flutter/samples/tree/main/simple_sdf From 7581f25c9ebdeaed58080ef7170a8bd44906a088 Mon Sep 17 00:00:00 2001 From: gaaclarke <30870216+gaaclarke@users.noreply.github.com> Date: Thu, 7 May 2026 09:41:33 -0700 Subject: [PATCH 3/5] added internal links --- sites/docs/src/content/perf/impeller.md | 2 ++ sites/docs/src/data/sidenav/default.yml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/sites/docs/src/content/perf/impeller.md b/sites/docs/src/content/perf/impeller.md index 036424d801b..c34cea4060d 100644 --- a/sites/docs/src/content/perf/impeller.md +++ b/sites/docs/src/content/perf/impeller.md @@ -142,6 +142,7 @@ check out the [README.md][] file in the source tree. ## Additional information +* [Impeller anti-aliasing][impeller-antialiasing] * [Frequently asked questions][impeller-faq] * [Impeller's coordinate system][impeller-coords] * [How to set up Xcode for GPU frame captures with metal][impeller-xcode-capture] @@ -151,6 +152,7 @@ check out the [README.md][] file in the source tree. * [Guidance for writing efficient shaders][impeller-shader-optimization] * [How color blending works in Impeller][impeller-blending] +[impeller-antialiasing]: /perf/antialiasing [impeller-faq]: {{site.repo.flutter}}/blob/main/docs/engine/impeller/docs/faq.md [impeller-coords]: {{site.repo.flutter}}/blob/main/docs/engine/impeller/docs/coordinate_system.md [impeller-xcode-capture]: {{site.repo.flutter}}/blob/main/docs/engine/impeller/docs/xcode_frame_capture.md diff --git a/sites/docs/src/data/sidenav/default.yml b/sites/docs/src/data/sidenav/default.yml index 392c6502608..f2f7c633cf4 100644 --- a/sites/docs/src/data/sidenav/default.yml +++ b/sites/docs/src/data/sidenav/default.yml @@ -542,6 +542,8 @@ permalink: /perf - title: Impeller permalink: /perf/impeller + - title: Impeller anti-aliasing + permalink: /perf/antialiasing - title: Performance best practices permalink: /perf/best-practices - title: App size From 0e740689fc5f20a81024a0dee1af6fc55dd1fac3 Mon Sep 17 00:00:00 2001 From: gaaclarke <30870216+gaaclarke@users.noreply.github.com> Date: Thu, 7 May 2026 11:01:04 -0700 Subject: [PATCH 4/5] adds some images --- sites/docs/src/content/perf/antialiasing.md | 6 ++++++ sites/docs/web/assets/images/docs/perf/msaa4.png | Bin 0 -> 1130 bytes .../web/assets/images/docs/perf/msaa4sdf.png | Bin 0 -> 1274 bytes sites/docs/web/assets/images/docs/perf/noaa.png | Bin 0 -> 1049 bytes 4 files changed, 6 insertions(+) create mode 100644 sites/docs/web/assets/images/docs/perf/msaa4.png create mode 100644 sites/docs/web/assets/images/docs/perf/msaa4sdf.png create mode 100644 sites/docs/web/assets/images/docs/perf/noaa.png diff --git a/sites/docs/src/content/perf/antialiasing.md b/sites/docs/src/content/perf/antialiasing.md index 7106e892d26..3737cf92ffe 100644 --- a/sites/docs/src/content/perf/antialiasing.md +++ b/sites/docs/src/content/perf/antialiasing.md @@ -39,6 +39,12 @@ 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. +### Examples + +| 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) | + ## Working with anti-aliasing ### SDFs with the FragmentShader API diff --git a/sites/docs/web/assets/images/docs/perf/msaa4.png b/sites/docs/web/assets/images/docs/perf/msaa4.png new file mode 100644 index 0000000000000000000000000000000000000000..36601684d1f951b1e9e08460ba9d29dfca2cffc4 GIT binary patch literal 1130 zcmeAS@N?(olHy`uVBq!ia0y~yVAKI&4mO}jWo=(6kYX$ja(809c~Yky$YDu$^mSxl z*x1kgCy^D%S4j2<@?~JCQe$9fXklRZ1r%y{!N5>zz`*b-fq}tl1_Oh5!JJ)zHb4os zByV>YAPodRop*yw<1FxqEM{O3Qw3p0&mff#Ktc8rPhVH|SFG%Us+u!rE&nB zVB`=}h+t@9Rfqtyfdq&R6yOjeQj%zec&)&0igtwrW6b8<+b=)Q`TX*8?S0;hZD^N8Y{7G~4ar+zFP0azA1(0G zTz)?K{pLd`vZ~7}X^{2`ibI}9nf@FEbopq(^SF7TuT5IQ^2OZBbS+VI` z-z|xHznMuIJ$NSQ&}mrjB^cP7sJHdk^s>K;y-x~YxZ}*x-y7IMybM`#Fg(Ct9wD1`H}dHmUQT2S z!BO<(uG1R1el_^tS(-5UD~Rrf^`4kO$N z)}5gBZo|C?yPJR#@aO?cG>Gr>{=s%%^vPoRx$lK;LE;Z61NG*NUTd8LpvWONbwYJ2 sM7S}4LzC3hjcPN6t^jI>=Cq!NoH1=yo-u0ipFug@)78&qol`;+06&{WhX4Qo literal 0 HcmV?d00001 diff --git a/sites/docs/web/assets/images/docs/perf/msaa4sdf.png b/sites/docs/web/assets/images/docs/perf/msaa4sdf.png new file mode 100644 index 0000000000000000000000000000000000000000..f687113fb20675f582d854152e402a6f41dbd523 GIT binary patch literal 1274 zcmeAS@N?(olHy`uVBq!ia0y~yVAKI&4mO}jWo=(6kYX$ja(809c~Yky$YDu$^mSxl z*x1kgCy^D%S4j2<@?~JCQe$9fXklRZ1r%y{!N5>zz`*b-fq}tl1_Oh5!JJ)zHb4os zByV>YAPodRop*yw<1FxqEM{O3Qw3p0&mff#Ktc8rPhVH|SFG%UYOD=8vlD@q+IhM- zhE&{odv{^qqX3bHhh;0XLgN=~nq~4ZR?F?n!2;h0s=rt`UR}r#vS~^QTQl#l+5x8W z{paP%)8EZk&dZpWdb6DE17n>flfwoE7H$C@hJ#E3I$$=C0I`7t3pbIHL@UH=1+pm> zEr$dT%$>fXWBtXiRiz$g=uW%zOjhiU0gtmq{QB!3RkdS`rNtB?7@AlWA{r7HImCcO z=VynOCs#{l&n?g7dLDb-(nT613Q_@723Fy+=kTM)Uu)&hna}pMIRE*M;w|)`cp!H# z@#D8+g*?yWKKo8y@Dfbc!FBk3PdH(ya-JIu@?_j3D+{qy}!RY;l6Je`EE$+W9 zb~%U)yGIBhg%zTfhKxX`K2HBVJP^PO&kgc;b|pg?qZ#pV9tUtX>G1#9gb z)Q|`II_O^F-o`?i!F6bod_yzz`*b-fq}tl1_Oh5!JJ)zHb4os zByV>YAPodRop*yw<1FxqEM{O3Qw3p0&mff#Ktc8rPhVH|SFG%Us?vdeUk@@cFvohj zIEGZ*dV9x^>#%`<>%q_yf7h=mVYHs`K;d@OTc6i{N0Ynzqg}o*cszK>$#9TKK*wPN z0}D5h0I`7tn9afsW)mYxv_iaAU^hjpqKZjk_4j{YtFzB4??iWEM7ONin?JV#A09&U zMT4xh&Z&)?ixL?*#2OM9n^+Yh8WJj*fDT~Wd{{}=T1y-x%ps-_!2pqC^f|`Y{qja6 z&?HpvD@a=F=%uH(a-)Su!_gawhI8hM>H$N~h7oKI*eVXOfF4<~_M0G+Py?@l*ILI8 zYy+CO^P3G^n>HV61v(Pw8n}ZQoNp%To;b&a;nbK@eA~ literal 0 HcmV?d00001 From 76cc499195fd4dae9f63316565065979759f7ce4 Mon Sep 17 00:00:00 2001 From: gaaclarke <30870216+gaaclarke@users.noreply.github.com> Date: Thu, 7 May 2026 15:59:11 -0700 Subject: [PATCH 5/5] shams feedback --- sites/docs/src/content/perf/antialiasing.md | 28 ++++++++++----------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/sites/docs/src/content/perf/antialiasing.md b/sites/docs/src/content/perf/antialiasing.md index 3737cf92ffe..47e7afd2662 100644 --- a/sites/docs/src/content/perf/antialiasing.md +++ b/sites/docs/src/content/perf/antialiasing.md @@ -4,8 +4,9 @@ description: How does Impeller perform anti-aliasing? --- Aliasing is the visual artifacts that result from drawing geometry to a grid of -pixels (rasterization). Impeller employs a couple of techniques to smooth out -the mapping to raster graphics (anti-aliasing). +pixels (rasterization). The artifacts show up as jagged or rough edges on +shapes. Impeller employs a couple techniques to smooth out the mapping to raster +graphics (anti-aliasing). ## Techniques @@ -24,15 +25,14 @@ On desktop and mobile 4x MSAA is used for all rendering calls. ### Signed distance fields ([SDFs][]) -Typically, hardware accelerated computer graphics is done by defining a series -of points and edges (a [mesh][]) and [shaders][]. SDF rendering instead renders -the shape of things in the fragment shader program using SDFs to define the -shape of the object being drawn. Since the shape is defined in the fragment -shader there is an opportunity to smooth out edges 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, 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. -On desktop, rendering with SDFs is enabled. On mobile platforms SDFs is an -option whose default value is false. +On desktop, rendering with SDFs is enabled. On mobile platforms, SDFs are an +option that defaults to false. 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 @@ -41,16 +41,16 @@ any imperfection will be more evident there. ### Examples -| No AA | MSAA 4x | MSAA 4x + SDF | -| --- | --- | --- | +| 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) | ## Working with anti-aliasing ### SDFs with the FragmentShader API -Standard primitive shapes in Flutter will be drawn automatically with SDFs. If -a Flutter developer wants to define their own custom graphics with SDFs they can +Standard primitive shapes in Flutter are drawn automatically with SDFs. If a +Flutter developer wants to define their own custom graphics with SDFs they can 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.