Cykl życia ulepszania multimediów w trybie mapy bitowej

Interfejs Media Enhancement API udostępnia rozwiązanie AI działające na urządzeniu, które zapewnia niskie opóźnienie i chroni prywatność. Wykorzystuje ono akcelerację sprzętową, aby poprawiać jakość multimediów bez zwiększania rozmiaru pliku APK. Więcej informacji znajdziesz w artykule Omówienie funkcji ulepszania multimediów.

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

Działanie w trybie bitmapy wymaga, aby system operacyjny serializował nieskompresowane dane pikseli i kopiował je z pamięci procesora przez magistralę systemową do pamięci GPU, a następnie zwracał przetworzoną klatkę za pomocą kopii odwrotnej. Jest on zoptymalizowany pod kątem wykonywania pojedynczych klatek i nie jest zgodny ze strumieniowaniem wideo w czasie rzeczywistym.

Ten proces obejmuje utworzenie sesji, przetworzenie za jej pomocą pojedynczej bitmapy, a następnie obsługę 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 enhancementMode jest ustawiony na EnhancementMode.BITMAP.
  2. Utwórz sesję: użyj zdefiniowanego wcześniej otoki createSessionAsync, aby utworzyć EnhancementSession. Jest to obiekt o dużej wadze, więc twórz go tylko wtedy, gdy jest to konieczne.
  3. Przetwarzaj obraz: wywołaj sesję, wejściową bitmapę i wybrane opcje.
  4. Obsłuż wynik: funkcja zawieszenia zwraca nową, ulepszoną bitmapę w przypadku powodzenia lub zgłasza wyjątek w przypadku niepowodzenia.
  5. Zakończ sesję: po zakończeniu pracy koniecznie wywołaj session.release(), aby zwolnić zasoby GPU.

Obiekt EnhancementSession to kontekstowy obiekt o dużej wadze, który utrzymuje trwały potok pamięci GPU lub NPU. Przydziela on 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. Opóźnione tworzenie instancji: 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łączonych opcjach).
  3. Szybkie zamykanie: natychmiast wywołaj session.release(), gdy zadania wizualne zostaną zakończone, aby zwolnić współdzielone zasoby sprzętowe.

Inicjowanie silnika ulepszania

Ta metoda koordynuje 2-etapowe sprawdzanie. Sprawdza, czy sprzęt urządzenia obsługuje akcelerację, a następnie upewnia się, że są dostępne wymagane moduły uczenia maszynowego.

Uruchomienie tej metody jako kroku wstępnego zapobiega błędom inicjowania w czasie działania, ponieważ sprawdza możliwości przed próbą przetworzenia multimediów przez aplikację.

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

Tworzenie otok do sesji i przetwarzania bitmap

Użyj tych otok do współprogramów Kotlin, aby przekształcić wywołania zwrotne klienta oparte na zadaniach w standardowe funkcje zawieszające, 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.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)
}

Wykonywanie potoku bitmap w ViewModel

Aby zintegrować potok ulepszania z architekturą aplikacji, użyj ViewModel do zarządzania cyklem życia sesji. Dzięki temu ciężkie zasoby GPU zostaną zwolnione, gdy ViewModel zostanie wyczyszczony.

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

// 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 {
                // 1. Establish the session lazily on demand

// Define enhancement options (for example, enable upscale, tonemapping) based
// on bitmap dimensions.
                if (enhancementSession == null) {
                    val options = EnhancementOptions(
                        bitmap.width,
                        bitmap.height,
                        EnhancementMode.BITMAP,
                        enableTonemap = true,
                        enableDeblurDenoise = true,
                        enableDenoiseOnly = false,
                        enableUpscale = false,
                    )
                    enhancementSession = enhancementClient.createSessionAsync(options, enhancementExecutor)
                }
                val session = enhancementSession ?: throw IllegalStateException("Session unavailable.")
                // 2. Dispatch image through the neural pipeline
                val enhancedBitmap = session.processBitmapAsync(bitmap, session.defaultOptions)
                // 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()
    }
}