Auf dieser Seite werden Versionsunterschiede bei Kamera-HALs, APIs und zugehörigen Compatibility Test Suite (CTS) -Tests detailliert beschrieben. Es behandelt außerdem mehrere Architekturänderungen, die vorgenommen wurden, um das Kamera-Framework in Android 7.0 zu härten und zu sichern, den Wechsel zu Treble in Android 8.0 und die Aktualisierungen, die Anbieter vornehmen müssen, um diese Änderungen in ihren Kameraimplementierungen zu unterstützen.
Terminologie
Auf dieser Seite werden folgende Begriffe verwendet:
- Kamera-API1
- Das Kamera-Framework auf App-Ebene auf Geräten mit Android 4.4 und niedriger, verfügbar gemacht durch die Klasse
android.hardware.Camera
. - Kamera-API2
- Das Kamera-Framework auf App-Ebene auf Geräten mit Android 5.0 und höher, bereitgestellt über das Paket
android.hardware.camera2
. - Kamera HAL
- Die von SoC-Anbietern implementierte Kameramodulschicht. Die öffentlichen Frameworks auf App-Ebene basieren auf dem Kamera-HAL.
- Kamera HAL3.1
- Mit Android 4.4 veröffentlichte Version des Kamerageräts HAL.
- Kamera HAL3.2
- Mit Android 5.0 veröffentlichte Version des Kamerageräts HAL.
- Kamera API1 CTS
- Satz von Kamera-CTS-Tests, die auf der Kamera-API1 ausgeführt werden.
- Kamera API2 CTS
- Zusätzlicher Satz Kamera-CTS-Tests, die zusätzlich zur Kamera-API2 ausgeführt werden.
- Verdreifachen
- Trennt die Anbieterimplementierung (gerätespezifische Software auf niedrigerer Ebene, die von Siliziumherstellern geschrieben wurde) über eine neue Anbieterschnittstelle vom Android-Betriebssystem-Framework.
- HIDL
- HAL-Schnittstellendefinitionssprache, die mit Treble eingeführt wurde und zur Spezifikation der Schnittstelle zwischen einem HAL und seinen Benutzern verwendet wird.
- VTS
- Zusammen mit Treble wurde die Testsuite eines Anbieters eingeführt.
Kamera-APIs
Android umfasst die folgenden Kamera-APIs.
Kamera-API1
Android 5.0 hat die Kamera-API1 als veraltet markiert und wird weiterhin auslaufen, da sich die Entwicklung neuer Plattformen auf die Kamera-API2 konzentriert. Allerdings wird die Auslaufphase langwierig sein und Android-Releases werden noch einige Zeit lang Kamera-API1-Apps unterstützen. Konkret wird weiterhin Unterstützung für Folgendes gewährt:
- Kamera-API1-Schnittstellen für Apps. Kamera-Apps, die auf der Kamera-API1 basieren, sollten genauso funktionieren wie auf Geräten mit niedrigeren Android-Versionen.
- Kamera-HAL-Versionen. Beinhaltet Unterstützung für Kamera HAL1.0.
Kamera-API2
Das Camera API2-Framework stellt der App eine Kamerasteuerung auf niedrigerer Ebene zur Verfügung, einschließlich effizienter Zero-Copy-Burst-/Streaming-Abläufe und Einzelbildsteuerungen für Belichtung, Verstärkung, Weißabgleich, Farbkonvertierung, Rauschunterdrückung, Schärfung und mehr. Weitere Informationen finden Sie in der Google I/O-Videoübersicht .
Android 5.0 und höher enthält Camera API2; Allerdings unterstützen Geräte mit Android 5.0 und höher möglicherweise nicht alle Kamera-API2-Funktionen. Die Eigenschaft android.info.supportedHardwareLevel
, die Apps über die Kamera-API2-Schnittstellen abfragen können, meldet eine der folgenden Unterstützungsstufen:
-
LEGACY
: Diese Geräte stellen Apps über die Kamera-API2-Schnittstellen Funktionen zur Verfügung, die ungefähr den gleichen Funktionen entsprechen wie die, die Apps über die Kamera-API1-Schnittstellen zur Verfügung gestellt werden. Der Code des Legacy-Frameworks übersetzt Kamera-API2-Aufrufe konzeptionell in Kamera-API1-Aufrufe. Ältere Geräte unterstützen keine Kamera-API2-Funktionen wie die Steuerung pro Bild. -
LIMITED
: Diese Geräte unterstützen einige Kamera-API2-Funktionen (aber nicht alle) und müssen Kamera-HAL 3.2 oder höher verwenden. -
FULL
: Diese Geräte unterstützen alle wichtigen Funktionen von Camera API2 und müssen Camera HAL 3.2 oder höher und Android 5.0 oder höher verwenden. -
LEVEL_3
: Diese Geräte unterstützen YUV-Neuverarbeitung und RAW-Bilderfassung sowie zusätzliche Ausgabestream-Konfigurationen. -
EXTERNAL
: Diese Geräte ähneln mit einigen AusnahmenLIMITED
Geräten. Beispielsweise werden einige Sensor- oder Objektivinformationen möglicherweise nicht gemeldet oder die Bildraten sind weniger stabil. Diese Ebene wird für externe Kameras wie USB-Webcams verwendet.
Einzelne Funktionen werden über die Eigenschaft android.request.availableCapabilities
in den Kamera-API2-Schnittstellen verfügbar gemacht. FULL
Geräte erfordern unter anderem die Funktionen MANUAL_SENSOR
und MANUAL_POST_PROCESSING
. Die RAW
Fähigkeit ist auch für FULL
Geräte optional. LIMITED
Geräte können jede Teilmenge dieser Funktionen anbieten, auch keine davon. Die Funktion BACKWARD_COMPATIBLE
muss jedoch immer definiert sein.
Die unterstützte Hardwarestufe des Geräts sowie die spezifischen unterstützten Camera API2-Funktionen sind als folgende Funktionsflags verfügbar, um die Google Play-Filterung von Camera API2-Kamera-Apps zu ermöglichen.
-
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-Anforderungen
Geräte mit Android 5.0 und höher müssen die Kameratests Camera API1 CTS, Camera API2 CTS und CTS Verifier bestehen.
Geräte, die nicht über eine Camera HAL3.2-Implementierung verfügen und nicht in der Lage sind, die vollständigen Camera API2-Schnittstellen zu unterstützen, müssen dennoch die Camera API2 CTS-Tests bestehen. Das Gerät läuft jedoch im Camera API2 LEGACY
Modus (in dem die Camera API2-Aufrufe konzeptionell den Camera API1-Aufrufen zugeordnet sind), sodass alle Camera API2 CTS-Tests, die sich auf Funktionen oder Fähigkeiten beziehen, die über Camera API1 hinausgehen, automatisch übersprungen werden.
Auf älteren Geräten nutzen die ausgeführten Camera API2 CTS-Tests die vorhandenen öffentlichen Camera API1-Schnittstellen und -Funktionen ohne neue Anforderungen. Aufgedeckte Fehler (und die einen CTS-Fehler der Kamera-API2 verursachen) sind Fehler, die bereits im vorhandenen Kamera-HAL des Geräts vorhanden sind und daher von vorhandenen Kamera-API1-Apps gefunden werden. Wir erwarten nicht viele Fehler dieser Art (allerdings müssen solche Fehler behoben werden, um die Camera API2 CTS-Tests zu bestehen).
VTS-Anforderungen
Geräte mit Android 8.0 und höher mit binderisierten HAL-Implementierungen müssen die Kamera- VTS-Tests bestehen.
Härtung des Kameragerüsts
Um die Sicherheit des Medien- und Kamera-Frameworks zu erhöhen, entfernt Android 7.0 den Kameradienst vom Medienserver. Ab Android 8.0 wird jede binderisierte Kamera-HAL in einem vom Kameradienst getrennten Prozess ausgeführt. Abhängig von den verwendeten API- und HAL-Versionen müssen Anbieter möglicherweise Änderungen am Kamera-HAL vornehmen. In den folgenden Abschnitten werden Architekturänderungen in AP1 und AP2 für HAL1 und HAL3 sowie allgemeine Anforderungen detailliert beschrieben.
Architekturänderungen für API1
Bei der API1-Videoaufzeichnung kann davon ausgegangen werden, dass Kamera und Video-Encoder im selben Prozess aktiv sind. Bei Verwendung von API1 auf:
- HAL3, wo der Kameradienst BufferQueue verwendet, um Puffer zwischen Prozessen zu übergeben, ist kein Anbieter-Update erforderlich.
Abbildung 1. Android 7.0-Kamera und Medienstapel in API1 auf HAL3
- HAL1, das die Weitergabe von Metadaten in Videopuffern unterstützt, müssen Anbieter die HAL aktualisieren, um
kMetadataBufferTypeNativeHandleSource
zu verwenden. (kMetadataBufferTypeCameraSource
wird in Android 7.0 nicht mehr unterstützt.)Abbildung 2. Android 7.0-Kamera und Medienstapel in API1 auf HAL1
Architekturänderungen für API2
Für API2 auf HAL1 oder HAL3 übergibt BufferQueue Puffer, sodass diese Pfade weiterhin funktionieren. Die Android 7.0-Architektur für API2 auf:
- HAL1 ist von der Kameraservice-Umstellung nicht betroffen und es ist kein Anbieter-Update erforderlich.
- HAL3 ist betroffen, es ist jedoch kein Hersteller-Update erforderlich:
Abbildung 3. Android 7.0-Kamera und Medienstapel in API2 auf HAL3
Zusätzliche Anforderungen
Die architektonischen Änderungen zur Härtung der Medien- und Kamera-Framework-Sicherheit umfassen die folgenden zusätzlichen Geräteanforderungen.
- Allgemein. Geräte benötigen aufgrund von IPC zusätzliche Bandbreite, was sich auf zeitkritische Kamera-Anwendungsfälle wie die Hochgeschwindigkeits-Videoaufzeichnung auswirken kann. Anbieter können die tatsächliche Wirkung messen, indem sie
android.hardware.camera2.cts.PerformanceTest
und die Google Camera-App für Hochgeschwindigkeitsvideoaufnahmen mit 120/240 FPS ausführen. Geräte benötigen außerdem eine kleine Menge zusätzlichen RAM, um den neuen Prozess zu erstellen. - Übergeben Sie Metadaten in Videopuffern ( nur HAL1 ). Wenn HAL1 Metadaten anstelle echter YUV-Framedaten in Videopuffern speichert, muss der HAL
kMetadataBufferTypeNativeHandleSource
als Metadatenpuffertyp verwenden undVideoNativeHandleMetadata
in Videopuffern übergeben. (kMetadataBufferTypeCameraSource
wird unter Android 7.0 nicht mehr unterstützt.) MitVideoNativeHandleMetadata
können Kamera- und Medienframeworks die Videopuffer zwischen Prozessen weitergeben, indem sie die nativen Handles ordnungsgemäß serialisieren und deserialisieren. - Die Puffer-Handle-Adresse speichert nicht immer denselben Puffer ( nur HAL3 ). Für jede Erfassungsanforderung erhält HAL3 Adressen von Pufferhandles. HAL kann die Adressen nicht zur Identifizierung von Puffern verwenden, da die Adressen möglicherweise ein weiteres Pufferhandle speichern, nachdem HAL den Puffer zurückgegeben hat. Sie müssen die HAL aktualisieren, um Pufferhandles zur Identifizierung der Puffer zu verwenden. HAL empfängt beispielsweise eine Puffer-Handle-Adresse A, die Puffer-Handle A speichert. Nachdem HAL Puffer-Handle A zurückgegeben hat, speichert Puffer-Handle-Adresse A möglicherweise Puffer-Handle B, wenn der HAL das nächste Mal das Puffer-Handle A empfängt.
- Aktualisieren Sie die SELinux-Richtlinien für den Kameraserver. Wenn gerätespezifische SELinux-Richtlinien dem Medienserver Berechtigungen zum Ausführen der Kamera erteilen, müssen Sie die SELinux-Richtlinien aktualisieren, um dem Kameraserver die entsprechenden Berechtigungen zu erteilen. Wir raten davon ab, die SELinux-Richtlinien des Medienservers für den Kameraserver zu replizieren (da Medienserver und Kameraserver im Allgemeinen unterschiedliche Ressourcen im System erfordern). Der Kameraserver sollte nur über die Berechtigungen verfügen, die zum Ausführen der Kamerafunktionen erforderlich sind, und alle unnötigen kamerabezogenen Berechtigungen im Medienserver sollten entfernt werden.
- Trennung zwischen Kamera-HAL und Kameraserver. Android 8.0 und höher trennen außerdem die gebundene Kamera-HAL auf andere Weise als der Kameraserver. IPC durchläuft HIDL-definierte Schnittstellen.
Validierung
Überprüfen Sie bei allen Geräten, die über eine Kamera verfügen und Android 7.0 ausführen, die Implementierung, indem Sie Android 7.0 CTS ausführen. Obwohl Android 7.0 keine neuen CTS-Tests enthält, die Änderungen an Kameradiensten überprüfen, schlagen bestehende CTS-Tests fehl, wenn Sie die oben genannten Aktualisierungen nicht vorgenommen haben.
Überprüfen Sie bei allen Geräten, die über eine Kamera verfügen und Android 8.0 und höher ausführen, die Implementierung des Anbieters, indem Sie VTS ausführen.
Versionsgeschichte der Kamera-HAL
Eine Liste der verfügbaren Tests zur Evaluierung des Android-Kamera-HAL finden Sie in der Checkliste für Kamera-HAL-Tests .
Android 10
Android 10 führt die folgenden Updates ein.
Kamera-API
- Multi-Kamera-Verbesserungen, die es ermöglichen, physische Kameras einzeln oder über entsprechende logische Kameras zu verwenden, indem physische Kamera-IDs ausgeblendet werden. Siehe Multi-Kamera-Unterstützung .
- Möglichkeit, zu überprüfen, ob eine bestimmte Sitzungskonfiguration unterstützt wird, ohne den Leistungsaufwand beim Erstellen einer neuen Sitzung. Siehe
CameraDevice
. - Möglichkeit, empfohlene Stream-Konfigurationen für einen bestimmten Anwendungsfall abzurufen, um den Client energieeffizienter und leistungsfähiger zu machen. Siehe
getRecommendedStreamConfigurationMap
. - Unterstützung für das Tiefen-JPEG-Bildformat . Weitere Einzelheiten finden Sie in der Dynamic Depth-Spezifikation .
- Unterstützung für das HEIC-Bildformat . Siehe HEIF-Bildgebung .
- Datenschutzverbesserungen. Bestimmte Schlüssel sind erforderlich, damit der Client über
CAMERA
Berechtigungen verfügt, bevor sie vonCameraCharacteristics
abgerufen werden können. SiehegetKeysNeedingPermission
.
Kamera HAL
Die folgenden Kamera-HAL-Versionen werden in Android 10 aktualisiert.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: Die statischen Kamerainformationen für eine physische Kamera-ID, die ein logisches Kameragerät unterstützt. Siehe Multi-Kamera-Unterstützung . -
isStreamCombinationSupported
: Diese Methode unterstützt eine öffentliche API, die Clients bei der Abfrage unterstützt, ob eine Sitzungskonfiguration unterstützt wird. Siehe API zum Abfragen von Stream-Kombinationen .
ICameraDeviceSession
-
isReconfigurationNeeded
: Methode, die dem Kamera-Framework mitteilt, ob eine vollständige Stream-Neukonfiguration für mögliche neue Sitzungsparameterwerte erforderlich ist. Dies trägt dazu bei, unnötige Verzögerungen bei der Neukonfiguration der Kamera zu vermeiden. Siehe Sitzungsrekonfigurationsabfrage . - HAL-Pufferverwaltungs-APIs : Diese APIs ermöglichen es der Kamera-HAL, Puffer nur bei Bedarf vom Kamera-Framework anzufordern, anstatt jede Aufnahmeanforderung mit den zugehörigen Puffern in der gesamten Kamera-Pipeline zu koppeln, was zu potenziell erheblichen Speichereinsparungen führt.
-
signalStreamFlush
: Signalisiert der HAL, dass der Kameradienst im Begriff ist,configureStreams_3_5
auszuführen, und dass die HAL alle Puffer der angegebenen Streams zurückgeben muss. -
configureStreams_3_5
: Ähnlich wieICameraDevice3.4.configureStreams
, aber zusätzlich wird derstreamConfigCounter
Zähler bereitgestellt, um zu prüfen, ob eine Race-Bedingung zwischen den AufrufenconfigureStreams_3_5
undsignalStreamFlush
vorliegt.
-
Aktualisierungen für ICameraDeviceCallback
:
-
requestStreamBuffers
: Synchroner Rückruf, den die Kamera-HAL aufruft, um den Kameraserver nach Puffern zu fragen. SieherequestStreamBuffers
. -
returnStreamBuffers
: Synchroner Rückruf für die Kamera-HAL, um Ausgabepuffer an den Kameraserver zurückzugeben. SiehereturnStreamBuffers
.
3.4
Die folgenden Schlüssel werden den Kamerametadaten in Android 10 hinzugefügt.
- Bildformate
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Kamera-Metadaten-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
-
- Fähigkeiten
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Werte für den Schlüssel
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Verfügbare dynamische Tiefenstromkonfigurationen
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Verfügbare HEIC-Stream-Konfigurationen
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Kameramodul
Die folgenden Kameramodulversionen werden in Android 10 aktualisiert.
2.5
- Fügt die
notifyDeviceStateChange
-Methode für Geräte hinzu, um die Kamera-HAL zu benachrichtigen, wenn physische Änderungen, wie z. B. Falten, Kamera und Routing beeinflussen.
2.4
- Geräte, die mit API-Level 29 oder höher gestartet werden, MÜSSEN für
isTorchModeSupported
true
melden.
Android 9
Mit der Android 9-Version werden die folgenden Updates für die Kamera-API2- und HAL-Schnittstelle eingeführt.
Kamera-API
- Führt die Multikamera-API ein, um Geräte mit mehreren in die gleiche Richtung gerichteten Kameras besser zu unterstützen und Funktionen wie Bokeh und nahtlosen Zoom zu ermöglichen. Dadurch können Apps mehrere Kameras auf einem Gerät als eine logische Einheit (logische Kamera) anzeigen. Aufnahmeanfragen können auch an einzelne Kamerageräte gesendet werden, die von einer logischen Kamera umfasst werden. Siehe Multi-Kamera-Unterstützung .
- Führt Sitzungsparameter ein. Sitzungsparameter sind eine Teilmenge der verfügbaren Erfassungsparameter, deren Änderung zu erheblichen Verarbeitungsverzögerungen führen kann. Diese Kosten können gemindert werden, wenn Clients ihre Anfangswerte während der Initialisierung der Erfassungssitzung übergeben. Siehe Sitzungsparameter .
- Fügt optische Stabilisierungsdatenschlüssel (OIS) für Stabilisierung und Effekte auf App-Ebene hinzu. Siehe
STATISTICS_OIS_SAMPLES
. - Fügt externe Flash-Unterstützung hinzu. Siehe
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Fügt eine Bewegungsverfolgungsabsicht in
CAPTURE_INTENT
hinzu. SieheCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Verwirft
LENS_RADIAL_DISTORTION
und fügt stattdessenLENS_DISTORTION
hinzu. - Fügt Verzerrungskorrekturmodi in
CaptureRequest
hinzu. SieheDISTORTION_CORRECTION_MODE
. - Fügt Unterstützung für externe USB-/UVC-Kameras auf unterstützten Geräten hinzu. Siehe
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Kamera HAL
3.4
Aktualisierungen für ICameraDeviceSession
-
configureStreams_3_4
: Fügt Unterstützung fürsessionParameters
und logische Kameras hinzu. -
processCaptureRequest_3_4
: Fügt Unterstützung für die Einbeziehung physischer Kamera-IDs in die Stream-Struktur hinzu.
Aktualisierungen für ICameraDeviceCallback
-
processCaptureResult_3_4
: Fügt Metadaten der physischen Kamera zu den Aufnahmeergebnissen hinzu.
3.3
Die folgenden Schlüssel werden den Kamerametadaten in Android 9 hinzugefügt.
- Fähigkeiten
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Kamera-Metadaten-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
Mit der Android 8.0-Version wird Treble eingeführt. Bei Treble müssen Kamera-HAL-Implementierungen des Anbieters binderisiert werden. Android 8.0 enthält außerdem diese wichtigen Verbesserungen des Kameradienstes:
- Gemeinsame Oberflächen: Aktivieren Sie mehrere Oberflächen, die dieselbe
OutputConfiguration
teilen - System-API für benutzerdefinierte Kameramodi
-
onCaptureQueueEmpty
Weitere Informationen zu diesen Funktionen finden Sie in den folgenden Abschnitten.
Gemeinsame Oberflächen
Mit dieser Funktion kann nur ein Puffersatz zwei Ausgaben steuern, z. B. Vorschau und Videokodierung, was den Strom- und Speicherverbrauch senkt. Um diese Funktion zu unterstützen, müssen Gerätehersteller sicherstellen, dass ihre Kamera-HAL- und Gralloc-HAL-Implementierungen Gralloc-Puffer erstellen können, die von mehreren verschiedenen Verbrauchern (z. B. dem Hardware-Composer/GPU und dem Video-Encoder) und nicht nur einem Verbraucher verwendet werden. Der Kameradienst übergibt die Verbrauchernutzungsflags an die Kamera-HAL und die Gralloc-HAL. Sie müssen entweder die richtigen Puffertypen zuweisen oder der Kamera-HAL muss einen Fehler zurückgeben, dass diese Kombination von Verbrauchern nicht unterstützt wird.
Weitere Einzelheiten finden Sie in der Entwicklerdokumentation enableSurfaceSharing
.
System-API für benutzerdefinierte Kameramodi
Die öffentliche Kamera-API definiert zwei Betriebsmodi: normale und eingeschränkte Hochgeschwindigkeitsaufzeichnung. Sie haben eine ziemlich unterschiedliche Semantik; Beispielsweise ist der Hochgeschwindigkeitsmodus auf höchstens zwei bestimmte Ausgänge gleichzeitig beschränkt. Verschiedene OEMs haben Interesse an der Definition anderer benutzerdefinierter Modi für hardwarespezifische Funktionen bekundet. Unter der Haube ist der Modus nur eine Ganzzahl, die an configure_streams
übergeben wird. Siehe: hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
Diese Funktion umfasst einen System-API-Aufruf, den OEM-Kamera-Apps verwenden können, um einen benutzerdefinierten Modus zu aktivieren. Diese Modi müssen mit dem Ganzzahlwert 0x8000 beginnen, um Konflikte mit zukünftigen Modi zu vermeiden, die der öffentlichen API hinzugefügt werden.
Um diese Funktion zu unterstützen, müssen OEMs lediglich den neuen Modus zu ihrem HAL hinzufügen, ausgelöst durch diese Ganzzahl, die auf configure_streams an den HAL übergeben wird, und dann ihre benutzerdefinierte Kamera-App die System-API verwenden lassen.
Der Methodenname lautet android.hardware.camera2.CameraDevice#createCustomCaptureSession
. Siehe: frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
Der Zweck dieser API besteht darin, die Latenz von Steueränderungen wie Zoom zu reduzieren, indem die Anforderungswarteschlange so leer wie möglich gehalten wird. onCaptureQueueEmpty
erfordert keine HAL-Arbeit; Es handelte sich lediglich um eine Framework-seitige Ergänzung. Anwendungen, die davon profitieren möchten, müssen diesem Rückruf einen Listener hinzufügen und entsprechend reagieren. Im Allgemeinen erfolgt dies durch Senden einer weiteren Aufnahmeanforderung an das Kameragerät.
Kamera-HIDL-Schnittstelle
Die Camera HIDL-Schnittstelle ist eine komplette Überarbeitung der Camera HAL-Schnittstelle, die stabile HIDL-definierte APIs verwendet. Alle Funktionen und Kamerafunktionen, die in den neuesten Legacy-Versionen 3.4 und 2.4 (für das Kameramodul) eingeführt wurden, sind auch Teil der HIDL-Definitionen.
3.4
Kleinere Ergänzungen zu unterstützten Metadaten und Änderungen an der data_space-Unterstützung:
- Fügen Sie die statischen Metadaten
ANDROID_SENSOR_OPAQUE_RAW_SIZE
als obligatorisch hinzu, wennRAW_OPAQUE
Format unterstützt wird. - Fügen Sie die statischen Metadaten
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
als obligatorisch hinzu, wenn ein RAW-Format unterstützt wird. - Stellen Sie das Feld
camera3_stream_t data_space
auf eine flexiblere Definition um und verwenden Sie die Version 0-Definition der Datenraumkodierung. - Allgemeine Metadaten-Ergänzungen, die für HALv3.2 oder neuer verfügbar sind:
-
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
Kleinere Überarbeitung des HAL mit erweiterten Funktionen:
- OPAQUE- und YUV-Wiederverarbeitungs-API-Updates.
- Grundlegende Unterstützung für Tiefenausgabepuffer.
- Hinzufügung des Feldes
data_space
zucamera3_stream_t
. - Hinzufügung eines Rotationsfelds zu
camera3_stream_t
. - Hinzufügung des Betriebsmodus „Kamera3-Stream-Konfiguration“ zu
camera3_stream_configuration_t
.
3.2
Kleinere Überarbeitung des HAL mit erweiterten Funktionen:
-
get_metadata_vendor_tag_ops
ist veraltet. Verwenden Sie stattdessenget_vendor_tag_ops
incamera_common.h
. -
register_stream_buffers
ist veraltet. Alle vom Framework für HAL inprocess_capture_request
bereitgestellten Gralloc-Puffer können jederzeit neu sein. - Teilergebnisunterstützung hinzufügen.
process_capture_result
kann mehrmals mit einer Teilmenge der verfügbaren Ergebnisse aufgerufen werden, bevor das vollständige Ergebnis verfügbar ist. - Manuelle Vorlage zu
camera3_request_template
hinzufügen. Anwendungen können diese Vorlage verwenden, um die Aufnahmeeinstellungen direkt zu steuern. - Überarbeiten Sie die bidirektionalen und Eingabestream-Spezifikationen.
- Ändern Sie den Rückgabepfad des Eingabepuffers. Der Puffer wird in
process_capture_result
anstelle vonprocess_capture_request
zurückgegeben.
3.1
Kleinere Überarbeitung des HAL mit erweiterten Funktionen:
-
configure_streams
übergibt Verbrauchernutzungsflags an die HAL. - Flush-Aufruf, um alle In-Flight-Anfragen/Puffer so schnell wie möglich zu löschen.
3,0
Erste Überarbeitung des HAL mit erweiterten Funktionen:
- Große Versionsänderung, da das ABI völlig anders ist. Keine Änderung der erforderlichen Hardwarefunktionen oder des Betriebsmodells gegenüber 2.0.
- Überarbeitete Eingabeanforderungs- und Stream-Warteschlangenschnittstellen: Framework-Aufrufe in HAL mit bereits aus der Warteschlange entfernten nächsten Anforderungs- und Stream-Puffer. Die Unterstützung des Sync-Frameworks ist enthalten, was für effiziente Implementierungen erforderlich ist.
- Auslöser wurden in Anfragen verschoben, die meisten Benachrichtigungen in Ergebnisse.
- Alle Rückrufe im Framework in einer Struktur und alle Setup-Methoden in einem einzigen
initialize()
Aufruf zusammengefasst. - Die Stream-Konfiguration wurde in einem einzigen Aufruf zusammengefasst, um die Stream-Verwaltung zu vereinfachen. Bidirektionale Streams ersetzen das
STREAM_FROM_STREAM
-Konstrukt. - Semantik des eingeschränkten Modus für ältere/eingeschränkte Hardwaregeräte.
2,0
Erstveröffentlichung von HAL mit erweiterten Funktionen (Android 4.2) [camera2.h]:
- Ausreichend für die Implementierung der vorhandenen
android.hardware.Camera
API. - Ermöglicht die ZSL-Warteschlange in der Kameradienstschicht.
- Nicht auf neue Funktionen wie manuelle Erfassungssteuerung, Bayer RAW-Erfassung, Neuverarbeitung von RAW-Daten usw. getestet.
1,0
Anfänglicher Android-Kamera-HAL (Android 4.0) [camera.h]:
- Konvertiert aus der C++-CameraHardwareInterface-Abstraktionsschicht.
- Unterstützt
android.hardware.Camera
API.
Versionsgeschichte des Kameramoduls
Dieser Abschnitt enthält Informationen zur Modulversionierung für das Kamera-Hardwaremodul, basierend auf camera_module_t.common.module_api_version
. Die beiden höchstwertigen Hexadezimalziffern repräsentieren die Hauptversion und die beiden niedrigstwertigen stellen die Nebenversion dar.
2.4
Diese Kameramodulversion fügt die folgenden API-Änderungen hinzu:
- Unterstützung für den Taschenlampenmodus. Das Framework kann den Taschenlampenmodus für jedes Kameragerät mit Blitzgerät aktivieren, ohne ein Kameragerät öffnen zu müssen. Das Kameragerät hat beim Zugriff auf das Blitzgerät eine höhere Priorität als das Kameramodul. Durch Öffnen eines Kamerageräts wird die Taschenlampe ausgeschaltet, wenn dies über die Modulschnittstelle aktiviert wurde. Wenn es Ressourcenkonflikte gibt, beispielsweise wenn
open()
aufgerufen wird, um ein Kameragerät zu öffnen, muss das Kamera-HAL-Modul das Framework über den Taschenlampenmodus-Statusrückruf darüber informieren, dass der Taschenlampenmodus ausgeschaltet wurde. - Unterstützung für externe Kameras (z. B. USB-Hot-Plug-Kamera). Die API-Updates geben an, dass die statischen Kamerainformationen nur verfügbar sind, wenn die Kamera angeschlossen und für externe Hot-Plug-Kameras einsatzbereit ist. Aufrufe zum Abrufen statischer Informationen sind ungültige Aufrufe, wenn der Kamerastatus nicht
CAMERA_DEVICE_STATUS_PRESENT
lautet. Das Framework verlässt sich ausschließlich auf Rückrufe zur Änderung des Gerätestatus, um die verfügbare Liste externer Kameras zu verwalten. - Hinweise zur Kamera-Schiedsgerichtsbarkeit. Integriert die Unterstützung für die explizite Angabe der Anzahl der Kamerageräte, die gleichzeitig geöffnet und verwendet werden können. Um gültige Gerätekombinationen anzugeben, sollten die Felder
resource_cost
“ undconflicting_devices
“ immer in der Struktur „camera_info
festgelegt werden, die vom Aufrufget_camera_info
zurückgegeben wird. - Modulinitialisierungsmethode. Wird vom Kameradienst aufgerufen, nachdem das HAL-Modul geladen wurde, um eine einmalige Initialisierung des HAL zu ermöglichen. Es wird aufgerufen, bevor andere Modulmethoden aufgerufen werden.
2.3
Diese Kameramodulversion bietet Unterstützung für offene Legacy-Kamera-HAL-Geräte. Das Framework kann damit das Kameragerät als HAL-Gerät mit niedrigerer Geräteversion öffnen, wenn dasselbe Gerät mehrere Geräte-API-Versionen unterstützen kann. Der Standardaufruf zum Öffnen des Hardwaremoduls ( common.methods->open
) öffnet das Kameragerät weiterhin mit der neuesten unterstützten Version, bei der es sich auch um die in camera_info_t.device_version
aufgeführte Version handelt.
2.2
Diese Kameramodulversion fügt Hersteller-Tag-Unterstützung vom Modul hinzu und veraltet die alten vendor_tag_query_ops
, auf die zuvor nur bei geöffnetem Gerät zugegriffen werden konnte.
2.1
Diese Kameramodulversion fügt dem Framework Unterstützung für asynchrone Rückrufe vom Kamera-HAL-Modul hinzu, die verwendet werden, um das Framework über Änderungen am Kameramodulstatus zu benachrichtigen. Module, die eine gültige set_callbacks()
Methode bereitstellen, müssen mindestens diese Versionsnummer melden.
2,0
Kameramodule, die diese Versionsnummer melden, implementieren die zweite Version der HAL-Schnittstelle des Kameramoduls. Kamerageräte, die über dieses Modul geöffnet werden können, unterstützen möglicherweise entweder Version 1.0 oder Version 2.0 der HAL-Schnittstelle des Kamerageräts. Das Feld device_version
von camera_info ist immer gültig; Das Feld „ static_camera_characteristics
von camera_info
ist gültig, wenn das Feld „ device_version
“ 2.0 oder höher ist.
1,0
Kameramodule, die diese Versionsnummern melden, implementieren die anfängliche HAL-Schnittstelle des Kameramoduls. Alle Kamerageräte, die über dieses Modul geöffnet werden können, unterstützen nur Version 1 des Kamerageräts HAL. Die Felder device_version
und static_camera_characteristics
von camera_info
sind ungültig. Nur die android.hardware.Camera
API kann von diesem Modul und seinen Geräten unterstützt werden.
Auf dieser Seite werden Versionsunterschiede bei Kamera-HALs, APIs und zugehörigen Compatibility Test Suite (CTS) -Tests detailliert beschrieben. Es behandelt außerdem mehrere Architekturänderungen, die vorgenommen wurden, um das Kamera-Framework in Android 7.0 zu härten und zu sichern, den Wechsel zu Treble in Android 8.0 und die Aktualisierungen, die Anbieter vornehmen müssen, um diese Änderungen in ihren Kameraimplementierungen zu unterstützen.
Terminologie
Auf dieser Seite werden folgende Begriffe verwendet:
- Kamera-API1
- Das Kamera-Framework auf App-Ebene auf Geräten mit Android 4.4 und niedriger, verfügbar gemacht durch die Klasse
android.hardware.Camera
. - Kamera-API2
- Das Kamera-Framework auf App-Ebene auf Geräten mit Android 5.0 und höher, bereitgestellt über das Paket
android.hardware.camera2
. - Kamera HAL
- Die von SoC-Anbietern implementierte Kameramodulschicht. Die öffentlichen Frameworks auf App-Ebene basieren auf dem Kamera-HAL.
- Kamera HAL3.1
- Mit Android 4.4 veröffentlichte Version des Kamerageräts HAL.
- Kamera HAL3.2
- Mit Android 5.0 veröffentlichte Version des Kamerageräts HAL.
- Kamera API1 CTS
- Satz von Kamera-CTS-Tests, die auf der Kamera-API1 ausgeführt werden.
- Kamera API2 CTS
- Zusätzlicher Satz Kamera-CTS-Tests, die zusätzlich zur Kamera-API2 ausgeführt werden.
- Verdreifachen
- Trennt die Anbieterimplementierung (gerätespezifische Software auf niedrigerer Ebene, die von Siliziumherstellern geschrieben wurde) über eine neue Anbieterschnittstelle vom Android-Betriebssystem-Framework.
- HIDL
- HAL-Schnittstellendefinitionssprache, die mit Treble eingeführt wurde und zur Spezifikation der Schnittstelle zwischen einem HAL und seinen Benutzern verwendet wird.
- VTS
- Zusammen mit Treble wurde die Testsuite eines Anbieters eingeführt.
Kamera-APIs
Android umfasst die folgenden Kamera-APIs.
Kamera-API1
Android 5.0 hat die Kamera-API1 als veraltet markiert und wird weiterhin auslaufen, da sich die Entwicklung neuer Plattformen auf die Kamera-API2 konzentriert. Allerdings wird die Auslaufphase langwierig sein und Android-Releases werden noch einige Zeit lang Kamera-API1-Apps unterstützen. Konkret wird weiterhin Unterstützung für Folgendes gewährt:
- Kamera-API1-Schnittstellen für Apps. Kamera-Apps, die auf der Kamera-API1 basieren, sollten genauso funktionieren wie auf Geräten mit niedrigeren Android-Versionen.
- Kamera-HAL-Versionen. Beinhaltet Unterstützung für Kamera HAL1.0.
Kamera-API2
Das Camera API2-Framework stellt der App eine Kamerasteuerung auf niedrigerer Ebene zur Verfügung, einschließlich effizienter Zero-Copy-Burst-/Streaming-Abläufe und Einzelbildsteuerungen für Belichtung, Verstärkung, Weißabgleich, Farbkonvertierung, Rauschunterdrückung, Schärfung und mehr. Weitere Informationen finden Sie in der Google I/O-Videoübersicht .
Android 5.0 und höher enthält Camera API2; Allerdings unterstützen Geräte mit Android 5.0 und höher möglicherweise nicht alle Kamera-API2-Funktionen. Die Eigenschaft android.info.supportedHardwareLevel
, die Apps über die Kamera-API2-Schnittstellen abfragen können, meldet eine der folgenden Unterstützungsstufen:
-
LEGACY
: Diese Geräte stellen Apps über die Kamera-API2-Schnittstellen Funktionen zur Verfügung, die ungefähr den gleichen Funktionen entsprechen wie die, die Apps über die Kamera-API1-Schnittstellen zur Verfügung gestellt werden. Der Code des Legacy-Frameworks übersetzt Kamera-API2-Aufrufe konzeptionell in Kamera-API1-Aufrufe. Ältere Geräte unterstützen keine Kamera-API2-Funktionen wie die Steuerung pro Bild. -
LIMITED
: Diese Geräte unterstützen einige Kamera-API2-Funktionen (aber nicht alle) und müssen Kamera-HAL 3.2 oder höher verwenden. -
FULL
: Diese Geräte unterstützen alle wichtigen Funktionen von Camera API2 und müssen Camera HAL 3.2 oder höher und Android 5.0 oder höher verwenden. -
LEVEL_3
: Diese Geräte unterstützen YUV-Neuverarbeitung und RAW-Bilderfassung sowie zusätzliche Ausgabestream-Konfigurationen. -
EXTERNAL
: Diese Geräte ähneln mit einigen AusnahmenLIMITED
Geräten. Beispielsweise werden einige Sensor- oder Objektivinformationen möglicherweise nicht gemeldet oder die Bildraten sind weniger stabil. Diese Ebene wird für externe Kameras wie USB-Webcams verwendet.
Einzelne Funktionen werden über die Eigenschaft android.request.availableCapabilities
in den Kamera-API2-Schnittstellen verfügbar gemacht. FULL
Geräte erfordern unter anderem die Funktionen MANUAL_SENSOR
und MANUAL_POST_PROCESSING
. Die RAW
Fähigkeit ist auch für FULL
Geräte optional. LIMITED
Geräte können jede Teilmenge dieser Funktionen anbieten, auch keine davon. Die Funktion BACKWARD_COMPATIBLE
muss jedoch immer definiert sein.
Die unterstützte Hardwarestufe des Geräts sowie die spezifischen unterstützten Camera API2-Funktionen sind als folgende Funktionsflags verfügbar, um die Google Play-Filterung von Camera API2-Kamera-Apps zu ermöglichen.
-
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-Anforderungen
Geräte mit Android 5.0 und höher müssen die Kameratests Camera API1 CTS, Camera API2 CTS und CTS Verifier bestehen.
Geräte, die nicht über eine Camera HAL3.2-Implementierung verfügen und nicht in der Lage sind, die vollständigen Camera API2-Schnittstellen zu unterstützen, müssen dennoch die Camera API2 CTS-Tests bestehen. Das Gerät läuft jedoch im Camera API2 LEGACY
Modus (in dem die Camera API2-Aufrufe konzeptionell den Camera API1-Aufrufen zugeordnet sind), sodass alle Camera API2 CTS-Tests, die sich auf Funktionen oder Fähigkeiten beziehen, die über Camera API1 hinausgehen, automatisch übersprungen werden.
Auf älteren Geräten nutzen die ausgeführten Camera API2 CTS-Tests die vorhandenen öffentlichen Camera API1-Schnittstellen und -Funktionen ohne neue Anforderungen. Aufgedeckte Fehler (und die einen CTS-Fehler der Kamera-API2 verursachen) sind Fehler, die bereits im vorhandenen Kamera-HAL des Geräts vorhanden sind und daher von vorhandenen Kamera-API1-Apps gefunden werden. Wir erwarten nicht viele Fehler dieser Art (allerdings müssen solche Fehler behoben werden, um die Camera API2 CTS-Tests zu bestehen).
VTS-Anforderungen
Geräte mit Android 8.0 und höher mit binderisierten HAL-Implementierungen müssen die Kamera- VTS-Tests bestehen.
Härtung des Kameragerüsts
Um die Sicherheit des Medien- und Kamera-Frameworks zu erhöhen, entfernt Android 7.0 den Kameradienst vom Medienserver. Ab Android 8.0 wird jede binderisierte Kamera-HAL in einem vom Kameradienst getrennten Prozess ausgeführt. Abhängig von den verwendeten API- und HAL-Versionen müssen Anbieter möglicherweise Änderungen am Kamera-HAL vornehmen. In den folgenden Abschnitten werden Architekturänderungen in AP1 und AP2 für HAL1 und HAL3 sowie allgemeine Anforderungen detailliert beschrieben.
Architekturänderungen für API1
Bei der API1-Videoaufzeichnung kann davon ausgegangen werden, dass Kamera und Video-Encoder im selben Prozess aktiv sind. Bei Verwendung von API1 auf:
- HAL3, wo der Kameradienst BufferQueue verwendet, um Puffer zwischen Prozessen zu übergeben, ist kein Anbieter-Update erforderlich.
Abbildung 1. Android 7.0-Kamera und Medienstapel in API1 auf HAL3
- HAL1, das die Weitergabe von Metadaten in Videopuffern unterstützt, müssen Anbieter die HAL aktualisieren, um
kMetadataBufferTypeNativeHandleSource
zu verwenden. (kMetadataBufferTypeCameraSource
wird in Android 7.0 nicht mehr unterstützt.)Abbildung 2. Android 7.0-Kamera und Medienstapel in API1 auf HAL1
Architekturänderungen für API2
Für API2 auf HAL1 oder HAL3 übergibt BufferQueue Puffer, sodass diese Pfade weiterhin funktionieren. Die Android 7.0-Architektur für API2 auf:
- HAL1 ist von der Kameraservice-Umstellung nicht betroffen und es ist kein Anbieter-Update erforderlich.
- HAL3 ist betroffen, es ist jedoch kein Hersteller-Update erforderlich:
Abbildung 3. Android 7.0-Kamera und Medienstapel in API2 auf HAL3
Zusätzliche Anforderungen
Die architektonischen Änderungen zur Härtung der Medien- und Kamera-Framework-Sicherheit umfassen die folgenden zusätzlichen Geräteanforderungen.
- Allgemein. 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.
Validierung
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.
Validierung
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.