Usar simultaneamente várias transmissões de 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 aplicativo de câmera pode usar mais de um stream de frames simultaneamente. Em alguns casos, streams diferentes exigem até mesmo uma resolução de frame ou um formato de pixel diferente. Veja alguns casos de uso comuns:

  • Gravação de vídeo: um stream para visualização, 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 stream para visualização, outro para detecção de rosto ou 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 recursos como memória crescem linearmente.

Vários destinos por solicitação

Vários streams da câmera podem ser combinados em um único CameraCaptureRequest. O snippet de código abaixo ilustra como configurar uma sessão de câmera com um stream para visualização da câmera 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 basic 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 basic 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 vai produzir apenas streams que atendam ao FPS mínimo determinado por StreamComfigurationMap.GetOutputMinFrameDuration(int, Size) e StreamComfigurationMap.GetOutputStallDuration(int, Size). O desempenho real varia de acordo com o dispositivo, mas o Android oferece algumas garantias de 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 em uma taxa de frames baixa. Se isso não acontecer, um dos callbacks de falha será acionado. A documentação do createCaptureSession descreve o que é garantido que funcione.

Tipo de saída

Tipo de saída se refere 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 descreve esses métodos.

Ao escolher o tipo de saída do aplicativo, se o objetivo for maximizar a compatibilidade, use ImageFormat.YUV_420_888 para análise de frames e ImageFormat.JPEG para imagens estáticas. Para cenários de visualização e gravação, é provável que você use um SurfaceView, TextureView, MediaRecorder, MediaCodec ou RenderScript.Allocation. Nesses casos, não especifique um formato de imagem. Para fins de compatibilidade, ele será contado como ImageFormat.PRIVATE, independentemente do formato real usado internamente. Para consultar os formatos compatíveis com um dispositivo de acordo com 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 de tamanho PREVIEW funcionar, qualquer coisa com um tamanho menor que PREVIEW também vai funcionar. O mesmo acontece com MAXIMUM. A documentação de CameraDevice explica esses tamanhos.

Os tamanhos de saída disponíveis dependem do formato escolhido. Considerando 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 compatíveis. 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 conseguir 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 se refere ao melhor tamanho correspondente à resolução da tela do dispositivo ou a 1080p (1920x1080), o que for menor. A proporção pode não corresponder exatamente à proporção da tela. Portanto, talvez seja necessário aplicar letterbox ou cortar o stream para que ele seja exibido no modo de tela cheia. Para conseguir o tamanho de visualização correto, compare os tamanhos de saída disponíveis com o tamanho da tela, considerando que a tela pode ser girada.

O código a seguir define uma classe auxiliar, SmartSize, que facilita um pouco 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 compatível

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

Juntando 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 resumo das configurações compatíveis com um CameraDevice com nível de hardware LEGACY.

Meta 1 Target 2 Meta 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 de fotos.
PRIV PREVIEW PRIV PREVIEW Gravação padrão.
PRIV PREVIEW YUV PREVIEW Pré-lançamento com processamento no app.
PRIV PREVIEW YUV PREVIEW JPEG MAXIMUM Captura de imagem estática e processamento no app.

LEGACY é o nível de hardware mais baixo possível. Essa tabela mostra que todos os dispositivos compatíveis com a Camera2 (nível 21 da API e versões mais recentes) podem gerar até três streams simultâneos usando a configuração certa e se não houver muita sobrecarga  limitando o desempenho, como restrições de memória, CPU ou térmicas.

O app também precisa configurar buffers de saída de segmentação. Por exemplo, para segmentar um dispositivo com o nível de hardware LEGACY, configure 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 ao usar o tamanho PREVIEW. Usando a função definida anteriormente neste documento, 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 a 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 dos exemplos de câmera no GitHub, que define um tamanho absoluto, considerando a proporção e o espaço disponível, enquanto se ajusta automaticamente quando as mudanças de atividade são acionadas.

Configurar a outra superfície de ImageReader com o formato escolhido é mais fácil, já que não há callbacks para aguardar:

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 é voltado para os dispositivos com o mínimo denominador comum. É possível adicionar ramificação condicional 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 aumentar para o tamanho MAXIMUM em dispositivos com nível de hardware FULL.