Observação:esta página se refere ao pacote Camera2. A menos que seu app exija recursos específicos e 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 aplicativo de câmera pode usar mais de um stream de frames simultaneamente. Em alguns casos, fluxos diferentes exigem até mesmo uma resolução de frame ou formato de pixel diferente. Veja alguns casos de uso comuns:
- Gravação de vídeo: um stream para visualização e outro sendo codificado e salvo em um arquivo.
- Leitura de código de barras: um stream para visualização e outro para detecção de código de barras.
- Fotografia computacional: um fluxo para visualização e outro para detecção facial/cena.
Há um custo de desempenho não trivial ao processar frames, e o custo é multiplicado ao fazer o processamento paralelo de stream ou pipeline.
Recursos como CPU, GPU e DSP podem aproveitar os recursos de reprocessamento do framework, mas outros recursos, como a memória, crescerão linearmente.
Vários destinos por solicitação
Vários streams de câmera podem ser combinados em um único
CameraCaptureRequest
.
O snippet de código a seguir ilustra como configurar uma sessão de câmera com um
stream para a visualização e outro para processamento de imagens:
Kotlin
val session: CameraCaptureSession = ... // from CameraCaptureSession.StateCallback // You will use the preview capture template for the combined streams // because it is optimized for low latency; for high-quality images, use // TEMPLATE_STILL_CAPTURE, and for a steady frame rate use TEMPLATE_RECORD val requestTemplate = CameraDevice.TEMPLATE_PREVIEW val combinedRequest = session.device.createCaptureRequest(requestTemplate) // Link the Surface targets with the combined request combinedRequest.addTarget(previewSurface) combinedRequest.addTarget(imReaderSurface) // In this simple case, the SurfaceView gets updated automatically. ImageReader // has its own callback that you have to listen to in order to retrieve the // frames so there is no need to set up a callback for the capture request session.setRepeatingRequest(combinedRequest.build(), null, null)
Java
CameraCaptureSession session = …; // from CameraCaptureSession.StateCallback // You will use the preview capture template for the combined streams // because it is optimized for low latency; for high-quality images, use // TEMPLATE_STILL_CAPTURE, and for a steady frame rate use TEMPLATE_RECORD CaptureRequest.Builder combinedRequest = session.getDevice().createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW); // Link the Surface targets with the combined request combinedRequest.addTarget(previewSurface); combinedRequest.addTarget(imReaderSurface); // In this simple case, the SurfaceView gets updated automatically. ImageReader // has its own callback that you have to listen to in order to retrieve the // frames so there is no need to set up a callback for the capture request session.setRepeatingRequest(combinedRequest.build(), null, null);
Se você configurar as superfícies de destino corretamente, esse código produzirá apenas
fluxos que atendam ao QPS mínimo determinado por
StreamComfigurationMap.GetOutputMinFrameDuration(int, Size)
e
StreamComfigurationMap.GetOutputStallDuration(int, Size)
.
O desempenho real varia de acordo com o dispositivo, embora o Android ofereça algumas
garantias para oferecer suporte a combinações específicas, dependendo de três variáveis:
tipo de saída, tamanho da saída e nível de hardware.
O uso de uma combinação incompatível de variáveis pode funcionar com um frame rate baixo.
Caso contrário, um dos callbacks de falha será acionado.
A documentação de createCaptureSession
descreve o que tem a garantia de funcionar.
Tipo de saída
O tipo de saída refere-se ao formato em que os frames são codificados. Os
valores possíveis são PRIV, YUV, JPEG e RAW. A documentação de
createCaptureSession
os descreve.
Ao escolher o tipo de saída do aplicativo, se o objetivo for maximizar
a compatibilidade, use
ImageFormat.YUV_420_888
para a análise de frames e
ImageFormat.JPEG
para imagens
estáticas. Para cenários de visualização e gravação, você provavelmente usará
SurfaceView
,
TextureView
,
MediaRecorder
,
MediaCodec
ou
RenderScript.Allocation
. Nesses
casos, não especifique um formato de imagem. Para compatibilidade, ele contará como
ImageFormat.PRIVATE
,
independente do formato real usado internamente. Para consultar os formatos com suporte
de um dispositivo considerando o
CameraCharacteristics
,
use o seguinte código:
Kotlin
val characteristics: CameraCharacteristics = ... val supportedFormats = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).outputFormats
Java
CameraCharacteristics characteristics = …; int[] supportedFormats = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP).getOutputFormats();
Tamanho da saída
Todos os tamanhos de saída disponíveis são listados por
StreamConfigurationMap.getOutputSizes()
,
mas apenas dois estão relacionados à compatibilidade: PREVIEW
e MAXIMUM
. Os tamanhos
atuam como limites superiores. Se algo do tamanho PREVIEW
funcionar, qualquer item com um
tamanho menor que PREVIEW
também funcionará. O mesmo acontece com MAXIMUM
. A
documentação de
CameraDevice
explica esses tamanhos.
Os tamanhos de saída disponíveis dependem da escolha do formato. Com o
CameraCharacteristics
e um formato, é possível consultar os tamanhos de saída disponíveis desta forma:
Kotlin
val characteristics: CameraCharacteristics = ... val outputFormat: Int = ... // such as ImageFormat.JPEG val sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(outputFormat)
Java
CameraCharacteristics characteristics = …; int outputFormat = …; // such as ImageFormat.JPEG Size[] sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(outputFormat);
Nos casos de uso de visualização e gravação da câmera, use a classe de destino para determinar os tamanhos com suporte. O formato será processado pelo próprio framework da câmera:
Kotlin
val characteristics: CameraCharacteristics = ... val targetClass: Class <T> = ... // such as SurfaceView::class.java val sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(targetClass)
Java
CameraCharacteristics characteristics = …; int outputFormat = …; // such as ImageFormat.JPEG Size[] sizes = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) .getOutputSizes(outputFormat);
Para conferir o tamanho de MAXIMUM
, classifique os tamanhos de saída por área e retorne o
maior:
Kotlin
fun <T>getMaximumOutputSize( characteristics: CameraCharacteristics, targetClass: Class <T>, format: Int? = null): Size { val config = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP) // If image format is provided, use it to determine supported sizes; or else use target class val allSizes = if (format == null) config.getOutputSizes(targetClass) else config.getOutputSizes(format) return allSizes.maxBy { it.height * it.width } }
Java
@RequiresApi(api = Build.VERSION_CODES.N) <T> Size getMaximumOutputSize(CameraCharacteristics characteristics, Class <T> targetClass, Integer format) { StreamConfigurationMap config = characteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP); // If image format is provided, use it to determine supported sizes; else use target class Size[] allSizes; if (format == null) { allSizes = config.getOutputSizes(targetClass); } else { allSizes = config.getOutputSizes(format); } return Arrays.stream(allSizes).max(Comparator.comparing(s -> s.getHeight() * s.getWidth())).get(); }
PREVIEW
refere-se à melhor correspondência de tamanho para a resolução de tela do dispositivo ou a
1080p (1920x1080), o que for menor. A proporção pode não corresponder exatamente
à da tela. Talvez seja necessário aplicar o efeito letterbox ou
o corte no stream para que ele seja mostrado no modo de tela cheia. Para ter o tamanho
correto da visualização, compare os tamanhos de saída disponíveis com o tamanho da tela,
considerando que a tela pode ser girada.
O código abaixo define uma classe auxiliar, SmartSize
, que facilita as comparações
de tamanho:
Kotlin
/** Helper class used to pre-compute shortest and longest sides of a [Size] */ class SmartSize(width: Int, height: Int) { var size = Size(width, height) var long = max(size.width, size.height) var short = min(size.width, size.height) override fun toString() = "SmartSize(${long}x${short})" } /** Standard High Definition size for pictures and video */ val SIZE_1080P: SmartSize = SmartSize(1920, 1080) /** Returns a [SmartSize] object for the given [Display] */ fun getDisplaySmartSize(display: Display): SmartSize { val outPoint = Point() display.getRealSize(outPoint) return SmartSize(outPoint.x, outPoint.y) } /** * Returns the largest available PREVIEW size. For more information, see: * https://d.android.com/reference/android/hardware/camera2/CameraDevice */ fun <T>getPreviewOutputSize( display: Display, characteristics: CameraCharacteristics, targetClass: Class <T>, format: Int? = null ): Size { // Find which is smaller: screen or 1080p val screenSize = getDisplaySmartSize(display) val hdScreen = screenSize.long >= SIZE_1080P.long || screenSize.short >= SIZE_1080P.short val maxSize = if (hdScreen) SIZE_1080P else screenSize // If image format is provided, use it to determine supported sizes; else use target class val config = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP)!! if (format == null) assert(StreamConfigurationMap.isOutputSupportedFor(targetClass)) else assert(config.isOutputSupportedFor(format)) val allSizes = if (format == null) config.getOutputSizes(targetClass) else config.getOutputSizes(format) // Get available sizes and sort them by area from largest to smallest val validSizes = allSizes .sortedWith(compareBy { it.height * it.width }) .map { SmartSize(it.width, it.height) }.reversed() // Then, get the largest output size that is smaller or equal than our max size return validSizes.first { it.long <= maxSize.long && it.short <= maxSize.short }.size }
Java
/** Helper class used to pre-compute shortest and longest sides of a [Size] */ class SmartSize { Size size; double longSize; double shortSize; public SmartSize(Integer width, Integer height) { size = new Size(width, height); longSize = max(size.getWidth(), size.getHeight()); shortSize = min(size.getWidth(), size.getHeight()); } @Override public String toString() { return String.format("SmartSize(%sx%s)", longSize, shortSize); } } /** Standard High Definition size for pictures and video */ SmartSize SIZE_1080P = new SmartSize(1920, 1080); /** Returns a [SmartSize] object for the given [Display] */ SmartSize getDisplaySmartSize(Display display) { Point outPoint = new Point(); display.getRealSize(outPoint); return new SmartSize(outPoint.x, outPoint.y); } /** * Returns the largest available PREVIEW size. For more information, see: * https://d.android.com/reference/android/hardware/camera2/CameraDevice */ @RequiresApi(api = Build.VERSION_CODES.N) <T> Size getPreviewOutputSize( Display display, CameraCharacteristics characteristics, Class <T> targetClass, Integer format ){ // Find which is smaller: screen or 1080p SmartSize screenSize = getDisplaySmartSize(display); boolean hdScreen = screenSize.longSize >= SIZE_1080P.longSize || screenSize.shortSize >= SIZE_1080P.shortSize; SmartSize maxSize; if (hdScreen) { maxSize = SIZE_1080P; } else { maxSize = screenSize; } // If image format is provided, use it to determine supported sizes; else use target class StreamConfigurationMap config = characteristics.get( CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP); if (format == null) assert(StreamConfigurationMap.isOutputSupportedFor(targetClass)); else assert(config.isOutputSupportedFor(format)); Size[] allSizes; if (format == null) { allSizes = config.getOutputSizes(targetClass); } else { allSizes = config.getOutputSizes(format); } // Get available sizes and sort them by area from largest to smallest List <Size> sortedSizes = Arrays.asList(allSizes); List <SmartSize> validSizes = sortedSizes.stream() .sorted(Comparator.comparing(s -> s.getHeight() * s.getWidth())) .map(s -> new SmartSize(s.getWidth(), s.getHeight())) .sorted(Collections.reverseOrder()).collect(Collectors.toList()); // Then, get the largest output size that is smaller or equal than our max size return validSizes.stream() .filter(s -> s.longSize <= maxSize.longSize && s.shortSize <= maxSize.shortSize) .findFirst().get().size; }
Verificar o nível de hardware suportado
Para determinar os recursos disponíveis no momento da execução, verifique o nível de hardware
com suporte usando
CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL
.
Com um objeto
CameraCharacteristics
, é possível recuperar o nível de hardware com uma única instrução:
Kotlin
val characteristics: CameraCharacteristics = ... // Hardware level will be one of: // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 val hardwareLevel = characteristics.get( CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL)
Java
CameraCharacteristics characteristics = ...; // Hardware level will be one of: // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL, // - CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3 Integer hardwareLevel = characteristics.get( CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL);
Unindo todas as peças
Com o tipo de saída, o tamanho da saída e o nível de hardware, é possível determinar quais
combinações de streams são válidas. O gráfico a seguir é um snapshot das
configurações compatíveis com um CameraDevice
com
nível de hardware
LEGACY
.
Objetivo 1 | Objetivo 2 | Objetivo 3 | Exemplos de casos de uso | |||
---|---|---|---|---|---|---|
Tipo | Tamanho máximo | Tipo | Tamanho máximo | Tipo | Tamanho máximo | |
PRIV |
MAXIMUM |
Visualização simples, processamento de vídeo por GPU ou gravação de vídeo sem visualização. | ||||
JPEG |
MAXIMUM |
Captura de imagem estática sem visor. | ||||
YUV |
MAXIMUM |
Processamento de vídeo/imagem no aplicativo. | ||||
PRIV |
PREVIEW |
JPEG |
MAXIMUM |
Imagem estática padrão. | ||
YUV |
PREVIEW |
JPEG |
MAXIMUM |
Processamento no app e captura estática. | ||
PRIV |
PREVIEW |
PRIV |
PREVIEW |
Gravação padrão. | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
Visualização e processamento no app. | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
Visualização e processamento no app. | ||
PRIV |
PREVIEW |
YUV |
PREVIEW |
JPEG |
MAXIMUM |
Captura estática e processamento no app. |
LEGACY
é o nível de hardware mais baixo possível. Esta tabela mostra que cada
dispositivo com suporte ao Camera2 (nível 21 da API e mais recentes) pode gerar até três
fluxos simultâneos usando a configuração correta e, se não houver muita
sobrecarga que limite o desempenho, como restrições de memória, CPU ou térmica.
Seu app também precisa configurar buffers de saída de segmentação. Por exemplo, para
direcionar a um dispositivo com nível de hardware LEGACY
, você pode configurar duas superfícies de saída
de destino, uma usando ImageFormat.PRIVATE
e outra usando
ImageFormat.YUV_420_888
. Essa é uma combinação compatível com o
tamanho PREVIEW
. Usando a função definida anteriormente neste tópico, para conseguir os
tamanhos de visualização necessários para um ID de câmera, é preciso usar o seguinte código:
Kotlin
val characteristics: CameraCharacteristics = ... val context = this as Context // assuming you are inside of an activity val surfaceViewSize = getPreviewOutputSize( context, characteristics, SurfaceView::class.java) val imageReaderSize = getPreviewOutputSize( context, characteristics, ImageReader::class.java, format = ImageFormat.YUV_420_888)
Java
CameraCharacteristics characteristics = ...; Context context = this; // assuming you are inside of an activity Size surfaceViewSize = getPreviewOutputSize( context, characteristics, SurfaceView.class); Size imageReaderSize = getPreviewOutputSize( context, characteristics, ImageReader.class, format = ImageFormat.YUV_420_888);
É necessário aguardar até que SurfaceView
esteja pronto usando os callbacks fornecidos:
Kotlin
val surfaceView = findViewById <SurfaceView>(...) surfaceView.holder.addCallback(object : SurfaceHolder.Callback { override fun surfaceCreated(holder: SurfaceHolder) { // You do not need to specify image format, and it will be considered of type PRIV // Surface is now ready and you could use it as an output target for CameraSession } ... })
Java
SurfaceView surfaceView = findViewById <SurfaceView>(...); surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() { @Override public void surfaceCreated(@NonNull SurfaceHolder surfaceHolder) { // You do not need to specify image format, and it will be considered of type PRIV // Surface is now ready and you could use it as an output target for CameraSession } ... });
É possível forçar o SurfaceView
a corresponder ao tamanho de saída da câmera chamando
SurfaceHolder.setFixedSize()
ou adotar uma abordagem semelhante a
AutoFitSurfaceView
do módulo
comum
das amostras de câmera no GitHub, que define um tamanho absoluto, considerando
a proporção e o espaço disponível, enquanto ajusta
automaticamente quando as mudanças de atividade são acionadas.
Configurar a outra plataforma de
ImageReader
com o formato desejado é
mais fácil, já que não há callbacks para esperar:
Kotlin
val frameBufferCount = 3 // just an example, depends on your usage of ImageReader val imageReader = ImageReader.newInstance( imageReaderSize.width, imageReaderSize.height, ImageFormat.YUV_420_888, frameBufferCount)
Java
int frameBufferCount = 3; // just an example, depends on your usage of ImageReader ImageReader imageReader = ImageReader.newInstance( imageReaderSize.width, imageReaderSize.height, ImageFormat.YUV_420_888, frameBufferCount);
Ao usar um buffer de destino de bloqueio, como ImageReader
, descarte os frames depois
de usá-los:
Kotlin
imageReader.setOnImageAvailableListener({ val frame = it.acquireNextImage() // Do something with "frame" here it.close() }, null)
Java
imageReader.setOnImageAvailableListener(listener -> { Image frame = listener.acquireNextImage(); // Do something with "frame" here listener.close(); }, null);
O nível de hardware LEGACY
é destinado aos dispositivos de menor denominador comum. É possível
adicionar ramificações condicionais e usar o tamanho RECORD
para uma das superfícies de destino
de saída em dispositivos com nível de hardware LIMITED
ou até mesmo aumentá-lo para
o tamanho MAXIMUM
para dispositivos com nível de hardware FULL
.