瞭解 Surface 模式中的媒體強化生命週期

Media Enhancement API 提供低延遲、隱私權保護的裝置端 AI 解決方案，可運用硬體加速功能，以零 APK 膨脹率提供高品質的媒體改善功能。詳情請參閱「瞭解媒體強化功能」。

下圖顯示 Media Enhancement API 的非同步介面模式執行生命週期。這個模式會直接連結硬體緩衝區，消除在 CPU 和 GPU 記憶體緩衝區之間來回複製未壓縮影格的效能瓶頸。

這張圖說明媒體增強 API 的 7 步驟非同步介面到介面生命週期。
圖 1：非同步介面模式執行生命週期，以及強化管道的七個可採取行動的步驟。

強化管道的實作步驟如下：

第 1 階段：設定強化工作階段

1. 提供輸入介面：應用程式會提供輸入介面控制代碼給強化架構，以存取要處理的影格。

2. 設定輸出介面：應用程式會直接向架構佈建及繫結算繪目標 (例如 SurfaceView 或 TextureView)。

第 2 階段：產生輸入影格

3. 準備基本媒體：應用程式會擷取未壓縮的基本媒體。例如從本機磁碟讀取檔案。

4. 插入影格資料：應用程式會將原始圖片酬載直接寫入繫結的輸入介面管道。

第 3 階段：處理及強化

5. 執行 AI 處理中：架構會在裝置的 GPU 或 NPU 上處理影格，並套用色調對映、去模糊或畫質提升等機器學習強化功能。

6. 提供強化影格：引擎會直接將強化版全解析度影格輸出至繫結的輸出介面。

第 4 階段：顯示或儲存結果

7. 完成輸出：應用程式會收到處理過的硬體串流緩衝區，以便在 UI 中算繪或儲存回儲存空間。

EnhancementSession 是重量級的內容物件，可維護持續性的 GPU 或 NPU 記憶體管道。並分配專屬視訊 RAM (VRAM) 和原生系統控制代碼。為避免嚴重記憶體流失和潛在的OutOfMemoryError當機問題，請遵守下列生命週期原則：

  • 延遲例項化：等到使用者啟動強化動作後，再建立工作階段。
  • 策略性重複使用：處理具有相同設定 (尺寸和切換選項) 的串流或影格時，請維護並重複使用單一工作階段例項。
  • 提示拆解：在視覺工作終止時立即叫用 session.release()，釋放共用硬體資源。

初始化強化引擎

這個方法會協調兩步驟檢查。這項功能會驗證裝置的硬體是否支援加速，然後確保有必要的機器學習模組。

執行這項必要步驟，可在應用程式嘗試處理媒體前驗證功能，避免發生執行階段初始化失敗的問題。

class MediaSetupViewModel(application: Application) : AndroidViewModel(application) {
    private val enhancementClient = Enhancement.getClient(application)
    fun initializeEnhancementEngine() {
        viewModelScope.launch {
            try {
                // 1. Verify hardware capability
                val isSupported = enhancementClient.isDeviceSupportedAsync()
                if (!isSupported) {
                    notifyUiDeviceIncompatible()
                    return@launch
                }
                // 2. Verify and download the Google Play services ML modules
                val isInstalled = enhancementClient.isModuleInstalledAsync()
                if (!isInstalled) {
                    notifyUiDownloadingModels()
                    enhancementClient.installModule().await() 
                }
                notifyUiEngineReady()
            } catch (e: Exception) {
                // Handle potential errors during session creation or image
                // processing.
                handleInitializationError(e)
            }
        }
    }
}

實作：表面模式 (表面內、表面外)

Surface 執行模式 (EnhancementMode.SURFACE) 可避免在 CPU 和 GPU 記憶體緩衝區之間移動影格時，造成效能負擔。而是直接對應原始硬體緩衝區、從輸入 Surface 讀取影格、以原生方式處理，然後直接傳輸至輸出 Surface。

單一畫面表面快照

這個方法用於有效率地將效果套用至單一硬體解碼的影像影格。

// Provisions input Surface (for example, ImageReader) and output Surface (for
// example, SurfaceView)
val inputSurface: Surface = imageReader.surface
val outputSurface: Surface = surfaceView.holder.surface
// 1. Configure parameters for SURFACE mode
val surfaceOptions = EnhancementOptions(
    imageReader.width,
    imageReader.height,
    EnhancementMode.SURFACE,
    enableTonemap = true,
    enableDeblurDenoise = true,
    enableFaceDetection = false
).also {
    // 2. Bind hardware surfaces
    it.setInputSurface(inputSurface)
    it.setOutputSurface(outputSurface)
}

// 3. Create the session to process the hardware frame
val singleFrameSession = enhancementClient.createSessionAsync(surfaceOptions, executor)
// The API processes the single frame. Upon completion, release the session.
singleFrameSession.release()