Lebenszyklus der Medienoptimierung im Bitmap-Modus

Die Media Enhancement API bietet eine datenschutzfreundliche On-Device-KI-Lösung mit niedriger Latenz, die Hardwarebeschleunigung nutzt, um hochwertige Medienverbesserungen ohne APK-Bloatware zu liefern. Weitere Informationen finden Sie unter Informationen zu den Funktionen zur Medienoptimierung.

Der statische Bitmap-Modus (EnhancementMode.BITMAP) ist für die Verarbeitung statischer, decodierter Bilder vorgesehen.

Im Bitmap-Modus muss das Betriebssystem unkomprimierte Pixeldaten serialisieren und vom CPU-Speicher über den Systembus in den GPU-Speicher kopieren. Der verarbeitete Frame wird dann über eine umgekehrte Kopie zurückgegeben. Es ist für die Ausführung einzelner Frames optimiert und nicht mit Echtzeit-Videostreaming kompatibel.

Dieser Workflow umfasst das Erstellen einer Sitzung, das Verarbeiten einer einzelnen Bitmap und das Verarbeiten des Ergebnisses. Die Codebeispiele aus den vorherigen Abschnitten decken diesen Anwendungsfall im Detail ab.

  1. Optionen konfigurieren: Erstellen Sie ein EnhancementOptions-Objekt und achten Sie darauf, dass enhancementMode auf EnhancementMode.BITMAP gesetzt ist.
  2. Sitzung erstellen: Verwenden Sie den zuvor definierten createSessionAsync-Wrapper, um eine EnhancementSession zu erstellen. Dies ist ein ressourcenintensives Objekt. Erstellen Sie es daher nur bei Bedarf.
  3. Bild verarbeiten: Rufen Sie die Sitzung, die Eingabe-Bitmap und die gewünschten Optionen auf.
  4. Ergebnis verarbeiten: Die Sperrfunktion gibt bei Erfolg eine neue, verbesserte Bitmap zurück oder löst bei einem Fehler eine Ausnahme aus.
  5. Sitzung freigeben: Rufen Sie unbedingt session.release() auf, wenn Sie fertig sind, um GPU-Ressourcen freizugeben.

Der EnhancementSession ist ein schwergewichtiges Kontextobjekt, das eine persistente GPU- oder NPU-Speicherpipeline verwaltet. Es weist dedizierten Video-RAM (VRAM) und native System-Handles zu. Halten Sie sich an die folgenden Lebenszyklusprinzipien, um schwerwiegende Speicherlecks und potenzielle OutOfMemoryError-Abstürze zu vermeiden:

  1. Lazy Instantiation: Erstellen Sie eine Sitzung erst, wenn der Nutzer eine Optimierungsaktion initiiert.
  2. Strategische Wiederverwendung: Behalten Sie eine einzelne Sitzungsinstanz bei und verwenden Sie sie wieder, wenn Sie mehrere Bilder mit identischen Konfigurationen (Abmessungen und Umschaltoptionen) verarbeiten.
  3. Prompt-Teardown: Rufen Sie session.release() sofort auf, wenn visuelle Aufgaben beendet werden, um freigegebene Hardwareressourcen freizugeben.

Optimierungs-Engine initialisieren

Diese Methode orchestriert eine zweistufige Prüfung. Es wird geprüft, ob die Hardware des Geräts die Beschleunigung unterstützt, und dann sichergestellt, dass die erforderlichen Module für maschinelles Lernen vorhanden sind.

Wenn Sie diesen Schritt als Voraussetzung ausführen, werden Fehler bei der Laufzeitinitialisierung vermieden, da die Funktionen validiert werden, bevor Ihre App versucht, Medien zu verarbeiten.

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

Sitzungs- und Bitmap-Prozess-Wrapper erstellen

Mit diesen Kotlin-Koroutinen-Wrappern können Sie aufgabenbasierte Client-Callbacks in standardmäßige aussetzbare Funktionen umwandeln, um eine sauberere und sequenzielle Ausführung zu ermöglichen.

// 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-Pipeline in einem ViewModel ausführen

