Cykl życia ulepszania multimediów w trybie mapy bitowej

Interfejs Media Enhancement API to rozwiązanie AI na urządzeniu, które zapewnia niskie opóźnienia i chroni prywatność. Wykorzystuje ono akcelerację sprzętową, aby zapewniać wysokiej jakości ulepszenia multimediów bez zwiększania rozmiaru pliku APK. Więcej informacji znajdziesz w artykule Funkcje ulepszania multimediów.

Tryb statycznej bitmapy (EnhancementMode.BITMAP) jest przeznaczony do przetwarzania statycznych, zdekodowanych obrazów.

Działanie w trybie mapy bitowej wymaga od systemu operacyjnego serializacji nieskompresowanych danych pikseli i skopiowania ich z pamięci procesora przez magistralę systemową do pamięci GPU, a następnie zwrócenia przetworzonej klatki przez kopię odwrotną. Jest zoptymalizowany pod kątem wykonywania pojedynczych klatek i nie jest zgodny ze strumieniowym przesyłaniem wideo w czasie rzeczywistym.

Ten przepływ pracy obejmuje utworzenie sesji, przetworzenie za jej pomocą pojedynczej bitmapy, a następnie obsłużenie wyniku. Przykłady kodu z poprzednich sekcji szczegółowo opisują ten przypadek użycia.

  1. Skonfiguruj opcje: utwórz obiekt EnhancementOptions, upewniając się, że właściwość enhancementMode jest ustawiona na EnhancementMode.BITMAP.
  2. Utworzenie sesji: użyj zdefiniowanego wcześniej kodu towarzyszącego createSessionAsync, aby utworzyć EnhancementSession. Jest to obiekt o dużym rozmiarze, więc twórz go tylko wtedy, gdy jest to konieczne.
  3. Przetwarzanie obrazu: wywołaj sesję, wejściową bitmapę i wybrane opcje.
  4. Obsługa wyniku: funkcja zawieszenia zwraca nową, ulepszoną bitmapę w przypadku powodzenia lub zgłasza wyjątek w przypadku niepowodzenia.
  5. Zwalnianie sesji: po zakończeniu pracy wywołaj funkcję session.release(), aby zwolnić zasoby GPU.

EnhancementSession to obiekt kontekstu o dużej wadze, który utrzymuje trwały potok pamięci GPU lub NPU. Przydziela dedykowaną pamięć RAM wideo (VRAM) i natywne uchwyty systemowe. Aby zapobiec poważnym wyciekom pamięci i potencjalnym awariom OutOfMemoryError, przestrzegaj tych zasad cyklu życia:

  1. Leniwa instancjacja: nie twórz sesji, dopóki użytkownik nie zainicjuje działania ulepszającego.
  2. Strategiczne ponowne użycie: utrzymuj i ponownie używaj pojedynczej instancji sesji podczas przetwarzania wielu obrazów o identycznych konfiguracjach (wymiarach i przełączanych opcjach).
  3. Natychmiastowe wyłączenie: wywołaj session.release() natychmiast po zakończeniu zadań wizualnych, aby zwolnić współdzielone zasoby sprzętowe.

Inicjowanie mechanizmu ulepszania

Ta metoda przeprowadza dwuetapową weryfikację. Sprawdza, czy sprzęt urządzenia obsługuje akcelerację, a następnie upewnia się, że są dostępne wymagane moduły uczenia maszynowego.

Uruchomienie tego kroku jako wstępnego zapobiega błędom inicjowania środowiska wykonawczego, ponieważ możliwości są sprawdzane, zanim aplikacja spróbuje przetworzyć multimedia.

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

Tworzenie kodu opakowującego sesję i proces bitmapy

Użyj tych kodów opakowujących współprogramów Kotlin, aby przekonwertować wywołania zwrotne klienta oparte na zadaniach na standardowe funkcje zawieszania, co umożliwi czystsze i sekwencyjne wykonywanie.

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

