Comprendre le cycle de vie de l'amélioration du contenu multimédia en mode Bitmap

L'API Media Enhancement fournit une solution d'IA sur l'appareil à faible latence et protégeant la confidentialité, qui exploite l'accélération matérielle pour offrir des améliorations multimédias de haute qualité sans alourdir l'APK. Pour en savoir plus, consultez Comprendre les fonctionnalités d'amélioration des contenus multimédias.

Le mode Bitmap statique (EnhancementMode.BITMAP) est conçu pour le traitement d'images statiques décodées.

Pour fonctionner en mode Bitmap, l'OS doit sérialiser les données de pixels non compressées et les copier de la mémoire du processeur vers la mémoire du GPU via le bus système, puis renvoyer le cadre traité via une copie inverse. Il est optimisé pour l'exécution d'une seule image et n'est pas compatible avec le streaming vidéo en temps réel.

Ce workflow implique de créer une session, de traiter un seul bitmap avec celle-ci, puis de gérer le résultat. Les exemples de code des sections précédentes couvrent ce cas d'utilisation en détail.

  1. Configurer les options : créez un objet EnhancementOptions en vous assurant que enhancementMode est défini sur EnhancementMode.BITMAP.
  2. Créer une session : utilisez le wrapper createSessionAsync que nous avons défini précédemment pour créer un EnhancementSession. Il s'agit d'un objet lourd. Ne le créez donc que lorsque cela est nécessaire.
  3. Traiter l'image : appelez la session, votre bitmap d'entrée et les options de votre choix.
  4. Gérer le résultat : la fonction de suspension renvoie un nouveau bitmap amélioré en cas de réussite ou génère une exception en cas d'échec.
  5. Libérer la session : il est essentiel d'appeler session.release() lorsque vous avez terminé pour libérer les ressources GPU.

EnhancementSession est un objet de contexte lourd qui gère un pipeline de mémoire GPU ou NPU persistant. Il alloue de la RAM vidéo (VRAM) dédiée et des handles système natifs. Pour éviter les fuites de mémoire graves et les plantages potentiels de OutOfMemoryError, respectez les principes de cycle de vie suivants :

  1. Instanciation différée : ne créez pas de session tant que l'utilisateur n'a pas lancé d'action d'amélioration.
  2. Réutilisation stratégique : conservez et réutilisez une seule instance de session lorsque vous traitez plusieurs images avec des configurations identiques (dimensions et options d'activation/de désactivation).
  3. Démontage de la requête : appelez immédiatement session.release() lorsque les tâches visuelles se terminent pour libérer les ressources matérielles partagées.

Initialiser le moteur d'amélioration

Cette méthode orchestre une vérification en deux étapes. Il vérifie si le matériel de l'appareil est compatible avec l'accélération, puis s'assure que les modules de machine learning requis sont présents.

L'exécution de cette étape préalable permet d'éviter les échecs d'initialisation de l'environnement d'exécution en validant les fonctionnalités avant que votre application ne tente de traiter les contenus multimédias.

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)
            }
        }
    }
}

Créer des wrappers de processus de session et de bitmap

Utilisez ces wrappers de coroutines Kotlin pour convertir les rappels client basés sur des tâches en fonctions de suspension standards, ce qui permet une exécution plus propre et séquentielle.

// 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)
}

Exécuter le pipeline de bitmap dans un ViewModel

Pour intégrer le pipeline d'amélioration à l'architecture de votre application, utilisez un ViewModel pour gérer le cycle de vie de la session. Cette approche garantit que les ressources GPU lourdes sont libérées lorsque ViewModel est effacé.

// 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()
    }
}

Charger les images progressivement sur les réseaux lents

Sur les réseaux lents, votre application peut télécharger une version plus petite et plus compressée d'une image au lieu du fichier en résolution maximale. Votre application peut ensuite utiliser le mode Bitmap pour améliorer la résolution et la netteté de l'image sur l'appareil. L'image améliorée remplace le téléchargement en résolution maximale. Les utilisateurs voient ainsi une image plus nette sans transfert de fichier volumineux.

Quand utiliser ce modèle

Ce modèle est adapté lorsque toutes les conditions suivantes sont remplies :

  • L'appareil est compatible : isDeviceSupportedAsync() renvoie true. L'API nécessite Android 11 (niveau d'API 30) ou version ultérieure, et est optimisée pour les appareils de niveau premium.
  • L'image est affichée dans une taille supérieure à celle de son téléchargement : par exemple, une petite image affichée en plein écran. Si l'image reste à la taille d'une vignette, l'upscaling n'apporte que peu d'avantages visibles.
  • Le module d'amélioration est déjà installé : isModuleInstalledAsync() renvoie true. L'installation du module télécharge les fichiers de modèle sur le réseau. Si l'utilisateur dispose déjà d'une connexion lente, ne lancez pas l'installation.

Si l'une de ces conditions n'est pas remplie, affichez l'image téléchargée sans amélioration.

Implémenter le modèle

Le modèle fonctionne comme suit :

  1. Afficher l'image basse résolution : affichez la petite image dès qu'elle est téléchargée.
  2. Améliorer en arrière-plan : si le moteur d'amélioration est prêt, traitez l'image en mode Bitmap avec l'upscaling et le défloutage activés.
  3. Remplacer par le résultat : remplacez l'image affichée par le bitmap amélioré. Un fondu enchaîné court rend le changement moins visible.

La classe ProgressiveImageEnhancer suivante traite une image à la fois et réutilise une seule session pour les images de même taille. Si l'amélioration échoue, enhance() renvoie null afin que votre application continue d'afficher l'image basse résolution. La classe utilise les wrappers createSessionAsync et processBitmapAsync définis dans Créer des wrappers de processus de session et de bitmap.

Installez le module à l'avance, comme indiqué dans Initialiser le moteur d'amélioration. Si isDeviceSupportedAsync() et isModuleInstalledAsync() renvoient true, appelez 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
    }
}

Lorsque vous utilisez ce modèle, suivez ces consignes :

  • Demander une taille cohérente : un EnhancementSession utilise des dimensions d'entrée fixes. Demandez des images basse résolution d'une taille cohérente afin que votre application puisse réutiliser une seule session pour toutes les images.
  • Mettre en cache le résultat amélioré : stockez le bitmap amélioré dans le cache d'images afin que votre application ne traite pas à nouveau la même image. Si vous activez l'upscaling, le bitmap amélioré est plus grand que le bitmap d'entrée. Dimensionnez votre cache pour les bitmaps plus volumineux.