The Android embedder for Flutter introduces a new API,SurfaceProducer, which allows plugins to render to aSurface without needing to manage what the backing implementation is. Plugins using the oldercreateSurfaceTexture API will continue to work withImpeller after thenext stable release, but are recommended to migrate to the new API.

An AndroidSurfaceTexture is a backing implementation for aSurface that uses anOpenGLES texture as the backing store.

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

In newer versions of the Android API (>= 29), Android introduced a backend-agnosticHardwareBuffer, which coincides with the minimum version that Flutter will attempt to use theVulkan renderer. The Android embedding API needed to be updated to support a more genericSurface creation API that doesn't rely on OpenGLES.

If you are using the oldercreateSurfaceTexture API, you should migrate to the newcreateSurfaceProducer 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 aSurfaceTextureEntry, create aSurfaceProducer:

   java

   TextureRegistry.SurfaceTextureEntryentry=textureRegistry.createSurfaceTexture();TextureRegistry.SurfaceProducerproducer=textureRegistry.createSurfaceProducer();

   content_copy

2. Instead of creating anew Surface(...), callgetSurface() on theSurfaceProducer:

   java

   Surfacesurface=newSurface(entry.surfaceTexture());Surfacesurface=producer.getSurface();

   content_copy

In order to conserve memory when the application is suspended in the background, Android and Fluttermay destroy a surface when it is no longer visible. To ensure that the surface is recreated when the application is resumed, you should use the providedsetCallback method to listen to surface lifecycle events:

surfaceProducer.setCallback(newTextureRegistry.SurfaceProducer.Callback(){@OverridepublicvoidonSurfaceAvailable(){// Do surface initialization here, and draw the current frame.}​@OverridepublicvoidonSurfaceDestroyed(){// Do surface cleanup here, and stop drawing frames.}});

A full example of using this new API can be found inPR 6989 for thevideo_player_android plugin.

If your plugin implements a camera preview, your migration might also require fixing the rotation of that preview. This is becauseSurfaces produced by theSurfaceProducer might not contain the transformation information that Android libraries need to correctly rotate the preview automatically.

In order to correct the rotation, you need to rotate the preview with respect to the camera sensor orientation and the device orientation according to the equation:

rotation = (sensorOrientationDegrees - deviceOrientationDegrees * sign + 360) % 360

wheredeviceOrientationDegrees is counterclockwise degrees andsign is 1 for front-facing cameras and -1 for back-facing cameras.

To calculate this rotation,

• UseSurfaceProducer.handlesCropAndRotation to check if the underlyingSurface handles rotation (iffalse, you may need to handle the rotation).
• Retrieve the sensor orientation degrees by retrieving the value ofCameraCharacteristics.SENSOR_ORIENTATION.
• Retrieve the device orientation degrees in one of the ways that theAndroid orientation calculation documentation details.

To apply this rotation, you can use aRotatedBox widget.

For more information on this calculation, check out theAndroid orientation calculation documentation. For a full example of making this fix, check outthiscamera_android_camerax PR.

Landed in version: 3.22

API documentation:

• SurfaceProducer
• createSurfaceProducer
• createSurfaceTexture

Relevant issues:

• Issue 139702
• Issue 145930

Relevant PRs:

• PR 51061, where we test the new API in the engine tests.
• PR 6456, where we migrate thevideo_player plugin to use the new API.
• PR 6461, where we migrate thecamera_android plugin to use the new API.
• PR 6989, where we add a full example of using the new API in thevideo_player_android plugin.