Wykonaj potok bitmapy w ViewModel

Aby zintegrować potok ulepszania z architekturą aplikacji, użyj ViewModel do zarządzania cyklem życia sesji. Dzięki temu zasoby GPU są zwalniane po wyczyszczeniu ViewModel.

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

Stopniowe ładowanie obrazów w wolnych sieciach

W wolnych sieciach aplikacja może pobrać mniejszą, bardziej skompresowaną wersję obrazu zamiast pliku w pełnej rozdzielczości. Aplikacja może następnie użyć trybu bitmapy, aby przeskalować i wyostrzyć obraz na urządzeniu. Ulepszony obraz zastępuje pobierany obraz w pełnej rozdzielczości, dzięki czemu użytkownicy widzą ostrzejszy obraz bez konieczności przesyłania dużego pliku.

Kiedy używać tego wzorca

Ten wzorzec jest odpowiedni, gdy spełnione są wszystkie te warunki:

  • Urządzenie jest obsługiwane: isDeviceSupportedAsync() zwraca true. Interfejs API wymaga Androida 11 (poziom API 30) lub nowszego i jest zoptymalizowany pod kątem urządzeń z abonamentem Premium.
  • Obraz jest wyświetlany w rozmiarze większym niż rozmiar pobranego pliku: na przykład mały obraz jest wyświetlany na pełnym ekranie. Jeśli obraz pozostanie w rozmiarze miniatury, skalowanie w górę nie przyniesie widocznych korzyści.
  • Moduł ulepszeń jest już zainstalowany: isModuleInstalledAsync() zwraca true. Instalacja modułu powoduje pobranie plików modelu przez sieć. Jeśli użytkownik ma już wolne połączenie, nie rozpoczynaj instalacji.

Jeśli którykolwiek z tych warunków nie jest spełniony, wyświetl pobrany obraz bez ulepszeń.

Wdrażanie wzorca

Wzorzec działa w ten sposób:

  1. Wyświetlanie obrazu o niskiej rozdzielczości: wyrenderuj mały obraz, gdy tylko zostanie pobrany.
  2. Ulepszanie w tle: jeśli silnik ulepszania jest gotowy, przetwórz obraz w trybie bitmapy z włączonym skalowaniem i usuwaniem rozmycia.
  3. Zamień na wynik: zastąp wyświetlany obraz ulepszoną bitmapą. Krótkie przenikanie sprawia, że zmiana jest mniej zauważalna.

Ta klasa ProgressiveImageEnhancer przetwarza po jednym obrazie naraz i ponownie używa jednej sesji w przypadku obrazów o tym samym rozmiarze. Jeśli ulepszenie się nie powiedzie, enhance() zwraca null, aby aplikacja nadal wyświetlała obraz o niskiej rozdzielczości. Klasa używa obiektów opakowujących createSessionAsync i processBitmapAsync zdefiniowanych w sekcji Tworzenie obiektów opakowujących sesji i procesu bitmapy.

Zainstaluj moduł z wyprzedzeniem, jak pokazano w sekcji Inicjowanie mechanizmu ulepszania. Jeśli isDeviceSupportedAsync() i isModuleInstalledAsync() zwracają true, wywołaj 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
    }
}

Podczas korzystania z tego wzorca postępuj zgodnie z tymi wskazówkami:

  • Żądaj stałego rozmiaru: EnhancementSession używa stałych wymiarów wejściowych. Żądaj obrazów o niskiej rozdzielczości w jednym spójnym rozmiarze, aby aplikacja mogła ponownie używać jednej sesji w przypadku różnych obrazów.
  • Zapisz ulepszony wynik w pamięci podręcznej: zapisz ulepszoną bitmapę w pamięci podręcznej obrazów, aby aplikacja nie przetwarzała ponownie tego samego obrazu. Jeśli włączysz skalowanie, ulepszona bitmapa będzie większa niż bitmapa wejściowa. Dostosuj rozmiar pamięci podręcznej do większych bitmap.