Estensioni per fotocamere

I produttori di dispositivi possono mostrare estensioni quali bokeh, modalità notturna e HDR agli sviluppatori di terze parti tramite l'interfaccia delle estensioni della fotocamera fornita dalla libreria dei fornitori OEM. Gli sviluppatori possono utilizzare l'API Camera2 Extensions e l'API CameraX Extensions per accedere alle estensioni implementate nella libreria del fornitore OEM.

Per un elenco delle estensioni supportate, che è lo stesso per Camera2 e CameraX, consulta l'API CameraX Extensions. Se vuoi aggiungere un'estensione, invia un bug tramite il tracker dei problemi.

Questa pagina descrive come implementare e attivare la raccolta di fornitori OEM sui dispositivi.

Architettura

Il seguente diagramma descrive l'architettura dell'interfaccia di Camera Extensions o extensions-interface:

Figura 1. Diagramma dell'architettura di Estensioni videocamera

Come mostrato nel diagramma, per supportare le Estensioni della fotocamera, devi implementare il extensions-interface fornito dalla libreria del fornitore OEM. La libreria del fornitore OEM abilita due API: l'API CameraX Extensions e l'API Camera2 Extensions, che vengono utilizzate rispettivamente dalle app CameraX e Camera2 per accedere alle estensioni del fornitore.

Implementa la libreria del fornitore OEM

Per implementare la libreria del fornitore OEM, copia i file camera-extensions-stub in un progetto di libreria di sistema. Questi file definiscono l'interfaccia di Camera Extensions.

I file camera-extensions-stub sono suddivisi nelle seguenti categorie:

File di interfaccia essenziali (non modificare)

• PreviewExtenderImpl.java
• ImageCaptureExtenderImpl.java
• ExtenderStateListener.java
• ProcessorImpl.java
• PreviewImageProcessorImpl.java
• CaptureProcessorImpl.java
• CaptureStageImpl.java
• RequestUpdateProcessorImpl.java
• ProcessResultImpl.java
• advanced/AdvancedExtenderImpl.java
• advanced/Camera2OutputConfigImpl.java
• advanced/Camera2SessionConfigImpl.java
• advanced/ImageProcessorImpl.java
• advanced/ImageReaderOutputConfigImpl.java
• advanced/ImageReferenceImpl.java
• advanced/MultiResolutionImageReaderOutputConfigImpl.java
• advanced/OutputSurfaceImpl.java
• advanced/RequestProcessorImpl.java
• advanced/SessionProcessorImpl.java
• advanced/SurfaceOutputConfigImpl.java

Implementazioni obbligatorie (aggiungi la tua implementazione)

• ExtensionVersionImpl.java
• InitializerImpl.java

