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:
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:
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.