Sessões e solicitações de captura da câmera

Observação: esta página se refere ao pacote Camera2. A menos que seu app exija recursos específicos de baixo nível do Camera2, recomendamos o uso do CameraX. CameraX e Camera2 oferecem suporte ao Android 5.0 (nível 21 da API) e versões mais recentes.

Um único dispositivo Android pode ter várias câmeras. Cada câmera é um CameraDevice, e um CameraDevice pode gerar mais de um stream simultaneamente.

Um motivo para fazer isso é que um stream, frames de câmera sequenciais provenientes de um CameraDevice, é otimizado para uma tarefa específica, como exibir um visor, enquanto outros podem ser usados para tirar uma foto ou fazer uma gravação de vídeo. Os streams funcionam como pipelines paralelos que processam frames brutos que saem da câmera, um por vez:

Processamento de stream paralelo de frames brutos de um dispositivo de câmera em diferentes formatos de saída
Figura 1. Ilustração de Como criar um app de câmera universal (Google I/O '18)

O processamento paralelo sugere que pode haver limites de desempenho dependendo da capacidade de processamento disponível da CPU, GPU ou outro processador. Se um pipeline não conseguir acompanhar os frames recebidos, ele vai começar a descartá-los.

Cada pipeline tem o próprio formato de saída. Os dados brutos recebidos são transformados automaticamente no formato de saída adequado pela lógica implícita associada a cada pipeline. O CameraDevice usado nos exemplos de código desta página não é específico. Portanto, primeiro enumere todas as câmeras disponíveis antes de continuar.

Use o CameraDevice para criar um CameraCaptureSession, que é específico para esse CameraDevice. Um CameraDevice precisa receber uma configuração de frame para cada frame bruto usando o CameraCaptureSession. A configuração especifica atributos da câmera, como foco automático, abertura, efeitos e exposição. Devido a restrições de hardware, apenas uma configuração fica ativa no sensor da câmera por vez, chamada de configuração ativa.

No entanto, os casos de uso de stream melhoram e ampliam as formas anteriores de usar CameraDevice para sessões de captura de stream, o que permite otimizar o stream da câmera para seu caso de uso específico. Por exemplo, ele pode melhorar a duração da bateria ao otimizar videochamadas.

Um CameraCaptureSession descreve todos os pipelines possíveis vinculados ao CameraDevice. Depois que uma sessão é criada, não é possível adicionar ou remover pipelines. O CameraCaptureSession mantém uma fila de CaptureRequests, que se tornam a configuração ativa.

Um CaptureRequest adiciona uma configuração à fila e seleciona um, mais de um ou todos os pipelines disponíveis para receber um frame do CameraDevice. É possível enviar muitas solicitações de captura durante uma sessão de captura. Cada solicitação pode mudar a configuração ativa e o conjunto de pipelines de saída que recebem a imagem bruta.

Usar casos de uso de streaming para melhorar a performance

Os casos de uso de stream são uma maneira de melhorar o desempenho das sessões de captura da Camera2. Eles dão ao dispositivo de hardware mais informações para ajustar os parâmetros, o que oferece uma experiência de câmera melhor para sua tarefa específica.

Isso permite que o dispositivo otimize os pipelines de hardware e software da câmera com base nos cenários do usuário para cada stream. Para mais informações sobre casos de uso de streaming, consulte setStreamUseCase.

Os casos de uso de stream permitem especificar como um determinado stream da câmera é usado em mais detalhes, além de definir um modelo em CameraDevice.createCaptureRequest(). Isso permite que o hardware de detecção da câmera otimize parâmetros, como ajuste, modo do sensor ou configurações do sensor da câmera, com base em compensações de qualidade ou latência adequadas para casos de uso específicos.

Os casos de uso de streaming incluem:

  • DEFAULT: abrange todo o comportamento do aplicativo. Isso equivale a não definir nenhum caso de uso de stream.

  • PREVIEW: recomendado para o visor ou análise de imagens no app.

  • STILL_CAPTURE: otimizado para captura de alta qualidade e alta resolução, sem a expectativa de manter frame rates semelhantes aos da prévia.

  • VIDEO_RECORD: otimizado para captura de vídeo de alta qualidade, incluindo estabilização de imagem de alta qualidade, se houver suporte do dispositivo e se estiver ativado pelo aplicativo. Essa opção pode produzir frames de saída com um atraso substancial em relação ao tempo real, para permitir a estabilização de alta qualidade ou outro processamento.

  • VIDEO_CALL: recomendado para usos prolongados da câmera em que o consumo de energia é uma preocupação.

  • PREVIEW_VIDEO_STILL: recomendado para apps de mídia social ou casos de uso de stream único. É uma transmissão multiuso.

  • VENDOR_START: usado para casos de uso definidos pelo OEM.

Criar uma CameraCaptureSession

Para criar uma sessão de câmera, forneça um ou mais buffers de saída em que o app possa gravar frames de saída. Cada buffer representa um pipeline. Isso precisa ser feito antes de começar a usar a câmera para que o framework possa configurar os pipelines internos do dispositivo e alocar buffers de memória para enviar frames aos destinos de saída necessários.

O snippet de código a seguir mostra como preparar uma sessão de câmera com dois buffers de saída, um pertencente a um SurfaceView e outro a um ImageReader. Adicionar o caso de uso de stream PREVIEW a previewSurface e o caso de uso de stream STILL_CAPTURE a imReaderSurface permite que o hardware do dispositivo otimize ainda mais esses streams.

// Retrieve the target surfaces, which might be coming from a number of places:
// 1. SurfaceView, if you want to display the image directly to the user
// 2. ImageReader, if you want to read each frame or perform frame-by-frame
// analysis
// 3. OpenGL Texture or TextureView, although discouraged for maintainability
// reasons
// 4. RenderScript.Allocation, if you want to do parallel processing
val surfaceView = findViewById<SurfaceView>(
    // ...
)
val imageReader = ImageReader.newInstance(
    // ...
)

// Remember to call this only *after* SurfaceHolder.Callback.surfaceCreated().
val previewSurface = surfaceView.holder.surface
val imReaderSurface = imageReader.surface
val targets = listOf(previewSurface, imReaderSurface)

// Create a capture session using the predefined targets; this also involves
// defining the session state callback to be notified of when the session is
// ready.
// Setup Stream Use Case while setting up your Output Configuration.
@RequiresApi(Build.VERSION_CODES.TIRAMISU)
fun configureSession(device: CameraDevice, targets: List<Surface>) {
    val configs = mutableListOf<OutputConfiguration>()
    val streamUseCase = CameraMetadata
        .SCALER_AVAILABLE_STREAM_USE_CASES_PREVIEW_VIDEO_STILL

    targets.forEach {
        val config = OutputConfiguration(it)
        config.streamUseCase = streamUseCase.toLong()
        configs.add(config)
    }
    // ...
    device.createCaptureSession(session)
}

Até o momento, você não definiu a configuração ativa da câmera. Quando a sessão estiver configurada, você poderá criar e enviar solicitações de captura para fazer isso.

A transformação aplicada às entradas conforme elas são gravadas no buffer é determinada pelo tipo de cada destino, que precisa ser um Surface. O framework do Android sabe como converter uma imagem bruta na configuração ativa em um formato apropriado para cada destino. A conversão é controlada pelo formato de pixel e pelo tamanho do Surface específico.

O framework tenta fazer o melhor, mas algumas combinações de configuração do Surface podem não funcionar, causando problemas como a não criação da sessão, um erro de tempo de execução ao enviar uma solicitação ou degradação de desempenho. O framework oferece garantias para combinações específicas de parâmetros de dispositivo, superfície e solicitação. A documentação do createCaptureSession() fornece mais informações.

CaptureRequests únicos

A configuração usada para cada frame é codificada em um CaptureRequest, que é enviado para a câmera. Para criar uma solicitação de captura, use um dos modelos predefinidos ou use TEMPLATE_MANUAL para ter controle total. Ao escolher um modelo, é necessário fornecer um ou mais buffers de saída para serem usados com a solicitação. Só é possível usar buffers que já foram definidos na sessão de captura que você pretende usar.

As solicitações de captura usam um padrão de builder e dão aos desenvolvedores a oportunidade de definir muitas opções diferentes, incluindo exposição automática, foco automático e abertura da lente. Antes de definir um campo, verifique se a opção específica está disponível para o dispositivo chamando CameraCharacteristics.getAvailableCaptureRequestKeys() e se o valor escolhido é compatível, verificando a característica apropriada da câmera, como os modos de exposição automática disponíveis.

Para criar uma solicitação de captura para um SurfaceView usando o modelo projetado para visualização sem modificações, use CameraDevice.TEMPLATE_PREVIEW:

val session: CameraCaptureSession = /* ... */ // from CameraCaptureSession.StateCallback
val captureRequest = session.device.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW)
captureRequest.addTarget(previewSurface)

