Entenda o ciclo de vida do aprimoramento de mídia no modo bitmap

A API Media Enhancement oferece uma solução de IA no dispositivo de baixa latência e que preserva a privacidade que aproveita a aceleração de hardware para oferecer melhorias de mídia de alta qualidade sem aumentar o tamanho do APK. Para mais informações, consulte Entenda os recursos de melhoria de mídia.

O modo Bitmap estático (EnhancementMode.BITMAP) foi projetado para processamento de imagens estáticas e decodificadas.

Operar no modo bitmap exige que o SO serializa dados de pixels não compactados e os copia da memória da CPU pelo barramento do sistema para a memória da GPU, retornando o frame processado por uma cópia inversa. Ele é otimizado para execução de um único frame e não é compatível com streaming de vídeo em tempo real.

Esse fluxo de trabalho envolve a criação de uma sessão, o processamento de um único bitmap com ela e o tratamento do resultado. Os exemplos de código das seções anteriores abordam esse caso de uso em detalhes.

  1. Configurar opções: crie um objeto EnhancementOptions e verifique se o enhancementMode está definido como EnhancementMode.BITMAP.
  2. Criar sessão: use o wrapper createSessionAsync que definimos antes para criar um EnhancementSession. Esse é um objeto pesado. Portanto, crie-o somente quando necessário.
  3. Processar imagem: chame a sessão, o bitmap de entrada e as opções desejadas.
  4. Processar resultado: a função de suspensão retorna um Bitmap novo e aprimorado em caso de sucesso ou gera uma exceção em caso de falha.
  5. Encerrar sessão: é fundamental chamar session.release() quando você terminar para liberar recursos de GPU.

O EnhancementSession é um objeto de contexto pesado que mantém um pipeline de memória persistente de GPU ou NPU. Ele aloca RAM de vídeo (VRAM) dedicada e processadores de sistema nativos. Para evitar vazamentos de memória graves e possíveis falhas de OutOfMemoryError, siga estes princípios de ciclo de vida:

  1. Instanciação lenta: não crie uma sessão até que o usuário inicie uma ação de melhoria.
  2. Reutilização estratégica: mantenha e reutilize uma única instância de sessão ao processar várias imagens com configurações idênticas (dimensões e opções ativadas).
  3. Desmontagem de comandos: invoque session.release() imediatamente quando as tarefas visuais forem concluídas para liberar recursos de hardware compartilhados.

Inicializar o mecanismo de melhoria

Esse método organiza uma verificação em duas etapas. Ele verifica se o hardware do dispositivo é compatível com a aceleração e garante que os módulos de aprendizado de máquina necessários estejam presentes.

Executar essa etapa como pré-requisito evita falhas de inicialização em tempo de execução ao validar recursos antes que o app tente processar mídia.

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

Criar wrappers de processo de sessão e bitmap

Use esses wrappers de corrotina do Kotlin para converter callbacks do cliente baseados em tarefas em funções de suspensão padrão, permitindo uma execução mais limpa e sequencial.

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

Executar o pipeline de bitmap em um ViewModel

Para integrar o pipeline de melhoria à arquitetura do aplicativo, use um ViewModel para gerenciar o ciclo de vida da sessão. Essa abordagem garante que os recursos de GPU pesados sejam liberados quando o ViewModel for limpo.

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