内容

用于渲染到 Surface 的 Android 插件的新 API

内容

摘要
背景
迁移指南
关于相机预览的说明
时间轴
参考

Flutter 的 Android 嵌入器引入了新的 API，SurfaceProducer，它允许插件渲染到 Surface，而无需管理后备实现是什么。使用旧版 createSurfaceTexture API 的插件在下一个稳定版本发布后将继续与 Impeller 一起使用，但建议迁移到新的 API。

Android 的 SurfaceTexture 是 Surface 的底层实现，它使用 OpenGLES 纹理作为其后备存储。

例如，一个插件可能会显示来自相机插件的帧。

Flowchart

在较新的 Android API 版本（>= 29）中，Android 引入了一个与后端无关的 HardwareBuffer，这与 Flutter 尝试使用 Vulkan 渲染器的最低版本相吻合。Android 嵌入 API 需要更新以支持更通用的 Surface 创建 API，该 API 不依赖于 OpenGLES。

如果您正在使用旧的 createSurfaceTexture API，则应迁移到新的 createSurfaceProducer API。新的 API 更加灵活，并允许 Flutter 引擎不透明地为当前平台和 API 级别选择最佳实现。

不要创建 SurfaceTextureEntry，而是创建 SurfaceProducer。

javaTextureRegistry.SurfaceTextureEntry entry = textureRegistry.createSurfaceTexture();
TextureRegistry.SurfaceProducer producer = textureRegistry.createSurfaceProducer();

不要创建 new Surface(...)，而是调用 SurfaceProducer 上的 getSurface()。

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

为了在应用程序在后台挂起时节省内存，Android 和 Flutter 可能会在表面不再可见时销毁它。为了确保在应用程序恢复时重新创建表面，您应该使用提供的 setCallback 方法来监听表面生命周期事件。

javasurfaceProducer.setCallback(
   new TextureRegistry.SurfaceProducer.Callback() {
      @Override
      public void onSurfaceAvailable() {
         // Do surface initialization here, and draw the current frame.
      }

      @Override
      public void onSurfaceDestroyed() {
         // Do surface cleanup here, and stop drawing frames.
      }
   }
);

在 PR 6989 中可以找到使用此新 API 的完整示例，该示例适用于 video_player_android 插件。

如果您的插件实现了相机预览，则您的迁移可能还需要修复该预览的旋转。这是因为由 SurfaceProducer 生成的 Surface 可能不包含 Android 库自动正确旋转预览所需的转换信息。

为了校正旋转，您需要根据以下公式相对于相机传感器方向和设备方向旋转预览：

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

其中 deviceOrientationDegrees 是逆时针度数，sign 对于前置摄像头为 1，对于后置摄像头为 -1。

要计算此旋转，

使用 SurfaceProducer.handlesCropAndRotation 检查底层 Surface 是否处理旋转（如果为 false，您可能需要处理旋转）。
通过检索 CameraCharacteristics.SENSOR_ORIENTATION 的值来检索传感器方向度数。
以 Android 方向计算文档中详细介绍的其中一种方式检索设备方向度数。

要应用此旋转，您可以使用 RotatedBox 小部件。

有关此计算的更多信息，请查看 Android 方向计算文档。有关进行此修复的完整示例，请查看此 camera_android_camerax PR。

包含在版本中：3.22

稳定版本：3.24

在即将发布的稳定版本 3.27 中，onSurfaceCreated 已弃用，并添加了 onSurfaceAvailable 和 handlesCropAndRotation。

API 文档

摘要

背景

迁移指南

关于相机预览的说明

时间轴

参考