Media Enhancement API, sıfır APK şişmesiyle yüksek kaliteli medya iyileştirmeleri sunmak için donanım hızlandırmadan yararlanan, düşük gecikmeli, gizliliği korumaya yönelik, cihaz üzerinde yapay zeka çözümü sunar. Daha fazla bilgi için Medya iyileştirme özelliklerini anlama başlıklı makaleyi inceleyin.
Statik Bitmap modu (EnhancementMode.BITMAP), statik ve kodu çözülmüş görüntü işleme için tasarlanmıştır.
Bit eşlem modunda çalışmak için OS'nin sıkıştırılmamış piksel verilerini serileştirmesi ve CPU belleğinden sistem veri yolu üzerinden GPU belleğine kopyalaması, işlenen kareyi ters kopyalama yoluyla döndürmesi gerekir. Tek kare yürütme için optimize edilmiştir ve gerçek zamanlı video akışıyla uyumlu değildir.
Bu iş akışında bir oturum oluşturulur, tek bir bitmap işlenir ve ardından sonuç işlenir. Önceki bölümlerdeki kod örnekleri bu kullanım alanını ayrıntılı olarak ele almaktadır.
- Seçenekleri yapılandırın:
EnhancementOptionsnesnesi oluşturun veenhancementModedeğerininEnhancementMode.BITMAPolarak ayarlandığından emin olun. - Oturum oluşturma:
EnhancementSessionoluşturmak için daha önce tanımladığımızcreateSessionAsyncsarmalayıcısını kullanın. Bu ağır bir nesne olduğundan yalnızca gerektiğinde oluşturun. - Resmi işleme: Oturumu, giriş bit eşleminizi ve istediğiniz seçenekleri çağırın.
- Sonucu işleme: Askıya alma işlevi, başarılı olduğunda yeni ve geliştirilmiş bir bit eşlem döndürür, başarısız olduğunda ise istisna oluşturur.
- Oturumu serbest bırakma: GPU kaynaklarını serbest bırakmak için işiniz bittiğinde
session.release()yöntemini çağırmanız çok önemlidir.
EnhancementSession, kalıcı bir GPU veya NPU bellek ardışık düzeni sağlayan ağır bir bağlam nesnesidir. Özel video RAM'i (VRAM) ve yerel sistem tanıtıcıları tahsis eder. Ciddi bellek sızıntılarını ve olası kilitlenmeleri önlemek için
OutOfMemoryError aşağıdaki yaşam döngüsü ilkelerine uyun:
- Geç başlatma: Kullanıcı bir geliştirme işlemi başlatana kadar oturum oluşturmayın.
- Stratejik yeniden kullanım: Aynı yapılandırmalara (boyutlar ve açma/kapatma seçenekleri) sahip birden fazla resmi işlerken tek bir oturum örneğini koruyun ve yeniden kullanın.
- İstem sonlandırma: Paylaşılan donanım kaynaklarını serbest bırakmak için görsel görevler sonlandırıldığında
session.release()yöntemini hemen çağırın.
Geliştirme motorunu başlatma
Bu yöntem, iki adımlı bir kontrol gerçekleştirir. Cihazın donanımının hızlandırmayı destekleyip desteklemediğini doğrular ve ardından gerekli makine öğrenimi modüllerinin mevcut olduğundan emin olur.
Bu adımı ön koşul olarak çalıştırmak, uygulamanız medyayı işlemeye çalışmadan önce özellikleri doğrulayarak çalışma zamanı başlatma hatalarını önler.
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)
}
}
}
}
Oturum ve bit eşlem işlemi sarmalayıcıları oluşturma
Görev tabanlı istemci geri çağırmalarını standart askıya alma işlevlerine dönüştürmek için bu Kotlin eş yordam sarmalayıcılarını kullanın. Böylece daha temiz ve sıralı bir yürütme elde edebilirsiniz.
// 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) {}
}
this.process(bitmap, options, callback)
}
Bitmap ardışık düzenini ViewModel içinde yürütme
İyileştirme ardışık düzenini uygulama mimarinize entegre etmek için oturum yaşam döngüsünü yönetmek üzere ViewModel kullanın. Bu yaklaşım, ViewModel temizlendiğinde ağır GPU kaynaklarının serbest bırakılmasını sağlar.
// 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()
}
}
Yavaş ağlarda resimleri kademeli olarak yükleme
Yavaş ağlarda uygulamanız, tam çözünürlüklü dosya yerine resmin daha küçük ve daha sıkıştırılmış bir sürümünü indirebilir. Uygulamanız, cihazdaki görüntüyü ölçeklendirmek ve bulanıklığı gidermek için bit eşlem modunu kullanabilir. İyileştirilmiş resim, tam çözünürlüklü indirme işleminin yerini alır. Böylece kullanıcılar, büyük bir dosya aktarımı olmadan daha net bir resim görür.
Bu kalıbı ne zaman kullanmalısınız?
Bu kalıp, aşağıdakilerin tümü geçerli olduğunda uygundur:
- Cihaz destekleniyor:
isDeviceSupportedAsync(),truedeğerini döndürür. API, Android 11 (API düzeyi 30) veya sonraki sürümleri gerektirir ve premium katman cihazlar için optimize edilmiştir. - Resim, indirilen boyutundan daha büyük gösteriliyor: Örneğin, küçük bir resmin tam ekran gösterilmesi. Resim küçük resim boyutunda kalırsa ölçek büyütme, görünürde pek bir fayda sağlamaz.
- İyileştirme modülü zaten yüklü:
isModuleInstalledAsync()truedöndürür. Modül yükleme işlemi, model dosyalarını ağ üzerinden indirir. Kullanıcı zaten yavaş bir bağlantı kullanıyorsa yüklemeyi başlatmayın.
Bu koşullardan herhangi biri karşılanmazsa indirilen resmi iyileştirme olmadan gösterin.
Kalıbı uygulama
Kalıp şu şekilde çalışır:
- Düşük çözünürlüklü resmi görüntüleme: Küçük resmi indirilir indirilmez oluşturun.
- Arka planda iyileştirme: İyileştirme motoru hazırsa resmi, ölçek büyütme ve bulanıklık giderme özellikleri etkinleştirilmiş şekilde bit eşlem modunda işleyin.
- Sonucu değiştir: Görüntülenen resmi, iyileştirilmiş bitmap ile değiştirir. Kısa bir çapraz geçiş, değişimin daha az fark edilmesini sağlar.
Aşağıdaki ProgressiveImageEnhancer sınıfı, her seferinde bir resim işler ve aynı boyuttaki resimler için tek bir oturumu yeniden kullanır. İyileştirme başarısız olursa enhance(), null değerini döndürür. Böylece uygulamanız düşük çözünürlüklü resmi göstermeye devam eder. Sınıf, Oturum ve bit eşlem işlemi sarmalayıcıları oluşturma bölümünde tanımlanan createSessionAsync ve processBitmapAsync sarmalayıcılarını kullanır.
Geliştirme motorunu başlatma bölümünde gösterildiği gibi modülü önceden yükleyin. isDeviceSupportedAsync() ve isModuleInstalledAsync(), true döndürürse enhance() işlevini çağırın.
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
}
}
Bu kalıbı kullanırken aşağıdaki yönergeleri uygulayın:
- Tutarlı bir boyut isteyin:
EnhancementSession, sabit giriş boyutları kullanır. Uygulamanızın resimler arasında tek bir oturumu yeniden kullanabilmesi için düşük çözünürlüklü resimleri tek bir tutarlı boyutta isteyin. - Geliştirilmiş sonucu önbelleğe alma: Uygulamanızın aynı resmi tekrar işlememesi için geliştirilmiş bit eşlemi resim önbelleğinizde saklayın. Ölçek büyütmeyi etkinleştirirseniz geliştirilmiş bit eşlem, giriş bit eşleminden daha büyük olur. Önbelleğinizi daha büyük bitmap'ler için boyutlandırın.