Wenn Sie die Optimierungspipeline in Ihre Anwendungsarchitektur einbinden möchten, verwenden Sie eine ViewModel, um den Sitzungslebenszyklus zu verwalten. So wird sichergestellt, dass die rechenintensiven GPU-Ressourcen freigegeben werden, wenn der ViewModel gelöscht wird.

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

Bilder in langsamen Netzwerken progressiv laden

In langsamen Netzwerken kann Ihre App eine kleinere, stärker komprimierte Version eines Bildes anstelle der Datei mit voller Auflösung herunterladen. Ihre App kann dann den Bitmap-Modus verwenden, um das Bild auf dem Gerät hochzuskalieren und scharfzuzeichnen. Das optimierte Bild ersetzt den Download in voller Auflösung, sodass Nutzer ein schärferes Bild sehen, ohne dass eine große Datei übertragen werden muss.

Wann dieses Muster verwendet werden sollte

Dieses Muster eignet sich gut, wenn alle der folgenden Bedingungen erfüllt sind:

  • Das Gerät wird unterstützt: isDeviceSupportedAsync() gibt true zurück. Die API erfordert Android 11 (API-Level 30) oder höher und ist für Premium-Geräte optimiert.
  • Das Bild wird größer als seine heruntergeladene Größe angezeigt: z. B. ein kleines Bild im Vollbildmodus. Wenn das Bild in Thumbnail-Größe bleibt, bietet das Upscaling kaum sichtbare Vorteile.
  • Das Erweiterungsmodul ist bereits installiert: isModuleInstalledAsync() gibt true zurück. Bei der Modulinstallation werden Modelldateien über das Netzwerk heruntergeladen. Wenn der Nutzer bereits eine langsame Verbindung hat, starten Sie die Installation nicht.

Wenn eine dieser Bedingungen nicht erfüllt ist, wird das heruntergeladene Bild ohne Optimierung angezeigt.

Muster implementieren

Das Muster funktioniert so:

  1. Bild mit niedriger Auflösung anzeigen: Rendern Sie das kleine Bild, sobald es heruntergeladen wurde.
  2. Im Hintergrund optimieren: Wenn die Optimierungs-Engine bereit ist, wird das Bild im Bitmap-Modus mit aktiviertem Upscaling und aktivierter Unschärfekorrektur verarbeitet.
  3. Ergebnis einfügen: Das angezeigte Bild wird durch die optimierte Bitmap ersetzt. Eine kurze Überblendung macht den Wechsel weniger auffällig.

Die folgende ProgressiveImageEnhancer-Klasse verarbeitet jeweils ein Bild und verwendet eine einzelne Sitzung für Bilder derselben Größe wieder. Wenn die Optimierung fehlschlägt, gibt enhance() null zurück, sodass in Ihrer App weiterhin das Bild mit niedriger Auflösung angezeigt wird. Die Klasse verwendet die Wrapper createSessionAsync und processBitmapAsync, die unter Wrapper für Sitzungs- und Bitmap-Prozesse erstellen definiert sind.

Installieren Sie das Modul im Voraus, wie unter Optimierungs-Engine initialisieren beschrieben. Wenn isDeviceSupportedAsync() und isModuleInstalledAsync() den Wert true zurückgeben, rufen Sie enhance() auf.

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

Beachten Sie bei der Verwendung dieses Musters die folgenden Richtlinien:

  • Konsistente Größe anfordern: Ein EnhancementSession verwendet feste Eingabedimensionen. Fordern Sie Bilder mit niedriger Auflösung in einer einheitlichen Größe an, damit Ihre App eine einzelne Sitzung für mehrere Bilder wiederverwenden kann.
  • Optimiertes Ergebnis im Cache speichern: Speichern Sie die optimierte Bitmap im Bild-Cache, damit Ihre App dasselbe Bild nicht noch einmal verarbeitet. Wenn Sie die Hochskalierung aktivieren, ist die optimierte Bitmap größer als die Eingabe-Bitmap. Passen Sie die Größe des Cache für die größeren Bitmaps an.