Estensioni per fotocamere

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

Per un elenco di estensioni supportate, che è lo stesso per Fotocamera2 e CameraX, vedi API CameraX Extensions. Se vuoi aggiungere un'estensione, segnala un bug al Issue Tracker.

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

Architettura

Il seguente diagramma descrive l'architettura delle estensioni della fotocamera interfaccia utente o extensions-interface: Architettura

Figura 1. Diagramma dell'architettura delle estensioni della fotocamera

Come mostrato nel diagramma, per supportare le estensioni della fotocamera, devi: implementare il valore extensions-interface fornito dalla libreria dei fornitori dell'OEM. Il tuo La libreria dei fornitori OEM abilita due API: API CameraX Extensions e API Camera2 Extensions, che vengono utilizzati rispettivamente dalle app CameraX e Camera2 per accedere le estensioni del fornitore.

Implementa la libreria dei fornitori OEM

Per implementare la libreria dei fornitori OEM, copia il camera-extensions-stub in un progetto della libreria di sistema. Questi file definiscono le estensioni della fotocamera a riga di comando.

La camera-extensions-stub di file 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 extender bokeh (implementalo se è supportata l'estensione Bokeh)

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

Classi degli extender notturni (implementali se è supportata l'estensione notturna)

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

Classi di extender automatici (implementalo se è supportata l'estensione automatica)

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

Classi di extender HDR (implementalo se è supportata l'estensione HDR)

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

Classi dell'extender Ritocco viso (implementalo se è supportata l'estensione Ritocco viso)

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

Utilità (facoltativa, può essere eliminata)

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

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

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

Flusso principale

Figura 2. Implementazione delle estensioni di notte

  1. Verifica della versione:

    Camera2/X chiama ExtensionVersionImpl.checkApiVersion() per garantire che La versione extensions-interface implementata dall'OEM è compatibile con Camera2/X versioni supportate.

  2. Inizializzazione della libreria dei fornitori:

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

  3. Creare istanze di classi Extender:

    Crea un'istanza per le classi Extender per l'estensione. Esistono due estensori tipi: estensore di base ed estensore avanzato. Devi implementarne uno Tipo di estensore per tutte le estensioni. Per ulteriori informazioni, vedi Extender di base ed extender avanzato.

    Camera2/X crea un'istanza e interagisce con le classi Extender per recuperare informazioni e attivare l'estensione. Per una determinata estensione, Camera2/X può creare più volte un'istanza per le classi Extender. Di conseguenza, non devi l'inizializzazione più impegnativa nel costruttore o nella chiamata init(). Esegui le il lavoro pesante solo quando la sessione della videocamera sta per avvia, ad esempio quando onInit() viene chiamato in Basic Extender o initSession() viene chiamato in Advanced Extender.

    Per l'estensione Night, viene creata un'istanza delle seguenti classi Extender il tipo di estensore di base:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    Per il tipo di extender avanzato:

    • NightAdvancedExtenderImpl.java

  4. Verifica la disponibilità delle estensioni:

    Prima di attivare l'estensione, isExtensionAvailable() controlla se è disponibile per l'ID fotocamera specificato tramite l'estensione in esecuzione in un'istanza Compute Engine.

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

    Camera2/X chiama init() sull'istanza Extender e le passa alla fotocamera ID e CameraCharacteristics.

  6. Informazioni sulla query:

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

  7. Abilita l'estensione sull'extender:

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

    Per il tipo Advanced Extender, Camera2/X interagisce con SessionProcessorImpl per attivare l'estensione. Camera2/X recupera SessionProcessorImpl mediante la chiamata di createSessionProcessor() sul Estensore.

Le seguenti sezioni descrivono in maggiore dettaglio il flusso dell'estensione.

Verifica della versione

Quando carichi la libreria del fornitore OEM dal dispositivo in fase di runtime, Camera2/X consente di verificare se la libreria è compatibile con la versione extensions-interface. extensions-interface utilizza il controllo delle versioni semantico oppure MAJOR.MINOR.PATCH, ad esempio 1.1.0 o 1.2.0. Tuttavia, solo principale e secondaria vengono utilizzate durante la verifica della versione.

Per verificare la versione, Camera2/X chiama ExtensionVersionImpl.checkApiVersion() con i servizi Versione extensions-interface. Camera2/X utilizza quindi la versione segnalata libreria OEM per determinare se è possibile attivare l'estensione e quali funzionalità che deve richiamare.

Compatibilità con le versioni principali

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

Compatibilità con le versioni precedenti

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

Compatibilità con l'inoltro

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

Inizializzazione della libreria del fornitore

Dopo aver verificato la versione extensions-interface implementata dall'OEM , Camera2/X avvia il processo di inizializzazione. La Il metodo InitializerImpl.init() segnala alla libreria OEM che un'app sta provando per utilizzare le estensioni.

Camera2/X non effettua altre chiamate alla libreria OEM (a parte il controllo della versione) finché la libreria di fornitori dell'OEM non chiama OnExtensionsInitializedCallback.onSuccess() per notificare il completamento dell'inizializzazione.

Devi implementare InitializerImpl a partire da extensions-interface 1.1.0. Camera2/X salta l'inizializzazione della libreria se la libreria dei fornitori dell'OEM implementa extensions-interface 1.0.0.

Extender di base ed extender avanzato

Esistono due tipi di implementazione di extensions-interface: extender di base e Extender avanzato. Advanced Extender è supportato da extensions-interface 1.2.0.

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

Implementa Advanced Extender per le estensioni che richiedono la personalizzazione della videocamera2 la configurazione dello streaming e inviare richieste di acquisizione in base alle esigenze.

Consulta la seguente tabella per il confronto:

Estensore di base Extender avanzato
Configurazioni degli stream Fissa
Anteprima: PRIVATE o YUV_420_888 (se esiste un processore)
Acquisizione ancora: 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 su queste richieste. Quando viene fornito un processore per l'acquisizione delle immagini, Camera2/X puoi inviare più richieste di acquisizione e inviare tutte le immagini e i risultati al processore. Ti viene fornita un'istanza RequestProcessorImpl eseguire la richiesta di acquisizione di camera2 e ottenere risultati e immagini.

Camera2/X richiama startRepeating e startCapture on SessionProcessorImpl per indicare all'OEM di iniziare la ripetizione di anteprima e avviare la sequenza di acquisizione di fotogrammi chiave.

Hook nella pipeline della videocamera
  • onPresetSession fornisce 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 fotocamera2 personalizzata configurazione di sessione per creare la 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.
  • Prevede implementazioni basate su Camera2 per le estensioni.
  • Richiede una configurazione dello stream personalizzata, ad esempio lo streaming RAW.
  • Richiede una sequenza di acquisizione interattiva.
Versione API supportata Estensioni Camera2: Android 13 o versioni successive
Estensioni di CameraX: camera-extensions 1.1.0 o versioni successive		 Estensioni di Camera2: Android 12L o versioni successive
Estensioni di CameraX: camera-extensions 1.2.0-alpha03 o versioni successive

Flussi di app

La tabella seguente mostra tre tipi di flussi di app e i relativi corrispondenti all'API Camera Extensions. Mentre Camera2/X offre API, devi implementare correttamente la libreria dei fornitori per supportarli che descrivono più dettagliatamente in una sezione successiva.

Estensioni Fotocamera 2 Estensioni di 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 il resto delle informazioni all'interno della raccolta.

Visualizzare l'anteprima e acquisire ancora foto con l'estensione abilitata CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector

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

Estensore di base

L'interfaccia dell'estensione di base fornisce ganci in diverse posizioni della videocamera una pipeline o un blocco note personalizzato. Ogni tipo di estensione ha classi di estensione corrispondenti necessarie agli OEM. da implementare.

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

Classi di extender 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 che segue. Sostituiscili con i nomi dei clienti effettivi file che stai implementando.

Basic Extender ha le seguenti capacità:

  • Inserisci i parametri di sessione durante la configurazione di CameraCaptureSession ( onPresetSession).
  • Invia una notifica relativa agli eventi di inizio e chiusura della sessione di acquisizione e invia un singolo richiesta di notifica all'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 acquisisci comunque immagini in grado di essere elaborate YUV_420_888 stream.
di Gemini Advanced.

Vediamo in che modo Camera2/X richiama extensions-interface per raggiungere i tre flussi di app indicati sopra.

Flusso di app 1: controllare la disponibilità delle estensioni

BasicExtenderAppFlow1

Figura 3. Flusso di app 1 su Basic Extender

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

Questo è spesso il primo passaggio in cui le app controllano se l'estensione specifica sia supportato per un determinato ID videocamera prima di attivare l'estensione. Questo accade perché alcune estensioni sono supportate solo su determinati ID videocamera.

Flusso di app 2: informazioni sulle query

BasicExtenderAppFlow2

Figura 4. Flusso di app 2 su Basic Extender

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

  • Intervallo di latenza di acquisizione ancora: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange restituisce l'intervallo di la latenza di acquisizione affinché l'app valuti se è opportuno attivare l'estensione per lo scenario attuale.

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

  • Chiavi di richiesta e risultati supportate: Camera2/X richiama i seguenti metodi per recuperare l'acquisizione supportata le chiavi di richiesta e le chiavi dei risultati della tua implementazione:

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X chiama sempre init() su queste classi di extender prima di eseguire la query per ulteriori informazioni.

Flusso di app 3: anteprima/acquisizione di fotogrammi con estensione abilitata (implementazione HAL)

BasicExtenderAppFlow3

Figura 5. Flusso di app 3 su Basic Extender

Il diagramma riportato sopra illustra il flusso principale per attivare l'anteprima e l'acquisizione con un'estensione senza alcun processore. Ciò significa che la videocamera HAL elabora l'estensione.

In questo flusso, la Fotocamera 2/X chiama prima il numero init() e poi onInit per avvisarti che una sessione della videocamera sta per iniziare con le estensioni specificate. Puoi eseguire l'inizializzazione più impegnativa in onInit().

Durante la configurazione di CameraCaptureSession, Camera2/X richiama onPresetSession per ottenere i parametri di sessione. Al termine della sessione di acquisizione configurata correttamente, Camera2/X richiama onEnableSession restituendo un CaptureStageImpl che contiene i parametri di acquisizione. Fotocamera2/X invia immediatamente una singola richiesta con questi parametri di cattura per HAL Analogamente, prima di chiudere la sessione di acquisizione, Camera2/X richiama onDisableSession, quindi invia una singola richiesta con l'acquisizione restituita parametri.

La richiesta ricorrente attivata da Camera2/X contiene i parametri della richiesta restituito da PreviewExtenderImpl.getCaptureStage(). Inoltre, Capture contiene i parametri restituiti ImageCaptureExtenderImpl.getCaptureStages().

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

Anteprima processore

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

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

  • PROCESSOR_TYPE_NONE: nessun processore. Le immagini vengono elaborate nella fotocamera HAL

  • PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: il tipo di processore ti consente Aggiornare la richiesta ricorrente con i nuovi parametri della richiesta di acquisizione in base al ultimo TotalCaptureResult.

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

  • PROCESSOR_TYPE_IMAGE_PROCESSOR: questo tipo ti consente di implementare una di elaborazione per elaborare YUV_420_888 immagini e scrivere l'output in un Piattaforma PRIVATE.

    Devi implementare e restituire un PreviewImageProcessorImpl in PreviewExtenderImpl.getProcessor. Il responsabile del trattamento per l'elaborazione di YUV_420_888 immagini di input. Dovrebbe scrivere l'output Formato di anteprima PRIVATE. Fotocamera2/X utilizza invece una superficie YUV_420_888 di PRIVATE per configurare CameraCaptureSession per l'anteprima.

    Vedi l'illustrazione seguente per il flusso:

AnteprimaProcessore

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 pixel come PixelFormat.RGBA_8888.

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

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

Processore per l'acquisizione di immagini

Per l'acquisizione di immagini statiche, puoi implementare un processore restituendo un CaptureProcessorImpl utilizzando ImageCaptureExtenderImpl.getCaptureProcessor. Il processore è responsabile di elaborare un elenco di YUV_420_888 immagini acquisite e TotalCaptureResult e scrive l'output su una piattaforma YUV_420_888.

Puoi tranquillamente presumere che l'anteprima sia abilitata e in esecuzione prima di inviare acquisire ancora la richiesta.

Osserva il flusso nel diagramma seguente:

AcquisizioneProcessore

Figura 7. Acquisisci ancora il flusso con CaptureProcessorImpl

  1. Camera2/X utilizza una superficie in formato YUV_420_888 per l'acquisizione di fotogrammi da configurare la sessione di acquisizione. Camera2/X prepara CaptureProcessorImpl chiamando il numero:

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

  2. ImageCaptureExtenderImpl.getCaptureStages restituisce un elenco di CaptureStageImpl , in cui ogni elemento viene mappato a un'istanza CaptureRequest con parametri di acquisizione inviate da Camera2/X. Ad esempio, se restituisce un elenco di tre CaptureStageImpl istanze, Camera2/X invia tre richieste di acquisizione con i parametri di acquisizione corrispondenti utilizzando captureBurst tramite Google Cloud CLI o tramite l'API Compute Engine.

  3. Le immagini ricevute e TotalCaptureResult istanze sono raggruppate insieme e inviato 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.

Supporto per le chiavi di richiesta di acquisizione e i risultati

Oltre all'anteprima e all'acquisizione della fotocamera, le app possono impostare lo zoom, parametri flash o attivare un tocco per mettere a fuoco. Questi parametri potrebbero non essere compatibili con l'implementazione delle estensioni.

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

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() restituisce il valore e acquisire chiavi di richiesta di acquisizione supportate dalla tua implementazione.
  • ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() restituisce il valore delle chiavi dei risultati dell'acquisizione contenute nel risultato dell'acquisizione.

Se la fotocamera HAL elabora l'estensione, Camera2/X recupera l'acquisizione porta a CameraCaptureSession.CaptureCallback. Tuttavia, se il processore è implementato, Camera2/X recupera i risultati dell'acquisizione ProcessResultImpl , che viene passato al process() in PreviewImageProcessorImpl e CaptureProcessorImpl Sei responsabile della segnalazione il risultato dell'acquisizione tramite ProcessResultImpl a Fotocamera2/X.

Consulta la definizione dell'interfaccia CaptureProcessorImpl di seguito come esempio. In extensions-interface 1.3.0 o versioni successive, viene richiamata la seconda chiamata a 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 operazioni comuni della fotocamera come zoom, tocco per mettere a fuoco, flash ed esposizione compensazione, consigliamo di supportare i seguenti tasti per entrambe le acquisizioni richiedi e acquisisci il risultato:

  • Zoom:
      .
    • CaptureRequest#CONTROL_ZOOM_RATIO
    • CaptureRequest#SCALER_CROP_REGION
  • Tocco 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 extender di base che implementano la versione 1.2.0 o versioni precedenti, L'API Extensions supporta esplicitamente tutte le chiavi precedenti. Per extensions-interface 1.3.0, sia CameraX che Camera2 rispettano l'elenco restituito e supportare solo le chiavi che contiene. Ad esempio, se decidi di restituire solo CaptureRequest#CONTROL_ZOOM_RATIO e CaptureRequest#SCALER_CROP_REGION nell'implementazione 1.3.0, significa che per l'app è supportato solo lo zoom e il tocco per mettere a fuoco, il flash e l'esposizione non sono ammessi compensi.

Extender avanzato

Advanced Extender è un tipo di implementazione del fornitore basato sull'API Camera2. Questo tipo di extender è stato aggiunto in extensions-interface 1.2.0. In base a il produttore del dispositivo, le estensioni possono essere implementate a livello di app che dipende dai seguenti fattori:

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

  • Capacità di inviare richieste Camera2: supporta un'interazione complicata. logica in grado di inviare richieste di acquisizione con parametri basati sui risultati richieste precedenti.

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

File da implementare

Per passare all'implementazione di Advanced Extender, Metodo isAdvancedExtenderImplemented() in ExtensionVersionImpl deve restituire true. Per ogni tipo di estensione, gli OEM devono implementare il le classi di estensione corrispondenti. I file di implementazione degli extender avanzati nel pacchetto avanzato.

Classi di extender 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 dell'estensione che stai implementazione.

Vediamo in che modo Camera2/X richiama extensions-interface per raggiungere i tre i flussi di dati delle app.

Flusso di app 1: verificare la disponibilità delle estensioni

AdvancedAppFlow1

Figura 8. Flusso di app 1 su Advanced Extender

Innanzitutto, l'app controlla se l'estensione in questione è supportata.

Flusso di 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 su seguendo le informazioni su AdvancedExtenderImpl:

  • Latenza stimata di acquisizione ancora: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() restituisce l'intervallo di la latenza di acquisizione affinché l'app valuti se è opportuno attivare l'estensione per lo scenario attuale.

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

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

    • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() restituisce il valore formati e dimensioni supportati per l'acquisizione di immagini fisse. Gli OEM devono supportare entrambi Output in formato JPEG e YUV_420_888.

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

  • Chiavi/risultati della richiesta di acquisizione disponibili (aggiunti in extensions-interface 1.3.0): Camera2/X richiama i seguenti metodi per recuperare l'acquisizione supportata le chiavi di richiesta e le chiavi dei risultati della tua implementazione:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Per ulteriori informazioni, vedi Supporta le chiavi di richiesta di acquisizione e i risultati.

Flusso di app 3: Anteprima/acquisizione di ancora con estensione abilitata

AdvancedAppFlow3

Figura 10. Flusso di app 3 su Advanced Extender

Il diagramma riportato sopra mostra il flusso principale per avviare l'anteprima ed eseguire l'acquisizione per il tipo Advanced Extender. Vediamo in dettaglio ogni passaggio.

  1. Istanza SessionProcessorImpl

    L'implementazione principale di Advanced Extender è in SessionProcessorImpl, che è responsabile di fornire configurazione personalizzata della sessione e di inviare acquisire le richieste per avviare l'anteprima e acquisire comunque la richiesta. AdvancedExtenderImpl.createSessionProcessor() viene richiamato per restituire un SessionProcessorImpl istanza.

  2. initSession

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

    Per i parametri di input, Camera2/X specifica le configurazioni della superficie di output per l'anteprima, acquisire immagini statiche e un'analisi YUV facoltativa. Questo output La configurazione della superficie (OutputSurfaceImpl) contiene la superficie, le dimensioni e l'immagine recuperato con i seguenti metodi in AdvancedExtenderImpl:

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

    Devi restituire un'istanza Camera2SessionConfigImpl, composta da un elenco di Camera2OutputConfigImpl istanze e i parametri di sessione utilizzati per la configurazione di CameraCaptureSession. Sei responsabile inviare le immagini corrette della fotocamera alle superfici di output trasmesse da Fotocamera2/X. Ecco alcune opzioni per abilitare l'output:

    • Elaborazione nella fotocamera HAL: puoi aggiungere direttamente le superfici di output a CameraCaptureSession con un SurfaceOutputConfigImpl implementazione. Questa operazione configura la superficie di output fornita alla fotocamera pipeline di dati e consente alla fotocamera HAL di elaborare l'immagine.

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

      Devi elaborare le immagini intermedie e scrivere l'immagine dei risultati in la superficie di output.

    di Gemini Advanced.
    • Utilizzare la condivisione di una superficie di Fotocamera 2: utilizza la condivisione di una superficie con un'altra piattaforma aggiungendo qualsiasi istanza Camera2OutputConfigImpl getSurfaceSharingOutputConfigs() metodo di un altro Camera2OutputConfigImpl istanza. Il formato e le dimensioni della superficie devono essere identici.

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

  3. onCaptureSessionStart e RequestProcessorImpl

    Quando viene avviato CameraCaptureSession e si attiva il framework Fotocamera onConfigured(), poi Camera2/X richiama SessionProcessorImpl.onCaptureSessionStart() con la richiesta Camera2 wrapper RequestProcessImpl. Camera2/X implementa RequestProcessImpl, che ti consente di eseguire le richieste di acquisizione. recuperare immagini se viene utilizzato ImageReaderOutputConfigImpl.

    Le API RequestProcessImpl sono simili a Camera2 CameraCaptureSession API in termini di esecuzione delle richieste. Le differenze sono:

    • La superficie target è specificata dall'ID del Camera2OutputConfigImpl istanza.
    • La funzionalità di recupero dell'immagine dell'elemento ImageReader.

    Puoi chiamare RequestProcessorImpl.setImageProcessor() con un ID Camera2OutputConfigImpl in cui registrare un'istanza ImageProcessorImpl ricevere immagini.

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

  4. Avviare l'anteprima e scattare una foto

    Nell'implementazione di Advanced Extender, puoi inviare richieste di acquisizione tramite l'interfaccia RequestProcessorImpl. Camera2/X ti avvisa avvia la richiesta ricorrente per l'anteprima o la sequenza di acquisizione di fotogrammi chiave chiamata a SessionProcessorImpl#startRepeating e rispettivamente SessionProcessorImpl#startCapture. Dovresti inviare screenshot per soddisfare queste richieste di anteprima e acquisizione continua.

    Camera2/X imposta inoltre i parametri della richiesta di acquisizione tramite SessionProcessorImpl#setParameters. Devi impostare questi parametri della richiesta (se i parametri sono supportati) sia nella richiesta ricorrente che in quella singola.

    Devi supportare almeno CaptureRequest.JPEG_ORIENTATION e CaptureRequest.JPEG_QUALITY. extensions-interface 1.3.0 supporta la richiesta che sono esposte con i seguenti metodi:

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

    Quando gli sviluppatori impostano le chiavi nell'elenco getAvailableCaptureRequestKeys, devi abilitare i parametri e assicurarti che l'acquisizione Il risultato contiene le chiavi nell'elenco getAvailableCaptureResultKeys.

  5. startTrigger

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

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

  6. Pulizia

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

Supporta anteprima, acquisizione di fotogrammi e analisi delle immagini

Dovresti applicare l'estensione sia per l'anteprima che per i casi d'uso di acquisizione continua. Tuttavia, se la latenza è troppo elevata per una visualizzazione uniforme dell'anteprima, puoi e applicare l'estensione solo per l'acquisizione.

Per il tipo di estensore di base, a prescindere dall'abilitazione dell'estensione per l'anteprima, devi implementare sia ImageCaptureExtenderImpl sia PreviewExtenderImpl per una determinata estensione. Spesso, un'app usa anche uno stream YUV per analizzare contenuti di immagini come la ricerca di testo o codici QR. Per supportare meglio questo caso d'uso , dovresti supportare la combinazione di streaming di anteprima, acquisizione fissa e Flusso di YUV_420_888 per la configurazione di CameraCaptureSession. Ciò significa se implementi un processore, devi supportare il flusso di tre stream YUV_420_888.

Per Advanced Extender, Camera2/X passa tre superfici di output al Chiamata SessionProcessorImpl.initSession(). Queste piattaforme di output sono per l'anteprima , acquisizione e analisi delle immagini, rispettivamente. Devi assicurarti che l'anteprima e acquisire ancora delle sezioni di output mostrano un output valido. Tuttavia, per l'immagine superficie di output dell'analisi, assicurati che funzioni solo se è diverso da null. Se le tue implementazione non supporta lo stream di analisi delle immagini, puoi restituire un elenco in AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Questo assicura che la superficie di output dell'analisi delle immagini sia sempre nulla SessionProcessorImpl.initSession().

Supporto dell'acquisizione video

L'architettura corrente delle estensioni per la fotocamera supporta solo l'anteprima e e acquisire casi d'uso. Non supportiamo l'attivazione dell'estensione sull'MediaCodec o MediaRecorder per la registrazione del video. Tuttavia, è possibile affinché le app registrino l'output dell'anteprima.

L'assistenza per le piattaforme MediaCodec e MediaRecorder è in fase di verifica.

Metadati specifici delle estensioni

Per Android 14 e versioni successive, metadati specifici delle estensioni consente ai client delle estensioni della fotocamera di impostare e ricevere acquisizioni specifiche per le estensioni impostazioni e risultati della richiesta. Nello specifico, l'estensione fotocamera I client possono utilizzare il parametro della richiesta di acquisizione EXTENSION_STRENGTH per controllare l'efficacia dell'estensione e il risultato dell'acquisizione EXTENSION_CURRENT_TYPE indicare il tipo di estensione abilitata.

Richieste di acquisizione

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

  • BOKEH: controlla la quantità di sfocatura.
  • HDR e NIGHT: controlla la quantità di immagini unite e la luminosità delle l'immagine finale.
  • FACE_RETOUCH: controlla la quantità di miglioramento estetico e della pelle attenuazione.

L'intervallo supportato per il parametro EXTENSION_STRENGTH è compreso tra 0 e 100, con 0 che indica nessuna elaborazione delle estensioni o semplice passthrough e 100 che indica l'intensità massima dell'estensione dell'effetto di elaborazione.

Per aggiungere il supporto per EXTENSION_STRENGTH, utilizza il fornitore API di parametri specifici introdotte nella versione 1.3.0 della libreria delle estensioni a riga di comando. Per ulteriori informazioni, vedi getAvailableCaptureRequestKeys()

Acquisisci risultati

La EXTENSION_CURRENT_TYPE il risultato dell'acquisizione consente alle implementazioni delle estensioni di notificare ai client di estensione.

Perché le estensioni che utilizzano il tipo AUTO passano dinamicamente da un'estensione all'altra tipi come HDR e NIGHT in base alle condizioni della scena, estensioni che le app possono utilizzare EXTENSION_CURRENT_TYPE per visualizzare informazioni su l'estensione corrente selezionata dall'estensione AUTO.

Stima della latenza di acquisizione ancora in tempo reale

Per Android 14 e versioni successive, client di estensione della fotocamera eseguire query in tempo reale e acquisire comunque stime di latenza in base alla scena le condizioni ambientali utilizzando getRealtimeStillCaptureLatency() Questo fornisce stime più accurate rispetto al metodo getEstimatedCaptureLatencyRangeMillis() . In base alla stima della latenza, le app possono decidere di ignorare l'estensione l'elaborazione o mostrare un'indicazione per informare gli utenti di un è in esecuzione un'operazione.

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 l'acquisizione in tempo reale delle stime di latenza, implementa le seguenti:

Acquisizione dei callback di avanzamento dell'elaborazione

Per Android 14 e versioni successive, client di estensione della fotocamera può ricevere callback per l'avanzamento dell'elaborazione dell'acquisizione continua a lunga esecuzione operazioni aziendali. Le app possono mostrare l'avanzamento corrente agli utenti per migliorare in generale l'esperienza utente.

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'acquisizione, il fornitore dell'estensione l'implementazione deve chiamare i seguenti callback con lo stato di avanzamento attuale valore:

Acquisizione ancora post-visualizzazione

Per Android 14 e versioni successive, le estensioni della fotocamera possono fornisce una visualizzazione post (immagine di anteprima) utilizzando setPostviewOutputConfiguration Per migliorare l'esperienza utente, le app possono mostrare un'immagine postview come quando un'estensione riscontra una maggiore latenza di elaborazione, e sostituirla 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 ancora l'acquisizione di postview, l'implementazione del fornitore deve implementare il seguenti:

Supporta l'output di SurfaceView

Per Android 14 e versioni successive, client di estensione della fotocamera puoi utilizzare i percorsi di rendering dell'anteprima ottimizzati per potenza e prestazioni registrando un'immagine SurfaceView per l'output di anteprima per le richieste ripetute.

Per supportare l'output SurfaceView, l'implementazione dell'estensione di fornitore deve essere in grado di trasmettere flussi di dati e inviare l'anteprima a SurfaceView istanze. A verifica che questa funzionalità sia supportata, esegui SurfaceViewExtensionPreviewTest.java Modulo CTS.

Tipi di sessione specifici del fornitore

Questa 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 al posto del valore predefinito.

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

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

Cronologia delle versioni dell'interfaccia delle estensioni

La tabella riportata di seguito mostra la cronologia delle versioni dell'interfaccia delle estensioni per le videocamere. Tu devono implementare sempre la libreria del fornitore con la versione più recente.

Versione Funzionalità aggiunte
1.0.0
  • Verifica della versione
    • ExtensionVersionImpl
  • Estensore di base
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Inizializzazione della libreria
    • InitializerImpl
  • Esponi le risoluzioni supportate
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • AdvancedExtender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Ottieni una latenza di acquisizione stimata
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • Esponi le chiavi di richiesta di acquisizione/risultati supportate
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys e getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys e getAvailableCaptureResultKeys
    • Nuova chiamata process() che richiede ProcessResultImpl tra PreviewImageProcessorImpl e CaptureProcessorImpl
    • Richiesta tipo di trigger di supporto
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Metadati specifici delle estensioni
  • L'acquisizione dinamica continua delle stime di latenza
  • Acquisizione dei callback di avanzamento dell'elaborazione
  • Acquisizione ancora post-visualizzazione
  • Supporto per l'output SurfaceView
  • Tipi di sessione specifici del fornitore

Implementazione dei riferimenti

Le seguenti implementazioni della libreria di fornitori OEM sono disponibili in frameworks/ex

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

  • sample: un'implementazione di base dell'estensione di base.

  • service_based_sample: un'implementazione che dimostra come ospitare Estensioni della fotocamera in un Service Questa implementazione contiene i seguenti componenti:

    • oem_library: Una libreria OEM Camera Extensions per le API Camera2 e CameraX Extensions che implementa Extensions-Interface. Questo funge da passthrough inoltra le chiamate da Extensions-Interface al servizio. Questa libreria fornisce anche file AIDL e classi wrapper per comunicare completamente gestito di Google Cloud.

      Advanced Extender è abilitato per impostazione predefinita. Per abilitare l'extender di base, modifica ExtensionsVersionImpl#isAdvancedExtenderImplemented per restituire false.

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

Configurare la libreria del fornitore su un dispositivo

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

In questo modo le app di terze parti che utilizzano le estensioni possono caricare automaticamente l'OEM e la libreria dei fornitori. La libreria OEM è contrassegnata come facoltativa per consentire l'esecuzione delle app sui dispositivi che non hanno la raccolta sul dispositivo. Fotocamera2/X gestisce automaticamente questo comportamento quando un'app tenta di utilizzare una fotocamera dell'estensione purché il produttore del dispositivo inserisca la libreria OEM nella dispositivo in modo che possa essere rilevato dall'app.

Per configurare la libreria OEM su un dispositivo:

  1. Aggiungi un file di autorizzazione, richiesto dal tag <uses-library>, utilizzando il seguente formato: /etc/permissions/ANY_FILENAME.xml. Per ad esempio /etc/permissions/camera_extensions.xml. I file in questo fornisce una mappatura della libreria denominata in <uses-library> alla sul percorso effettivo del file sul dispositivo.

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

    • name deve essere androidx.camera.extensions.impl poiché è nella raccolta cercata da CameraX.
    • file è il percorso assoluto del file che contiene un'implementazione delle estensioni (ad es. /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 CameraX le estensioni devono avere la proprietà ro.camerax.extensions.enabled impostata su true, che consente di chiedere se un dispositivo supporta le estensioni. A tale scopo, aggiungi la seguente riga nel file di marca del dispositivo:

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

Convalida

Per testare l'implementazione della libreria di fornitori OEM durante la di sviluppo, usa l'app di esempio androidx-main/camera/integration-tests/extensionstestapp/, che viene eseguito con varie estensioni di fornitori.

Dopo aver completato l'implementazione, utilizza strumento di convalida delle estensioni per le videocamere eseguire test automatici e manuali per verificare che la libreria del fornitore sia correttamente implementato.

Modalità scena estesa rispetto alle estensioni della fotocamera

Per l'estensione bokeh, oltre a mostrarla tramite le estensioni della fotocamera, può esporre l'estensione utilizzando la modalità scena estesa, abilitata tramite il CONTROL_EXTENDED_SCENE_MODE chiave. Per ulteriori dettagli sull'implementazione, consulta l'articolo Bokeh della fotocamera.

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

Uno svantaggio della modalità scena estesa è che puoi implementarla solo videocamera HAL, il che significa che deve essere verificata per funzionare controlli ortogonali a disposizione degli sviluppatori di app.

Consigliamo di esporre il bokeh utilizzando sia la modalità scena estesa sia la fotocamera Estensioni perché le app potrebbero preferire utilizzare una determinata API per attivare il bokeh. Ti consigliamo prima di usare la modalità Scena estesa perché è la modalità un modo flessibile per attivare l'estensione bokeh nelle app. Poi puoi implementare dell'interfaccia delle estensioni della videocamera basata sulla modalità scena estesa. Se implementi l'effetto bokeh nella fotocamera HAL è difficile, ad esempio, perché richiede un post in esecuzione nel livello app per elaborare le immagini, consigliamo di implementare l'estensione bokeh utilizzando l'interfaccia Estensioni fotocamera.

Domande frequenti

Esistono limitazioni sui livelli API?

Sì. Dipende dal set di funzionalità dell'API Android richiesto dall'OEM. dell'implementazione della libreria dei fornitori. Ad esempio: ExtenderStateListener.onPresetSession() utilizza SessionConfiguration.setSessionParameters() per impostare un insieme di riferimento di tag. Questa chiamata è disponibile solo a livello API 28 e successive. Per maggiori dettagli su metodi specifici dell'interfaccia, consulta documentazione di riferimento API.