Sessioni e richieste di acquisizione della videocamera

Nota: questa pagina fa riferimento al pacchetto Camera2. A meno che la tua app non richieda funzionalità specifiche di basso livello di Camera2, ti consigliamo di utilizzare CameraX. Sia CameraX che Camera2 supportano Android 5.0 (livello API 21) e versioni successive.

Un singolo dispositivo Android può avere più fotocamere. Ogni videocamera è un CameraDevice e un CameraDevice può produrre più di uno stream contemporaneamente.

Un motivo per farlo è che un flusso, ovvero i frame sequenziali della fotocamera provenienti da un CameraDevice, è ottimizzato per un'attività specifica, ad esempio la visualizzazione di un mirino, mentre altri potrebbero essere utilizzati per scattare una foto o registrare un video. Gli stream agiscono come pipeline parallele che elaborano i frame non elaborati provenienti dalla fotocamera, un frame alla volta:

Elaborazione dei flussi paralleli di frame non elaborati da un dispositivo con fotocamera in diversi formati di output
Figura 1. Illustrazione tratta da Building a Universal Camera App (Google I/O '18)

L'elaborazione parallela suggerisce che possono esserci limiti di prestazioni a seconda della potenza di elaborazione disponibile della CPU, della GPU o di un altro processore. Se una pipeline non riesce a tenere il passo con i frame in entrata, inizia a ignorarli.

Ogni pipeline ha il proprio formato di output. I dati non elaborati in entrata vengono trasformati automaticamente nel formato di output appropriato dalla logica implicita associata a ogni pipeline. Il valore CameraDevice utilizzato negli esempi di codice di questa pagina non è specifico, quindi devi prima enumerare tutte le fotocamere disponibili prima di procedere.

Puoi utilizzare CameraDevice per creare un CameraCaptureSession specifico per CameraDevice. Un CameraDevice deve ricevere una configurazione del frame per ogni frame non elaborato utilizzando CameraCaptureSession. La configurazione specifica gli attributi della fotocamera, come messa a fuoco automatica, apertura, effetti ed esposizione. A causa dei vincoli hardware, nel sensore della fotocamera è attiva una sola configurazione alla volta, chiamata configurazione attiva.

Tuttavia, i casi d'uso degli stream migliorano ed estendono i modi precedenti di utilizzare CameraDevice per acquisire sessioni di streaming, consentendoti di ottimizzare lo stream della videocamera per il tuo caso d'uso specifico. Ad esempio, può migliorare la durata della batteria durante l'ottimizzazione delle videochiamate.

Un CameraCaptureSession descrive tutte le possibili pipeline associate a CameraDevice. Una volta creata una sessione, non puoi aggiungere o rimuovere pipeline. CameraCaptureSession gestisce una coda di CaptureRequest, che diventano la configurazione attiva.

Un CaptureRequest aggiunge una configurazione alla coda e seleziona una, più di una o tutte le pipeline disponibili per ricevere un frame da CameraDevice. Puoi inviare molte richieste di acquisizione nel corso di una sessione di acquisizione. Ogni richiesta può modificare la configurazione attiva e l'insieme di pipeline di output che ricevono l'immagine non elaborata.

Utilizza i casi d'uso di Stream per migliorare il rendimento

I casi d'uso degli stream sono un modo per migliorare le prestazioni delle sessioni di acquisizione di Camera2. Forniscono al dispositivo hardware maggiori informazioni per ottimizzare i parametri, offrendo un'esperienza con la fotocamera migliore per la tua attività specifica.

In questo modo, il dispositivo con fotocamera può ottimizzare le pipeline hardware e software della fotocamera in base agli scenari utente per ogni stream. Per ulteriori informazioni sui casi d'uso degli stream, consulta setStreamUseCase.

I casi d'uso degli stream ti consentono di specificare in modo più dettagliato come viene utilizzato un determinato stream della videocamera, oltre a impostare un modello in CameraDevice.createCaptureRequest(). In questo modo, l'hardware della fotocamera può ottimizzare i parametri, come la regolazione, la modalità del sensore o le impostazioni del sensore della fotocamera, in base ai compromessi di qualità o latenza adatti a casi d'uso specifici.

I casi d'uso di Stream includono:

  • DEFAULT: copre tutto il comportamento dell'applicazione esistente. Equivale a non impostare alcun caso d'uso dello stream.

  • PREVIEW: consigliato per l'analisi delle immagini nel mirino o nell'app.

  • STILL_CAPTURE: ottimizzata per l'acquisizione ad alta risoluzione e di alta qualità, non è previsto che mantenga frequenze fotogrammi simili a quelle dell'anteprima.

  • VIDEO_RECORD: ottimizzata per l'acquisizione di video di alta qualità, inclusa la stabilizzazione dell'immagine di alta qualità, se supportata dal dispositivo e attivata dall'applicazione. Questa opzione potrebbe produrre frame di output con un ritardo sostanziale rispetto al tempo reale, per consentire una stabilizzazione o un'altra elaborazione di massima qualità.

  • VIDEO_CALL: consigliata per utilizzi della fotocamera di lunga durata in cui il consumo di energia è un problema.

  • PREVIEW_VIDEO_STILL: consigliato per app di social media o casi d'uso di stream singolo. È uno stream multiuso.

  • VENDOR_START: utilizzato per i casi d'uso definiti dall'OEM.

Crea una CameraCaptureSession

Per creare una sessione della fotocamera, fornisci uno o più buffer di output in cui la tua app può scrivere i frame di output. Ogni buffer rappresenta una pipeline. Devi farlo prima di iniziare a utilizzare la fotocamera, in modo che il framework possa configurare le pipeline interne del dispositivo e allocare i buffer di memoria per l'invio dei frame alle destinazioni di output necessarie.

Il seguente snippet di codice mostra come preparare una sessione della fotocamera con due buffer di output, uno appartenente a un SurfaceView e un altro a un ImageReader. L'aggiunta di PREVIEW Stream Use Case a previewSurface e STILL_CAPTURE Stream Use Case a imReaderSurface consente all'hardware del dispositivo di ottimizzare ulteriormente questi stream.

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

A questo punto, non hai definito la configurazione attiva della videocamera. Quando la sessione è configurata, puoi creare e inviare richieste di acquisizione per farlo.

La trasformazione applicata agli input quando vengono scritti nel buffer è determinata dal tipo di ogni target, che deve essere un Surface. Il framework Android sa come convertire un'immagine non elaborata nella configurazione attiva in un formato appropriato per ogni destinazione. La conversione è controllata dal formato dei pixel e dalle dimensioni del particolare Surface.

Il framework cerca di fare del suo meglio, ma alcune combinazioni di configurazione di Surface potrebbero non funzionare, causando problemi come la mancata creazione della sessione, la generazione di un errore di runtime durante l'invio di una richiesta o il peggioramento delle prestazioni. Il framework fornisce garanzie per combinazioni specifiche di parametri di dispositivo, piattaforma e richiesta. La documentazione di createCaptureSession() fornisce ulteriori informazioni.

Singole CaptureRequest

La configurazione utilizzata per ogni frame è codificata in un CaptureRequest, che viene inviato alla videocamera. Per creare una richiesta di acquisizione, puoi utilizzare uno dei template predefiniti oppure TEMPLATE_MANUAL per un controllo completo. Quando scegli un modello, devi fornire uno o più buffer di output da utilizzare con la richiesta. Puoi utilizzare solo i buffer già definiti nella sessione di acquisizione che intendi utilizzare.

Le richieste di acquisizione utilizzano un pattern builder e offrono agli sviluppatori l'opportunità di impostare molte opzioni diverse, tra cui esposizione automatica, messa a fuoco automatica e apertura dell'obiettivo. Prima di impostare un campo, assicurati che l'opzione specifica sia disponibile per il dispositivo chiamando CameraCharacteristics.getAvailableCaptureRequestKeys() e che il valore scelto sia supportato controllando la caratteristica della fotocamera appropriata, ad esempio le modalità di esposizione automatica disponibili.

Per creare una richiesta di acquisizione per un SurfaceView utilizzando il template progettato per l'anteprima senza modifiche, utilizza CameraDevice.TEMPLATE_PREVIEW:

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

Una volta definita una richiesta di acquisizione, puoi inviarla alla sessione della fotocamera:

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 un frame di output viene inserito nel buffer specifico, viene attivato un callback di acquisizione. In molti casi, vengono attivati callback aggiuntivi, come ImageReader.OnImageAvailableListener, quando viene elaborato il frame che contiene. È a questo punto che puoi recuperare i dati dell'immagine dal buffer specificato.

Ripeti CaptureRequest

Le richieste per una singola fotocamera sono semplici da eseguire, ma non sono molto utili per visualizzare un'anteprima in tempo reale o un video. In questo caso, devi ricevere un flusso continuo di frame, non solo uno. Il seguente snippet di codice mostra come aggiungere una richiesta ripetuta alla sessione:

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)

