Media Enhancement API 使用入门

Media Enhancement API 是一款强大的工具，可利用设备端 GPU 加速功能，实现高质量、低延迟的图片自动美化。这包括自动色调映射、去模糊、去噪和放大等功能。

在初始化 API 之前，您必须配置项目依赖项，并在清单中声明硬件加速要求。跳过这些配置是导致 GLOBAL_INIT_FAILED 运行时错误的主要原因。

Gradle 依赖项

将以下依赖项添加到 app/build.gradle.kts 文件中。为了实现异步、非阻塞执行，请添加 Kotlin 协程和 Jetpack Media3，以便进行硬件 Surface 处理。

dependencies {
    // Google Play services Media Enhancement Library (Beta)
    implementation("com.google.android.gms:play-services-media-effect-enhancement:16.0.0-beta04")
}

在 Google 的 Maven 制品库中查看 play-services-media-effect-enhancement 的软件包详细信息。

我们还建议使用 Kotlin 协程来异步管理增强会话。

// Kotlin coroutines for asynchronous API handling
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.7.3")

Android 清单要求

在 AndroidManifest.xml 文件的 <application> 标记内添加以下元素：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <!-- 1. Google Play services version for runtime compatibility checks -->
        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />
        <!-- 2. Declare OpenCL compute libraries for NPU/GPU neural acceleration -->
        <uses-native-library android:name="libOpenCL.so" android:required="false" />
        <uses-native-library android:name="libOpenCL-car.so" android:required="false" />
        <uses-native-library android:name="libOpenCL-pixel.so" android:required="false" />
        <!-- 3. Declare OpenGL ES for high-performance graphics rendering -->
        <uses-native-library android:name="libGLESv2.so" android:required="false" />
        <uses-native-library android:name="libGLESv3.so" android:required="false" />
    </application>
</manifest>

OpenCL 提供原生计算库，这些库是为媒体增强任务启用 NPU 和 GPU 神经加速所必需的。在清单中声明这些库是 API 利用硬件加速的前提条件，而硬件加速对于执行高质量、低延迟的增强功能至关重要。如需详细了解 OpenCL，请参阅 OpenCL 实现。

OpenGL ES 提供原生图形库，这些库是高性能渲染媒体增强输出所必需的。在清单中声明这些库对于确保渲染流水线能够在硬件加速表面上有效显示处理后的媒体至关重要。如需了解 OpenGL，请参阅 OpenGL API 文档概览。

Android 渲染流水线必须经过硬件加速，以防止出现瓶颈。虽然对于以 API 14+ 为目标平台的应用，该功能默认处于启用状态，但您仍需在 <activity> 标记中明确设置 android:hardwareAccelerated="true"。

设备兼容性和模块设置

Google Play 服务会动态提供机器学习模型，以节省初始 APK 存储空间。在执行增强功能之前，应用必须使用 EnhancementClient 验证硬件支持，并确保必要的模型权重已下载并缓存在本地。每台设备只需执行一次此流程。

使用 suspendCancellableCoroutine，您可以将基于任务的客户端回调封装在标准 Kotlin 挂起函数中，以便更清晰地按顺序执行：

// Verifies if host hardware supports NPU/GPU acceleration
suspend fun EnhancementClient.isDeviceSupportedAsync(): Boolean = suspendCancellableCoroutine { continuation ->
    this.isDeviceSupported()
        .addOnSuccessListener { result -> continuation.resume(result) }
        .addOnFailureListener { exception -> continuation.resumeWithException(exception) }
}
// Verifies the presence of required neural network models
suspend fun EnhancementClient.isModuleInstalledAsync(): Boolean = suspendCancellableCoroutine { continuation ->
    this.isModuleInstalled()
        .addOnSuccessListener { result -> continuation.resume(result) }
        .addOnFailureListener { exception -> continuation.resumeWithException(exception) }
}