用於渲染到 Surface 的 Android 外掛程式的新 API

Flutter 的 Android 嵌入器引入了一個新的 API，SurfaceProducer，允許外掛程式渲染到 Surface，而無需管理後端實作。使用較舊的 createSurfaceTexture API 的外掛程式在下一個穩定版本之後，將繼續使用 Impeller，但建議移轉到新的 API。

Android SurfaceTexture 是 Surface 的後端實作，使用 OpenGLES 紋理作為後端儲存。

舉例來說，一個外掛程式可能會顯示來自相機外掛程式的影格。

在較新版本的 Android API (>= 29) 中，Android 引入了一個與後端無關的 HardwareBuffer，這與 Flutter 嘗試使用 Vulkan 渲染器的最低版本一致。Android 嵌入 API 需要更新，以支援更通用的 Surface 建立 API，該 API 不依賴 OpenGLES。

如果您正在使用較舊的 createSurfaceTexture API，您應該遷移到新的 createSurfaceProducer API。新的 API 更加靈活，並允許 Flutter 引擎不透明地為目前的平台和 API 層級選擇最佳實作方式。

1. 請建立 SurfaceProducer，而不是建立 SurfaceTextureEntry。

   java

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

2. 請在 SurfaceProducer 上呼叫 getSurface()，而不是建立 new Surface(...)。

   java

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

為了在應用程式於背景暫停時節省記憶體，Android 和 Flutter *可能*會在 Surface 不再可見時銷毀它。為了確保在應用程式恢復時重新建立 Surface，您應該使用提供的 setCallback 方法來監聽 Surface 生命週期事件。

surfaceProducer.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.
      }
   }
);

您可以在 video_player_android 外掛程式的 PR 6989 中找到使用此新 API 的完整範例。

如果您的外掛程式實作了相機預覽，您的遷移也可能需要修正該預覽的旋轉。這是因為 SurfaceProducer 產生的 Surface 可能不包含 Android 函式庫正確自動旋轉預覽所需的轉換資訊。

為了修正旋轉，您需要根據相機感測器方向和裝置方向，按照以下公式旋轉預覽：

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

其中 deviceOrientationDegrees 是逆時針方向的度數，而 sign 對於前置相機為 1，對於後置相機為 -1。

為了計算此旋轉：

• 使用 SurfaceProducer.handlesCropAndRotation 來檢查底層的 Surface 是否處理旋轉 (如果為 false，您可能需要處理旋轉)。
• 透過擷取 CameraCharacteristics.SENSOR_ORIENTATION 的值來擷取感測器方向的度數。
• 以 Android 方向計算文件 中詳細說明的方式之一來擷取裝置方向的度數。

為了套用此旋轉，您可以使用 RotatedBox widget。

有關此計算的更多資訊，請查閱 Android 方向計算文件。如需修正此問題的完整範例，請查閱 此 camera_android_camerax PR。

已於版本中發佈：3.22

在穩定版本中發佈：3.24

在即將發佈的穩定版本 3.27 中，onSurfaceCreated 已被棄用，並新增了 onSurfaceAvailable 和 handlesCropAndRotation。

API 文件

• SurfaceProducer
• createSurfaceProducer
• createSurfaceTexture

相關問題

• Issue 139702
• Issue 145930

相關 PR

• PR 51061，我們在引擎測試中測試新的 API。
• PR 6456，我們將 video_player 外掛程式遷移為使用新的 API。
• PR 6461，我們將 camera_android 外掛程式遷移為使用新的 API。
• PR 6989，我們在 video_player_android 外掛程式中新增了使用新 API 的完整範例。

除非另有說明，否則本網站上的文件反映了 Flutter 的最新穩定版本。頁面上次更新於 2024-10-11。 檢視原始碼 或 回報問題。