Una richiesta di acquisizione ripetuta fa sì che la fotocamera acquisisca continuamente immagini utilizzando le impostazioni nell'oggetto CaptureRequest fornito. L'API Camera2 consente inoltre agli utenti di acquisire video dalla fotocamera inviando CaptureRequests ripetuti, come mostrato in questo repository di esempi di Camera2 su GitHub. Può anche eseguire il rendering di video in slow motion acquisendo un video ad alta velocità (slow motion) utilizzando la sequenza ripetuta CaptureRequests, come mostrato nell'app di esempio di video in slow motion Camera2 su GitHub.

Interleave CaptureRequests

Per inviare una seconda richiesta di acquisizione mentre è attiva la richiesta di acquisizione ripetuta, ad esempio per visualizzare un mirino e consentire agli utenti di scattare una foto, non è necessario interrompere la richiesta ripetuta in corso. Invece, invii una richiesta di acquisizione non ripetuta mentre la richiesta ripetuta continua a essere eseguita.

Qualsiasi buffer di output utilizzato deve essere configurato come parte della sessione della fotocamera quando viene creata per la prima volta. Le richieste ripetute hanno una priorità inferiore rispetto alle richieste di singoli frame o di scatti, il che consente il funzionamento del seguente esempio:

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)

Tuttavia, questo approccio presenta uno svantaggio: non sai esattamente quando si verifica la singola richiesta. Nella figura seguente, se A è la richiesta di acquisizione ripetuta e B è la richiesta di acquisizione di un singolo frame, la sessione elabora la coda delle richieste nel seguente modo:

Coda di richieste di acquisizione ripetute attive interrotta da una singola richiesta di acquisizione
Figura 2. Illustrazione di una coda di richieste per la sessione della fotocamera in corso

Non esistono garanzie per la latenza tra l'ultima richiesta ripetuta da A prima che la richiesta B venga attivata e la volta successiva in cui A viene utilizzata di nuovo, pertanto potresti riscontrare alcuni frame saltati. Ecco alcune azioni che puoi intraprendere per mitigare questo problema:

  • Aggiungi i target di output dalla richiesta A alla richiesta B. In questo modo, quando il frame di B è pronto, viene copiato nei target di output di A. Ad esempio, questo è essenziale quando si eseguono istantanee video per mantenere una frequenza fotogrammi costante. Nel codice precedente, aggiungi singleRequest.addTarget(previewSurface) prima di creare la richiesta.

  • Utilizza una combinazione di modelli progettati per funzionare in questo particolare scenario, ad esempio zero-shutter-lag.