Com uma solicitação de captura definida, agora é possível enviá-la para a sessão da câmera:

val session: CameraCaptureSession = ...  // from CameraCaptureSession.StateCallback
val captureRequest: CaptureRequest.Builder = ...  // from CameraDevice.createCaptureRequest()

// The first null argument corresponds to the capture callback, which you
// provide if you want to retrieve frame metadata or keep track of failed capture
// requests that can indicate dropped frames; the second null argument
// corresponds to the Handler used by the asynchronous callback, which falls
// back to the current thread's looper if null.
session.capture(captureRequest.build(), null, null)

Quando um frame de saída é colocado no buffer específico, um callback de captura é acionado. Em muitos casos, callbacks adicionais, como ImageReader.OnImageAvailableListener, são acionados quando o frame que eles contêm é processado. Nesse momento, é possível recuperar dados de imagem do buffer especificado.

Repetir CaptureRequests

As solicitações de câmera única são fáceis de fazer, mas não são muito úteis para exibir uma prévia ao vivo ou um vídeo. Nesse caso, você precisa receber um stream contínuo de frames, não apenas um. O snippet de código a seguir mostra como adicionar uma solicitação repetida à sessão:

val session: CameraCaptureSession = ... // from CameraCaptureSession.StateCallback
val captureRequest: CaptureRequest.Builder = ... // from CameraDevice.createCaptureRequest()

