New APIs for Android plugins that render to a Surface

Summary

#

The Android embedder for Flutter introduces a new API, SurfaceProducer, which allows plugins to render to a Surface without needing to manage what the backing implementation is. Plugins using the older createSurfaceTexture API will not work with Impeller.

Background

#

An Android SurfaceTexture is a backing implementation for a Surface that uses an OpenGLES texture as the backing store.

For example, a plugin might display frames from a camera plugin:

Flowchart

In newer versions of the Android API (>= 29), Android introduced a backend-agnostic HardwareBuffer, which coincides with the minimum version that Flutter will attempt to use the Vulkan renderer. In order to support this, the Android embedding API needed to be updated to support a more generic Surface creation API that doesn't rely on OpenGLES.

Migration guide

#

If you are using the older createSurfaceTexture API, you should migrate to the new createSurfaceProducer API. The new API is more flexible and allows the Flutter engine to opaquely pick the best implementation for the current platform and API level.

  1. Instead of creating a SurfaceTextureEntry, create a SurfaceProducer:

    - TextureRegistry.SurfaceTextureEntry entry = textureRegistry.createSurfaceTexture();
    + TextureRegistry.SurfaceProducer producer = textureRegistry.createSurfaceProducer();
  2. Instead of creating a new Surface(...), call getSurface() on the SurfaceProducer:

    - Surface surface = new Surface(entry.surfaceTexture());
    + Surface surface = producer.getSurface();

Otherwise, the API is the same as before.

Timeline

#

Landed in version: 3.22.0-12.0.pre-56

In stable release: 3.22.0

References

#

API documentation:

Relevant issues:

Relevant PRs:

  • PR 51061, where we test the new API in the engine tests.
  • PR 6456, where we migrate the video_player plugin to use the new API.
  • PR 6461, where we migrate the camera_android plugin to use the new API.