了解 Surface 模式下的媒体增强功能生命周期

媒体增强 API 提供了一种低延迟、可保护隐私的设备端 AI 解决方案，该解决方案利用硬件加速功能来提供高质量的媒体改进，且不会造成 APK 膨胀。如需了解详情，请参阅了解媒体增强功能。

以下架构图显示了媒体增强 API 的异步 Surface 模式执行生命周期。此模式直接关联硬件缓冲区，从而消除在 CPU 和 GPU 内存缓冲区之间来回复制未压缩帧的性能瓶颈。

图表：说明了媒体增强 API 的 7 步异步表面到表面生命周期。
图 1. 异步 Surface 模式执行生命周期和增强流水线的七个可操作步骤。

增强流水线通过以下步骤实现：

第 1 阶段：设置增强会话

1. 提供输入 surface：您的应用会向增强框架提供一个输入 surface 句柄，以访问要处理的帧。

2. 设置输出 Surface：您的应用直接向框架预配并绑定渲染目标（例如 SurfaceView 或 TextureView）。

第 2 阶段。生成输入帧

3. 准备基本媒体：应用检索基本未压缩媒体。例如，通过从本地磁盘读取文件。

4. 注入帧数据：您的应用将原始图像载荷直接写入绑定输入源管道。

第 3 阶段。处理和增强

5. 执行 AI 处理：框架在设备的 GPU 或 NPU 上处理帧，应用机器学习增强功能，例如色调映射、模糊修复或高清重塑。

6. 提供增强帧：引擎直接将增强的全分辨率帧输出到绑定的输出界面。

第 4 阶段：显示或保存结果

7. 最终输出：应用接收处理后的硬件流缓冲区，以便在界面中呈现或将其保存回存储空间。

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 模式（surface in、surface out）

Surface 执行模式 (EnhancementMode.SURFACE) 可避免在 CPU 和 GPU 内存缓冲区之间移动帧时产生的性能开销。相反，增强库会直接映射原始硬件缓冲区，从输入 Surface 读取帧，以原生方式处理这些帧，然后直接将它们传输到输出 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()