Media Enhancement API menyediakan solusi AI di perangkat yang berlatensi rendah, menjaga privasi, dan memanfaatkan akselerasi hardware untuk memberikan peningkatan media berkualitas tinggi tanpa bloatware APK. Untuk mengetahui informasi selengkapnya, lihat Memahami kemampuan peningkatan kualitas media.
Mode Bitmap statis (EnhancementMode.BITMAP) dirancang untuk pemrosesan gambar statis yang didekode.
Beroperasi dalam mode Bitmap mengharuskan OS melakukan serialisasi data piksel yang tidak dikompresi dan menyalinnya dari memori CPU di seluruh bus sistem ke memori GPU, sehingga menampilkan frame yang diproses melalui salinan terbalik. Model ini dioptimalkan untuk eksekusi frame tunggal dan tidak kompatibel dengan streaming video real-time.
Alur kerja ini melibatkan pembuatan sesi, pemrosesan satu bitmap dengan sesi tersebut, lalu penanganan hasilnya. Contoh kode dari bagian sebelumnya membahas kasus penggunaan ini secara mendetail.
- Konfigurasikan opsi: Buat objek
EnhancementOptions, pastikanenhancementModeditetapkan keEnhancementMode.BITMAP. - Membuat sesi: Gunakan wrapper
createSessionAsyncyang telah kita tentukan sebelumnya untuk membuatEnhancementSession. Ini adalah objek yang berat, jadi buatlah hanya jika diperlukan. - Memproses gambar: Panggil sesi, bitmap input, dan opsi yang Anda inginkan.
- Menangani hasil: Fungsi penangguhan menampilkan Bitmap baru yang ditingkatkan saat berhasil atau menampilkan pengecualian saat gagal.
- Rilis sesi: Yang terpenting, panggil
session.release()setelah Anda selesai untuk mengosongkan resource GPU.
EnhancementSession adalah objek konteks berat yang mempertahankan
pipeline memori GPU atau NPU persisten. Proses ini mengalokasikan RAM video (VRAM) khusus
dan handle sistem native. Untuk mencegah kebocoran memori yang parah dan potensi
error OutOfMemoryError, patuhi prinsip siklus proses berikut:
- Pembuatan instance lambat: Jangan membuat sesi sampai pengguna memulai tindakan peningkatan.
- Penggunaan kembali yang strategis: Pertahankan dan gunakan kembali satu instance sesi saat memproses beberapa gambar dengan konfigurasi yang identik (dimensi dan opsi beralih).
- Penghapusan cepat: Panggil
session.release()segera setelah tugas visual berakhir untuk mengosongkan resource hardware bersama.
Melakukan inisialisasi mesin peningkatan
Metode ini mengatur pemeriksaan dua langkah. API ini memverifikasi apakah hardware perangkat mendukung akselerasi, lalu memastikan modul machine learning yang diperlukan tersedia.
Menjalankan langkah ini sebagai prasyarat akan mencegah kegagalan inisialisasi runtime dengan memvalidasi kemampuan sebelum aplikasi Anda mencoba memproses media.
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(installStatusCallback).await() } notifyUiEngineReady() } catch (e: Exception) { // Handle potential errors during session creation or image processing. handleInitializationError(e) } } } }
Membuat wrapper proses sesi dan bitmap
Gunakan wrapper coroutine Kotlin ini untuk mengonversi callback klien berbasis tugas menjadi fungsi penangguhan standar, sehingga memungkinkan eksekusi yang lebih rapi dan berurutan.
// Wraps the task-based createSession callback into a suspending function. suspend fun EnhancementClient.createSessionAsync( options: EnhancementOptions, executor: Executor ): EnhancementSession = withContext(Dispatchers.Main) { suspendCancellableCoroutine { continuation -> // EnhancementSessionCallback handles session success or failure. val callback = object : EnhancementSessionCallback { override fun onSessionCreated(session: EnhancementSession) { continuation.resume(session) } override fun onSessionCreationFailed(status: Status) { continuation.resumeWithException( Exception("Session creation failed: ${status.statusMessage} (${status.statusCode})") ) } override fun onSessionDestroyed() {} override fun onSessionDisconnected(status: Status) {} } // Handles errors during the initial request trigger. this@createSessionAsync.createSession(options, callback).addOnFailureListener(executor) { e -> if (continuation.isActive) { continuation.resumeWithException(e) } } } } // Wraps this process in a suspending function for cleaner execution. suspend fun EnhancementSession.processBitmapAsync( bitmap: Bitmap, options: EnhancementOptions ): Bitmap = suspendCancellableCoroutine { continuation -> // EnhancementCallback returns the processed bitmap or an error code. val callback = object : EnhancementCallback { override fun onBitmapProcessed(enhancedBitmap: Bitmap) { continuation.resume(enhancedBitmap) } override fun onError(statusCode: Int) { continuation.resumeWithException( Exception("Bitmap processing failed with status code: $statusCode") ) } override fun onSurfaceProcessed(timestamp: Long) {} override fun onCancelled(statusCode: Int) {} } this.process(bitmap, options, callback) }
Menjalankan pipeline bitmap di ViewModel
Untuk mengintegrasikan pipeline peningkatan ke dalam arsitektur aplikasi Anda, gunakan
ViewModel untuk mengelola siklus proses sesi. Pendekatan ini memastikan bahwa
resource GPU yang berat akan dirilis saat ViewModel dihapus.
// Define a data class to hold image information. data class ImageInfo(val bitmap: Bitmap) // Define a UI state class to hold loading status, errors, and enhanced image. data class EnhancementUiState( val isLoading: Boolean = false, val enhancementError: String? = null, val enhancedImage: ImageInfo? = null ) class EnhancementViewModel(application: Application) : AndroidViewModel(application) { // Backing field for UI state, initialized with default values. private val _uiState = MutableStateFlow(EnhancementUiState()) // Publicly exposed UI state flow for observation. val uiState: StateFlow<EnhancementUiState> = _uiState.asStateFlow() // Initialize client to interact with the Media Enhancement service. private val enhancementClient: EnhancementClient = Enhancement.getClient(application) // Single-thread executor for processing background enhancement tasks. private val enhancementExecutor = Executors.newSingleThreadExecutor() // Track session state to enable reuse across multiple processing calls. private var enhancementSession: EnhancementSession? = null private var sessionOptions: EnhancementOptions? = null // Primary function to trigger the enhancement workflow for a provided bitmap. fun enhanceImage(bitmap: Bitmap) { viewModelScope.launch(Dispatchers.IO) { _uiState.update { it.copy(isLoading = true, enhancementError = null) } try { // Define enhancement options (for example, enable upscale, tonemapping) based // on bitmap dimensions. val options = EnhancementOptions( bitmap.width, bitmap.height, EnhancementMode.BITMAP, isTonemappingEnabled = true, isDeblurAndDenoisePhotoEnabled = true, isUpscalePhotoEnabled = false, ) // 1. Establish the session lazily on demand. A session is configured for // specific input dimensions, so replace it when the bitmap size changes. if (enhancementSession == null || sessionOptions?.width != options.width || sessionOptions?.height != options.height ) { enhancementSession?.release() enhancementSession = null enhancementSession = enhancementClient.createSessionAsync(options, enhancementExecutor) sessionOptions = options } val session = enhancementSession ?: throw IllegalStateException("Session unavailable.") // 2. Dispatch image through the neural pipeline. val enhancedBitmap = session.processBitmapAsync(bitmap, options) // 3. Render output to UI. _uiState.update { it.copy(enhancedImage = ImageInfo(bitmap = enhancedBitmap)) } } catch (e: Exception) { _uiState.update { it.copy(enhancementError = e.message) } } finally { // Ensure loading state is reset regardless of the outcome. _uiState.update { it.copy(isLoading = false) } } } } override fun onCleared() { // 4. Critical: Release native GPU hardware resources. enhancementSession?.release() enhancementSession = null enhancementExecutor.shutdown() super.onCleared() } }
Memuat gambar secara progresif di jaringan yang lambat
Di jaringan yang lambat, aplikasi Anda dapat mendownload versi gambar yang lebih kecil dan lebih dikompresi, bukan file resolusi penuh. Kemudian, aplikasi Anda dapat menggunakan mode Bitmap untuk melakukan peningkatan skala dan menghilangkan blur pada gambar di perangkat. Gambar yang ditingkatkan kualitasnya menggantikan download resolusi penuh, sehingga pengguna melihat gambar yang lebih tajam tanpa transfer file yang besar.
Kapan harus menggunakan pola ini
Pola ini cocok jika semua hal berikut terpenuhi:
- Perangkat didukung:
isDeviceSupportedAsync()menampilkantrue. API ini memerlukan Android 11 (API level 30) atau yang lebih tinggi dan dioptimalkan untuk perangkat tingkat premium. - Gambar ditampilkan lebih besar dari ukuran yang didownload: Misalnya, gambar kecil yang ditampilkan dalam layar penuh. Jika gambar tetap dalam ukuran thumbnail, upscaling tidak akan memberikan banyak manfaat yang terlihat.
- Modul peningkatan sudah diinstal:
isModuleInstalledAsync()menampilkantrue. Penginstalan modul mendownload file model melalui jaringan. Jika pengguna sudah menggunakan koneksi yang lambat, jangan mulai penginstalan.
Jika salah satu kondisi ini tidak terpenuhi, tampilkan gambar yang didownload tanpa peningkatan kualitas.
Menerapkan pola
Pola ini berfungsi sebagai berikut:
- Menampilkan gambar beresolusi rendah: Render gambar kecil segera setelah didownload.
- Sempurnakan di latar belakang: Jika mesin peningkatan kualitas sudah siap, proses gambar dalam mode Bitmap dengan mengaktifkan peningkatan skala dan penghilang blur.
- Tukar hasil: Ganti gambar yang ditampilkan dengan bitmap yang ditingkatkan. Cross-fade singkat membuat pertukaran menjadi kurang terlihat.
Class ProgressiveImageEnhancer berikut memproses satu gambar dalam satu waktu dan
menggunakan kembali satu sesi untuk gambar dengan ukuran yang sama. Jika peningkatan gagal,
enhance() akan menampilkan null sehingga aplikasi Anda terus menampilkan
gambar beresolusi rendah. Class ini menggunakan wrapper createSessionAsync dan
processBitmapAsync yang ditentukan dalam Membuat wrapper proses sesi dan bitmap.
Instal modul terlebih dahulu, seperti yang ditunjukkan dalam Melakukan inisialisasi mesin
peningkatan. Jika isDeviceSupportedAsync() dan isModuleInstalledAsync() menampilkan
true, panggil enhance().
class ProgressiveImageEnhancer( private val enhancementClient: EnhancementClient, private val executor: Executor, ) { // Callers can request enhancements concurrently, but they all share one // session, so process one image at a time. private val mutex = Mutex() private var session: EnhancementSession? = null private var sessionOptions: EnhancementOptions? = null // Enhancement is optional for this pattern, so return null instead of // throwing. The caller can keep the low-resolution image without extra // error handling. suspend fun enhance(lowResBitmap: Bitmap): Bitmap? = mutex.withLock { val options = EnhancementOptions( width = lowResBitmap.width, height = lowResBitmap.height, enhancementMode = EnhancementMode.BITMAP, isDeblurAndDenoisePhotoEnabled = true, isUpscalePhotoEnabled = true, ) try { getOrCreateSession(options).processBitmapAsync(lowResBitmap, options) } catch (e: CancellationException) { // A cancelled request (for example, the user scrolled away) isn't // an enhancement failure, so let the caller's scope handle it. throw e } catch (e: Exception) { null } } // Sessions are expensive to create and are configured for specific input // dimensions, so reuse the current one until the image size changes. private suspend fun getOrCreateSession(options: EnhancementOptions): EnhancementSession { val currentSession = session val currentOptions = sessionOptions if (currentSession != null && currentOptions != null && currentOptions.width == options.width && currentOptions.height == options.height ) { return currentSession } releaseSession() return enhancementClient.createSessionAsync(options, executor).also { session = it sessionOptions = options } } // A session holds GPU memory until it's released, so free it as soon as // the images it enhances are no longer on screen. Taking the lock first // waits for any in-progress enhancement, so a session that's still being // created isn't leaked. suspend fun release() = mutex.withLock { releaseSession() } private fun releaseSession() { session?.release() session = null sessionOptions = null } }
Saat Anda menggunakan pola ini, ikuti panduan berikut:
- Minta ukuran yang konsisten:
EnhancementSessionmenggunakan dimensi input tetap. Minta gambar beresolusi rendah dalam satu ukuran yang konsisten sehingga aplikasi Anda dapat menggunakan kembali satu sesi di seluruh gambar. - Menyimpan hasil yang ditingkatkan ke dalam cache: Simpan bitmap yang ditingkatkan dalam cache gambar agar aplikasi Anda tidak memproses gambar yang sama lagi. Jika Anda mengaktifkan upscaling, bitmap yang ditingkatkan akan lebih besar daripada bitmap input. Ukur cache Anda untuk bitmap yang lebih besar.