Estensioni della videocamera

I produttori di dispositivi possono esporre estensioni come bokeh, modalità notturna e HDR a sviluppatori di terze parti tramite l'interfaccia delle estensioni della fotocamera fornita dalla libreria del fornitore 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 API CameraX Extensions. Se vuoi aggiungere un'estensione, apri un bug con Issue Tracker.

Questa pagina descrive come implementare e attivare la libreria del fornitore OEM sui dispositivi.

Architettura

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

Figura 1. Diagramma dell'architettura delle estensioni per fotocamera

Come mostrato nel diagramma, per supportare le estensioni della fotocamera, devi implementare extensions-interface fornito dalla libreria del fornitore OEM. La libreria del fornitore OEM attiva due API: API CameraX Extensions e 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 delle estensioni della videocamera.

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 estensione Bokeh (implementale se l'estensione Bokeh è supportata)

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

Lezioni di estensione notturna (implementale se l'estensione notturna è supportata)

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

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

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

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

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

Classi di estensione del ritocco viso (implementalo se l'estensione del ritocco viso è supportata)

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

Utilità (facoltativo, può essere eliminato)

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

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

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

Mainflow

Figura 2. Implementazione dell'estensione notturna

  1. Verifica della versione:

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

  2. Inizializzazione della libreria 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. Istanzia le classi Extender:

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

    Camera2/X crea istanze e interagisce con le classi Extender per recuperare informazioni e attivare l'estensione. Per una determinata estensione, Camera2/X può creare un'istanza delle classi Extender più volte. Di conseguenza, non eseguire l'inizializzazione pesante nel costruttore o nella chiamata init(). Esegui l'operazione pesante 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 Night, vengono istanziate le seguenti classi Extender per il tipo di Extender Basic:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    Per il tipo di estensore avanzato:

    • NightAdvancedExtenderImpl.java

  4. Verifica la disponibilità dell'estensione:

    Prima di attivare l'estensione, isExtensionAvailable() verifica se l'estensione è disponibile sull'ID videocamera specificato tramite l'istanza dell'extender.

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

    Camera2/X chiama init() sull'istanza Extender e le trasmette l'ID videocamera e CameraCharacteristics.

  6. Informazioni sulla query:

    Richiama la classe Extender per recuperare informazioni come le risoluzioni supportate, acquisire la latenza stimata e acquisire le chiavi di richiesta dall'extender in preparazione all'attivazione dell'estensione.

  7. Attiva l'estensione sull'extender:

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

    Per il tipo di estensione avanzata, Camera2/X interagisce con SessionProcessorImpl per attivare l'estensione. Camera2/X recupera l'istanza di SessionProcessorImpl chiamando createSessionProcessor() sull'extender.

Le sezioni seguenti descrivono il flusso dell'estensione in modo più dettagliato.

Verifica della versione

Quando carica la libreria del fornitore OEM dal dispositivo in fase di runtime, 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, chiama Camera2/X ExtensionVersionImpl.checkApiVersion() con la versione extensions-interface supportata. 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 la versione principale

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 con le librerie dei fornitori OEM create con versioni extensions-interface precedenti. Ad esempio, se Camera2/X supporta extensions-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 si assicura che la libreria sia compatibile con le versioni future di extension-interface.

Compatibilità futura

La compatibilità futura 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 volerle attivare 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, ad esempio 99.0.0, per disattivare le estensioni.

Inizializzazione della libreria del fornitore

Dopo aver verificato la versione extensions-interface implementata dalla libreria OEM, Camera2/X avvia la procedura di inizializzazione. Il metodo InitializerImpl.init() segnala 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) finché la libreria del fornitore OEM non chiama OnExtensionsInitializedCallback.onSuccess() per comunicare il completamento dell'inizializzazione.

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

Estensore di base e avanzato

Esistono due tipi di implementazione di extensions-interface: Basic Extender e Advanced Extender. Advanced Extender è supportato dalla versione 1.2.0 di extensions-interface.

Implementa Basic Extender per le estensioni che elaborano le immagini nell'HAL della fotocamera o utilizza un post-processore in grado di elaborare i flussi YUV.

Implementa Advanced Extender 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:

Estensore di base Advanced Extender
Configurazioni dello stream Correzione
Anteprima: PRIVATE o YUV_420_888 (se esiste un processore)
Acquisizione di immagini fisse: JPEG o YUV_420_888 (se esiste un processore) 		Personalizzabile dall'OEM.
Invio della richiesta di acquisizione Solo Camera2/X può inviare richieste di acquisizione. Puoi impostare i parametri per queste richieste. Quando il processore viene fornito per l'acquisizione di immagini, Camera2/X può inviare più richieste di acquisizione e inviare tutte le immagini e i risultati dell'acquisizione al processore. Ti viene fornita un'istanza RequestProcessorImpl per eseguire la richiesta di acquisizione camera2 e ottenere risultati e immagini.

Camera2/X richiama startRepeating e startCapture su SessionProcessorImpl per segnalare all'OEM di avviare la richiesta ripetuta di anteprima e la sequenza di acquisizione di foto, rispettivamente.

Hook nella pipeline della fotocamera
  • onPresetSession fornisce i parametri di sessione.
  • onEnableSession invia una singola richiesta subito dopo la configurazione di CameraCaptureSession.
  • onDisableSession invia una singola richiesta prima della chiusura di CameraCaptureSession.
  • initSession inizializza e restituisce una configurazione personalizzata della sessione camera2 per la creazione della sessione di acquisizione.
  • onCaptureSessionStart viene richiamato subito dopo la configurazione di CameraCaptureSession.
  • onCaptureSessionEnd viene richiamato prima della chiusura di CameraCaptureSession.
Adatto a Estensioni implementate nell'HAL della fotocamera o in un processore che elabora immagini YUV.
  • Dispone di implementazioni basate su Camera2 per le estensioni.
  • Richiede una configurazione dello stream personalizzata, ad esempio lo stream RAW.
  • Richiede una sequenza di acquisizione interattiva.
Versione API supportata Estensioni Camera2: Android 13 o versioni successive
Estensioni CameraX: camera-extensions 1.1.0 o versioni successive		 Estensioni Camera2: Android 12L o versioni successive
Estensioni CameraX: camera-extensions 1.2.0-alpha03 o versioni successive

Flussi di app

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

Estensioni Camera2 Estensioni CameraX
Disponibilità dell'espansione delle query CameraExtensionCharacteristics .getSupportedExtensions ExtensionsManager. isExtensionAvailable
Informazioni sulla query CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

CameraX gestisce il resto delle informazioni all'interno della libreria.

Anteprima e acquisizione di immagini fisse con l'estensione abilitata CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector

bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)

Estensore di base

L'interfaccia Basic Extender fornisce hook in diverse posizioni della pipeline della videocamera. Ogni tipo di estensione ha classi Extender corrispondenti che gli OEM devono implementare.

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

Classi di estensione da implementare
Notte NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR HdrPreviewExtenderImpl.java

HdrImageCaptureExtenderImpl.java

Automatica AutoPreviewExtenderImpl.java

AutoImageCaptureExtenderImpl.java

Bokeh BokehPreviewExtenderImpl.java

BokehImageCaptureExtenderImpl.java

Ritocco viso BeautyPreviewExtenderImpl.java

BeautyImageCaptureExtenderImpl.java

Utilizziamo PreviewExtenderImpl e ImageCaptureExtenderImpl come segnaposto nell'esempio seguente. Sostituiscili con i nomi dei file che stai implementando.

Basic Extender ha le seguenti funzionalità:

  • Inserisci i parametri di sessione durante la configurazione di CameraCaptureSession ( onPresetSession).
  • Notificarti gli eventi di apertura e chiusura della sessione di acquisizione e inviare 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 l'acquisizione di immagini fisse in grado di elaborare il flusso YUV_420_888.

Vediamo come Camera2/X richiama extensions-interface per ottenere i tre flussi dell'app menzionati sopra.

Flusso dell'app 1: controlla la disponibilità dell'estensione

BasicExtenderAppFlow1

Figura 3. Flusso dell'app 1 su Basic Extender

In questo flusso, Camera2/X chiama direttamente il metodo isExtensionAvailable() di PreviewExtenderImpl e ImageCaptureExtenderImpl senza chiamare init(). Entrambe le classi Extender devono restituire true per attivare le estensioni.

Questo è spesso il primo passo per le app per verificare se il tipo di estensione specificato è supportato per un determinato ID fotocamera prima di attivare l'estensione. perché alcune estensioni sono supportate solo su determinati ID videocamera.

Flusso dell'app 2: informazioni query

BasicExtenderAppFlow2

Figura 4. Flusso dell'app 2 su Estensore di base

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

  • Still capture latency range:ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange restituisce l'intervallo di latenza di acquisizione per l'app per valutare se è opportuno abilitare l'estensione per lo scenario attuale.

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

  • Chiavi di richiesta e 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 init() per prima su queste classi Extender prima di eseguire query per ulteriori informazioni.

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

BasicExtenderAppFlow3

Figura 5. Flusso dell'app 3 su Basic Extender

Il diagramma riportato sopra illustra il flusso principale di attivazione dell'anteprima e dell'acquisizione di immagini fisse con un'estensione senza 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 una sessione della videocamera sta per iniziare con le estensioni specificate. Puoi eseguire l'inizializzazione di attività che richiedono molte risorse in onInit().

Quando configura CameraCaptureSession, Camera2/X richiama onPresetSession per ottenere i parametri della sessione. Una volta configurata correttamente la sessione di acquisizione, Camera2/X richiama onEnableSession restituendo un'istanza di CaptureStageImpl che contiene i parametri di acquisizione. Camera2/X invia immediatamente una singola richiesta con questi parametri di acquisizione per notificare l'HAL. Analogamente, prima che la sessione di acquisizione venga chiusa, Camera2/X richiama onDisableSession e poi invia una singola richiesta con i parametri di acquisizione restituiti.

La richiesta ripetuta attivata da Camera2/X contiene i parametri della richiesta restituiti 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 rilasciare le risorse in onDeinit().

Processore di anteprima

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

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

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

  • PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: il tipo di processore consente di aggiornare la richiesta ripetuta con nuovi parametri di richiesta di acquisizione in base all'ultimo TotalCaptureResult.

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

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

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

    Per il flusso, vedi l'illustrazione seguente:

PreviewProcessor

Figura 6. Flusso di anteprima con PreviewImageProcessorImpl

L'interfaccia PreviewImageProcessorImpl estende ProcessImpl e ha 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 di acquisizione immagini

Per l'acquisizione di immagini statiche, puoi implementare un processore restituendo un'istanza CaptureProcessorImpl utilizzando ImageCaptureExtenderImpl.getCaptureProcessor. Il processore è responsabile dell'elaborazione di un elenco di immagini YUV_420_888 acquisite e istanze TotalCaptureResult e della scrittura dell'output su una superficie YUV_420_888.

Puoi dare per scontato che l'anteprima sia abilitata e in esecuzione prima di inviare la richiesta di acquisizione di foto.

Vedi il flusso nel diagramma seguente:

CaptureProcessor

Figura 7. Ancora flusso di acquisizione con CaptureProcessorImpl

  1. Camera2/X utilizza una superficie in formato YUV_420_888 per l'acquisizione di immagini fisse 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 di YUV_420_888 uscita.

  2. ImageCaptureExtenderImpl.getCaptureStages restituisce un elenco di CaptureStageImpl , in cui ogni elemento corrisponde a un'istanza 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 ricevute e le istanze di TotalCaptureResult vengono raggruppate e inviate a CaptureProcessorImpl per l'elaborazione.

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

Supporta le chiavi e i risultati delle richieste di acquisizione

Oltre all'anteprima e all'acquisizione della videocamera, le app possono impostare lo zoom, i parametri del flash o attivare la messa a fuoco con un tocco. 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 della 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 videocamera elabora l'estensione, Camera2/X recupera l'acquisizione risultati in CameraCaptureSession.CaptureCallback. Tuttavia, se il processore è implementato, Camera2/X recupera i risultati dell'acquisizione in ProcessResultImpl , che viene passato al metodo process() in PreviewImageProcessorImpl e CaptureProcessorImpl. È tua responsabilità segnalare il risultato dell'acquisizione tramite ProcessResultImpl a Camera2/X.

Vedi di seguito la definizione dell'interfaccia CaptureProcessorImpl come esempio. In extensions-interface 1.3.0 o versioni successive, viene richiamata 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, messa a fuoco con tocco, flash e compensazione dell'esposizione, ti consigliamo di supportare i seguenti tasti sia per la richiesta di acquisizione sia per il risultato dell'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 le estensioni di base che implementano la versione 1.2.0 o precedenti, l'API CameraX Extensions supporta esplicitamente tutte le chiavi precedenti. Per extensions-interface 1.3.0, sia CameraX che Camera2 rispettano l'elenco restituito e supportano solo le chiavi contenute al suo interno. Ad esempio, se decidi di restituire solo CaptureRequest#CONTROL_ZOOM_RATIO e CaptureRequest#SCALER_CROP_REGION nell'implementazione 1.3.0, ciò significa che per l'app è supportato solo lo zoom, mentre il tocco per mettere a fuoco, il flash e la compensazione dell'esposizione non sono consentiti.

Advanced Extender

Advanced Extender è un tipo di implementazione del fornitore basato 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, che dipende dai seguenti fattori:

  • Configurazione personalizzata dello stream: configura stream personalizzati come lo stream RAW o disponi di 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 basati sui risultati di 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'extender avanzato, 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 dell'estensione avanzata si trovano nel pacchetto advanced.

Classi di estensione da implementare
Notte advanced/NightAdvancedExtenderImpl.java
HDR advanced/HdrAdvancedExtenderImpl.java
Automatica advanced/AutoAdvancedExtenderImpl.java
Bokeh advanced/BokehAdvancedExtenderImpl.java
Ritocco del volto advanced/BeautyAdvancedExtenderImpl.java

Utilizziamo AdvancedExtenderImpl come segnaposto nell'esempio seguente. Sostituiscilo con il nome del file Extender per l'estensione che stai implementando.

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

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

AdvancedAppFlow1

Figura 8. Flusso dell'app 1 sull'Advanced Extender

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

Flusso dell'app 2: informazioni query

AdvancedAppFlow2

Figura 9. Flusso dell'app 2 sull'extender avanzato

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

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

  • Risoluzioni supportate per l'anteprima e l'acquisizione di immagini fisse:

    • 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 la superficie di acquisizione di immagini fisse. Gli OEM devono supportare l'output in formato JPEG e YUV_420_888.

    • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() restituisce le dimensioni supportate per un flusso 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 Chiavi e risultati delle richieste di acquisizione del supporto.

Flusso dell'app 3: anteprima/acquisizione di immagini fisse con l'estensione abilitata

AdvancedAppFlow3

Figura 10. Flusso dell'app 3 sull'extender avanzato

Il diagramma riportato sopra mostra il flusso principale per l'avvio dell'anteprima e dell'acquisizione di foto per il tipo di estensore avanzato. Vediamo nel dettaglio la procedura da seguire.

  1. Istanza SessionProcessorImpl

    L'implementazione principale di Advanced Extender si trova in SessionProcessorImpl, che è responsabile della fornitura della configurazione della sessione personalizzata e dell'invio delle richieste di acquisizione per avviare l'anteprima e acquisire comunque la richiesta. AdvancedExtenderImpl.createSessionProcessor() viene richiamato per restituire l'istanza SessionProcessorImpl.

  2. initSession

    SessionProcessorImpl.initSession() inizializza la sessione per l'estensione. È qui che allochi le risorse e restituisci una configurazione di sessione per preparare un CameraCaptureSession.

    Per i parametri di input, Camera2/X specifica le configurazioni della superficie 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, che consiste in un elenco di istanze Camera2OutputConfigImpl e nei parametri di sessione utilizzati per configurare CameraCaptureSession. Sei responsabile dell'output delle immagini corrette della videocamera sulle superfici di output passate da Camera2/X. Ecco alcune opzioni per abilitare l'output:

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

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

      Devi elaborare le immagini intermedie e scrivere l'immagine risultante nella superficie di output.

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

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

  3. onCaptureSessionStart e RequestProcessorImpl

    Quando CameraCaptureSession viene avviato e il framework della fotocamera richiama onConfigured(), Camera2/X richiama SessionProcessorImpl.onCaptureSessionStart() con il wrapper della richiesta Camera2 RequestProcessImpl. 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 Camera2 CameraCaptureSession in termini di esecuzione delle richieste. Le differenze sono:

    • La superficie target è 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 immagini.

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

  4. Avviare l'anteprima e scattare una foto

    Nell'implementazione dell'estensione avanzata, puoi inviare richieste di acquisizione tramite l'interfaccia RequestProcessorImpl. Camera2/X ti avvisa 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 acquisizione di immagini fisse.

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

    Devi supportare almeno CaptureRequest.JPEG_ORIENTATION e CaptureRequest.JPEG_QUALITY. extensions-interface 1.3.0 supporta le chiavi di richiesta e risultato, 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 dell'acquisizione contenga le chiavi nell'elenco getAvailableCaptureResultKeys.

  5. startTrigger

    SessionProcessorImpl.startTrigger() viene richiamato per avviare il trigger, ad esempio CaptureRequest.CONTROL_AF_TRIGGER e CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER. Puoi ignorare le chiavi di richiesta di acquisizione che non sono state pubblicizzate in AdvancedExtenderImpl.getAvailableCaptureRequestKeys().

    startTrigger() è supportato dalla versione 1.3.0 di extensions-interface. Consente alle app di implementare la messa a fuoco con un tocco e il flash con le estensioni.

  6. Pulizia

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

Supporta l'anteprima, l'acquisizione di immagini fisse e l'analisi delle immagini

Devi applicare l'estensione sia per l'anteprima sia per i casi d'uso di acquisizione di immagini statiche. Tuttavia, se la latenza è troppo elevata per mostrare l'anteprima in modo fluido, puoi applicare l'estensione solo per l'acquisizione di immagini fisse.

Per il tipo di estensione di base, indipendentemente dall'attivazione dell'estensione per l'anteprima, devi implementare sia ImageCaptureExtenderImpl sia PreviewExtenderImpl per una determinata estensione. Spesso, un'app utilizza anche un flusso 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 immagini fisse e uno stream YUV_420_888 per la configurazione di CameraCaptureSession. Ciò significa che se implementi un processore, devi supportare la combinazione di stream di tre stream YUV_420_888.

Per Advanced Extender, Camera2/X passa tre superfici di output alla chiamata SessionProcessorImpl.initSession(). Queste superfici di output sono rispettivamente per l'anteprima, l'acquisizione di immagini fisse e l'analisi delle immagini. Devi assicurarti che le superfici di output di anteprima e acquisizione di immagini fisse mostrino l'output valido. Tuttavia, per la superficie di output dell'analisi delle immagini, assicurati che funzioni solo quando non è nulla. Se la tua implementazione non supporta lo stream di analisi delle immagini, puoi restituire un elenco vuoto in AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). In questo modo, la superficie di output dell'analisi dell'immagine è sempre nulla in SessionProcessorImpl.initSession().

Supportare l'acquisizione video

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

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

Metadati specifici dell'estensione

Per Android 14 e versioni successive, i metadati specifici dell'estensione consentono ai client di estensione della fotocamera di impostare e ricevere impostazioni e risultati della richiesta di acquisizione specifici dell'estensione. In particolare, 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 di intensità predefinito se questo parametro non è impostato in modo esplicito dal client. Questo parametro può essere applicato nel seguente modo per questi tipi di estensione:

  • BOKEH: controlla la quantità di sfocatura.
  • HDR e NIGHT: controllano la quantità di immagini unite e la luminosità dell'immagine finale.
  • FACE_RETOUCH: controlla la quantità di miglioramento estetico e levigatura 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 un semplice passthrough e 100 indica la massima intensità di estensione dell'effetto di elaborazione.

Per aggiungere il supporto di 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, vedi getAvailableCaptureRequestKeys().

Risultati dell'acquisizione

Il risultato EXTENSION_CURRENT_TYPE di acquisizione consente alle implementazioni delle estensioni di comunicare ai client il tipo di estensione attivo.

Poiché le estensioni che utilizzano il tipo AUTO passano dinamicamente da un tipo di estensione all'altro, ad esempio HDR e NIGHT, a seconda delle condizioni della scena, le app di estensioni della videocamera possono utilizzare EXTENSION_CURRENT_TYPE per visualizzare informazioni sull'estensione corrente selezionata dall'estensione AUTO.

Stima della latenza di acquisizione di immagini fisse in tempo reale

Per Android 14 e versioni successive, i client di estensione della fotocamera possono eseguire query sulle stime della latenza di acquisizione di immagini fisse in tempo reale in base alla scena e alle condizioni ambientali utilizzando getRealtimeStillCaptureLatency(). Questo metodo fornisce stime più accurate rispetto al metodo getEstimatedCaptureLatencyRangeMillis() statico. In base alla stima della latenza, le app possono decidere di saltare l'elaborazione dell'estensione o di mostrare un'indicazione per informare gli utenti di un'operazione di lunga durata.

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 immagini fisse in tempo reale, implementa quanto segue:

Callback di 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 dell'acquisizione di foto a lunga esecuzione. Le app possono mostrare agli utenti lo stato di avanzamento attuale 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 di avanzamento dell'elaborazione dell'acquisizione, l'implementazione del fornitore dell'estensione deve chiamare i seguenti callback con il valore di avanzamento corrente:

Post-visualizzazione ancora in fase di acquisizione

Per Android 14 e versioni successive, le estensioni della fotocamera possono fornire un'immagine postview (anteprima) utilizzando setPostviewOutputConfiguration. Per migliorare l'esperienza utente, le app possono visualizzare un'immagine post-view come segnaposto quando un'estensione sta riscontrando una maggiore latenza di elaborazione e sostituire l'immagine quando è disponibile l'immagine finale. Le app possono configurare ed 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 post-visualizzazione, l'implementazione del fornitore deve implementare quanto segue:

Supporto dell'output SurfaceView

Per Android 14 e versioni successive, i client di estensione della fotocamera possono utilizzare percorsi di rendering dell'anteprima ottimizzati per 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 eseguire lo streaming e l'output dell'anteprima alle istanze SurfaceView. Per verificare che sia supportato, esegui il modulo SurfaceViewExtensionPreviewTest.java CTS.

Tipi di sessione specifici del fornitore

La funzionalità consente alle implementazioni dell'estensione del fornitore di selezionare un tipo di sessione specifico del fornitore che verrà impostato nella sessione di acquisizione della videocamera interna anziché il valore predefinito.

La funzionalità opera interamente all'interno del framework e dello stack del fornitore e non ha alcun impatto sull'API visibile al cliente/pubblico.

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 l'ultima versione.

Versione Funzionalità aggiunte
1.0.0
  • Verifica della versione
    • ExtensionVersionImpl
  • Basic Extender
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Inizializzazione della raccolta
    • InitializerImpl
  • Mostra le risoluzioni supportate
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • AdvancedExtender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Ottenere la latenza di acquisizione stimata
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • Esporre le chiavi di richiesta/risultato di acquisizione supportate
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys e getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys e getAvailableCaptureResultKeys
    • Nuova chiamata process() che si terrà il giorno ProcessResultImpl alle ore PreviewImageProcessorImpl e CaptureProcessorImpl
    • Richiesta di tipo di attivatore di supporto
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Metadati specifici dell'estensione
  • Stime della latenza di acquisizione di immagini statiche dinamiche
  • Callback di avanzamento dell'elaborazione dell'acquisizione
  • Post-visualizzazione ancora in fase di acquisizione
  • Supporto per l'output SurfaceView
  • Tipi di sessione specifici del fornitore

Implementazione di riferimento

Le seguenti implementazioni della libreria del fornitore OEM di riferimento sono disponibili in frameworks/ex.

  • advancedSample: Un'implementazione di base di Advanced Extender.

  • sample: un'implementazione di base di Basic Extender.

  • service_based_sample: un'implementazione che mostra come ospitare le estensioni della fotocamera in un Service. Questa implementazione contiene i seguenti componenti:

    • oem_library: Una libreria OEM di estensioni della fotocamera per le API Camera2 e CameraX Extensions che implementa Extensions-Interface. che inoltra le chiamate da Extensions-Interface al servizio. Questa libreria fornisce anche file AIDL e classi wrapper per comunicare con il servizio.

      Advanced Extender è attivo per impostazione predefinita. Per attivare l'extender di base, modifica ExtensionsVersionImpl#isAdvancedExtenderImplemented in modo che restituisca false.

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

Configurare la libreria dei fornitori su un dispositivo

La libreria del fornitore 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 file AndroidManifest.xml della libreria camera-extensions, è una dipendenza di CameraX e deve essere caricata in fase di 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 le estensioni caricano automaticamente la libreria del fornitore OEM. La libreria OEM è contrassegnata come facoltativa, quindi le app possono essere eseguite su dispositivi che non la includono. Camera2/X gestisce questo comportamento automaticamente quando un'app tenta di utilizzare un'estensione della videocamera, 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 autorizzazioni, richiesto dal 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 libreria 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 che CameraX cerca.
    • 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. Per farlo, aggiungi la seguente riga nel file make 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 per verificare che la libreria del fornitore sia implementata correttamente.

Modalità Scena estesa e estensioni della fotocamera

Per l'estensione bokeh, oltre a esporla utilizzando le estensioni della fotocamera, puoi esporla utilizzando la modalità scena estesa, che viene attivata tramite il tasto CONTROL_EXTENDED_SCENE_MODE. Per ulteriori dettagli sull'implementazione, vedi Bokeh della fotocamera.

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

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

Ti consigliamo di esporre il bokeh utilizzando sia la modalità scena estesa sia le estensioni della fotocamera, perché le app potrebbero preferire l'utilizzo di una particolare API per attivare il bokeh. Ti consigliamo di utilizzare prima la modalità Scena estesa perché è il modo più flessibile per le app di attivare l'estensione bokeh. Quindi puoi implementare l'interfaccia delle estensioni della videocamera 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, ti consigliamo di implementare l'estensione bokeh utilizzando l'interfaccia delle estensioni della fotocamera.

Domande frequenti

Esistono limitazioni per i livelli API?

Sì. 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 base di tag. Questa chiamata è disponibile solo a livello API 28 e versioni successive. Per informazioni dettagliate su metodi di interfaccia specifici, consulta la documentazione di riferimento dell'API.