Estensioni per fotocamere

I produttori di dispositivi possono esporre estensioni come bokeh, modalità notturna e HDR a sviluppatori di terze parti tramite l'interfaccia Estensioni della fotocamera fornita dalla biblioteca 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, 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: Architettura

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: 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 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 (implementale 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:

Mainflow

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:

    Consente di creare istanze delle 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 Base Extender e Advanced Extender.

    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 complessa nel costruttore o nella chiamata a init(). Esegui le operazioni più complesse 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 attivare l'estensione, isExtensionAvailable() controlla se l'estensione è disponibile nell'ID videocamera specificato tramite l'istanza dell'estensore.

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

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

  6. Informazioni sulla query:

    Richiama la classe Extender per recuperare informazioni come le risoluzioni supportate, acquisire comunque la latenza stimata e acquisire le chiavi di richiesta dall'Extender 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 aggiuntivo 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 supportataextensions-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 assicura che la libreria sia compatibile con le versioni precedenti di extension-interface.

Compatibilità con le versioni successive

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: Extender di base e Extender 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:

Estensore di base Estensore avanzato
Configurazioni dello stream Correzione
Anteprima: PRIVATE o YUV_420_888 (se esiste un processore)
Acquisizione di foto: 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 di acquisizione al processore. Ti viene fornita un'istanza di RequestProcessorImpl per eseguire la richiesta di acquisizione della fotocamera 2 e ottenere i risultati e l'immagine.

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

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 della sessione camera2 personalizzata per la creazione della sessione di acquisizione.
  • onCaptureSessionStart viene invocato subito dopo la configurazione di CameraCaptureSession.
  • onCaptureSessionEnd viene invocato prima della chiusura di CameraCaptureSession.
Idoneo per Estensioni implementate nell'HAL della fotocamera o in un processore che elabora le immagini YUV.
  • Ha implementazioni basate su Camera2 per le estensioni.
  • Richiede una configurazione dello stream personalizzata, ad esempio uno stream RAW.
  • Richiede una sequenza di acquisizione interattiva.
Versione dell'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 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, descritti in maggiore dettaglio in una sezione successiva.

Estensioni Camera2 Estensioni CameraX
Disponibilità delle estensioni di query CameraExtensionCharacteristics .getSupportedExtensions ExtensionsManager. isExtensionAvailable
Informazioni sulle query CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

CameraX gestisce le restanti informazioni all'interno della libreria.

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

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector

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

Estensore di base

L'interfaccia di Base Extender fornisce hook in diversi punti 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

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 il flusso YUV_420_888.

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

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

BasicExtenderAppFlow1

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

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

BasicExtenderAppFlow2

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 attuale.

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

BasicExtenderAppFlow3

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

Il diagramma riportato sopra illustra il flusso principale per attivare l'anteprima e l'acquisizione di foto con un'estensione senza un 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 fotocamera. 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 elaboratore 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 actualizare 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() deve anche riflettere il risultato dell'elaborazione e restituire l'ultimo CaptureStageImpl.

  • PROCESSOR_TYPE_IMAGE_PROCESSOR: questo tipo 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 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 la seguente illustrazione:

PreviewProcessor

Figura 6. Visualizza l'anteprima del flusso 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 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:

CaptureProcessor

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 di output YUV_420_888.

  2. ImageCaptureExtenderImpl.getCaptureStages restituisce un elenco di CaptureStageImpl , in cui ogni elemento corrisponde a un'istanza di CaptureRequest con i 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 del risultato (formato YUV_420_888) sulla 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.

Vedi 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 ivi 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'estensore 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 di Advanced Extender 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 viso advanced/BeautyAdvancedExtenderImpl.java

Nell'esempio seguente utilizziamo AdvancedExtenderImpl come segnaposto. 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 di app.

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

AdvancedAppFlow1

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

AdvancedAppFlow2

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 foto. 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

AdvancedAppFlow3

Figura 10. Flusso di app 3 sull'estensore 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 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 del 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 pubblicizzate in AdvancedExtenderImpl.getAvailableCaptureRequestKeys().

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

  6. Pulizia

    Al termine di una sessione di acquisizione,SessionProcessorImpl.onCaptureSessionEnd() viene richiamato prima della chiusuraCameraCaptureSession. 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 sia per acquisire i casi d'uso. 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 plug-in 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 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 destinate rispettivamente all'anteprima, all'acquisizione di immagini e all'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 di immagini, assicurati che funzioni solo quando non è null. 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 delle immagini è 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 di EXTENSION_STRENGTH, utilizza le API di 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 all'altro, ad esempio HDR e NIGHT, a seconda delle condizioni della scena, le app di estensioni della fotocamera possono utilizzare EXTENSION_CURRENT_TYPE per visualizzare informazioni sull'estensione corrente selezionata dall'estensione AUTO.

Stima della latenza di acquisizione di foto 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:

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 foto di lunga durata. Le app possono mostrare agli utenti l'avanzamento corrente per migliorare l'esperienza 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:

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:

Supporta l'output SurfaceView

Per Android 14 e versioni successive, i client delle estensioni 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 di SurfaceView, l'implementazione dell'estensione del fornitore deve essere in grado di eseguire lo streaming e l'output dell'anteprima nelle 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à funziona interamente all'interno del framework e dello stack del fornitore e non ha alcun impatto sulle API visibili 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 la versione più recente.

Versione Funzionalità aggiunte
1.0.0
  • Verifica della versione
    • ExtensionVersionImpl
  • Prolunga di base
    • 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 di acquisizione/i risultati supportati
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys e getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys e getAvailableCaptureResultKeys
    • Nuova chiamata process() che prende ProcessResultImpl in PreviewImageProcessorImpl e CaptureProcessorImpl
    • Richiesta di supporto per il tipo di trigger
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Metadati specifici dell'estensione
  • Stime della latenza di acquisizione di foto dinamiche
  • Callback relativi all'avanzamento dell'elaborazione dell'acquisizione
  • Acquisizione di immagini fisse post-visualizzazione
  • Supporto per l'output SurfaceView
  • Tipi di sessione specifici del fornitore

Implementazione dei riferimenti

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

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

  • 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 obbligatori per rendere Image e TotalCaptureResult parcellabili.

Configurare la libreria del fornitore 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 al runtime. In Camera2, il framework carica un servizio di estensioni che dichiara anche che <uses-library>carica la stessa androidx.camera.extensions.impl libreria in fase di esecuzione.

In questo modo, le app di terze parti che utilizzano le estensioni possono caricare automaticamente la libreria del fornitore OEM. La libreria OEM è contrassegnata come facoltativa, pertanto le app possono essere eseguite sui 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 per le fotocamere 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.

Ti consigliamo di esporre il bokeh utilizzando sia la modalità Scena estesa sia le Estensioni della fotocamera perché le app potrebbero preferire utilizzare una determinata API per attivare il bokeh. Ti consigliamo di utilizzare innanzitutto la modalità Scena estesa perché è il modo più flessibile per consentire alle 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 per i 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.