// This keeps sending the capture request as frequently as possible until
// the session is torn down or session.stopRepeating() is called.
session.setRepeatingRequest(captureRequest.build(), null, null)

Uma solicitação de captura repetida faz com que o dispositivo de câmera capture imagens continuamente usando as configurações no CaptureRequest fornecido. A API Camera2 também permite que os usuários capturem vídeos da câmera enviando CaptureRequests repetidos, como visto neste repositório de exemplos da Camera2 no GitHub. Ela também pode renderizar vídeos em câmera lenta capturando um vídeo de alta velocidade (câmera lenta) usando a captura contínua repetida CaptureRequests, conforme mostrado no app de exemplo de vídeo em câmera lenta da Camera2 no GitHub.

Intercalar CaptureRequests

Para enviar uma segunda solicitação de captura enquanto a solicitação de captura repetida estiver ativa, como para exibir um visor e permitir que os usuários tirem uma foto, não é necessário interromper a solicitação repetida em andamento. Em vez disso, emita uma solicitação de captura não repetida enquanto a solicitação repetida continua em execução.

Qualquer buffer de saída usado precisa ser configurado como parte da sessão da câmera quando ela é criada. As solicitações repetidas têm prioridade menor do que as solicitações de frame único ou de burst, o que permite que o exemplo a seguir funcione:

val session: CameraCaptureSession = /* ... */ // from CameraCaptureSession.StateCallback

// Create the repeating request and dispatch it.
val repeatingRequest = session.device.createCaptureRequest(
    CameraDevice.TEMPLATE_PREVIEW
)
repeatingRequest.addTarget(previewSurface)
session.setRepeatingRequest(repeatingRequest.build(), null, null)

// Some time later...

// Create the single request and dispatch it.
// NOTE: This can disrupt the ongoing repeating request momentarily.
val singleRequest = session.device.createCaptureRequest(
    CameraDevice.TEMPLATE_STILL_CAPTURE
)
singleRequest.addTarget(imReaderSurface)
session.capture(singleRequest.build(), null, null)

No entanto, há uma desvantagem nessa abordagem: você não sabe exatamente quando a solicitação única ocorre. Na figura a seguir, se A for a solicitação de captura repetida e B for a solicitação de captura de frame único, é assim que a sessão processa a fila de solicitações:

Fila de solicitações de captura repetida ativa interrompida por uma única
       solicitação de captura
Figura 2. Ilustração de uma fila de solicitações para a sessão de câmera em andamento

Não há garantias para a latência entre a última solicitação repetida de A antes que a solicitação B seja ativada e a próxima vez que A for usada novamente. Portanto, talvez você veja alguns frames pulados. Há algumas coisas que você pode fazer para reduzir esse problema:

  • Adicione os destinos de saída da solicitação A à solicitação B. Dessa forma, quando o frame de B estiver pronto, ele será copiado para os destinos de saída de A. Por exemplo, isso é essencial ao fazer snapshots de vídeo para manter um frame rate estável. No código anterior, você adiciona singleRequest.addTarget(previewSurface) antes de criar a solicitação.

  • Use uma combinação de modelos projetados para funcionar nesse cenário específico, como o atraso zero do obturador.