diff --git a/sites/docs/src/content/perf/antialiasing.md b/sites/docs/src/content/perf/antialiasing.md new file mode 100644 index 00000000000..47e7afd2662 --- /dev/null +++ b/sites/docs/src/content/perf/antialiasing.md @@ -0,0 +1,79 @@ +--- +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). 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 + +### 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 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 MSAA is used for all rendering calls. + +### 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 +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 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 +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 + +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. + +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 + +``` + +[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 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 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 00000000000..36601684d1f Binary files /dev/null and b/sites/docs/web/assets/images/docs/perf/msaa4.png differ 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 00000000000..f687113fb20 Binary files /dev/null and b/sites/docs/web/assets/images/docs/perf/msaa4sdf.png differ diff --git a/sites/docs/web/assets/images/docs/perf/noaa.png b/sites/docs/web/assets/images/docs/perf/noaa.png new file mode 100644 index 00000000000..a1605c89b0f Binary files /dev/null and b/sites/docs/web/assets/images/docs/perf/noaa.png differ