Skip to content

impeller.md

Latest commit

 

History

History
163 lines (124 loc) · 5.68 KB

impeller.md

File metadata and controls

163 lines (124 loc) · 5.68 KB
Raw
title Impeller rendering engine
description What is Impeller and how to enable it?

:::note As of the 3.27 release, Impeller is the default rendering engine for both iOS and Android API 29+. To see detailed info on where Impeller is currently supported, check out the Can I use Impeller? page. :::

What is Impeller?

Impeller provides a new rendering runtime for Flutter. Impeller precompiles a smaller, simpler set of shaders at engine-build time so they don't compile at runtime.

For a video introduction to Impeller, check out the following talk from Google I/O 2023.

Impeller has the following objectives:

  • Predictable performance: Impeller compiles all shaders and reflection offline at build time. It builds all pipeline state objects upfront. The engine controls caching and caches explicitly.
  • Instrumentable: Impeller tags and labels all graphics resources, such as textures and buffers. It can capture and persist animations to disk without affecting per-frame rendering performance.
  • Portable: Flutter doesn't tie Impeller to a specific client-rendering API. You can author shaders once and convert them to backend-specific formats, as necessary.
  • Leverages modern graphics APIs: Impeller uses, but doesn't depend on, features available in modern APIs like Metal and Vulkan.
  • Leverages concurrency: Impeller can distribute single-frame workloads across multiple threads, if necessary.

Availability

Where can you use Impeller? For detailed info, check out the Can I use Impeller? page.

iOS

Impeller is the only supported rendering engine on iOS with no ability to switch to Skia.

Android

Impeller is available and enabled by default on Android API 29+. On devices running lower versions of Android or don't support Vulkan, Impeller falls back to the legacy OpenGL renderer. No action on your part is necessary for this fallback behavior.

  • To disable Impeller when debugging, pass --no-enable-impeller to the flutter run command.

    flutter run --no-enable-impeller

  • To disable Impeller when deploying your app, add the following setting to your project's AndroidManifest.xml file under the <application> tag:

<meta-data
    android:name="io.flutter.embedding.android.EnableImpeller"
    android:value="false" />

Web

Flutter on the web offers two renderers -- canvaskit and skwasm -- which both currently use Skia. They might use Impeller in the future.

macOS

You can try out Impeller for macOS behind a flag. In a future release, the ability to opt-out of using Impeller will be removed.

To enable Impeller on macOS when debugging, pass --enable-impeller to the flutter run command.

flutter run --enable-impeller

To enable Impeller on macOS when deploying your app, add the following tags under the top-level <dict> tag in your app's Info.plist file.

  <key>FLTEnableImpeller</key>
  <true />

Bugs and issues

The team continues to improve Impeller support. If you encounter performance or fidelity issues with Impeller on any platform, file an issue in the GitHub tracker. Prefix the issue title with [Impeller] and include a small reproducible test case.

Please include the following information when submitting an issue for Impeller:

  • The device you are running on, including the chip information.
  • Screenshots or recordings of any visible issues.
  • An export of the performance trace. Zip the file and attach it to the GitHub issue.

Architecture

To learn more details about Impeller's design and architecture, check out the README.md file in the source tree.

Additional information