Cette page détaille les différences de version dans les caméras HAL, les API et les tests CTS (Compatibility Test Suite) associés. Il couvre également plusieurs modifications architecturales apportées pour renforcer et sécuriser le cadre de la caméra dans Android 7.0, le passage à Treble dans Android 8.0 et les mises à jour que les fournisseurs doivent effectuer pour prendre en charge ces modifications dans leurs implémentations de caméra.
Terminologie
Les termes suivants sont utilisés sur cette page :
- API de caméra1
- Le cadre de caméra au niveau de l'application sur les appareils Android 4.4 et inférieurs, exposé via la classe
android.hardware.Camera
. - API de caméra2
- Le cadre de caméra au niveau de l'application sur les appareils Android 5.0 et versions ultérieures, exposé via le package
android.hardware.camera2
. - Caméra HAL
- La couche de module de caméra implémentée par les fournisseurs de SoC. Les frameworks publics au niveau de l'application sont construits au-dessus de la caméra HAL.
- Caméra HAL3.1
- Version de l'appareil photo HAL publiée avec Android 4.4.
- Caméra HAL3.2
- Version de l'appareil photo HAL publiée avec Android 5.0.
- Caméra API1 CTS
- Ensemble de tests CTS de caméra qui s'exécutent au-dessus de Camera API1.
- Caméra API2 CTS
- Ensemble supplémentaire de tests CTS de caméra qui s'exécutent au-dessus de Camera API2.
- Tripler
- Sépare l'implémentation du fournisseur (logiciel de niveau inférieur spécifique à l'appareil écrit par les fabricants de silicium) du cadre du système d'exploitation Android via une nouvelle interface de fournisseur.
- HIDL
- Langage de définition d'interface HAL introduit avec Treble et utilisé pour spécifier l'interface entre un HAL et ses utilisateurs.
- VTS
- Suite de tests du fournisseur introduite aux côtés de Treble.
API de caméra
Android inclut les API de caméra suivantes.
API de caméra1
Android 5.0 a rendu obsolète Camera API1, qui continue d'être supprimée à mesure que le développement d'une nouvelle plate-forme se concentre sur Camera API2. Cependant, la période de suppression progressive sera longue et les versions d'Android continueront de prendre en charge les applications Camera API1 pendant un certain temps. Plus précisément, le soutien se poursuit pour :
- Interfaces de caméra API1 pour les applications. Les applications de caméra construites sur Camera API1 devraient fonctionner comme elles le font sur les appareils exécutant des versions inférieures d'Android.
- Versions HAL de la caméra. Inclut la prise en charge de la caméra HAL1.0.
API de caméra2
Le cadre Camera API2 expose le contrôle de la caméra de niveau inférieur à l'application, y compris les flux efficaces de rafale/streaming sans copie et les contrôles par image de l'exposition, du gain, des gains de balance des blancs, de la conversion des couleurs, du débruitage, de la netteté, etc. Pour plus de détails, regardez la vidéo de présentation de Google I/O .
Android 5.0 et supérieur inclut Camera API2 ; cependant, les appareils exécutant Android 5.0 et versions ultérieures peuvent ne pas prendre en charge toutes les fonctionnalités Camera API2. La propriété android.info.supportedHardwareLevel
que les applications peuvent interroger via les interfaces Camera API2 signale l'un des niveaux de prise en charge suivants :
-
LEGACY
: Ces appareils exposent des capacités aux applications via les interfaces Camera API2 qui sont approximativement les mêmes capacités que celles exposées aux applications via les interfaces Camera API1. Le code des frameworks hérités traduit conceptuellement les appels Camera API2 en appels Camera API1 ; Les appareils hérités ne prennent pas en charge les fonctionnalités Camera API2 telles que les commandes par image. -
LIMITED
: Ces appareils prennent en charge certaines fonctionnalités Camera API2 (mais pas toutes) et doivent utiliser Camera HAL 3.2 ou supérieur. -
FULL
: Ces appareils prennent en charge toutes les fonctionnalités principales de Camera API2 et doivent utiliser Camera HAL 3.2 ou supérieur et Android 5.0 ou supérieur. -
LEVEL_3
: ces appareils prennent en charge le retraitement YUV et la capture d'images RAW, ainsi que des configurations de flux de sortie supplémentaires. -
EXTERNAL
: Ces appareils sont similaires aux appareilsLIMITED
à quelques exceptions près ; par exemple, certaines informations de capteur ou d'objectif peuvent ne pas être signalées ou avoir des fréquences d'images moins stables. Ce niveau est utilisé pour les caméras externes telles que les webcams USB.
Les capacités individuelles sont exposées via la propriété android.request.availableCapabilities
dans les interfaces Camera API2. Les appareils FULL
nécessitent, entre autres, les capacités MANUAL_SENSOR
et MANUAL_POST_PROCESSING
. La capacité RAW
est facultative même pour les appareils FULL
. Les appareils LIMITED
peuvent annoncer n'importe quel sous-ensemble de ces fonctionnalités, y compris aucune d'entre elles. Cependant, la capacité BACKWARD_COMPATIBLE
doit toujours être définie.
Le niveau matériel pris en charge de l'appareil, ainsi que les capacités spécifiques de l'API Camera2 qu'il prend en charge, sont disponibles sous la forme d'indicateurs de fonctionnalité suivants pour permettre le filtrage Google Play des applications d'appareil photo 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
Exigences CTS
Les appareils exécutant Android 5.0 et versions ultérieures doivent réussir les tests de caméra Camera API1 CTS, Camera API2 CTS et CTS Verifier.
Les appareils qui ne disposent pas d'une implémentation Camera HAL3.2 et ne sont pas capables de prendre en charge les interfaces Camera API2 complètes doivent tout de même réussir les tests Camera API2 CTS. Cependant, l'appareil fonctionne en mode Camera API2 LEGACY
(dans lequel les appels Camera API2 sont conceptuellement mappés sur les appels Camera API1) de sorte que tous les tests Camera API2 CTS liés à des fonctionnalités ou capacités au-delà de Camera API1 sont automatiquement ignorés.
Sur les appareils hérités, les tests Camera API2 CTS qui sont exécutés utilisent les interfaces et les fonctionnalités publiques existantes de Camera API1 sans nouvelles exigences. Les bogues qui sont exposés (et qui provoquent une défaillance de Camera API2 CTS) sont des bogues déjà présents dans Camera HAL existant de l'appareil, et seraient donc trouvés par les applications Camera API1 existantes. Nous ne nous attendons pas à beaucoup de bogues de cette nature (toutefois, ces bogues doivent être corrigés pour réussir les tests Camera API2 CTS).
Exigences VTS
Les appareils exécutant Android 8.0 et versions ultérieures avec des implémentations HAL binderisées doivent réussir les tests Camera VTS .
Durcissement du cadre de la caméra
Pour renforcer la sécurité du cadre multimédia et de la caméra, Android 7.0 déplace le service de caméra hors du serveur multimédia. À partir d'Android 8.0, chaque caméra HAL binderisée s'exécute dans un processus distinct du service de caméra. Les fournisseurs peuvent avoir besoin d'apporter des modifications à la caméra HAL en fonction des versions d'API et de HAL utilisées. Les sections suivantes détaillent les changements architecturaux dans AP1 et AP2 pour HAL1 et HAL3, ainsi que les exigences générales.
Modifications architecturales pour l'API1
L'enregistrement vidéo API1 peut supposer que la caméra et l'encodeur vidéo vivent dans le même processus. Lors de l'utilisation d'API1 sur :
- HAL3, où le service de caméra utilise BufferQueue pour transmettre des tampons entre les processus, aucune mise à jour du fournisseur n'est nécessaire.
Figure 1. Appareil photo et pile multimédia Android 7.0 dans API1 sur HAL3
- HAL1, qui prend en charge la transmission des métadonnées dans les tampons vidéo, les fournisseurs doivent mettre à jour HAL pour utiliser
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
n'est plus pris en charge dans Android 7.0.)Figure 2. Appareil photo et pile multimédia Android 7.0 dans API1 sur HAL1
Changements architecturaux pour API2
Pour API2 sur HAL1 ou HAL3, BufferQueue passe des tampons afin que ces chemins continuent de fonctionner. L'architecture Android 7.0 pour API2 sur :
- HAL1 n'est pas affecté par le déplacement du service de caméra et aucune mise à jour du fournisseur n'est nécessaire.
- HAL3 est affecté, mais aucune mise à jour fournisseur n'est nécessaire :
Figure 3. Appareil photo et pile multimédia Android 7.0 dans API2 sur HAL3
Exigences supplémentaires
Les modifications architecturales apportées pour renforcer la sécurité des supports et de la structure de la caméra incluent les exigences supplémentaires suivantes en matière de périphériques.
- Général. Les appareils nécessitent une bande passante supplémentaire en raison de l'IPC, ce qui peut affecter les cas d'utilisation de caméras sensibles au facteur temps, tels que l'enregistrement vidéo à grande vitesse. Les fournisseurs peuvent mesurer l'impact réel en exécutant
android.hardware.camera2.cts.PerformanceTest
et l'application Google Camera pour un enregistrement vidéo à haute vitesse de 120/240 FPS. Les appareils nécessitent également une petite quantité de RAM supplémentaire pour créer le nouveau processus. - Passez les métadonnées dans les tampons vidéo ( HAL1 uniquement ). Si HAL1 stocke des métadonnées au lieu de données de trame YUV réelles dans des tampons vidéo, HAL doit utiliser
kMetadataBufferTypeNativeHandleSource
comme type de tampon de métadonnées et transmettreVideoNativeHandleMetadata
dans des tampons vidéo. (kMetadataBufferTypeCameraSource
n'est plus pris en charge sur Android 7.0.) AvecVideoNativeHandleMetadata
, les infrastructures de caméra et de médias sont capables de transmettre les tampons vidéo entre les processus en sérialisant et en désérialisant correctement les poignées natives. - L'adresse du handle de tampon ne stocke pas toujours le même tampon ( HAL3 uniquement ). Pour chaque demande de capture, HAL3 obtient les adresses des descripteurs de tampon. HAL ne peut pas utiliser les adresses pour identifier les tampons car les adresses peuvent stocker un autre descripteur de tampon après que HAL a renvoyé le tampon. Vous devez mettre à jour la couche HAL pour utiliser des descripteurs de tampon pour identifier les tampons. Par exemple, HAL reçoit une adresse de descripteur de tampon A, qui stocke le descripteur de tampon A. Une fois que HAL a renvoyé le descripteur de tampon A, l'adresse de descripteur de tampon A peut stocker le descripteur de tampon B la prochaine fois que HAL le reçoit.
- Mettre à jour les politiques SELinux pour cameraserver. Si les politiques SELinux spécifiques à l'appareil accordent des autorisations au serveur multimédia pour exécuter la caméra, vous devez mettre à jour les politiques SELinux pour accorder les autorisations appropriées au serveur de la caméra. Nous déconseillons de répliquer les politiques SELinux du serveur multimédia pour le serveur de caméra (car le serveur multimédia et le serveur de caméra nécessitent généralement des ressources différentes dans le système). Cameraserver ne doit disposer que des autorisations nécessaires pour exécuter les fonctionnalités de la caméra et toutes les autorisations inutiles liées à la caméra dans le serveur multimédia doivent être supprimées.
- Séparation entre Camera HAL et cameraserver. Android 8.0 et supérieur séparent en outre la caméra HAL binderisée dans un processus différent de cameraserver. IPC passe par des interfaces définies par HIDL .
Validation
Pour tous les appareils qui incluent un appareil photo et exécutent Android 7.0, vérifiez la mise en œuvre en exécutant Android 7.0 CTS. Bien qu'Android 7.0 n'inclue pas de nouveaux tests CTS qui vérifient les modifications du service de caméra, les tests CTS existants échouent si vous n'avez pas effectué les mises à jour indiquées ci-dessus.
Pour tous les appareils qui incluent une caméra et exécutent Android 8.0 et versions ultérieures, vérifiez l'implémentation du fournisseur en exécutant VTS.
Historique des versions HAL de la caméra
Pour obtenir une liste des tests disponibles pour évaluer l'appareil photo Android HAL, consultez la liste de vérification des tests de l'appareil photo HAL .
Android 10
Android 10 introduit les mises à jour suivantes.
API de caméra
- Améliorations multi-caméras qui permettent aux caméras physiques d'être utilisées individuellement ou via les caméras logiques correspondantes en masquant les ID de caméra physique. Voir Prise en charge de plusieurs caméras .
- Possibilité de vérifier si une configuration de session particulière est prise en charge sans la surcharge de performances liée à la création d'une nouvelle session. Voir
CameraDevice
. - Possibilité de récupérer les configurations de flux recommandées pour un cas d'utilisation donné afin de rendre le client plus efficace et plus performant. Voir
getRecommendedStreamConfigurationMap
. - Prise en charge du format d'image JPEG de profondeur . Pour plus de détails, consultez la spécification Dynamic Depth .
- Prise en charge du format d'image HEIC . Voir Imagerie HEIF .
- Améliorations de la confidentialité. Certaines clés sont nécessaires pour que le client dispose des autorisations
CAMERA
avant de pouvoir les récupérer à partir deCameraCharacteristics
. VoirgetKeysNeedingPermission
.
Caméra HAL
Les versions suivantes de Camera HAL sont mises à jour dans Android 10.
3.5
ICameraDevice
-
getPhysicalCameraCharacteristics
: les informations statiques de la caméra pour un ID de caméra physique prenant en charge un périphérique de caméra logique. Voir Prise en charge de plusieurs caméras . -
isStreamCombinationSupported
: cette méthode prend en charge une API publique qui aide les clients à demander si une configuration de session est prise en charge. Voir API pour interroger les combinaisons de flux .
ICameraDeviceSession
-
isReconfigurationNeeded
: méthode qui indique à la structure de la caméra si une reconfiguration complète du flux est requise pour d'éventuelles nouvelles valeurs de paramètre de session. Cela permet d'éviter les retards inutiles de reconfiguration de la caméra. Voir Requête de reconfiguration de session . - API de gestion des tampons HAL : ces API permettent à la caméra HAL de demander des tampons au framework de la caméra uniquement lorsque cela est nécessaire au lieu de coupler chaque demande de capture avec ses tampons associés tout au long du pipeline de la caméra, ce qui entraîne des économies de mémoire potentiellement importantes.
-
signalStreamFlush
: signale à la HAL que le service de caméra est sur le point d'effectuerconfigureStreams_3_5
et que la HAL doit renvoyer tous les tampons des flux désignés. -
configureStreams_3_5
: Similaire àICameraDevice3.4.configureStreams
, mais en plus, le compteurstreamConfigCounter
est fourni pour vérifier une condition de concurrence entre les appelsconfigureStreams_3_5
etsignalStreamFlush
.
-
Mises à jour de ICameraDeviceCallback
:
-
requestStreamBuffers
: rappel synchrone que la caméra HAL appelle pour demander des tampons au serveur de la caméra. VoirrequestStreamBuffers
. -
returnStreamBuffers
: Rappel synchrone pour que la caméra HAL renvoie les tampons de sortie au serveur de la caméra. VoirreturnStreamBuffers
.
3.4
Les clés suivantes sont ajoutées aux métadonnées de la caméra dans Android 10.
- Formats d'images
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW10
-
ANDROID_SCALER_AVAILABLE_FORMATS_RAW12
-
ANDROID_SCALER_AVAILABLE_FORMATS_Y8
-
- Balises de métadonnées de caméra
-
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és
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SECURE_IMAGE_DATA
-
- Valeurs de la clé
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_MONO
-
ANDROID_SENSOR_INFO_COLOR_FILTER_ARRANGEMENT_NIR
-
- Configurations dynamiques de flux de profondeur disponibles
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_DEPTH_AVAILABLE_DYNAMIC_DEPTH_STREAM_CONFIGURATIONS_INPUT
-
- Configurations de flux HEIC disponibles
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_OUTPUT
-
ANDROID_HEIC_AVAILABLE_HEIC_STREAM_CONFIGURATIONS_INPUT
-
Module caméra
Les versions suivantes du module de caméra sont mises à jour dans Android 10.
2.5
- Ajoute la méthode
notifyDeviceStateChange
pour que les appareils avertissent la caméra HAL lorsque des modifications physiques, telles que le pliage, affectent la caméra et le routage.
2.4
- Les appareils lancés avec le niveau d'API 29 ou supérieur DOIVENT signaler
true
pourisTorchModeSupported
.
Androïde 9
La version Android 9 introduit les mises à jour suivantes de l'interface API2 et HAL de la caméra.
API de caméra
- Introduit l'API multi-caméras pour mieux prendre en charge les appareils avec plusieurs caméras orientées dans la même direction, permettant des fonctionnalités telles que le bokeh et le zoom continu. Cela permet aux applications de visualiser plusieurs caméras sur un appareil comme une seule unité logique (caméra logique). Les demandes de capture peuvent également être envoyées à des appareils photo individuels englobés par une caméra logique. Voir Prise en charge de plusieurs caméras .
- Présente les paramètres de session. Les paramètres de session sont un sous-ensemble des paramètres de capture disponibles qui peuvent entraîner des retards de traitement importants lorsqu'ils sont modifiés. Ces coûts peuvent être atténués si les clients transmettent leurs valeurs initiales lors de l'initialisation de la session de capture. Voir Paramètres de session .
- Ajoute des clés de données de stabilisation optique (OIS) pour la stabilisation et les effets au niveau de l'application. Voir
STATISTICS_OIS_SAMPLES
. - Ajoute la prise en charge du flash externe. Voir
CONTROL_AE_MODE_ON_EXTERNAL_FLASH
. - Ajoute une intention de suivi de mouvement dans
CAPTURE_INTENT
. VoirCONTROL_CAPTURE_INTENT_MOTION_TRACKING
. - Obsolète
LENS_RADIAL_DISTORTION
et ajouteLENS_DISTORTION
à sa place. - Ajoute des modes de correction de distorsion dans
CaptureRequest
. VoirDISTORTION_CORRECTION_MODE
. - Ajoute la prise en charge des caméras USB/UVC externes sur les appareils pris en charge. Voir
INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL
.
Caméra HAL
3.4
Mises à jour de ICameraDeviceSession
-
configureStreams_3_4
: ajoute la prise en chargesessionParameters
et des caméras logiques. -
processCaptureRequest_3_4
: ajoute la prise en charge de l'inclusion des ID de caméra physique dans la structure du flux.
Mises à jour de ICameraDeviceCallback
-
processCaptureResult_3_4
: ajoute des métadonnées de caméra physique dans les résultats de capture.
3.3
Les clés suivantes sont ajoutées aux métadonnées de la caméra dans Android 9.
- Capacités
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MOTION_TRACKING
-
ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME
-
- Balises de métadonnées de caméra
-
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 version Android 8.0 introduit Treble. Avec Treble, les implémentations Camera HAL du fournisseur doivent être bindérisées . Android 8.0 contient également ces améliorations clés du service Appareil photo :
- Surfaces partagées : activez plusieurs surfaces partageant la même
OutputConfiguration
- API système pour les modes de caméra personnalisés
-
onCaptureQueueEmpty
Consultez les sections ci-dessous pour plus d'informations sur ces fonctionnalités.
Surfaces partagées
Cette fonctionnalité permet à un seul ensemble de tampons de piloter deux sorties, telles que la prévisualisation et l'encodage vidéo, ce qui réduit la consommation d'énergie et de mémoire. Pour prendre en charge cette fonctionnalité, les fabricants d'appareils doivent s'assurer que leurs implémentations HAL de caméra et gralloc HAL peuvent créer des tampons gralloc qui sont utilisés par plusieurs consommateurs différents (tels que le compositeur matériel/GPU et l'encodeur vidéo), au lieu d'un seul consommateur. Le service de caméra transmet les indicateurs d'utilisation du consommateur à la HAL de la caméra et à la HAL gralloc ; ils doivent soit allouer les bons types de tampons, soit la caméra HAL doit renvoyer une erreur indiquant que cette combinaison de consommateurs n'est pas prise en charge.
Consultez la documentation du développeur enableSurfaceSharing
pour plus de détails.
API système pour les modes de caméra personnalisés
L'API de la caméra publique définit deux modes de fonctionnement : enregistrement haute vitesse normal et contraint. Ils ont une sémantique assez différente ; par exemple, le mode haute vitesse est limité à au plus deux sorties spécifiques à la fois. Divers OEM ont exprimé leur intérêt pour la définition d'autres modes personnalisés pour les capacités spécifiques au matériel. Sous le capot, le mode est juste un entier passé à configure_streams
. Voir : hardware/camera/device/3.2/ICameraDeviceSession#configurestreams
.
Cette fonctionnalité inclut un appel d'API système que les applications de caméra OEM peuvent utiliser pour activer un mode personnalisé. Ces modes doivent commencer à la valeur entière 0x8000 pour éviter tout conflit avec les futurs modes ajoutés à l'API publique.
Pour prendre en charge cette fonctionnalité, les OEM doivent simplement ajouter le nouveau mode à leur HAL, déclenché par cet entier transmis à la HAL sur configure_streams, puis faire en sorte que leur application de caméra personnalisée utilise l'API système.
Le nom de la méthode est android.hardware.camera2.CameraDevice#createCustomCaptureSession
. Voir : frameworks/base/core/java/android/hardware/camera2/CameraDevice
.
onCaptureQueueEmpty
Le but de cette API est de réduire la latence des changements de contrôle comme le zoom en gardant la file d'attente des demandes aussi vide que possible. onCaptureQueueEmpty
ne nécessite aucun travail HAL ; c'était purement un ajout côté cadre. Les applications qui souhaitent en tirer parti doivent ajouter un écouteur à ce rappel et répondre de manière appropriée. Généralement, cela se fait en envoyant une autre demande de capture à l'appareil photo.
Interface caméra HIDL
L'interface Camera HIDL est une refonte complète de l'interface Camera HAL qui utilise des API stables définies par HIDL. Toutes les fonctionnalités et capacités de caméra introduites dans les versions 3.4 et 2.4 les plus récentes (pour le module de caméra) font également partie des définitions HIDL.
3.4
Ajouts mineurs aux métadonnées prises en charge et modifications de la prise en charge de data_space :
- Ajoutez les métadonnées statiques
ANDROID_SENSOR_OPAQUE_RAW_SIZE
comme obligatoires si le formatRAW_OPAQUE
est pris en charge. - Ajoutez les métadonnées statiques
ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE
comme obligatoires si n'importe quel format RAW est pris en charge. - Basculez le champ
camera3_stream_t data_space
vers une définition plus flexible, en utilisant la définition de la version 0 de l'encodage de l'espace de données. - Ajouts de métadonnées générales disponibles pour HALv3.2 ou plus récent :
-
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
Révision mineure de HAL à capacité étendue :
- Mises à jour des API de retraitement OPAQUE et YUV.
- Prise en charge de base des tampons de sortie de profondeur.
- Ajout du champ
data_space
àcamera3_stream_t
. - Ajout du champ de rotation à
camera3_stream_t
. - Ajout du mode de fonctionnement de la configuration du flux camera3 à
camera3_stream_configuration_t
.
3.2
Révision mineure de HAL à capacité étendue :
- Obsolète
get_metadata_vendor_tag_ops
. Utilisez plutôtget_vendor_tag_ops
danscamera_common.h
. - Obsolète
register_stream_buffers
. Tous les tampons gralloc fournis par le framework à HAL dansprocess_capture_request
peuvent être nouveaux à tout moment. - Ajoutez la prise en charge des résultats partiels.
process_capture_result
peut être appelé plusieurs fois avec un sous-ensemble des résultats disponibles avant que le résultat complet ne soit disponible. - Ajoutez un modèle manuel à
camera3_request_template
. Les applications peuvent utiliser ce modèle pour contrôler directement les paramètres de capture. - Retravailler les spécifications de flux bidirectionnel et d'entrée.
- Modifiez le chemin de retour du tampon d'entrée. Le tampon est renvoyé dans
process_capture_result
au lieu deprocess_capture_request
.
3.1
Révision mineure de HAL à capacité étendue :
-
configure_streams
transmet les indicateurs d'utilisation du consommateur à HAL. - appel flush pour supprimer toutes les requêtes/tampons en cours le plus rapidement possible.
3.0
Première révision de HAL à capacité étendue :
- Changement de version majeur puisque l'ABI est complètement différente. Aucune modification des capacités matérielles requises ou du modèle opérationnel à partir de la version 2.0.
- Interfaces de demande d'entrée et de file d'attente de flux retravaillées : appels du framework dans HAL avec les prochains tampons de demande et de flux déjà retirés de la file d'attente. La prise en charge de la structure de synchronisation est incluse, nécessaire pour des implémentations efficaces.
- Déplacement des déclencheurs dans les requêtes, la plupart des notifications dans les résultats.
- Consolidation de tous les rappels dans le framework en une seule structure et de toutes les méthodes de configuration en un seul appel
initialize()
. - Configuration du flux en un seul appel pour simplifier la gestion des flux. Les flux bidirectionnels remplacent la construction
STREAM_FROM_STREAM
. - Sémantique en mode limité pour les périphériques matériels plus anciens/limités.
2.0
Version initiale de HAL à capacité étendue (Android 4.2) [camera2.h] :
- Suffisant pour implémenter l'API
android.hardware.Camera
existante. - Autorise la file d'attente ZSL dans la couche de service de caméra.
- Non testé pour de nouvelles fonctionnalités telles que le contrôle manuel de la capture, la capture Bayer RAW, le retraitement des données RAW, etc.
1.0
Appareil photo Android initial HAL (Android 4.0) [camera.h] :
- Converti à partir de la couche d'abstraction C++ CameraHardwareInterface.
- Prend en charge l'API
android.hardware.Camera
.
Historique des versions du module caméra
Cette section contient des informations de version de module pour le module matériel de la caméra, basées sur camera_module_t.common.module_api_version
. Les deux chiffres hexadécimaux les plus significatifs représentent la version majeure et les deux moins significatifs représentent la version mineure.
2.4
Cette version du module de caméra ajoute les modifications d'API suivantes :
- Prise en charge du mode torche. Le cadre peut activer le mode torche pour tout appareil photo doté d'un flash, sans ouvrir un appareil photo. L'appareil photo a une priorité plus élevée pour accéder au flash que le module de l'appareil photo ; l'ouverture d'un appareil photo éteint la torche si elle avait été activée via l'interface du module. Lorsqu'il y a des conflits de ressources, comme
open()
est appelé pour ouvrir un appareil photo, le module HAL de la caméra doit informer le framework via le rappel d'état du mode torche que le mode torche a été désactivé. - Prise en charge d'une caméra externe (par exemple, une caméra USB enfichable à chaud). Les mises à jour de l'API spécifient que les informations statiques de la caméra sont disponibles uniquement lorsque la caméra est connectée et prête à être utilisée pour les caméras externes enfichables à chaud. Les appels pour obtenir des informations statiques sont des appels non valides lorsque l'état de la caméra n'est pas
CAMERA_DEVICE_STATUS_PRESENT
. Le cadre compte uniquement sur les rappels de changement d'état de l'appareil pour gérer la liste des caméras externes disponibles. - Conseils d'arbitrage de caméra. Ajoute la prise en charge de l'indication explicite du nombre d'appareils photo pouvant être ouverts et utilisés simultanément. Pour spécifier des combinaisons valides de périphériques, les champs
resource_cost
etconflicting_devices
doivent toujours être définis dans la structurecamera_info
renvoyée par l'appelget_camera_info
. - Méthode d'initialisation du module. Appelé par le service de caméra après le chargement du module HAL pour permettre une initialisation unique de HAL. Il est appelé avant que toute autre méthode de module ne soit invoquée.
2.3
Cette version du module de caméra ajoute la prise en charge des périphériques HAL de caméra hérités ouverts. Le framework peut l'utiliser pour ouvrir le périphérique de caméra en tant que périphérique HAL de version inférieure du périphérique HAL si le même périphérique peut prendre en charge plusieurs versions d'API de périphérique. L'appel ouvert du module matériel standard ( common.methods->open
) continue d'ouvrir l'appareil photo avec la dernière version prise en charge, qui est également la version répertoriée dans camera_info_t.device_version
.
2.2
Cette version du module de caméra ajoute la prise en charge des balises de fournisseur à partir du module et rend obsolète l'ancien vendor_tag_query_ops
qui n'était auparavant accessible qu'avec un appareil ouvert.
2.1
Cette version du module caméra ajoute la prise en charge des rappels asynchrones au framework à partir du module caméra HAL, qui est utilisé pour notifier au framework les changements d'état du module caméra. Les modules qui fournissent une méthode set_callbacks()
valide doivent rapporter au moins ce numéro de version.
2.0
Les modules de caméra qui signalent ce numéro de version implémentent la deuxième version de l'interface HAL du module de caméra. Les appareils photo pouvant être ouverts via ce module peuvent prendre en charge la version 1.0 ou la version 2.0 de l'interface HAL de l'appareil photo. Le champ device_version
de camera_info est toujours valide ; le champ static_camera_characteristics
de camera_info
est valide si le champ device_version
est 2.0 ou supérieur.
1.0
Les modules de caméra qui signalent ces numéros de version implémentent l'interface HAL du module de caméra initial. Tous les appareils photo pouvant être ouverts via ce module ne prennent en charge que la version 1 de l'appareil photo HAL. Les champs device_version
et static_camera_characteristics
de camera_info
ne sont pas valides. Seule l'API android.hardware.Camera
peut être prise en charge par ce module et ses appareils.
Cette page détaille les différences de version dans les caméras HAL, les API et les tests CTS (Compatibility Test Suite) associés. Il couvre également plusieurs modifications architecturales apportées pour renforcer et sécuriser le cadre de la caméra dans Android 7.0, le passage à Treble dans Android 8.0 et les mises à jour que les fournisseurs doivent effectuer pour prendre en charge ces modifications dans leurs implémentations de caméra.
Terminologie
Les termes suivants sont utilisés sur cette page :
- API de caméra1
- Le cadre de caméra au niveau de l'application sur les appareils Android 4.4 et inférieurs, exposé via la classe
android.hardware.Camera
. - API de caméra2
- Le cadre de caméra au niveau de l'application sur les appareils Android 5.0 et versions ultérieures, exposé via le package
android.hardware.camera2
. - Caméra HAL
- La couche de module de caméra implémentée par les fournisseurs de SoC. Les frameworks publics au niveau de l'application sont construits au-dessus de la caméra HAL.
- Caméra HAL3.1
- Version de l'appareil photo HAL publiée avec Android 4.4.
- Caméra HAL3.2
- Version de l'appareil photo HAL publiée avec Android 5.0.
- Caméra API1 CTS
- Ensemble de tests CTS de caméra qui s'exécutent au-dessus de Camera API1.
- Caméra API2 CTS
- Ensemble supplémentaire de tests CTS de caméra qui s'exécutent au-dessus de Camera API2.
- Tripler
- Sépare l'implémentation du fournisseur (logiciel de niveau inférieur spécifique à l'appareil écrit par les fabricants de silicium) du cadre du système d'exploitation Android via une nouvelle interface de fournisseur.
- HIDL
- Langage de définition d'interface HAL introduit avec Treble et utilisé pour spécifier l'interface entre un HAL et ses utilisateurs.
- VTS
- Suite de tests du fournisseur introduite aux côtés de Treble.
API de caméra
Android inclut les API de caméra suivantes.
API de caméra1
Android 5.0 a rendu obsolète Camera API1, qui continue d'être supprimée à mesure que le développement d'une nouvelle plate-forme se concentre sur Camera API2. Cependant, la période de suppression progressive sera longue et les versions d'Android continueront de prendre en charge les applications Camera API1 pendant un certain temps. Plus précisément, le soutien se poursuit pour :
- Interfaces de caméra API1 pour les applications. Les applications de caméra construites sur Camera API1 devraient fonctionner comme elles le font sur les appareils exécutant des versions inférieures d'Android.
- Versions HAL de la caméra. Inclut la prise en charge de la caméra HAL1.0.
API de caméra2
Le cadre Camera API2 expose le contrôle de la caméra de niveau inférieur à l'application, y compris les flux efficaces de rafale/streaming sans copie et les contrôles par image de l'exposition, du gain, des gains de balance des blancs, de la conversion des couleurs, du débruitage, de la netteté, etc. Pour plus de détails, regardez la vidéo de présentation de Google I/O .
Android 5.0 et supérieur inclut Camera API2 ; cependant, les appareils exécutant Android 5.0 et versions ultérieures peuvent ne pas prendre en charge toutes les fonctionnalités Camera API2. La propriété android.info.supportedHardwareLevel
que les applications peuvent interroger via les interfaces Camera API2 signale l'un des niveaux de prise en charge suivants :
-
LEGACY
: Ces appareils exposent des capacités aux applications via les interfaces Camera API2 qui sont approximativement les mêmes capacités que celles exposées aux applications via les interfaces Camera API1. Le code des frameworks hérités traduit conceptuellement les appels Camera API2 en appels Camera API1 ; Les appareils hérités ne prennent pas en charge les fonctionnalités Camera API2 telles que les commandes par image. -
LIMITED
: Ces appareils prennent en charge certaines fonctionnalités Camera API2 (mais pas toutes) et doivent utiliser Camera HAL 3.2 ou supérieur. -
FULL
: Ces appareils prennent en charge toutes les fonctionnalités principales de Camera API2 et doivent utiliser Camera HAL 3.2 ou supérieur et Android 5.0 ou supérieur. -
LEVEL_3
: ces appareils prennent en charge le retraitement YUV et la capture d'images RAW, ainsi que des configurations de flux de sortie supplémentaires. -
EXTERNAL
: Ces appareils sont similaires aux appareilsLIMITED
à quelques exceptions près ; par exemple, certaines informations de capteur ou d'objectif peuvent ne pas être signalées ou avoir des fréquences d'images moins stables. Ce niveau est utilisé pour les caméras externes telles que les webcams USB.
Les capacités individuelles sont exposées via la propriété android.request.availableCapabilities
dans les interfaces Camera API2. Les appareils FULL
nécessitent, entre autres, les capacités MANUAL_SENSOR
et MANUAL_POST_PROCESSING
. La capacité RAW
est facultative même pour les appareils FULL
. Les appareils LIMITED
peuvent annoncer n'importe quel sous-ensemble de ces fonctionnalités, y compris aucune d'entre elles. Cependant, la capacité BACKWARD_COMPATIBLE
doit toujours être définie.
Le niveau matériel pris en charge de l'appareil, ainsi que les capacités spécifiques de l'API Camera2 qu'il prend en charge, sont disponibles sous la forme d'indicateurs de fonctionnalité suivants pour permettre le filtrage Google Play des applications d'appareil photo 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
Exigences CTS
Les appareils exécutant Android 5.0 et versions ultérieures doivent réussir les tests de caméra Camera API1 CTS, Camera API2 CTS et CTS Verifier.
Les appareils qui ne disposent pas d'une implémentation Camera HAL3.2 et ne sont pas capables de prendre en charge les interfaces Camera API2 complètes doivent tout de même réussir les tests Camera API2 CTS. Cependant, l'appareil fonctionne en mode Camera API2 LEGACY
(dans lequel les appels Camera API2 sont conceptuellement mappés sur les appels Camera API1) de sorte que tous les tests Camera API2 CTS liés à des fonctionnalités ou capacités au-delà de Camera API1 sont automatiquement ignorés.
Sur les appareils hérités, les tests Camera API2 CTS qui sont exécutés utilisent les interfaces et les fonctionnalités publiques existantes de Camera API1 sans nouvelles exigences. Les bogues qui sont exposés (et qui provoquent une défaillance de Camera API2 CTS) sont des bogues déjà présents dans Camera HAL existant de l'appareil, et seraient donc trouvés par les applications Camera API1 existantes. Nous ne nous attendons pas à beaucoup de bogues de cette nature (toutefois, ces bogues doivent être corrigés pour réussir les tests Camera API2 CTS).
Exigences VTS
Les appareils exécutant Android 8.0 et versions ultérieures avec des implémentations HAL binderisées doivent réussir les tests Camera VTS .
Durcissement du cadre de la caméra
Pour renforcer la sécurité du cadre multimédia et de la caméra, Android 7.0 déplace le service de caméra hors du serveur multimédia. À partir d'Android 8.0, chaque caméra HAL binderisée s'exécute dans un processus distinct du service de caméra. Les fournisseurs peuvent avoir besoin d'apporter des modifications à la caméra HAL en fonction des versions d'API et de HAL utilisées. Les sections suivantes détaillent les changements architecturaux dans AP1 et AP2 pour HAL1 et HAL3, ainsi que les exigences générales.
Modifications architecturales pour l'API1
L'enregistrement vidéo API1 peut supposer que la caméra et l'encodeur vidéo vivent dans le même processus. Lors de l'utilisation d'API1 sur :
- HAL3, où le service de caméra utilise BufferQueue pour transmettre des tampons entre les processus, aucune mise à jour du fournisseur n'est nécessaire.
Figure 1. Appareil photo et pile multimédia Android 7.0 dans API1 sur HAL3
- HAL1, qui prend en charge la transmission des métadonnées dans les tampons vidéo, les fournisseurs doivent mettre à jour HAL pour utiliser
kMetadataBufferTypeNativeHandleSource
. (kMetadataBufferTypeCameraSource
n'est plus pris en charge dans Android 7.0.)Figure 2. Appareil photo et pile multimédia Android 7.0 dans API1 sur HAL1
Changements architecturaux pour API2
Pour API2 sur HAL1 ou HAL3, BufferQueue passe des tampons afin que ces chemins continuent de fonctionner. L'architecture Android 7.0 pour API2 sur :
- HAL1 n'est pas affecté par le déplacement du service de caméra et aucune mise à jour du fournisseur n'est nécessaire.
- HAL3 est affecté, mais aucune mise à jour fournisseur n'est nécessaire :
Figure 3. Appareil photo et pile multimédia Android 7.0 dans API2 sur HAL3
Exigences supplémentaires
Les modifications architecturales apportées pour renforcer la sécurité des supports et de la structure de la caméra incluent les exigences supplémentaires suivantes en matière de périphériques.
- Général. 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.
Validation
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.
Validation
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.