Classi di estensioni Bokeh (implementale se l'estensione Bokeh è supportata)

• BokehImageCaptureExtenderImpl.java
• BokehPreviewExtenderImpl.java
• advanced/BokehAdvancedExtenderImpl.java

Classi di extender notturno (implementa se l'estensione Notte è supportata)

• NightImageCaptureExtenderImpl.java
• NightPreviewExtenderImpl.java
• advanced/NightAdvancedExtenderImpl.java

Classi di estensioni automatiche (implementale se l'estensione automatica è supportata)

• AutoImageCaptureExtenderImpl.java
• AutoPreviewExtenderImpl.java
• advanced/AutoAdvancedExtenderImpl.java

Classi di estensioni HDR (implementale se l'estensione HDR è supportata)

• HdrImageCaptureExtenderImpl.java
• HdrPreviewExtenderImpl.java
• advanced/HdrAdvancedExtenderImpl.java

Classi di estensioni di Ritocco viso (implementale se l'estensione è supportata)

• BeautyImageCaptureExtenderImpl.java
• BeautyPreviewExtenderImpl.java
• advanced/BeautyAdvancedExtenderImpl.java

Utilità (facoltative, possono essere eliminate)

• advanced/Camera2OutputConfigImplBuilder.java
• advanced/Camera2SessionConfigImplBuilder.java

Non è necessario fornire un'implementazione per ogni estensione. Se non implementi un'estensione, imposta isExtensionAvailable() in modo da restituire false o rimuovi le classi Extender corrispondenti. Le API Camera2 e CameraX Extensions segnalano all'app che l'estensione non è disponibile.

Vediamo come le API Camera2 ed Extensions di CameraX interagiscono con la libreria del fornitore per attivare un'estensione. Il seguente diagramma illustra il flusso end-to-end utilizzando l'estensione Notte come esempio:

Figura 2. Implementazione dell'estensione Notte

1. Verifica della versione:

   Camera2/X chiama ExtensionVersionImpl.checkApiVersion() per assicurarsi che la versione di ExtensionVersionImpl.checkApiVersion() implementata dall'OEM sia compatibile con le versioni supportate da Camera2/X.extensions-interface

2. Inizializzazione della raccolta del fornitore:

   InitializerImpl ha un metodo init() che inizializza la libreria del fornitore. Camera2/X completa l'inizializzazione prima di accedere alle classi Extender.

3. Esegui l'inizializzazione delle classi Extender:

   Crea un'istanza per le classi Extender per l'estensione. Esistono due tipi di estensori: di base e avanzato. Devi implementare un tipo di Extender per tutte le estensioni. Per saperne di più, consulta la sezione Estensore di base ed estensore avanzato.

   Camera2/X esegue l'inizializzazione e interagisce con le classi Extender per recuperare informazioni e attivare l'estensione. Per una determinata estensione, Camera2/X può eseguire l'inizializzazione delle classi Extender più volte. Di conseguenza, non eseguire l'inizializzazione di operazioni complesse nel costruttore o nella chiamata a init(). Svolgere il lavoro più impegnativo solo quando la sessione della videocamera sta per iniziare, ad esempio quando viene chiamato onInit() in Basic Extender o initSession() in Advanced Extender.

   Per l'estensione Notte, vengono create le seguenti classi di Extender per il tipo di Extender di base:

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   E per il tipo di ripetitore avanzato:

   • NightAdvancedExtenderImpl.java

4. Verifica la disponibilità dell'estensione:

   Prima di abilitare l'estensione, isExtensionAvailable() controlla se l'estensione è disponibile sull'ID fotocamera specificato tramite l'istanza dell'estensione.

5. Inizializza l'extender con le informazioni della fotocamera:

   Camera2/X chiama init() sull'istanza Extender e gli passa l'ID camera e CameraCharacteristics.

6. Informazioni sulla query:

   Chiama la classe Extender per recuperare informazioni come le risoluzioni supportate, acquisire comunque la latenza stimata e le chiavi di richiesta dell'estensione in preparazione all'abilitazione dell'estensione.

7. Attiva l'estensione sull'extender:

   La classe Extender fornisce tutte le interfacce necessarie per attivare la classe. Offre un meccanismo per collegare l'implementazione OEM alla pipeline Camera2, ad esempio l'inserimento di parametri di richiesta di acquisizione o l'attivazione di un post-processor.

   Per il tipo di plug-in avanzato, Camera2/X interagisce conSessionProcessorImpl per attivare l'estensione. Camera2/X recupera l'istanza SessionProcessorImpl chiamando createSessionProcessor() sull'estensore.

Le sezioni seguenti descrivono il flusso di estensione in maggiore dettaglio.

Verifica della versione

Quando carica la libreria del fornitore OEM dal dispositivo in fase di esecuzione, Camera2/X verifica se la libreria è compatibile con la versione extensions-interface. extensions-interface utilizza il controllo delle versioni semantico o MAJOR.MINOR.PATCH, ad esempio 1.1.0 o 1.2.0. Tuttavia, durante la verifica della versione vengono utilizzate solo le versioni principali e secondarie.

Per verificare la versione, Camera2/X chiama ExtensionVersionImpl.checkApiVersion() con la versione supportata extensions-interface. Camera2/X utilizza quindi la versione segnalata dalla libreria OEM per determinare se l'estensione può essere attivata e quali funzionalità deve richiamare.

Compatibilità con le versioni principali

Se le versioni principali dell'interfaccia di estensione sono diverse tra Camera2/X e la libreria del fornitore, l'estensione è considerata incompatibile e viene disattivata.

Compatibilità con le versioni precedenti

Finché la versione principale è identica, Camera2/X garantisce la compatibilità con le versioni precedenti delle librerie dei fornitori OEM create con le versioni extensions-interface precedenti. Ad esempio, se Camera2/X supportaextensions-interface 1.3.0, le librerie del fornitore OEM che hanno implementato 1.0.0, 1.1.0 e 1.2.0 sono ancora compatibili. Ciò significa anche che dopo aver implementato una versione specifica della libreria del fornitore, Camera2/X verifica che la libreria sia compatibile con le versioni precedenti di extension-interface.

Compatibilità con le versioni future

La compatibilità con le librerie dei fornitori di extensions-interface più recenti dipende da te, l'OEM. Se hai bisogno di alcune funzionalità per implementare le estensioni, potresti attivarle a partire da una determinata versione. In questo caso, puoi restituire la versione extensions-interface supportata quando la versione della libreria Camera2/X soddisfa i requisiti. Se le versioni Camera2/X non sono supportate, puoi restituire una versione incompatibile come 99.0.0 per disattivare le estensioni.

Inizializzazione della libreria del fornitore

Dopo aver verificato la versione extensions-interface implementata dalla biblioteca OEM, Camera2/X avvia la procedura di inizializzazione. Il metodo InitializerImpl.init() indica alla libreria OEM che un'app sta tentando di utilizzare le estensioni.

Camera2/X non effettua altre chiamate alla libreria OEM (a parte il controllo della versione) fino a quando la libreria del fornitore OEM non chiama OnExtensionsInitializedCallback.onSuccess() per notificare il completamento dell'inizializzazione.

Devi implementare InitializerImpl a partire dalla versione extensions-interface 1.1.0. Camera2/X salta il passaggio di inizializzazione della libreria se la libreria del fornitore OEM implementa extensions-interface 1.0.0.

Estensore di base ed estensore avanzato

Esistono due tipi di implementazione di extensions-interface: estensore di base ed estensore avanzato. L'estensore avanzato è supportato dalla versioneextensions-interface 1.2.0.

Implementa l'estensore di base per le estensioni che elaborano le immagini nell'HAL della fotocamera o utilizza un post-processore in grado di elaborare stream YUV.

Implementa l'estensore avanzato per le estensioni che devono personalizzare la configurazione dello stream Camera2 e inviare richieste di acquisizione in base alle esigenze.

Consulta la seguente tabella per il confronto:

Flussi di app

La tabella seguente mostra tre tipi di flussi di app e le relative chiamate all'API Camera Extensions. Sebbene Camera2/X fornisca queste API, devi implementare correttamente la libreria del fornitore per supportare questi flussi, che descriveremo più dettagliatamente in una sezione successiva.

Estensore di base

L'interfaccia di Base Extender fornisce hook in diversi punti della pipeline della videocamera. Ogni tipo di estensione ha classi di estensione corrispondenti che gli OEM devono implementare.

La seguente tabella elenca le classi di estensioni che gli OEM devono implementare per ogni estensione:

Nell'esempio seguente utilizziamo PreviewExtenderImpl e ImageCaptureExtenderImpl come segnaposto. Sostituiscili con i nomi dei file effettivi che stai implementando.

L'estensore di base ha le seguenti funzionalità:

• Inserisci i parametri di sessione durante la configurazione di CameraCaptureSession ( onPresetSession).
• Ti invia una notifica relativa agli eventi di inizio e chiusura della sessione di acquisizione e invia una singola richiesta per notificare l'HAL con i parametri restituiti (onEnableSession, onDisableSession).
• Inserisci i parametri di acquisizione per la richiesta (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• Aggiungi processori per l'anteprima e la cattura che siano in grado di elaborare YUV_420_888 stream.

Vediamo come Camera2/X richiama extensions-interface per realizzare i tre flussi di app sopra menzionati.

Flusso di app 1: verifica la disponibilità dell'estensione

Figura 3. Flusso di app 1 su Basic Extender

In questo flusso, Camera2/X chiama direttamente il metodo isExtensionAvailable() di entrambi PreviewExtenderImpl e ImageCaptureExtenderImpl senza chiamare init(). Entrambi i tipi di estensore devono restituire true per attivare le estensioni.

Spesso questo è il primo passaggio per le app per verificare se il tipo di estensione specificato è supportato per un determinato ID videocamera prima di attivarlo. Questo perché alcune estensioni sono supportate solo su determinati ID videocamera.

Flusso dell'app 2: informazioni sulle query

Figura 4. Flusso di app 2 su Base Extender

Dopo aver stabilito se l'estensione è disponibile, le app devono eseguire query sulle seguenti informazioni prima di attivarla.

• Intervallo di latenza di acquisizione di foto: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange restituisce l'intervallo di la latenza di acquisizione per consentire all'app di valutare se è opportuno attivare l'estensione per lo scenario corrente.

• Dimensioni supportate per l'area di anteprima e di acquisizione: ImageCaptureExtenderImpl.getSupportedResolutions e PreviewExtenderImpl.getSupportedResolutions restituiscono un elenco di formati di immagine e le dimensioni supportate per il formato e le dimensioni dell'area.

• Chiavi di richiesta e di risultato supportate: Camera2/X richiama i seguenti metodi per recuperare le chiavi di richiesta di acquisizione e le chiavi di risultato supportate dalla tua implementazione:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X chiama sempre prima init() in queste classi di Extender prima di eseguire query per ulteriori informazioni.

Flusso dell'app 3: anteprima/acquisizione di foto con l'estensione abilitata (implementazione HAL)

Figura 5. Flusso di app 3 sull'extender di base

Il diagramma riportato sopra illustra il flusso principale per attivare l'anteprima e acquisire comunque un'estensione senza alcun processore. Ciò significa che l'HAL della fotocamera elabora l'estensione.

In questo flusso, Camera2/X chiama prima init() e poi onInit, che ti avvisa che sta per iniziare una sessione della videocamera con le estensioni specificate. Puoi eseguire l'inizializzazione complessa in onInit().

Durante la configurazione di CameraCaptureSession, Camera2/X invoca onPresetSession per ottenere i parametri della sessione. Dopo che la sessione di acquisizione è stata configurata correttamente, Camera2/X richiama onEnableSession restituendo un'istanza di CaptureStageImpl contenente i parametri di acquisizione. Camera2/X invia immediatamente una singola richiesta con questi parametri di acquisizione per notificare l'HAL. Analogamente, prima della chiusura della sessione di acquisizione, Camera2/X invoca onDisableSession e poi invia una singola richiesta con i parametri di acquisizione restituito.

La richiesta ripetuta attivata da Camera2/X contiene i parametri della richiesta restituito da PreviewExtenderImpl.getCaptureStage(). Inoltre, la richiesta di acquisizione di foto contiene i parametri restituiti da ImageCaptureExtenderImpl.getCaptureStages().

Infine, Camera2/X richiama onDeInit() al termine della sessione della videocamera. Puoi svincolare le risorse in onDeinit().

Processore di anteprima

Oltre all'HAL della fotocamera, puoi anche implementare estensioni in un processore.

Implementa PreviewExtenderImpl.getProcessorType per specificare il tipo di processore come spiegato di seguito:

• PROCESSOR_TYPE_NONE: nessun elaboratore. Le immagini vengono elaborate nell'HAL della fotocamera.

• PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: il tipo di elaboratore ti consente di aggiornare la richiesta ripetuta con nuovi parametri di richiesta di acquisizione in base all'TotalCaptureResult più recente.

  PreviewExtenderImpl.getProcessor deve restituire un'istanza RequestUpdateProcessorImpl che elabora l'istanza TotalCaptureResult e restituisce un'istanza CaptureStageImpl per aggiornare la richiesta ripetuta. PreviewExtenderImpl.getCaptureStage() dovrebbe anche riflettere il risultato dell'elaborazione e restituire l'elemento CaptureStageImpl più recente.

• PROCESSOR_TYPE_IMAGE_PROCESSOR: questo tipo consente di implementare un processore per elaborare le immagini YUV_420_888 e scrivere l'output in una piattaforma PRIVATE.

  Devi implementare e restituire un'istanza di PreviewImageProcessorImpl in PreviewExtenderImpl.getProcessor. Il responsabile è responsabile dell'elaborazione delle immagini di input YUV_420_888. L'output deve essere scritto nel formato PRIVATE dell'anteprima. Camera2/X utilizza una superficie YUV_420_888 anziché PRIVATE per configurare CameraCaptureSession per l'anteprima.

  Per il flusso, consulta l'illustrazione seguente:

Figura 6. Visualizza l'anteprima del flusso con PreviewImageProcessorImpl

L'interfaccia di PreviewImageProcessorImpl estende ProcessImpl e prevede tre metodi importanti:

• onOutputSurface(Surface surface, int imageFormat) imposta la superficie di output per il processore. Per PreviewImageProcessorImpl, imageFormat è un formato pixel come PixelFormat.RGBA_8888.

• onResolutionUpdate(Size size) imposta le dimensioni dell'immagine di input.

• onImageFormatUpdate(int imageFormat) imposta il formato dell'immagine di input. Al momento, può essere solo YUV_420_888.

Processore per l'acquisizione di immagini

Per l'acquisizione di foto, puoi implementare un'elaborazione restituendo un'istanza CaptureProcessorImpl utilizzando ImageCaptureExtenderImpl.getCaptureProcessor. Il responsabile è incaricato di elaborare un elenco di immagini e istanze YUV_420_888 acquisite e di scrivere l'output su una piattaforma YUV_420_888.TotalCaptureResult

Puoi presumere che l'anteprima sia attivata ed eseguita prima di inviare la richiesta di acquisizione di foto.

Guarda il flusso nel diagramma seguente:

Figura 7. Continuare a acquisire il flusso con CaptureProcessorImpl

1. Camera2/X utilizza una superficie di formato YUV_420_888 per l'acquisizione di foto per configurare la sessione di acquisizione. Camera2/X prepara CaptureProcessorImpl chiamando:

   • CaptureProcessorImpl.onImageFormatUpdate() con YUV_420_888.
   • CaptureProcessorImpl.onResolutionUpdate() con le dimensioni dell'immagine di input.
   • CaptureProcessorImpl.onOutputSurface() con una superficie YUV_420_888 di output.

2. ImageCaptureExtenderImpl.getCaptureStages restituisce un elenco di CaptureStageImpl , in cui ogni elemento corrisponde a un'istanza di CaptureRequest con parametri di acquisizione inviati da Camera2/X. Ad esempio, se restituisce un elenco di tre istanze CaptureStageImpl, Camera2/X invia tre richieste di acquisizione con i parametri di acquisizione corrispondenti utilizzando l'API captureBurst.

3. Le immagini e le istanze TotalCaptureResult ricevute vengono raggruppate e inviate a CaptureProcessorImpl per l'elaborazione.

4. CaptureProcessorImpl scrive l'immagine risultato (formato YUV_420_888) nella superficie di output specificata dalla chiamata onOutputSurface(). Camera2/X le converte in immagini JPEG, se necessario.

Supporta le chiavi e i risultati delle richieste di acquisizione

Oltre a consentire l'anteprima e lo scatto della fotocamera, le app possono impostare lo zoom, i parametri del flash o attivare un tocco per mettere a fuoco. Questi parametri potrebbero non essere compatibili con l'implementazione dell'estensione.

I seguenti metodi sono stati aggiunti a extensions-interface 1.3.0 per consentirti di esporre i parametri supportati dalla tua implementazione:

• ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() restituisce le chiavi di richiesta di acquisizione supportate dalla tua implementazione.
• ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() restituisce le chiavi del risultato dell'acquisizione contenute nel risultato dell'acquisizione.

Se l'HAL della fotocamera elabora l'estensione, Camera2/X recupera i risultati di acquisizione in CameraCaptureSession.CaptureCallback. Tuttavia, se il processore è implementato, Camera2/X recupera i risultati di acquisizione in ProcessResultImpl, che vengono passati al metodo process() in PreviewImageProcessorImpl e CaptureProcessorImpl. È tua responsabilità segnalare il risultato dell'acquisizione tramite ProcessResultImpl a Camera2/X.

Consulta la definizione dell'interfaccia CaptureProcessorImpl di seguito come esempio. In extensions-interface 1.3.0 o versioni successive, viene invocata la seconda chiamata process():

Interface CaptureProcessorImpl extends ProcessorImpl {
    // invoked when extensions-interface version < 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results);
    // invoked when extensions-interface version >= 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results,
            ProcessResultImpl resultCallback, Executor executor);
}

Per le operazioni comuni della fotocamera come zoom, tocco per mettere a fuoco, flash e compensazione dell'esposizione, consigliamo di supportare le seguenti chiavi sia per la richiesta di acquisizione sia per il risultato di acquisizione:

• Zoom:
  • CaptureRequest#CONTROL_ZOOM_RATIO
  • CaptureRequest#SCALER_CROP_REGION
• Tocca per mettere a fuoco:
  • CaptureRequest#CONTROL_AF_MODE
  • CaptureRequest#CONTROL_AF_TRIGGER
  • CaptureRequest#CONTROL_AF_REGIONS
  • CaptureRequest#CONTROL_AE_REGIONS
  • CaptureRequest#CONTROL_AWB_REGIONS
• Flash:
  • CaptureRequest#CONTROL_AE_MODE
  • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
  • CaptureRequest#FLASH_MODE
• Compensazione dell'esposizione:
  • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Per gli estensori di base che implementano la versione 1.2.0 o precedenti, l'API CameraX Extensions supporta esplicitamente tutte le chiavi sopra indicate. Per extensions-interface 1.3.0, sia CameraX che Camera2 rispettano l'elenco restituito e supportano solo le chiavi in esso contenute. Ad esempio, se decidi di restituire solo CaptureRequest#CONTROL_ZOOM_RATIO e CaptureRequest#SCALER_CROP_REGION nell'implementazione 1.3.0, significa che solo lo zoom è supportato per l'app, mentre il tocco per mettere a fuoco, il flash e la compensazione dell'esposizione non sono consentiti.

Estensore avanzato

Advanced Extender è un tipo di implementazione del fornitore basata sull'API Camera2. Questo tipo di Extender è stato aggiunto in extensions-interface 1.2.0. A seconda del produttore del dispositivo, le estensioni potrebbero essere implementate nel livello dell'app, il che dipende dai seguenti fattori:

• Configurazione di stream personalizzati: configura stream personalizzati come lo stream RAW o più stream per ID videocamera fisici diversi.

• Possibilità di inviare richieste Camera2: supporta una logica di interazione complessa che può inviare richieste di acquisizione con parametri in base ai risultati delle richieste precedenti.

Advanced Extender fornisce un wrapper o un livello intermedio, in modo da poter personalizzare la configurazione dello stream e inviare richieste di acquisizione on demand.

File da implementare

Per passare all'implementazione dell'estensione avanzata, il metodo isAdvancedExtenderImplemented() in ExtensionVersionImpl deve restituire true. Per ogni tipo di estensione, gli OEM devono implementare le classi Extender corrispondenti. I file di implementazione di Advanced Extender si trovano nel pacchetto advanced.

Nell'esempio seguente utilizziamo AdvancedExtenderImpl come segnaposto. Sostituiscilo con il nome del file extender dell'estensione che stai implementando.

Vediamo come Camera2/X richiama extensions-interface per ottenere i tre flussi di app.

Flusso dell'app 1: verifica la disponibilità delle estensioni

Figura 8. Flusso di app 1 su Advanced Extender

Innanzitutto, l'app controlla se l'estensione specificata è supportata.

Flusso dell'app 2: informazioni sulle query

Figura 9. Flusso di app 2 su Advanced Extender

Dopo aver chiamato AdvancedExtenderImpl.init(), l'app può eseguire query sulle seguenti informazioni su AdvancedExtenderImpl:

• Latenza stimata di acquisizione di foto: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() restituisce l'intervallo della latenza di acquisizione per consentire all'app di valutare se è opportuno attivare l'estensione per lo scenario attuale.

• Risoluzioni supportate per l'anteprima e l'acquisizione di foto:

  • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() restituisce una mappa del formato dell'immagine all'elenco delle dimensioni supportate per il formato e le dimensioni della superficie di anteprima. Gli OEM devono supportare almeno il formato PRIVATE.

  • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() restituisce il formato e le dimensioni supportati per l'area di acquisizione di immagini. Gli OEM devono supportare sia l'output in formato JPEG sia quello in formato YUV_420_888.

  • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() restituisce le dimensioni supportate per uno stream YUV_420_888 aggiuntivo per l'analisi delle immagini. Se la superficie YUV di analisi delle immagini non è supportata, getSupportedYuvAnalysisResolutions() deve restituire null o un elenco vuoto.

• Chiavi/risultati delle richieste di acquisizione disponibili (aggiunti in extensions-interface 1.3.0): Camera2/X richiama i seguenti metodi per recuperare le chiavi delle richieste di acquisizione e le chiavi dei risultati supportate dalla tua implementazione:

  • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
  • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Per ulteriori informazioni, consulta Supportare le chiavi e i risultati delle richieste di acquisizione.

Flusso di app 3: anteprima/acquisizione di foto con l'estensione abilitata

Figura 10. Flusso di app 3 sull'extender avanzato

Il diagramma riportato sopra mostra il flusso principale per avviare l'anteprima e l'acquisizione di foto per il tipo di Extender avanzato. Vediamo i passaggi uno per uno.

1. Istanza SessionProcessorImpl

   L'implementazione di base dell'estensore avanzato è in SessionProcessorImpl, che è responsabile della fornitura di una configurazione della sessione personalizzata e dell'invio di richieste di acquisizione per avviare l'anteprima e acquisire comunque la richiesta. AdvancedExtenderImpl.createSessionProcessor() viene invocato per restituire l'istanza SessionProcessorImpl.

2. initSession

   SessionProcessorImpl.initSession() inizializza la sessione per l'estensione. È qui che puoi allocare le risorse e restituire una configurazione della sessione per la preparazione di un CameraCaptureSession.

   Per i parametri di input, Camera2/X specifica le configurazioni delle piattaforme di output per l'anteprima, l'acquisizione di foto e un'analisi facoltativa delle immagini YUV. Questa configurazione della superficie di output (OutputSurfaceImpl) contiene la superficie, le dimensioni e il formato dell'immagine recuperati dai seguenti metodi in AdvancedExtenderImpl:

   • getSupportedPreviewOutputResolutions()
   • getSupportedCaptureOutputResolutions()
   • getSupportedYuvAnalysisResolutions()

   Devi restituire un'istanza Camera2SessionConfigImpl, costituita da un elenco di istanze Camera2OutputConfigImpl e dai parametri di sessione utilizzati per configurare CameraCaptureSession. Spetta a te gestire l'output delle immagini della videocamera sulle piattaforme di output passate da Camera2/X. Ecco alcune opzioni per attivare l'output:

   • Elaborazione nell'HAL della fotocamera: puoi aggiungere direttamente le piattaforme di output a CameraCaptureSession con un'implementazione SurfaceOutputConfigImpl. In questo modo, la superficie di output fornita viene configurata nella pipeline della fotocamera e l'HAL della fotocamera può elaborare l'immagine.

   • Elaborazione di una superficie ImageReader intermedia (RAW, YUV e così via): aggiungi le superfici ImageReader intermedie al CameraCaptureSession con un'istanza ImageReaderOutputConfigImpl.

     Devi elaborare le immagini intermedie e scrivere l'immagine di risultato sulla superficie di output.

   • Utilizza la condivisione della superficie di Camera2:utilizza la condivisione della superficie con un'altra aggiungendo un'istanza Camera2OutputConfigImpl al metodo getSurfaceSharingOutputConfigs() di un'altra istanza Camera2OutputConfigImpl. Il formato e le dimensioni della superficie devono essere identici.

   Tutti i Camera2OutputConfigImpl, inclusi SurfaceOutputConfigImpl e ImageReaderOutputConfigImpl, devono avere un ID univoco (getId()), che viene utilizzato per specificare la superficie di destinazione e recuperare l'immagine da ImageReaderOutputConfigImpl.

3. onCaptureSessionStart e RequestProcessorImpl

   Quando CameraCaptureSession si avvia e il framework della fotocamera invocaonConfigured(), Camera2/X invocaSessionProcessorImpl.onCaptureSessionStart() con il wrapper della richiesta Camera2RequestProcessImpl. Camera2/X implementa RequestProcessImpl, che ti consente di eseguire le richieste di acquisizione e recuperare le immagini se viene utilizzato ImageReaderOutputConfigImpl.

   Le API RequestProcessImpl sono simili alle API Camera2CameraCaptureSession in termini di esecuzione delle richieste. Le differenze sono:

   • La superficie di destinazione è specificata dall'ID dell'istanza Camera2OutputConfigImpl.
   • La possibilità di recuperare l'immagine del ImageReader.

   Puoi chiamare RequestProcessorImpl.setImageProcessor() con un ID Camera2OutputConfigImpl specificato per registrare un'istanza ImageProcessorImpl per ricevere le immagini.

   L'istanza RequestProcessImpl diventa non valida dopo le chiamate Camera2/X SessionProcessorImpl.onCaptureSessionEnd().

4. Avvia l'anteprima e scatta una foto

   Nell'implementazione dell'estensore avanzato, puoi inviare richieste di acquisizione tramite l'interfaccia RequestProcessorImpl. Camera2/X ti chiede di avviare la richiesta ripetuta di anteprima o la sequenza di acquisizione di foto chiamando rispettivamente SessionProcessorImpl#startRepeating e SessionProcessorImpl#startCapture. Devi inviare richieste di acquisizione per soddisfare queste richieste di anteprima e di acquisizione di foto.

   Camera2/X imposta anche i parametri di richiesta di acquisizione tramite SessionProcessorImpl#setParameters. Devi impostare questi parametri di richiesta (se supportati) sia nelle richieste ripetute che in quelle singole.

   Devi supportare almeno CaptureRequest.JPEG_ORIENTATION e CaptureRequest.JPEG_QUALITY. extensions-interface 1.3.0 supporta le chiavi di richiesta e di risultato, che sono esposte dai seguenti metodi:

   • AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
   • AdvancedExtenderImpl.getAvailableCaptureResultKeys()

   Quando gli sviluppatori impostano le chiavi nell'elenco getAvailableCaptureRequestKeys, devi attivare i parametri e assicurarti che il risultato della cattura contenga le chiavi nell'elenco getAvailableCaptureRequestKeys.getAvailableCaptureResultKeys

5. startTrigger

   SessionProcessorImpl.startTrigger() viene invocato per avviare l'attivatore, ad esempio CaptureRequest.CONTROL_AF_TRIGGER e CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER. Puoi ignorare le chiavi di richiesta di acquisizione che non sono state annunciate in AdvancedExtenderImpl.getAvailableCaptureRequestKeys().

   startTrigger() è supportato a partire da extensions-interface 1.3.0. Consente alle app di implementare il tocco per mettere a fuoco e il flash con estensioni.

6. Pulizia

   Al termine di una sessione di acquisizione, SessionProcessorImpl.onCaptureSessionEnd() viene richiamato prima della chiusura di CameraCaptureSession. Al termine della sessione di acquisizione, deInitSession() esegue la pulizia.

Supporta l'anteprima, l'acquisizione di foto e l'analisi di immagini

Dovresti applicare l'estensione sia per l'anteprima che per i casi d'uso di acquisizione continua. Tuttavia, se la latenza è troppo elevata per mostrare l'anteprima senza problemi, puoi applicare l'estensione solo per l'acquisizione di foto.

Per il tipo di estensore di base, indipendentemente dall'abilitazione dell'estensione per l'anteprima, devi implementare sia ImageCaptureExtenderImpl sia PreviewExtenderImpl per una determinata estensione. Spesso un'app utilizza anche uno stream YUV per analizzare i contenuti delle immagini, ad esempio per trovare codici QR o testo. Per supportare meglio questo caso d'uso, devi supportare la combinazione di stream di anteprima, acquisizione di foto e un YUV_420_888 stream per la configurazione di CameraCaptureSession. Ciò significa che se implementi un elaboratore, devi supportare la combinazione di tre stream YUV_420_888.

Per l'estensore avanzato, Camera2/X passa tre superfici di output alla chiamataSessionProcessorImpl.initSession(). Queste piattaforme di output sono rispettivamente per l'anteprima, l'acquisizione e l'analisi delle immagini. Devi assicurarti che le piattaforme di output di anteprima e di acquisizione statica mostrino l'output valido. Tuttavia, per la superficie di output dell'analisi dell'immagine, assicurati che funzioni solo se non è null. Se la tua implementazione non supporta lo stream di analisi delle immagini, puoi restituire un elenco vuoto in AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Ciò assicura che la superficie di output dell'analisi delle immagini sia sempre nulla in SessionProcessorImpl.initSession().

Supporta l'acquisizione video

L'attuale architettura dell'estensione della fotocamera supporta solo i casi d'uso di anteprima e acquisizione di foto. Non supportiamo l'attivazione dell'estensione sulle piattaforme MediaCodec o MediaRecorder per la registrazione del video. Tuttavia, è possibile per le app registrare l'output dell'anteprima.

Il supporto delle piattaforme MediaCodec e MediaRecorder è in fase di indagine.

Metadati specifici dell'estensione

Per Android 14 e versioni successive, i metadati specifici dell'estensione consentono ai client delle estensioni della fotocamera di impostare e ricevere impostazioni e risultati delle richieste di acquisizione specifici dell'estensione. Nello specifico, i client di estensione della videocamera possono utilizzare il parametro di richiesta di acquisizione EXTENSION_STRENGTH per controllare l'intensità dell'estensione e il risultato di acquisizione EXTENSION_CURRENT_TYPE per indicare il tipo di estensione abilitato.

Acquisire le richieste

Il parametro di richiesta di acquisizione EXTENSION_STRENGTH controlla l'intensità dell'effetto di post-elaborazione dell'estensione. Il risultato di acquisizione corrispondente include il valore predefinito dell'intensità se questo parametro non è impostato esplicitamente dal client. Questo parametro può essere applicato come segue per i seguenti tipi di estensioni:

• BOKEH: controlla la quantità di sfocatura.
• HDR e NIGHT: controllano la quantità di immagini fuse e la luminosità dell'immagine finale.
• FACE_RETOUCH: controlla la quantità di miglioramento cosmetico e l'appiattimento della pelle.

L'intervallo supportato per il parametro EXTENSION_STRENGTH è compreso tra 0 e 100, dove 0 indica l'assenza di elaborazione dell'estensione o il semplice passaggio e 100 indica l'intensità massima dell'estensione dell'effetto di elaborazione.

Per aggiungere il supporto per EXTENSION_STRENGTH, utilizza le API dei parametri specifici del fornitore introdotte nella versione 1.3.0 dell'interfaccia della libreria di estensioni. Per ulteriori informazioni, consulta getAvailableCaptureRequestKeys().

Acquisisci risultati

Il risultato di acquisizione EXTENSION_CURRENT_TYPE consente alle implementazioni delle estensioni di informare i clienti sul tipo di estensione attivo.

Poiché le estensioni che utilizzano il tipo AUTO passano dinamicamente da un tipo di estensione come HDR a NIGHT a seconda delle condizioni della scena, le app con estensioni per videocamera possono usare EXTENSION_CURRENT_TYPE per mostrare informazioni sull'estensione corrente selezionata dall'estensione AUTO.

Stima della latenza di acquisizione ancora in tempo reale

Per Android 14 e versioni successive, i client di estensione della videocamera possono eseguire query sulle stime della latenza di acquisizione di foto in tempo reale in base alle condizioni della scena e dell'ambiente utilizzando getRealtimeStillCaptureLatency(). Questo metodo fornisce stime più precise rispetto al metodo statico getEstimatedCaptureLatencyRangeMillis(). In base alla stima della latenza, le app possono decidere di saltare l'elaborazione delle estensioni o di mostrare un'indicazione per notificare agli utenti un'operazione in esecuzione prolungata.

CameraExtensionSession.StillCaptureLatency latency;

latency = extensionSession.getRealtimeStillCaptureLatency();

// The capture latency from ExtensionCaptureCallback#onCaptureStarted() until ExtensionCaptureCallback#onCaptureProcessStarted().

latency.getCaptureLatency();

// The processing latency from  ExtensionCaptureCallback#onCaptureProcessStarted() until  the processed frame returns to the client.

latency.getProcessingLatency();

Per supportare le stime della latenza di acquisizione di foto in tempo reale, implementa quanto segue:

• Estensioni di base: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• Estensioni avanzate: SessionProcessorImpl.getRealtimeCaptureLatency

Callback relativi all'avanzamento dell'elaborazione dell'acquisizione

Per Android 14 e versioni successive, i client di estensione della fotocamera possono ricevere callback per l'avanzamento delle operazioni di elaborazione di acquisizioni di foto di lunga durata. Le app possono mostrare agli utenti l'avanzamento corrente per migliorare l'esperienza utente complessiva.

Le app possono utilizzare il seguente codice per integrare questa funzionalità:

import android.hardware.camera2.CameraExtensionSession.
ExtensionCaptureCallback;

{
…
  class AppCallbackImpl extends ExtensionCaptureCallback {
…
    @Override
    public void onCaptureProcessProgressed(
      @NonNull CameraExtensionSession session,
      @NonNull CaptureRequest request,
      @IntRange(from = 0, to = 100) int progress) {
      // Update app UI with current progress
    }
  }
…
}

Per supportare i callback relativi all'avanzamento dell'elaborazione delle acquisizioni, l'implementazione del fornitore dell'estensione deve chiamare i seguenti callback con il valore di avanzamento corrente:

• Estensioni di base: ProcessResultImpl.onCaptureProcessProgressed()
• Estensioni avanzate: CaptureCallback.onCaptureProcessProgressed()

Acquisizione di immagini fisse post-visualizzazione

Per Android 14 e versioni successive, le estensioni della fotocamera possono fornire un postview (immagine di anteprima) utilizzando setPostviewOutputConfiguration. Per migliorare l'esperienza utente, le app possono mostrare un'immagine post-visualizzazione come segnaposto quando un'estensione presenta una maggiore latenza di elaborazione e sostituire l'immagine quando è disponibile quella finale. Le app possono configurare e emettere richieste di acquisizione post-visualizzazione utilizzando il seguente codice di riferimento:

{
…
if (!CameraExtensionCharacteristics.isPostviewAvailable()) {
    continue;
}
…
ExtensionSessionConfiguration extensionConfiguration = new
        ExtensionSessionConfiguration(
                CameraExtensionCharacteristics.EXTENSION_NIGHT,
                outputConfig,
                backgroundExecutor,
                extensionSessionStateCallback
    );

extensionConfiguration.setPostviewOutputConfiguration(
    postviewImageOutput);
…
CaptureRequest.Builder captureRequestBuilder =
    cameraDevice.createCaptureRequest(
        CameraDevice.TEMPLATE_STILL_CAPTURE);
captureRequestBuilder.addTarget(stillImageReader.getSurface());
captureRequestBuilder.addTarget(postviewImageSurface);

CaptureRequest captureRequest = captureRequestBuilder.build();
…
}

Per supportare l'acquisizione di immagini dopo la visualizzazione, l'implementazione del fornitore deve includere quanto segue:

• Estensioni di base: CaptureProcessorImpl.onPostviewOutputSurface e CaptureProcessorImpl.processWithPostview

• Estensioni avanzate: SessionProcessorImpl.startCaptureWithPostview

Supporta l'output SurfaceView

Per Android 14 e versioni successive, i client delle estensioni della fotocamera possono utilizzare percorsi di rendering dell'anteprima ottimizzati in termini di potenza e prestazioni registrando un'istanza SurfaceView per l'output dell'anteprima per le richieste ripetute.

Per supportare l'output SurfaceView, l'implementazione dell'estensione del fornitore deve essere in grado di trasmettere flussi di dati e inviare l'anteprima alle istanze SurfaceView. Per verificare che questa funzionalità sia supportata, esegui il SurfaceViewExtensionPreviewTest.java modulo CTS.

Tipi di sessione specifici del fornitore

La funzionalità consente alle implementazioni delle estensioni del fornitore di selezionare un tipo di sessione specifico del fornitore che verrà impostato nella sessione di acquisizione della fotocamera interna anziché il valore predefinito.

La funzionalità opera interamente all'interno del framework e dello stack del fornitore e non ha alcun impatto visibile a livello di client/API pubblica.

Per selezionare un tipo di sessione specifico del fornitore, implementa quanto segue per le librerie di estensioni: * ExtenderStateListener.onSessionType() per le estensioni di base * Camera2SessionConfigImpl.getSessionType() per le estensioni avanzate

Cronologia delle versioni dell'interfaccia delle estensioni

La tabella seguente mostra la cronologia delle versioni dell'interfaccia dell'estensione della videocamera. Devi sempre implementare la libreria del fornitore con la versione più recente.

Implementazione dei riferimenti

Le seguenti implementazioni di librerie dei fornitori OEM di riferimento sono disponibili in frameworks/ex.

• advancedSample: un'implementazione di base di Estensore avanzato.

• sample: un'implementazione di base di Estensore di base.

• service_based_sample: un'implementazione che mostra come ospitare le Estensioni per le videocamere in un Service. Questa implementazione contiene i seguenti componenti:

  • oem_library: una libreria OEM di Camera Extensions per le API Camera2 e CameraX Extensions che implementa Extensions-Interface. Questo agisce come un passthrough che forwarda le chiamate da Extensions-Interface al servizio. Questa libreria fornisce inoltre file AIDL e classi wrapper per comunicare con il servizio.

    L'estensore avanzato è attivo per impostazione predefinita. Per attivare l'estensore di base, modifica ExtensionsVersionImpl#isAdvancedExtenderImplemented in return false.

  • extensions_service: un'implementazione di esempio del servizio Estensioni. Aggiungi la tua implementazione qui. L'interfaccia da implementare nel servizio è simile a quella di Extensions-Interface. Ad esempio, l'implementazione di IAdvancedExtenderImpl.Stub esegue le stesse operazioni di AdvancedExtenderImpl. ImageWrapper e TotalCaptureResultWrapper sono necessari per rendere Image e TotalCaptureResult assegnabili.

Configurare la libreria del fornitore su un dispositivo

La libreria dei fornitori OEM non è integrata in un'app, ma viene caricata dal dispositivo in fase di runtime da Camera2/X. In CameraX, il tag <uses-library> dichiara che la libreria androidx.camera.extensions.impl, definita nel AndroidManifest.xml file della libreria camera-extensions, è una dipendenza di CameraX e deve essere caricata al runtime. In Camera2, il framework carica un servizio di estensioni che dichiara anche che <uses-library>carica la stessa libreria androidx.camera.extensions.impl in fase di runtime.

In questo modo, le app di terze parti che utilizzano estensioni possono caricare automaticamente la libreria del fornitore OEM. La libreria OEM è contrassegnata come facoltativa, pertanto le app possono essere eseguite su dispositivi che non dispongono della libreria. Camera2/X gestisce questo comportamento automaticamente quando un'app tenta di utilizzare un'estensione della fotocamera, a condizione che il produttore del dispositivo inserisca la libreria OEM sul dispositivo in modo che possa essere rilevata dall'app.

Per configurare la libreria OEM su un dispositivo:

1. Aggiungi un file di autorizzazione, obbligatorio per il tag <uses-library>, utilizzando il seguente formato: /etc/permissions/ANY_FILENAME.xml. Ad esempio, /etc/permissions/camera_extensions.xml. I file in questa directory forniscono una mappatura della raccolta denominata in <uses-library> al percorso del file effettivo sul dispositivo.

2. Utilizza l'esempio riportato di seguito per aggiungere le informazioni richieste al file.

   • name deve essere androidx.camera.extensions.impl perché è la libreria cercata da CameraX.
   • file è il percorso assoluto del file che contiene l'implementazione delle estensioni (ad esempio /system/framework/androidx.camera.extensions.impl.jar).

   <?xml version="1.0" encoding="utf-8"?>
   <permissions>
       <library name="androidx.camera.extensions.impl"
                file="OEM_IMPLEMENTED_JAR" />
   </permissions>

In Android 12 o versioni successive, i dispositivi che supportano le estensioni CameraX devono avere la proprietà ro.camerax.extensions.enabled impostata su true, il che consente di verificare se un dispositivo supporta le estensioni. A tale scopo, aggiungi la seguente riga nel file del produttore del dispositivo:

PRODUCT_VENDOR_PROPERTIES += \
    ro.camerax.extensions.enabled=true \

Convalida

Per testare l'implementazione della libreria del fornitore OEM durante la fase di sviluppo, utilizza l'app di esempio all'indirizzo androidx-main/camera/integration-tests/extensionstestapp/, che esegue varie estensioni del fornitore.

Una volta completata l'implementazione, utilizza lo strumento di convalida delle estensioni della fotocamera per eseguire test automatici e manuali al fine di verificare che la libreria del fornitore sia implementata correttamente.

Modalità Scena estesa rispetto alle estensioni della fotocamera

Per l'effetto bokeh, oltre a utilizzarlo con le estensioni della fotocamera, puoi attivarlo tramite la modalità Scena estesa, che viene attivata tramite la chiave CONTROL_EXTENDED_SCENE_MODE. Per ulteriori dettagli sull'implementazione, vedi Bokeh della fotocamera.

La modalità Scena estesa presenta meno limitazioni rispetto alle estensioni della fotocamera per le app camera2. Ad esempio, puoi attivare la modalità Scena estesa in una normale istanza CameraCaptureSession che supporta combinazioni di stream flessibili e acquisisce i parametri di richiesta. Al contrario, le estensioni della videocamera supportano solo un insieme fisso di tipi di stream e hanno un supporto limitato per i parametri di richiesta di acquisizione.

Uno svantaggio della modalità Scena estesa è che puoi implementarla solo nell'HAL della fotocamera, il che significa che deve essere verificata per funzionare su tutti i controlli ortogonali disponibili per gli sviluppatori di app.

Consigliamo di esporre il bokeh utilizzando sia la modalità scena estesa sia le estensioni della fotocamera, in quanto le app potrebbero preferire utilizzare un'API specifica per attivare il bokeh. Consigliamo prima di utilizzare la modalità scena estesa perché è il modo più flessibile per le app di attivare l'estensione bokeh. A questo punto, puoi implementare l'interfaccia delle estensioni della fotocamera in base alla modalità Scena estesa. Se l'implementazione del bokeh nell'HAL della fotocamera è difficile, ad esempio perché richiede un post-processore in esecuzione nel livello dell'app per elaborare le immagini, consigliamo di implementare l'estensione bokeh utilizzando l'interfaccia Camera Extensions.

Domande frequenti

Esistono limitazioni sui livelli API?

Sì. Questo dipende dal set di funzionalità dell'API Android richiesto dall'implementazione della libreria del fornitore OEM. Ad esempio, ExtenderStateListener.onPresetSession() utilizza la chiamata SessionConfiguration.setSessionParameters() per impostare un insieme di tag di riferimento. Questa chiamata è disponibile solo a partire dal livello API 28. Per informazioni dettagliate su metodi di interfaccia specifici, consulta la documentazione di riferimento dell'API.