Questa pagina descrive in dettaglio le differenze di versione negli HAL della fotocamera, nelle API e nei test CTS (Compatibility Test Suite) associati. Copre anche diverse modifiche architettoniche apportate per rafforzare e proteggere il framework della fotocamera in Android 7.0, il passaggio a Treble in Android 8.0 e gli aggiornamenti che i fornitori devono apportare per supportare queste modifiche nelle loro implementazioni della fotocamera.
Terminologia
In questa pagina vengono utilizzati i seguenti termini:
- API della fotocamera1
- Il framework della fotocamera a livello di app su dispositivi Android 4.4 e versioni precedenti, esposto tramite la classe
android.hardware.Camera
. - API della fotocamera2
- Il framework della fotocamera a livello di app su dispositivi Android 5.0 e versioni successive, esposto tramite il pacchetto
android.hardware.camera2
. - Fotocamera HAL
- Il livello del modulo della fotocamera implementato dai fornitori di SoC. I framework pubblici a livello di app sono basati sull'HAL della fotocamera.
- Fotocamera HAL3.1
- Versione del dispositivo fotocamera HAL rilasciata con Android 4.4.
- Fotocamera HAL3.2
- Versione del dispositivo fotocamera HAL rilasciata con Android 5.0.
- Fotocamera API1 CTS
- Set di test CTS della fotocamera che vengono eseguiti su Camera API1.
- Fotocamera API2 CTS
- Set aggiuntivo di test CTS della fotocamera che vengono eseguiti su Camera API2.
- Acuti
- Separa l'implementazione del fornitore (software di livello inferiore specifico del dispositivo scritto dai produttori di silicio) dal framework del sistema operativo Android tramite una nuova interfaccia del fornitore.
- HIDL
- Linguaggio di definizione dell'interfaccia HAL introdotto con Treble e utilizzato per specificare l'interfaccia tra un HAL e i suoi utenti.
- VTS
- Suite di test del fornitore introdotta insieme a Treble.
API della fotocamera
Android include le seguenti API della fotocamera.
API della fotocamera1
Android 5.0 ha deprecato Camera API1, che continua a essere gradualmente eliminato poiché lo sviluppo di una nuova piattaforma si concentra su Camera API2. Tuttavia, il periodo di eliminazione graduale sarà lungo e le versioni di Android continueranno a supportare le app Camera API1 per un po' di tempo. In particolare, continua il supporto per:
- Interfacce Camera API1 per app. Le app della fotocamera basate su Camera API1 dovrebbero funzionare come sui dispositivi che eseguono versioni precedenti di Android.
- Versioni HAL della fotocamera. Include il supporto per la fotocamera HAL1.0.
API della fotocamera2
Il framework Camera API2 espone all'app il controllo della fotocamera di livello inferiore, inclusi flussi di burst/streaming a copia zero efficienti e controlli per fotogramma di esposizione, guadagno, guadagni di bilanciamento del bianco, conversione del colore, riduzione del rumore, nitidezza e altro ancora. Per i dettagli, guarda la panoramica video di Google I/O .
Android 5.0 e versioni successive includono Camera API2; tuttavia, i dispositivi con Android 5.0 e versioni successive potrebbero non supportare tutte le funzionalità API2 della fotocamera. La proprietà android.info.supportedHardwareLevel
che le app possono eseguire query tramite le interfacce Camera API2 riporta uno dei seguenti livelli di supporto:
-
LEGACY
: questi dispositivi espongono funzionalità alle app tramite le interfacce Camera API2 che sono approssimativamente le stesse funzionalità di quelle esposte alle app tramite le interfacce Camera API1. Il codice dei framework legacy traduce concettualmente le chiamate Camera API2 in chiamate Camera API1; i dispositivi legacy non supportano le funzioni Camera API2 come i controlli per fotogramma. -
LIMITED
: questi dispositivi supportano alcune funzionalità di Camera API2 (ma non tutte) e devono utilizzare Camera HAL 3.2 o superiore. -
FULL
: questi dispositivi supportano tutte le principali funzionalità di Camera API2 e devono utilizzare Camera HAL 3.2 o versioni successive e Android 5.0 o versioni successive. -
LEVEL_3
: questi dispositivi supportano la rielaborazione YUV e l'acquisizione di immagini RAW, insieme a configurazioni aggiuntive del flusso di output. -
EXTERNAL
: Questi dispositivi sono simili ai dispositiviLIMITED
con alcune eccezioni; ad esempio, alcune informazioni sul sensore o sull'obiettivo potrebbero non essere riportate o avere frame rate meno stabili. Questo livello viene utilizzato per le fotocamere esterne come le webcam USB.
Le singole funzionalità sono esposte tramite la proprietà android.request.availableCapabilities
nelle interfacce Camera API2. I dispositivi FULL
richiedono, tra le altre, le funzionalità MANUAL_SENSOR
e MANUAL_POST_PROCESSING
. La funzionalità RAW
è opzionale anche per i dispositivi FULL
. I dispositivi LIMITED
possono pubblicizzare qualsiasi sottoinsieme di queste funzionalità, inclusa nessuna di esse. Tuttavia, la funzionalità BACKWARD_COMPATIBLE
deve essere sempre definita.
Il livello hardware supportato del dispositivo, così come le funzionalità specifiche di Camera API2 che supporta, sono disponibili come flag di funzionalità seguenti per consentire a Google Play di filtrare le app della fotocamera Camera API2.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
Requisiti CTS
I dispositivi con Android 5.0 e versioni successive devono superare i test della fotocamera Camera API1 CTS, Camera API2 CTS e CTS Verifier.
I dispositivi che non presentano un'implementazione Camera HAL3.2 e non sono in grado di supportare le interfacce Camera API2 complete devono comunque superare i test Camera API2 CTS. Tuttavia, il dispositivo viene eseguito in modalità Camera API2 LEGACY
(in cui le chiamate Camera API2 sono mappate concettualmente alle chiamate Camera API1), quindi tutti i test Camera API2 CTS relativi a funzioni o funzionalità oltre Camera API1 vengono automaticamente ignorati.
Sui dispositivi legacy, i test Camera API2 CTS che vengono eseguiti utilizzano le interfacce e le funzionalità dell'API1 Camera pubblica esistente senza nuovi requisiti. I bug che vengono esposti (e che causano un errore CTS Camera API2) sono bug già presenti nell'HAL Camera esistente del dispositivo e quindi verrebbero rilevati dalle app Camera API1 esistenti. Non ci aspettiamo molti bug di questa natura (tuttavia, qualsiasi bug di questo tipo deve essere corretto per superare i test Camera API2 CTS).
Requisiti VTS
I dispositivi che eseguono Android 8.0 e versioni successive con implementazioni HAL binderizzate devono superare i test Camera VTS .
Indurimento della struttura della fotocamera
Per rafforzare la sicurezza del framework dei media e della fotocamera, Android 7.0 sposta il servizio della fotocamera fuori dal mediaserver. A partire da Android 8.0, ogni Camera HAL binderizzato viene eseguito in un processo separato dal servizio fotocamera. I fornitori potrebbero dover apportare modifiche all'HAL della videocamera a seconda delle versioni dell'API e dell'HAL in uso. Le sezioni seguenti descrivono in dettaglio le modifiche dell'architettura in AP1 e AP2 per HAL1 e HAL3, oltre ai requisiti generali.
Modifiche architetturali per API1
La registrazione video API1 può presupporre che la telecamera e il codificatore video siano attivi nello stesso processo. Quando si utilizza API1 su:
- HAL3, in cui il servizio fotocamera utilizza BufferQueue per passare i buffer tra i processi, non è necessario alcun aggiornamento del fornitore .
Figura 1. Fotocamera Android 7.0 e stack multimediale in API1 su HAL3
- HAL1, che supporta il passaggio di metadati nei buffer video, i fornitori devono aggiornare l'HAL per utilizzare
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
non è più supportato in Android 7.0.)Figura 2. Fotocamera Android 7.0 e stack multimediale in API1 su HAL1
Modifiche architetturali per API2
Per API2 su HAL1 o HAL3, BufferQueue passa i buffer in modo che quei percorsi continuino a funzionare. L'architettura Android 7.0 per API2 su:
- HAL1 non è interessato dallo spostamento del servizio fotografico e non è necessario alcun aggiornamento del fornitore .
- HAL3 è interessato, ma non è necessario alcun aggiornamento del fornitore :
Figura 3. Fotocamera Android 7.0 e stack multimediale in API2 su HAL3
Requisiti addizionali
Le modifiche all'architettura apportate per rafforzare la sicurezza del framework di supporti e fotocamere includono i seguenti requisiti aggiuntivi del dispositivo.
- Generale. I dispositivi richiedono una larghezza di banda aggiuntiva a causa dell'IPC, che può influire sui casi d'uso della fotocamera sensibili al fattore tempo come la registrazione video ad alta velocità. I fornitori possono misurare l'impatto effettivo eseguendo
android.hardware.camera2.cts.PerformanceTest
e l'app Google Fotocamera per la registrazione video ad alta velocità a 120/240 FPS. I dispositivi richiedono anche una piccola quantità di RAM aggiuntiva per creare il nuovo processo. - Passa i metadati nei buffer video ( solo HAL1 ). Se HAL1 memorizza i metadati anziché i dati dei frame YUV reali nei buffer video, l'HAL deve utilizzare
kMetadataBufferTypeNativeHandleSource
come tipo di buffer dei metadati e passareVideoNativeHandleMetadata
nei buffer video. (kMetadataBufferTypeCameraSource
non è più supportato su Android 7.0.) ConVideoNativeHandleMetadata
, i framework di fotocamere e supporti sono in grado di passare i buffer video tra i processi serializzando e deserializzando correttamente gli handle nativi. - L'indirizzo dell'handle del buffer non memorizza sempre lo stesso buffer ( solo HAL3 ). Per ogni richiesta di acquisizione, HAL3 ottiene gli indirizzi degli handle del buffer. HAL non può utilizzare gli indirizzi per identificare i buffer perché gli indirizzi possono memorizzare un altro handle di buffer dopo che HAL restituisce il buffer. È necessario aggiornare l'HAL per utilizzare gli handle di buffer per identificare i buffer. Ad esempio, HAL riceve un indirizzo di handle di buffer A, che memorizza l'handle di buffer A. Dopo che HAL restituisce l'handle di buffer A, l'indirizzo di handle di buffer A può memorizzare l'handle di buffer B la prossima volta che l'HAL lo riceve.
- Aggiorna i criteri di SELinux per il cameraserver. Se le policy SELinux specifiche del dispositivo danno al mediaserver le autorizzazioni per eseguire la telecamera, è necessario aggiornare le policy SELinux per dare al cameraserver le autorizzazioni appropriate. Si sconsiglia di replicare le policy SELinux del mediaserver per il cameraserver (poiché mediaserver e cameraserver generalmente richiedono risorse diverse nel sistema). Cameraserver dovrebbe avere solo le autorizzazioni necessarie per eseguire le funzionalità della fotocamera e tutte le autorizzazioni non necessarie relative alla fotocamera in mediaserver dovrebbero essere rimosse.
- Separazione tra Camera HAL e cameraserver. Android 8.0 e versioni successive separano inoltre l'HAL della fotocamera binderizzato in un processo diverso dal server della fotocamera. IPC passa attraverso interfacce definite da HIDL .
Convalida
Per tutti i dispositivi che includono una fotocamera ed eseguono Android 7.0, verifica l'implementazione eseguendo Android 7.0 CTS. Sebbene Android 7.0 non includa nuovi test CTS che verificano le modifiche al servizio della fotocamera, i test CTS esistenti falliscono se non hai effettuato gli aggiornamenti sopra indicati.
Per tutti i dispositivi che includono una fotocamera ed eseguono Android 8.0 e versioni successive, verifica l'implementazione del fornitore eseguendo VTS.
Cronologia delle versioni HAL della fotocamera
Per un elenco dei test disponibili per la valutazione dell'HAL della fotocamera Android, vedere l' elenco di controllo per il test dell'HAL della fotocamera .
Androide 10
Android 10 introduce i seguenti aggiornamenti.
API della fotocamera
- Miglioramenti multicamera che consentono di utilizzare le telecamere fisiche singolarmente o tramite le corrispondenti telecamere logiche nascondendo gli ID delle telecamere fisiche. Vedere Supporto multicamera .
- Possibilità di verificare se una particolare configurazione di sessione è supportata senza il sovraccarico delle prestazioni dovuto alla creazione di una nuova sessione. Vedere
CameraDevice
. - Possibilità di recuperare le configurazioni di flusso consigliate per un determinato caso d'uso per rendere il client più efficiente dal punto di vista energetico e performante. Vedere
getRecommendedStreamConfigurationMap
. - Supporto per il formato immagine JPEG di profondità . Per ulteriori dettagli, vedere la specifica della profondità dinamica .
- Supporto per il formato immagine HEIC . Vedere Imaging HEIF .
- Miglioramenti della privacy. Alcune chiavi sono necessarie affinché il client disponga delle autorizzazioni
CAMERA
prima che possano essere recuperate daCameraCharacteristics
. VederegetKeysNeedingPermission
.
Fotocamera HAL
Le seguenti versioni di Camera HAL sono aggiornate in Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: le informazioni statiche sulla fotocamera per un ID fotocamera fisica che supporta un dispositivo fotocamera logico. Vedere Supporto multicamera . -
isStreamCombinationSupported
: questo metodo supporta un'API pubblica che consente ai client di interrogare se è supportata una configurazione di sessione. Vedere API per eseguire query sulle combinazioni di flussi .
ICameraDeviceSession
-
isReconfigurationNeeded
: metodo che indica al framework della telecamera se è necessaria la riconfigurazione completa del flusso per possibili nuovi valori dei parametri di sessione. Ciò consente di evitare inutili ritardi nella riconfigurazione della telecamera. Vedere Query di riconfigurazione della sessione . - API di gestione del buffer HAL : queste API consentono all'HAL della telecamera di richiedere i buffer dal framework della telecamera solo quando richiesto, invece di accoppiare ogni richiesta di acquisizione con i buffer associati in tutta la pipeline della telecamera, con conseguenti risparmi di memoria potenzialmente significativi.
-
signalStreamFlush
: segnala all'HAL che il servizio videocamera sta per eseguireconfigureStreams_3_5
e che l'HAL deve restituire tutti i buffer dei flussi designati. -
configureStreams_3_5
: simile aICameraDevice3.4.configureStreams
, ma in aggiunta, viene fornito il contatorestreamConfigCounter
per verificare la presenza di una race condition tra le chiamateconfigureStreams_3_5
esignalStreamFlush
.
-
Aggiornamenti a ICameraDeviceCallback
:
-
requestStreamBuffers
: Callback sincrono che l'HAL della telecamera chiama per chiedere al server della telecamera i buffer. VedirequestStreamBuffers
. -
returnStreamBuffers
: callback sincrono per l'HAL della telecamera per restituire i buffer di output al server della telecamera. VedireturnStreamBuffers
.
3.4
Le seguenti chiavi vengono aggiunte ai metadati della fotocamera in Android 10.
- Formati immagine
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Tag dei metadati della fotocamera
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capacità
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Valori per la chiave
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Configurazioni del flusso di profondità dinamico disponibili
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Configurazioni di flusso HEIC disponibili
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Modulo fotocamera
Le seguenti versioni del modulo della fotocamera sono aggiornate in Android 10.
2.5
- Aggiunge il metodo
notifyDeviceStateChange
per i dispositivi per notificare all'HAL della videocamera quando le modifiche fisiche, ad esempio la piegatura, influiscono sulla videocamera e sul routing.
2.4
- I dispositivi che si avviano con il livello API 29 o superiore DEVONO riportare
true
perisTorchModeSupported
.
Android9
La versione Android 9 introduce i seguenti aggiornamenti all'API2 della fotocamera e all'interfaccia HAL.
API della fotocamera
- Introduce l'API multi-camera per supportare meglio i dispositivi con più fotocamere rivolte nella stessa direzione, abilitando funzionalità come bokeh e zoom continuo. Ciò consente alle app di visualizzare più telecamere su un dispositivo come un'unica unità logica (telecamera logica). Le richieste di acquisizione possono anche essere inviate a singoli dispositivi telecamera racchiusi da una telecamera logica. Vedere Supporto multicamera .
- Introduce i parametri di sessione. I parametri di sessione sono un sottoinsieme dei parametri di acquisizione disponibili che possono causare gravi ritardi di elaborazione se modificati. Questi costi possono essere mitigati se i client trasmettono i loro valori iniziali durante l'inizializzazione della sessione di acquisizione. Vedere Parametri di sessione .
- Aggiunge le chiavi dei dati di stabilizzazione ottica (OIS) per la stabilizzazione e gli effetti a livello di app. Vedi
STATISTICS_OIS_SAMPLES
. - Aggiunge il supporto flash esterno. Vedi
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Aggiunge un intento di tracciamento del movimento in
CAPTURE_INTENT
. VediCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Depreca
LENS_RADIAL_DISTORTION
e aggiungeLENS_DISTORTION
al suo posto. - Aggiunge modalità di correzione della distorsione in
CaptureRequest
. VediDISTORTION_CORRECTION_MODE
. - Aggiunge il supporto per fotocamere USB/UVC esterne sui dispositivi supportati. Vedi
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Fotocamera HAL
3.4
Aggiornamenti a ICameraDeviceSession
-
configureStreams_3_4
: aggiunge il supporto persessionParameters
e telecamere logiche. -
processCaptureRequest_3_4
: aggiunge il supporto per l'inclusione di ID fisici della fotocamera nella struttura del flusso.
Aggiornamenti a ICameraDeviceCallback
-
processCaptureResult_3_4
: aggiunge i metadati della fotocamera fisica nei risultati dell'acquisizione.
3.3
Le seguenti chiavi vengono aggiunte ai metadati della fotocamera in Android 9.
- Capacità
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Tag dei metadati della fotocamera
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
La versione Android 8.0 introduce Treble. Con Treble, le implementazioni Camera HAL del fornitore devono essere binderizzate . Android 8.0 contiene anche questi miglioramenti chiave al servizio Fotocamera:
- Superfici condivise: abilita più superfici che condividono la stessa
OutputConfiguration
- API di sistema per modalità fotocamera personalizzate
-
onCaptureQueueEmpty
Vedere le sezioni seguenti per ulteriori informazioni su queste funzionalità.
Superfici condivise
Questa funzione consente a un solo set di buffer di gestire due output, come l'anteprima e la codifica video, riducendo il consumo di energia e memoria. Per supportare questa funzione, i produttori di dispositivi devono garantire che le loro implementazioni HAL della fotocamera e HAL gralloc possano creare buffer gralloc utilizzati da più consumatori diversi (come il compositore hardware/GPU e il codificatore video), anziché da un solo consumatore. Il servizio fotocamera passa i flag di utilizzo del consumatore all'HAL della fotocamera e all'HAL gralloc; devono allocare i giusti tipi di buffer oppure l'HAL della videocamera deve restituire un errore che indica che questa combinazione di consumatori non è supportata.
Consulta la documentazione per gli sviluppatori enableSurfaceSharing
per ulteriori dettagli.
API di sistema per modalità fotocamera personalizzate
L'API della telecamera pubblica definisce due modalità operative: registrazione ad alta velocità normale e vincolata. Hanno una semantica abbastanza diversa; ad esempio, la modalità ad alta velocità è limitata a un massimo di due uscite specifiche contemporaneamente. Vari OEM hanno espresso interesse nella definizione di altre modalità personalizzate per funzionalità specifiche dell'hardware. Sotto il cofano, la modalità è solo un numero intero passato a configure_streams
. Vedi: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
Questa funzione include una chiamata API di sistema che le app della fotocamera OEM possono utilizzare per abilitare una modalità personalizzata. Queste modalità devono iniziare con il valore intero 0x8000 per evitare conflitti con le modalità future aggiunte all'API pubblica.
Per supportare questa funzione, gli OEM devono semplicemente aggiungere la nuova modalità al loro HAL, attivata da questo numero intero passato all'HAL su configure_streams, e quindi fare in modo che la loro app per fotocamera personalizzata utilizzi l'API di sistema.
Il nome del metodo è android.hardware.camera2.CameraDevice#createCustomCaptureSession
. Vedi: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
Lo scopo di questa API è ridurre la latenza delle modifiche di controllo come lo zoom mantenendo la coda delle richieste il più vuota possibile. onCaptureQueueEmpty
non richiede lavoro HAL; era puramente un'aggiunta lato framework. Le applicazioni che vogliono trarne vantaggio devono aggiungere un listener a tale richiamata e rispondere in modo appropriato. Generalmente ciò avviene inviando un'altra richiesta di acquisizione al dispositivo della fotocamera.
Interfaccia HIDL della fotocamera
L'interfaccia Camera HIDL è una revisione completa dell'interfaccia Camera HAL che utilizza API stabili definite da HIDL. Anche tutte le funzionalità e le funzionalità della fotocamera introdotte nelle versioni legacy più recenti 3.4 e 2.4 (per il modulo della fotocamera) fanno parte delle definizioni HIDL.
3.4
Aggiunte minori ai metadati supportati e modifiche al supporto data_space:
- Aggiungi i metadati statici
ANDROID_SENSOR_OPAQUE_RAW_SIZE
come obbligatori se il formatoRAW_OPAQUE
è supportato. - Aggiungi i metadati statici
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
come obbligatori se è supportato qualsiasi formato RAW. - Cambia il campo
camera3_stream_t data_space
in una definizione più flessibile, utilizzando la definizione della versione 0 della codifica dello spazio dati. - Aggiunte di metadati generali disponibili per l'uso per HALv3.2 o versioni successive:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Revisione minore dell'HAL con funzionalità espanse:
- Aggiornamenti dell'API di rielaborazione OPAQUE e YUV.
- Supporto di base per buffer di output di profondità.
- Aggiunta del campo
data_space
acamera3_stream_t
. - Aggiunta del campo di rotazione a
camera3_stream_t
. - Aggiunta della modalità operativa di configurazione del flusso camera3 a
camera3_stream_configuration_t
.
3.2
Revisione minore dell'HAL con funzionalità espanse:
- Depreca
get_metadata_vendor_tag_ops
. Usa inveceget_vendor_tag_ops
incamera_common.h
. - Depreca
register_stream_buffers
. Tutti i buffer gralloc forniti dal framework a HAL inprocess_capture_request
possono essere nuovi in qualsiasi momento. - Aggiungi il supporto dei risultati parziali.
process_capture_result
può essere chiamato più volte con un sottoinsieme dei risultati disponibili prima che sia disponibile il risultato completo. - Aggiungi modello manuale a
camera3_request_template
. Le applicazioni possono utilizzare questo modello per controllare direttamente le impostazioni di acquisizione. - Rielaborare le specifiche bidirezionali e del flusso di input.
- Modificare il percorso di ritorno del buffer di input. Il buffer viene restituito in
process_capture_result
anziché inprocess_capture_request
.
3.1
Revisione minore dell'HAL con funzionalità espanse:
-
configure_streams
passa i flag di utilizzo del consumatore all'HAL. - flush call per eliminare tutte le richieste/buffer in corso il più velocemente possibile.
3.0
Prima revisione dell'HAL con funzionalità espanse:
- Importante modifica della versione poiché l'ABI è completamente diverso. Nessuna modifica alle capacità hardware richieste o al modello operativo dalla versione 2.0.
- Richieste di input rielaborate e interfacce della coda del flusso: il framework chiama in HAL con la richiesta successiva e i buffer del flusso già rimossi dalla coda. È incluso il supporto del framework di sincronizzazione, necessario per implementazioni efficienti.
- Trigger spostati nelle richieste, la maggior parte delle notifiche nei risultati.
- Consolidato tutti i callback nel framework in un'unica struttura e tutti i metodi di installazione in una singola chiamata
initialize()
. - Configurazione del flusso semplificata in un'unica chiamata per semplificare la gestione del flusso. I flussi bidirezionali sostituiscono il costrutto
STREAM_FROM_STREAM
. - Semantica in modalità limitata per dispositivi hardware meno recenti/limitati.
2.0
Versione iniziale di HAL con funzionalità espanse (Android 4.2) [camera2.h]:
- Sufficiente per implementare l'API
android.hardware.Camera
esistente. - Consente la coda ZSL nel livello di servizio della telecamera.
- Non testato per nuove funzionalità come il controllo dell'acquisizione manuale, l'acquisizione RAW di Bayer, la rielaborazione dei dati RAW, ecc.
1.0
HAL iniziale della fotocamera Android (Android 4.0) [camera.h]:
- Convertito dal livello di astrazione C++ CameraHardwareInterface.
- Supporta l'API
android.hardware.Camera
.
Cronologia delle versioni del modulo della fotocamera
Questa sezione contiene informazioni sulla versione del modulo per il modulo hardware della fotocamera, basato su camera_module_t.common.module_api_version
. Le due cifre esadecimali più significative rappresentano la versione principale e le due meno significative rappresentano la versione minore.
2.4
Questa versione del modulo della fotocamera aggiunge le seguenti modifiche API:
- Supporto modalità torcia. Il framework può attivare la modalità torcia per qualsiasi dispositivo fotocamera dotato di unità flash, senza aprire un dispositivo fotocamera. Il dispositivo fotocamera ha una priorità più alta nell'accedere all'unità flash rispetto al modulo fotocamera; aprendo un dispositivo telecamera si spegne la torcia se era stata abilitata tramite l'interfaccia del modulo. Quando si verificano conflitti di risorse, ad esempio
open()
viene chiamato per aprire un dispositivo della fotocamera, il modulo HAL della fotocamera deve notificare al framework tramite il callback dello stato della modalità torcia che la modalità torcia è stata disattivata. - Supporto per fotocamera esterna (ad esempio, fotocamera USB hot-plug). Gli aggiornamenti dell'API specificano che le informazioni statiche sulla videocamera sono disponibili solo quando la videocamera è collegata e pronta per l'uso per le videocamere hot plug esterne. Le chiamate per ottenere informazioni statiche sono chiamate non valide quando lo stato della videocamera non è
CAMERA_DEVICE_STATUS_PRESENT
. Il framework conta esclusivamente sui callback di modifica dello stato del dispositivo per gestire l'elenco delle telecamere esterne disponibili. - Suggerimenti per l'arbitrato della fotocamera. Aggiunge il supporto per l'indicazione esplicita del numero di dispositivi fotocamera che possono essere aperti e utilizzati contemporaneamente. Per specificare combinazioni valide di dispositivi, i campi
resource_cost
econflicting_devices
devono essere sempre impostati nella strutturacamera_info
restituita dalla chiamataget_camera_info
. - Metodo di inizializzazione del modulo. Chiamato dal servizio della telecamera dopo che il modulo HAL è stato caricato per consentire l'inizializzazione una tantum dell'HAL. Viene chiamato prima che venga richiamato qualsiasi altro metodo del modulo.
2.3
Questa versione del modulo fotocamera aggiunge il supporto per dispositivi HAL per fotocamere legacy aperte. Il framework può usarlo per aprire il dispositivo della fotocamera come dispositivo HAL versione inferiore del dispositivo HAL se lo stesso dispositivo può supportare più versioni dell'API del dispositivo. La chiamata open del modulo hardware standard ( common.methods->open
) continua ad aprire il dispositivo della fotocamera con l'ultima versione supportata, che è anche la versione elencata in camera_info_t.device_version
.
2.2
Questa versione del modulo della videocamera aggiunge il supporto per i tag del fornitore dal modulo e depreca il vecchio vendor_tag_query_ops
che in precedenza era accessibile solo con un dispositivo aperto.
2.1
Questa versione del modulo della videocamera aggiunge il supporto per i callback asincroni al framework dal modulo HAL della videocamera, che viene utilizzato per notificare al framework le modifiche allo stato del modulo della videocamera. I moduli che forniscono un metodo set_callbacks()
valido devono riportare almeno questo numero di versione.
2.0
I moduli telecamera che riportano questo numero di versione implementano la seconda versione dell'interfaccia HAL del modulo telecamera. I dispositivi fotocamera apribili tramite questo modulo possono supportare la versione 1.0 o la versione 2.0 dell'interfaccia HAL del dispositivo fotocamera. Il campo device_version
di camera_info è sempre valido; il campo static_camera_characteristics
di camera_info
è valido se il campo device_version
è 2.0 o superiore.
1.0
I moduli telecamera che riportano questi numeri di versione implementano l'interfaccia HAL del modulo telecamera iniziale. Tutti i dispositivi fotocamera apribili tramite questo modulo supportano solo la versione 1 del dispositivo fotocamera HAL. I campi device_version
e static_camera_characteristics
di camera_info
non sono validi. Solo l'API android.hardware.Camera
può essere supportata da questo modulo e dai suoi dispositivi.
Questa pagina descrive in dettaglio le differenze di versione negli HAL della fotocamera, nelle API e nei test CTS (Compatibility Test Suite) associati. Copre anche diverse modifiche architettoniche apportate per rafforzare e proteggere il framework della fotocamera in Android 7.0, il passaggio a Treble in Android 8.0 e gli aggiornamenti che i fornitori devono apportare per supportare queste modifiche nelle loro implementazioni della fotocamera.
Terminologia
In questa pagina vengono utilizzati i seguenti termini:
- API della fotocamera1
- Il framework della fotocamera a livello di app su dispositivi Android 4.4 e versioni precedenti, esposto tramite la classe
android.hardware.Camera
. - API della fotocamera2
- Il framework della fotocamera a livello di app su dispositivi Android 5.0 e versioni successive, esposto tramite il pacchetto
android.hardware.camera2
. - Fotocamera HAL
- Il livello del modulo della fotocamera implementato dai fornitori di SoC. I framework pubblici a livello di app sono basati sull'HAL della fotocamera.
- Fotocamera HAL3.1
- Versione del dispositivo fotocamera HAL rilasciata con Android 4.4.
- Fotocamera HAL3.2
- Versione del dispositivo fotocamera HAL rilasciata con Android 5.0.
- Fotocamera API1 CTS
- Set di test CTS della fotocamera che vengono eseguiti su Camera API1.
- Fotocamera API2 CTS
- Set aggiuntivo di test CTS della fotocamera che vengono eseguiti su Camera API2.
- Acuti
- Separa l'implementazione del fornitore (software di livello inferiore specifico del dispositivo scritto dai produttori di silicio) dal framework del sistema operativo Android tramite una nuova interfaccia del fornitore.
- HIDL
- Linguaggio di definizione dell'interfaccia HAL introdotto con Treble e utilizzato per specificare l'interfaccia tra un HAL e i suoi utenti.
- VTS
- Suite di test del fornitore introdotta insieme a Treble.
API della fotocamera
Android include le seguenti API della fotocamera.
API della fotocamera1
Android 5.0 ha deprecato Camera API1, che continua a essere gradualmente eliminato poiché lo sviluppo di una nuova piattaforma si concentra su Camera API2. Tuttavia, il periodo di eliminazione graduale sarà lungo e le versioni di Android continueranno a supportare le app Camera API1 per un po' di tempo. In particolare, continua il supporto per:
- Interfacce Camera API1 per app. Le app della fotocamera basate su Camera API1 dovrebbero funzionare come sui dispositivi che eseguono versioni precedenti di Android.
- Versioni HAL della fotocamera. Include il supporto per la fotocamera HAL1.0.
API della fotocamera2
Il framework Camera API2 espone all'app il controllo della fotocamera di livello inferiore, inclusi flussi di burst/streaming a copia zero efficienti e controlli per fotogramma di esposizione, guadagno, guadagni di bilanciamento del bianco, conversione del colore, riduzione del rumore, nitidezza e altro ancora. Per i dettagli, guarda la panoramica video di Google I/O .
Android 5.0 e versioni successive includono Camera API2; tuttavia, i dispositivi con Android 5.0 e versioni successive potrebbero non supportare tutte le funzionalità API2 della fotocamera. La proprietà android.info.supportedHardwareLevel
che le app possono eseguire query tramite le interfacce Camera API2 riporta uno dei seguenti livelli di supporto:
-
LEGACY
: questi dispositivi espongono funzionalità alle app tramite le interfacce Camera API2 che sono approssimativamente le stesse funzionalità di quelle esposte alle app tramite le interfacce Camera API1. Il codice dei framework legacy traduce concettualmente le chiamate Camera API2 in chiamate Camera API1; i dispositivi legacy non supportano le funzioni Camera API2 come i controlli per fotogramma. -
LIMITED
: questi dispositivi supportano alcune funzionalità di Camera API2 (ma non tutte) e devono utilizzare Camera HAL 3.2 o superiore. -
FULL
: questi dispositivi supportano tutte le principali funzionalità di Camera API2 e devono utilizzare Camera HAL 3.2 o versioni successive e Android 5.0 o versioni successive. -
LEVEL_3
: questi dispositivi supportano la rielaborazione YUV e l'acquisizione di immagini RAW, insieme a configurazioni aggiuntive del flusso di output. -
EXTERNAL
: Questi dispositivi sono simili ai dispositiviLIMITED
con alcune eccezioni; ad esempio, alcune informazioni sul sensore o sull'obiettivo potrebbero non essere riportate o avere frame rate meno stabili. Questo livello viene utilizzato per le fotocamere esterne come le webcam USB.
Le singole funzionalità sono esposte tramite la proprietà android.request.availableCapabilities
nelle interfacce Camera API2. I dispositivi FULL
richiedono, tra le altre, le funzionalità MANUAL_SENSOR
e MANUAL_POST_PROCESSING
. La funzionalità RAW
è opzionale anche per i dispositivi FULL
. I dispositivi LIMITED
possono pubblicizzare qualsiasi sottoinsieme di queste funzionalità, inclusa nessuna di esse. Tuttavia, la funzionalità BACKWARD_COMPATIBLE
deve essere sempre definita.
Il livello hardware supportato del dispositivo, così come le funzionalità specifiche di Camera API2 che supporta, sono disponibili come flag di funzionalità seguenti per consentire a Google Play di filtrare le app della fotocamera Camera API2.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
Requisiti CTS
I dispositivi con Android 5.0 e versioni successive devono superare i test della fotocamera Camera API1 CTS, Camera API2 CTS e CTS Verifier.
I dispositivi che non presentano un'implementazione Camera HAL3.2 e non sono in grado di supportare le interfacce Camera API2 complete devono comunque superare i test Camera API2 CTS. Tuttavia, il dispositivo viene eseguito in modalità Camera API2 LEGACY
(in cui le chiamate Camera API2 sono mappate concettualmente alle chiamate Camera API1), quindi tutti i test Camera API2 CTS relativi a funzioni o funzionalità oltre Camera API1 vengono automaticamente ignorati.
Sui dispositivi legacy, i test Camera API2 CTS che vengono eseguiti utilizzano le interfacce e le funzionalità dell'API1 Camera pubblica esistente senza nuovi requisiti. I bug che vengono esposti (e che causano un errore CTS Camera API2) sono bug già presenti nell'HAL Camera esistente del dispositivo e quindi verrebbero rilevati dalle app Camera API1 esistenti. Non ci aspettiamo molti bug di questa natura (tuttavia, qualsiasi bug di questo tipo deve essere corretto per superare i test Camera API2 CTS).
Requisiti VTS
I dispositivi che eseguono Android 8.0 e versioni successive con implementazioni HAL binderizzate devono superare i test Camera VTS .
Indurimento della struttura della fotocamera
Per rafforzare la sicurezza del framework dei media e della fotocamera, Android 7.0 sposta il servizio della fotocamera fuori dal mediaserver. A partire da Android 8.0, ogni Camera HAL binderizzato viene eseguito in un processo separato dal servizio fotocamera. I fornitori potrebbero dover apportare modifiche all'HAL della videocamera a seconda delle versioni dell'API e dell'HAL in uso. Le sezioni seguenti descrivono in dettaglio le modifiche dell'architettura in AP1 e AP2 per HAL1 e HAL3, oltre ai requisiti generali.
Modifiche architetturali per API1
La registrazione video API1 può presupporre che la telecamera e il codificatore video siano attivi nello stesso processo. Quando si utilizza API1 su:
- HAL3, in cui il servizio fotocamera utilizza BufferQueue per passare i buffer tra i processi, non è necessario alcun aggiornamento del fornitore .
Figura 1. Fotocamera Android 7.0 e stack multimediale in API1 su HAL3
- HAL1, che supporta il passaggio di metadati nei buffer video, i fornitori devono aggiornare l'HAL per utilizzare
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
non è più supportato in Android 7.0.)Figura 2. Fotocamera Android 7.0 e stack multimediale in API1 su HAL1
Modifiche architetturali per API2
Per API2 su HAL1 o HAL3, BufferQueue passa i buffer in modo che quei percorsi continuino a funzionare. L'architettura Android 7.0 per API2 su:
- HAL1 non è influenzato dallo spostamento del servizio fotografico e non è necessario alcun aggiornamento del fornitore .
- HAL3 è interessato, ma non è necessario alcun aggiornamento del fornitore :
Figura 3. Fotocamera Android 7.0 e stack multimediale in API2 su HAL3
Requisiti addizionali
Le modifiche all'architettura apportate per rafforzare la sicurezza del framework di supporti e fotocamere includono i seguenti requisiti aggiuntivi del dispositivo.
- Generale. Devices require additional bandwidth due to IPC, which may affect time-sensitive camera use cases such as high-speed video recording. Vendors can measure actual impact by running
android.hardware.camera2.cts.PerformanceTest
and the Google Camera app for 120/240 FPS high-speed video recording. Devices also require a small amount of additional RAM to create the new process. - Pass metadata in video buffers ( HAL1 only ). If HAL1 stores metadata instead of real YUV frame data in video buffers, the HAL must use
kMetadataBufferTypeNativeHandleSource
as the metadata buffer type and passVideoNativeHandleMetadata
in video buffers. (kMetadataBufferTypeCameraSource
is no longer supported on Android 7.0.) WithVideoNativeHandleMetadata
, camera and media frameworks are able to pass the video buffers between processes by serializing and deserializing the native handles properly. - Buffer handle address doesn't always store the same buffer ( HAL3 only ). For each capture request, HAL3 gets addresses of buffer handles. HAL can't use the addresses to identify buffers because the addresses may store another buffer handle after HAL returns the buffer. You must update the HAL to use buffer handles to identify the buffers. For example, HAL receives a buffer handle address A, which stores buffer handle A. After HAL returns buffer handle A, buffer handle address A may store buffer handle B next time the HAL receives it.
- Update SELinux policies for cameraserver. If device-specific SELinux policies give mediaserver permissions to run the camera, you must update the SELinux policies to give cameraserver proper permissions. We discourage replicating the mediaserver's SELinux policies for cameraserver (as mediaserver and cameraserver generally require different resources in the system). Cameraserver should have only the permissions needed to perform camera functionalities and any unnecessary camera-related permissions in mediaserver should be removed.
- Separation between Camera HAL and cameraserver. Android 8.0 and higher additionally separate the binderized Camera HAL in a process different from cameraserver. IPC goes through HIDL-defined interfaces.
Convalida
For all devices that include a camera and run Android 7.0, verify the implementation by running Android 7.0 CTS. Although Android 7.0 doesn't include new CTS tests that verify camera service changes, existing CTS tests fail if you haven't made the updates indicated above.
For all devices that include a camera and run Android 8.0 and higher, verify the vendor implementation by running VTS.
Camera HAL version history
For a list of tests available for evaluating the Android Camera HAL, see the Camera HAL Testing Checklist .
Android 10
Android 10 introduces the following updates.
Camera API
- Multi-camera improvements that allow physical cameras to be used individually or through corresponding logical cameras by hiding physical camera IDs. See Multi-Camera Support .
- Ability to check whether a particular session configuration is supported without the performance overhead of creating a new session. See
CameraDevice
. - Ability to retrieve recommended stream configurations for a given use case to make the client more power efficient and performant. See
getRecommendedStreamConfigurationMap
. - Support for the depth JPEG image format . For further details, see the Dynamic Depth specification .
- Support for the HEIC Image format . See HEIF Imaging .
- Privacy improvements. Certain keys are required for the client to have
CAMERA
permissions before they can be retrieved fromCameraCharacteristics
. SeegetKeysNeedingPermission
.
Camera HAL
The following Camera HAL versions are updated in Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: The static camera information for a physical camera ID backing a logical camera device. See Multi-Camera Support . -
isStreamCombinationSupported
: This method supports a public API that helps clients query if a session configuration is supported. See API to query stream combinations .
ICameraDeviceSession
-
isReconfigurationNeeded
: Method that tells the camera framework whether complete stream reconfiguration is required for possible new session parameter values. This helps avoid unnecessary camera reconfiguration delays. See Session reconfiguration query . - HAL buffer management APIs : These APIs allow the camera HAL to request buffers from the camera framework only when required instead of coupling each capture request with its associated buffers throughout the camera pipeline, resulting in potentially significant memory savings.
-
signalStreamFlush
: Signals to the HAL that the camera service is about to performconfigureStreams_3_5
and that the HAL must return all buffers of designated streams. -
configureStreams_3_5
: Similar toICameraDevice3.4.configureStreams
, but in addition, thestreamConfigCounter
counter is provided to check for a race condition between theconfigureStreams_3_5
andsignalStreamFlush
calls.
-
Updates to ICameraDeviceCallback
:
-
requestStreamBuffers
: Synchronous callback that the camera HAL calls to ask the camera server for buffers. SeerequestStreamBuffers
. -
returnStreamBuffers
: Synchronous callback for the camera HAL to return output buffers to the camera server. SeereturnStreamBuffers
.
3.4
The following keys are added to camera metadata in Android 10.
- Image formats
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Camera metadata tags
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Values for the
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
key-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Available dynamic depth stream configurations
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Available HEIC stream configurations
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Camera module
The following camera module versions are updated in Android 10.
2.5
- Adds the
notifyDeviceStateChange
method for devices to notify the camera HAL when physical changes, such as folding, affect camera and routing.
2.4
- Devices launching with API level 29 or higher MUST report
true
forisTorchModeSupported
.
Android 9
The Android 9 release introduces the following updates to the camera API2 and HAL interface.
Camera API
- Introduces the multi-camera API to better support devices with multiple cameras facing in the same direction, enabling features such as bokeh and seamless zoom. This allows apps to view multiple cameras on a device as one logical unit (logical camera). Capture requests can also be sent to individual camera devices encompassed by one logical camera. See Multi-Camera Support .
- Introduces session parameters. Session parameters are a subset of the available capture parameters that can cause severe processing delays when modified. These costs can be mitigated if clients pass their initial values during capture session initialization. See Session Parameters .
- Adds optical stabilization (OIS) data keys for app-level stabilization and effects. See
STATISTICS_OIS_SAMPLES
. - Adds external flash support. See
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Adds a motion tracking intent in
CAPTURE_INTENT
. SeeCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Deprecates
LENS_RADIAL_DISTORTION
and addsLENS_DISTORTION
in its place. - Adds distortion correction modes in
CaptureRequest
. SeeDISTORTION_CORRECTION_MODE
. - Adds support for external USB/UVC cameras on supported devices. See
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Camera HAL
3.4
Updates to ICameraDeviceSession
-
configureStreams_3_4
: Adds support forsessionParameters
and logical cameras. -
processCaptureRequest_3_4
: Adds support for including physical camera IDs in stream structure.
Updates to ICameraDeviceCallback
-
processCaptureResult_3_4
: Adds physical camera metadata in capture results.
3.3
The following keys are added to camera metadata in Android 9.
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Camera metadata tags
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
The Android 8.0 release introduces Treble. With Treble, vendor Camera HAL implementations must be binderized . Android 8.0 also contains these key enhancements to the Camera service:
- Shared surfaces: Enable multiple surfaces sharing the same
OutputConfiguration
- System API for custom camera modes
-
onCaptureQueueEmpty
See the sections below for more information on these features.
Shared surfaces
This feature enables only one set of buffers to drive two outputs, such as preview and video encoding, which lowers power and memory consumption. To support this feature, device manufacturers need to ensure their camera HAL and gralloc HAL implementations can create gralloc buffers that are used by multiple different consumers (such as the hardware composer/GPU and the video encoder), instead of just one consumer. The camera service passes the consumer usage flags to the camera HAL and the gralloc HAL; they need to either allocate the right kinds of buffers, or the camera HAL needs to return an error that this combination of consumers isn't supported.
See the enableSurfaceSharing
developer documentation for additional details.
System API for custom camera modes
The public camera API defines two operating modes: normal and constrained high-speed recording. They have fairly different semantics; for example, high-speed mode is limited to at most two specific outputs at once. Various OEMs have expressed interest in defining other custom modes for hardware-specific capabilities. Under the hood, the mode is just an integer passed to configure_streams
. See: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
This feature includes a system API call that OEM camera apps can use to enable a custom mode. These modes must start at integer value 0x8000 to avoid conflicting with future modes added to the public API.
To support this feature, OEMs merely need to add the new mode to their HAL, triggered by this integer passed to the HAL on configure_streams, and then have their custom camera app use the system API.
The method name is android.hardware.camera2.CameraDevice#createCustomCaptureSession
. See: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
The purpose of this API is to reduce the latency of control changes like zoom by keeping the request queue as empty as possible. onCaptureQueueEmpty
requires no HAL work; it was purely a framework-side addition. Applications that want to take advantage of it need to add a listener to that callback and respond appropriately. Generally that's by sending another capture request to the camera device.
Camera HIDL interface
The Camera HIDL interface is a complete overhaul of the Camera HAL interface that uses stable HIDL-defined APIs. All features and camera capabilities introduced in the most recent legacy versions 3.4 and 2.4 (for the camera module) are also part of the HIDL definitions.
3.4
Minor additions to supported metadata and changes to data_space support:
- Add
ANDROID_SENSOR_OPAQUE_RAW_SIZE
static metadata as mandatory ifRAW_OPAQUE
format is supported. - Add
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
static metadata as mandatory if any RAW format is supported. - Switch
camera3_stream_t data_space
field to a more flexible definition, using the version 0 definition of dataspace encoding. - General metadata additions which are available to use for HALv3.2 or newer:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Minor revision of expanded-capability HAL:
- OPAQUE and YUV reprocessing API updates.
- Basic support for depth output buffers.
- Addition of
data_space
field tocamera3_stream_t
. - Addition of rotation field to
camera3_stream_t
. - Addition of camera3 stream configuration operation mode to
camera3_stream_configuration_t
.
3.2
Minor revision of expanded-capability HAL:
- Deprecates
get_metadata_vendor_tag_ops
. Useget_vendor_tag_ops
incamera_common.h
instead. - Deprecates
register_stream_buffers
. All gralloc buffers provided by framework to HAL inprocess_capture_request
may be new at any time. - Add partial result support.
process_capture_result
may be called multiple times with a subset of the available results before the full result is available. - Add manual template to
camera3_request_template
. Applications may use this template to control the capture settings directly. - Rework the bidirectional and input stream specifications.
- Change the input buffer return path. The buffer is returned in
process_capture_result
instead ofprocess_capture_request
.
3.1
Minor revision of expanded-capability HAL:
-
configure_streams
passes consumer usage flags to the HAL. - flush call to drop all in-flight requests/buffers as fast as possible.
3.0
First revision of expanded-capability HAL:
- Major version change since the ABI is completely different. No change to the required hardware capabilities or operational model from 2.0.
- Reworked input request and stream queue interfaces: Framework calls into HAL with next request and stream buffers already dequeued. Sync framework support is included, necessary for efficient implementations.
- Moved triggers into requests, most notifications into results.
- Consolidated all callbacks into framework into one structure, and all setup methods into a single
initialize()
call. - Made stream configuration into a single call to simplify stream management. Bidirectional streams replace the
STREAM_FROM_STREAM
construct. - Limited mode semantics for older/limited hardware devices.
2.0
Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:
- Sufficient for implementing existing
android.hardware.Camera
API. - Allows for ZSL queue in camera service layer.
- Not tested for any new features such as manual capture control, Bayer RAW capture, reprocessing of RAW data, etc.
1.0
Initial Android camera HAL (Android 4.0) [camera.h]:
- Converted from C++ CameraHardwareInterface abstraction layer.
- Supports
android.hardware.Camera
API.
Camera module version history
This section contains module versioning information for the Camera hardware module, based on camera_module_t.common.module_api_version
. The two most significant hex digits represent the major version, and the two least significant represent the minor version.
2.4
This camera module version adds the following API changes:
- Torch mode support. The framework can turn on torch mode for any camera device that has a flash unit, without opening a camera device. The camera device has a higher priority accessing the flash unit than the camera module; opening a camera device turns off the torch if it had been enabled through the module interface. When there are any resource conflicts, such as
open()
is called to open a camera device, the camera HAL module must notify the framework through the torch mode status callback that the torch mode has been turned off. - External camera (for example, USB hot-plug camera) support. The API updates specify the camera static info is available only when camera is connected and ready to use for external hot-plug cameras. Calls to get static info are invalid calls when camera status isn't
CAMERA_DEVICE_STATUS_PRESENT
. The framework counts solely on device status change callbacks to manage the available external camera list. - Camera arbitration hints. Adds support for explicitly indicating the number of camera devices that can be simultaneously opened and used. To specify valid combinations of devices, the
resource_cost
andconflicting_devices
fields should always be set in thecamera_info
structure returned by theget_camera_info
call. - Module initialization method. Called by the camera service after the HAL module is loaded to allow for one-time initialization of the HAL. It is called before any other module methods are invoked.
2.3
This camera module version adds open legacy camera HAL device support. The framework can use it to open the camera device as lower device HAL version HAL device if the same device can support multiple device API versions. The standard hardware module open call ( common.methods->open
) continues to open the camera device with the latest supported version, which is also the version listed in camera_info_t.device_version
.
2.2
This camera module version adds vendor tag support from the module, and deprecates the old vendor_tag_query_ops
that were previously only accessible with a device open.
2.1
This camera module version adds support for asynchronous callbacks to the framework from the camera HAL module, which is used to notify the framework about changes to the camera module state. Modules that provide a valid set_callbacks()
method must report at least this version number.
2.0
Camera modules that report this version number implement the second version of the camera module HAL interface. Camera devices openable through this module may support either version 1.0 or version 2.0 of the camera device HAL interface. The device_version
field of camera_info is always valid; the static_camera_characteristics
field of camera_info
is valid if the device_version
field is 2.0 or higher.
1.0
Camera modules that report these version numbers implement the initial camera module HAL interface. All camera devices openable through this module support only version 1 of the camera device HAL. The device_version
and static_camera_characteristics
fields of camera_info
aren't valid. Only the android.hardware.Camera
API can be supported by this module and its devices.
This page details version differences in Camera HALs, APIs, and associated Compatibility Test Suite (CTS) tests. It also covers several architectural changes made to harden and secure the camera framework in Android 7.0, the switch to Treble in Android 8.0, and the updates vendors must make to support these changes in their camera implementations.
Terminology
The following terms are used on this page:
- Camera API1
- The app-level camera framework on Android 4.4 and lower devices, exposed through the
android.hardware.Camera
class. - Camera API2
- The app-level camera framework on Android 5.0 and higher devices, exposed through the
android.hardware.camera2
package. - Camera HAL
- The camera module layer implemented by SoC vendors. The app-level public frameworks are built on top of the camera HAL.
- Camera HAL3.1
- Version of the camera device HAL released with Android 4.4.
- Camera HAL3.2
- Version of the camera device HAL released with Android 5.0.
- Camera API1 CTS
- Set of camera CTS tests that run on top of Camera API1.
- Camera API2 CTS
- Additional set of camera CTS tests that run on top of Camera API2.
- Treble
- Separates the vendor implementation (device-specific, lower-level software written by silicon manufacturers) from the Android OS framework through a new vendor interface.
- HIDL
- HAL interface definition language introduced with Treble and used to specify the interface between a HAL and its users.
- VTS
- Vendor test suite introduced alongside Treble.
Camera APIs
Android includes the following camera APIs.
Camera API1
Android 5.0 deprecated Camera API1, which continues to be phased out as new platform development focuses on Camera API2. However, the phase-out period will be lengthy, and Android releases will continue to support Camera API1 apps for some time. Specifically, support continues for:
- Camera API1 interfaces for apps. Camera apps built on top of Camera API1 should work as they do on devices running lower Android release versions.
- Camera HAL versions. Includes support for Camera HAL1.0.
Camera API2
The Camera API2 framework exposes lower-level camera control to the app, including efficient zero-copy burst/streaming flows and per-frame controls of exposure, gain, white balance gains, color conversion, denoising, sharpening, and more. For details, watch the Google I/O video overview .
Android 5.0 and higher includes Camera API2; however, devices running Android 5.0 and higher may not support all Camera API2 features. The android.info.supportedHardwareLevel
property that apps can query through the Camera API2 interfaces reports one of the following support levels:
-
LEGACY
: These devices expose capabilities to apps through the Camera API2 interfaces that are approximately the same capabilities as those exposed to apps through the Camera API1 interfaces. The legacy frameworks code conceptually translates Camera API2 calls into Camera API1 calls; legacy devices don't support Camera API2 features such as per-frame controls. -
LIMITED
: These devices support some Camera API2 capabilities (but not all) and must use Camera HAL 3.2 or higher. -
FULL
: These devices support all of the major capabilities of Camera API2 and must use Camera HAL 3.2 or higher and Android 5.0 or higher. -
LEVEL_3
: These devices support YUV reprocessing and RAW image capture, along with additional output stream configurations. -
EXTERNAL
: These devices are similar toLIMITED
devices with some exceptions; for example, some sensor or lens information may not be reported or have less stable frame rates. This level is used for external cameras such as USB webcams.
Individual capabilities are exposed through the android.request.availableCapabilities
property in the Camera API2 interfaces. FULL
devices require the MANUAL_SENSOR
and MANUAL_POST_PROCESSING
capabilities, among others. The RAW
capability is optional even for FULL
devices. LIMITED
devices can advertise any subset of these capabilities, including none of them. However, the BACKWARD_COMPATIBLE
capability must always be defined.
The supported hardware level of the device, as well as the specific Camera API2 capabilities it supports, are available as the following feature flags to allow Google Play filtering of Camera API2 camera apps.
-
android.hardware.camera.hardware_level.full
-
android.hardware.camera.capability.raw
-
android.hardware.camera.capability.manual_sensor
-
android.hardware.camera.capability.manual_post_processing
CTS requirements
Devices running Android 5.0 and higher must pass the Camera API1 CTS, Camera API2 CTS, and CTS Verifier camera tests.
Devices that don't feature a Camera HAL3.2 implementation and aren't capable of supporting the full Camera API2 interfaces must still pass the Camera API2 CTS tests. However, the device runs in Camera API2 LEGACY
mode (in which the Camera API2 calls are conceptually mapped to Camera API1 calls) so any Camera API2 CTS tests related to features or capabilities beyond Camera API1 are automatically skipped.
On legacy devices, Camera API2 CTS tests that are run use the existing public Camera API1 interfaces and capabilities with no new requirements. Bugs that are exposed (and that cause a Camera API2 CTS failure) are bugs already present in the device's existing Camera HAL, and thus would be found by existing Camera API1 apps. We don't expect many bugs of this nature (however, any such bugs must be fixed to pass the Camera API2 CTS tests).
VTS requirements
Devices running Android 8.0 and higher with binderized HAL implementations must pass the Camera VTS tests .
Camera framework hardening
To harden media and camera framework security, Android 7.0 moves camera service out of mediaserver. Starting with Android 8.0, each binderized Camera HAL runs in a process separate from camera service. Vendors may need to make changes in the camera HAL depending on the API and HAL versions in use. The following sections detail architectural changes in AP1 and AP2 for HAL1 and HAL3, as well as general requirements.
Architectural changes for API1
API1 video recording may assume camera and video encoder live in the same process. When using API1 on:
- HAL3, where camera service uses BufferQueue to pass buffers between processes, no vendor update is necessary.
Figure 1. Android 7.0 camera and media stack in API1 on HAL3
- HAL1, which supports passing metadata in video buffers, vendors must update the HAL to use
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
is no longer supported in Android 7.0.)Figure 2. Android 7.0 camera and media stack in API1 on HAL1
Architectural changes for API2
For API2 on HAL1 or HAL3, BufferQueue passes buffers so those paths continue to work. The Android 7.0 architecture for API2 on:
- HAL1 isn't affected by the cameraservice move, and no vendor update is necessary.
- HAL3 is affected, but no vendor update is necessary:
Figure 3. Android 7.0 camera and media stack in API2 on HAL3
Additional requirements
The architectural changes made for hardening media and camera framework security include the following additional device requirements.
- General. Devices require additional bandwidth due to IPC, which may affect time-sensitive camera use cases such as high-speed video recording. Vendors can measure actual impact by running
android.hardware.camera2.cts.PerformanceTest
and the Google Camera app for 120/240 FPS high-speed video recording. Devices also require a small amount of additional RAM to create the new process. - Pass metadata in video buffers ( HAL1 only ). If HAL1 stores metadata instead of real YUV frame data in video buffers, the HAL must use
kMetadataBufferTypeNativeHandleSource
as the metadata buffer type and passVideoNativeHandleMetadata
in video buffers. (kMetadataBufferTypeCameraSource
is no longer supported on Android 7.0.) WithVideoNativeHandleMetadata
, camera and media frameworks are able to pass the video buffers between processes by serializing and deserializing the native handles properly. - Buffer handle address doesn't always store the same buffer ( HAL3 only ). For each capture request, HAL3 gets addresses of buffer handles. HAL can't use the addresses to identify buffers because the addresses may store another buffer handle after HAL returns the buffer. You must update the HAL to use buffer handles to identify the buffers. For example, HAL receives a buffer handle address A, which stores buffer handle A. After HAL returns buffer handle A, buffer handle address A may store buffer handle B next time the HAL receives it.
- Update SELinux policies for cameraserver. If device-specific SELinux policies give mediaserver permissions to run the camera, you must update the SELinux policies to give cameraserver proper permissions. We discourage replicating the mediaserver's SELinux policies for cameraserver (as mediaserver and cameraserver generally require different resources in the system). Cameraserver should have only the permissions needed to perform camera functionalities and any unnecessary camera-related permissions in mediaserver should be removed.
- Separation between Camera HAL and cameraserver. Android 8.0 and higher additionally separate the binderized Camera HAL in a process different from cameraserver. IPC goes through HIDL-defined interfaces.
Convalida
For all devices that include a camera and run Android 7.0, verify the implementation by running Android 7.0 CTS. Although Android 7.0 doesn't include new CTS tests that verify camera service changes, existing CTS tests fail if you haven't made the updates indicated above.
For all devices that include a camera and run Android 8.0 and higher, verify the vendor implementation by running VTS.
Camera HAL version history
For a list of tests available for evaluating the Android Camera HAL, see the Camera HAL Testing Checklist .
Android 10
Android 10 introduces the following updates.
Camera API
- Multi-camera improvements that allow physical cameras to be used individually or through corresponding logical cameras by hiding physical camera IDs. See Multi-Camera Support .
- Ability to check whether a particular session configuration is supported without the performance overhead of creating a new session. See
CameraDevice
. - Ability to retrieve recommended stream configurations for a given use case to make the client more power efficient and performant. See
getRecommendedStreamConfigurationMap
. - Support for the depth JPEG image format . For further details, see the Dynamic Depth specification .
- Support for the HEIC Image format . See HEIF Imaging .
- Privacy improvements. Certain keys are required for the client to have
CAMERA
permissions before they can be retrieved fromCameraCharacteristics
. SeegetKeysNeedingPermission
.
Camera HAL
The following Camera HAL versions are updated in Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: The static camera information for a physical camera ID backing a logical camera device. See Multi-Camera Support . -
isStreamCombinationSupported
: This method supports a public API that helps clients query if a session configuration is supported. See API to query stream combinations .
ICameraDeviceSession
-
isReconfigurationNeeded
: Method that tells the camera framework whether complete stream reconfiguration is required for possible new session parameter values. This helps avoid unnecessary camera reconfiguration delays. See Session reconfiguration query . - HAL buffer management APIs : These APIs allow the camera HAL to request buffers from the camera framework only when required instead of coupling each capture request with its associated buffers throughout the camera pipeline, resulting in potentially significant memory savings.
-
signalStreamFlush
: Signals to the HAL that the camera service is about to performconfigureStreams_3_5
and that the HAL must return all buffers of designated streams. -
configureStreams_3_5
: Similar toICameraDevice3.4.configureStreams
, but in addition, thestreamConfigCounter
counter is provided to check for a race condition between theconfigureStreams_3_5
andsignalStreamFlush
calls.
-
Updates to ICameraDeviceCallback
:
-
requestStreamBuffers
: Synchronous callback that the camera HAL calls to ask the camera server for buffers. SeerequestStreamBuffers
. -
returnStreamBuffers
: Synchronous callback for the camera HAL to return output buffers to the camera server. SeereturnStreamBuffers
.
3.4
The following keys are added to camera metadata in Android 10.
- Image formats
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Camera metadata tags
-
ANDROID_REQUEST_CHARACTERISTIC_KEYS_NEEDING_PERMISSION
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS
-
ANDROID_SCALER_AVAILABLE_RECOMMENDED_INPUT_OUTPUT_FORMATS_MAP
-
ANDROID_INFO_SUPPORTED_BUFFER_MANAGEMENT_VERSION
-
ANDROID_DEPTH_AVAILABLE_RECOMMENDED_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_MIN_FRAME_DURATIONS
-
ANDROID_LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_MIN_FRAME_DURATIONS
-
ANDROID_HEIC_AVAILABLE_HEIC_STALL_DURATIONS
-
ANDROID_HEIC_INFO_SUPPORTED
-
ANDROID_HEIC_INFO_MAX_JPEG_APP_SEGMENTS_COUNT
-
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Values for the
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
key-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Available dynamic depth stream configurations
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Available HEIC stream configurations
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Camera module
The following camera module versions are updated in Android 10.
2.5
- Adds the
notifyDeviceStateChange
method for devices to notify the camera HAL when physical changes, such as folding, affect camera and routing.
2.4
- Devices launching with API level 29 or higher MUST report
true
forisTorchModeSupported
.
Android 9
The Android 9 release introduces the following updates to the camera API2 and HAL interface.
Camera API
- Introduces the multi-camera API to better support devices with multiple cameras facing in the same direction, enabling features such as bokeh and seamless zoom. This allows apps to view multiple cameras on a device as one logical unit (logical camera). Capture requests can also be sent to individual camera devices encompassed by one logical camera. See Multi-Camera Support .
- Introduces session parameters. Session parameters are a subset of the available capture parameters that can cause severe processing delays when modified. These costs can be mitigated if clients pass their initial values during capture session initialization. See Session Parameters .
- Adds optical stabilization (OIS) data keys for app-level stabilization and effects. See
STATISTICS_OIS_SAMPLES
. - Adds external flash support. See
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Adds a motion tracking intent in
CAPTURE_INTENT
. SeeCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Deprecates
LENS_RADIAL_DISTORTION
and addsLENS_DISTORTION
in its place. - Adds distortion correction modes in
CaptureRequest
. SeeDISTORTION_CORRECTION_MODE
. - Adds support for external USB/UVC cameras on supported devices. See
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Camera HAL
3.4
Updates to ICameraDeviceSession
-
configureStreams_3_4
: Adds support forsessionParameters
and logical cameras. -
processCaptureRequest_3_4
: Adds support for including physical camera IDs in stream structure.
Updates to ICameraDeviceCallback
-
processCaptureResult_3_4
: Adds physical camera metadata in capture results.
3.3
The following keys are added to camera metadata in Android 9.
- Capabilities
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Camera metadata tags
-
ANDROID_LOGICAL_MULTI_CAMERA_PHYSICAL_IDS
-
ANDROID_LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE
-
ANDROID_DISTORTION_CORRECTION_AVAILABLE_MODES
-
ANDROID_LENS_POSE_REFERENCE
-
ANDROID_LENS_DISTORTION
-
ANDROID_REQUEST_AVAILABLE_SESSION_KEYS
-
ANDROID_REQUEST_AVAILABLE_PHYSICAL_CAMERA_REQUEST_KEYS
-
ANDROID_STATISTICS_OIS_DATA_MODE
-
ANDROID_STATISTICS_OIS_TIMESTAMPS
-
ANDROID_STATISTICS_OIS_X_SHIFTS
-
ANDROID_STATISTICS_OIS_Y_SHIFTS
-
Android 8.0
The Android 8.0 release introduces Treble. With Treble, vendor Camera HAL implementations must be binderized . Android 8.0 also contains these key enhancements to the Camera service:
- Shared surfaces: Enable multiple surfaces sharing the same
OutputConfiguration
- System API for custom camera modes
-
onCaptureQueueEmpty
See the sections below for more information on these features.
Shared surfaces
This feature enables only one set of buffers to drive two outputs, such as preview and video encoding, which lowers power and memory consumption. To support this feature, device manufacturers need to ensure their camera HAL and gralloc HAL implementations can create gralloc buffers that are used by multiple different consumers (such as the hardware composer/GPU and the video encoder), instead of just one consumer. The camera service passes the consumer usage flags to the camera HAL and the gralloc HAL; they need to either allocate the right kinds of buffers, or the camera HAL needs to return an error that this combination of consumers isn't supported.
See the enableSurfaceSharing
developer documentation for additional details.
System API for custom camera modes
The public camera API defines two operating modes: normal and constrained high-speed recording. They have fairly different semantics; for example, high-speed mode is limited to at most two specific outputs at once. Various OEMs have expressed interest in defining other custom modes for hardware-specific capabilities. Under the hood, the mode is just an integer passed to configure_streams
. See: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
This feature includes a system API call that OEM camera apps can use to enable a custom mode. These modes must start at integer value 0x8000 to avoid conflicting with future modes added to the public API.
To support this feature, OEMs merely need to add the new mode to their HAL, triggered by this integer passed to the HAL on configure_streams, and then have their custom camera app use the system API.
The method name is android.hardware.camera2.CameraDevice#createCustomCaptureSession
. See: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
The purpose of this API is to reduce the latency of control changes like zoom by keeping the request queue as empty as possible. onCaptureQueueEmpty
requires no HAL work; it was purely a framework-side addition. Applications that want to take advantage of it need to add a listener to that callback and respond appropriately. Generally that's by sending another capture request to the camera device.
Camera HIDL interface
The Camera HIDL interface is a complete overhaul of the Camera HAL interface that uses stable HIDL-defined APIs. All features and camera capabilities introduced in the most recent legacy versions 3.4 and 2.4 (for the camera module) are also part of the HIDL definitions.
3.4
Minor additions to supported metadata and changes to data_space support:
- Add
ANDROID_SENSOR_OPAQUE_RAW_SIZE
static metadata as mandatory ifRAW_OPAQUE
format is supported. - Add
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
static metadata as mandatory if any RAW format is supported. - Switch
camera3_stream_t data_space
field to a more flexible definition, using the version 0 definition of dataspace encoding. - General metadata additions which are available to use for HALv3.2 or newer:
-
ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST
-
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
-
ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL
-
ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL
-
ANDROID_SENSOR_OPAQUE_RAW_SIZE
-
ANDROID_SENSOR_OPTICAL_BLACK_REGIONS
-
3.3
Minor revision of expanded-capability HAL:
- OPAQUE and YUV reprocessing API updates.
- Basic support for depth output buffers.
- Addition of
data_space
field tocamera3_stream_t
. - Addition of rotation field to
camera3_stream_t
. - Addition of camera3 stream configuration operation mode to
camera3_stream_configuration_t
.
3.2
Minor revision of expanded-capability HAL:
- Deprecates
get_metadata_vendor_tag_ops
. Useget_vendor_tag_ops
incamera_common.h
instead. - Deprecates
register_stream_buffers
. All gralloc buffers provided by framework to HAL inprocess_capture_request
may be new at any time. - Add partial result support.
process_capture_result
may be called multiple times with a subset of the available results before the full result is available. - Add manual template to
camera3_request_template
. Applications may use this template to control the capture settings directly. - Rework the bidirectional and input stream specifications.
- Change the input buffer return path. The buffer is returned in
process_capture_result
instead ofprocess_capture_request
.
3.1
Minor revision of expanded-capability HAL:
-
configure_streams
passes consumer usage flags to the HAL. - flush call to drop all in-flight requests/buffers as fast as possible.
3.0
First revision of expanded-capability HAL:
- Major version change since the ABI is completely different. No change to the required hardware capabilities or operational model from 2.0.
- Reworked input request and stream queue interfaces: Framework calls into HAL with next request and stream buffers already dequeued. Sync framework support is included, necessary for efficient implementations.
- Moved triggers into requests, most notifications into results.
- Consolidated all callbacks into framework into one structure, and all setup methods into a single
initialize()
call. - Made stream configuration into a single call to simplify stream management. Bidirectional streams replace the
STREAM_FROM_STREAM
construct. - Limited mode semantics for older/limited hardware devices.
2.0
Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:
- Sufficient for implementing existing
android.hardware.Camera
API. - Allows for ZSL queue in camera service layer.
- Not tested for any new features such as manual capture control, Bayer RAW capture, reprocessing of RAW data, etc.
1.0
Initial Android camera HAL (Android 4.0) [camera.h]:
- Converted from C++ CameraHardwareInterface abstraction layer.
- Supports
android.hardware.Camera
API.
Camera module version history
This section contains module versioning information for the Camera hardware module, based on camera_module_t.common.module_api_version
. The two most significant hex digits represent the major version, and the two least significant represent the minor version.
2.4
This camera module version adds the following API changes:
- Torch mode support. The framework can turn on torch mode for any camera device that has a flash unit, without opening a camera device. The camera device has a higher priority accessing the flash unit than the camera module; opening a camera device turns off the torch if it had been enabled through the module interface. When there are any resource conflicts, such as
open()
is called to open a camera device, the camera HAL module must notify the framework through the torch mode status callback that the torch mode has been turned off. - External camera (for example, USB hot-plug camera) support. The API updates specify the camera static info is available only when camera is connected and ready to use for external hot-plug cameras. Calls to get static info are invalid calls when camera status isn't
CAMERA_DEVICE_STATUS_PRESENT
. The framework counts solely on device status change callbacks to manage the available external camera list. - Camera arbitration hints. Adds support for explicitly indicating the number of camera devices that can be simultaneously opened and used. To specify valid combinations of devices, the
resource_cost
andconflicting_devices
fields should always be set in thecamera_info
structure returned by theget_camera_info
call. - Module initialization method. Called by the camera service after the HAL module is loaded to allow for one-time initialization of the HAL. It is called before any other module methods are invoked.
2.3
This camera module version adds open legacy camera HAL device support. The framework can use it to open the camera device as lower device HAL version HAL device if the same device can support multiple device API versions. The standard hardware module open call ( common.methods->open
) continues to open the camera device with the latest supported version, which is also the version listed in camera_info_t.device_version
.
2.2
This camera module version adds vendor tag support from the module, and deprecates the old vendor_tag_query_ops
that were previously only accessible with a device open.
2.1
This camera module version adds support for asynchronous callbacks to the framework from the camera HAL module, which is used to notify the framework about changes to the camera module state. Modules that provide a valid set_callbacks()
method must report at least this version number.
2.0
Camera modules that report this version number implement the second version of the camera module HAL interface. Camera devices openable through this module may support either version 1.0 or version 2.0 of the camera device HAL interface. The device_version
field of camera_info is always valid; the static_camera_characteristics
field of camera_info
is valid if the device_version
field is 2.0 or higher.
1.0
Camera modules that report these version numbers implement the initial camera module HAL interface. All camera devices openable through this module support only version 1 of the camera device HAL. The device_version
and static_camera_characteristics
fields of camera_info
aren't valid. Only the android.hardware.Camera
API can be supported by this module and its devices.