Prise en charge de la version de la caméra

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 appareils LIMITED à 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 transmettre VideoNativeHandleMetadata dans des tampons vidéo. ( kMetadataBufferTypeCameraSource n'est plus pris en charge sur Android 7.0.) Avec VideoNativeHandleMetadata , 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 de CameraCharacteristics . Voir getKeysNeedingPermission .

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'effectuer configureStreams_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 compteur streamConfigCounter est fourni pour vérifier une condition de concurrence entre les appels configureStreams_3_5 et signalStreamFlush .

Mises à jour de ICameraDeviceCallback :

• requestStreamBuffers : rappel synchrone que la caméra HAL appelle pour demander des tampons au serveur de la caméra. Voir requestStreamBuffers .
• returnStreamBuffers : Rappel synchrone pour que la caméra HAL renvoie les tampons de sortie au serveur de la caméra. Voir returnStreamBuffers .

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 pour isTorchModeSupported .

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 . Voir CONTROL_CAPTURE_INTENT_MOTION_TRACKING .
• Obsolète LENS_RADIAL_DISTORTION et ajoute LENS_DISTORTION à sa place.
• Ajoute des modes de correction de distorsion dans CaptureRequest . Voir DISTORTION_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 charge sessionParameters 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 format RAW_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ôt get_vendor_tag_ops dans camera_common.h .
• Obsolète register_stream_buffers . Tous les tampons gralloc fournis par le framework à HAL dans process_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 de process_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 :

1. 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é.
2. 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.
3. 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 et conflicting_devices doivent toujours être définis dans la structure camera_info renvoyée par l'appel get_camera_info .
4. 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 appareils LIMITED à 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 pass VideoNativeHandleMetadata in video buffers. ( kMetadataBufferTypeCameraSource is no longer supported on Android 7.0.) With VideoNativeHandleMetadata , 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 from CameraCharacteristics . See getKeysNeedingPermission .

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 perform configureStreams_3_5 and that the HAL must return all buffers of designated streams.
  • configureStreams_3_5 : Similar to ICameraDevice3.4.configureStreams , but in addition, the streamConfigCounter counter is provided to check for a race condition between the configureStreams_3_5 and signalStreamFlush calls.

Updates to ICameraDeviceCallback :

• requestStreamBuffers : Synchronous callback that the camera HAL calls to ask the camera server for buffers. See requestStreamBuffers .
• returnStreamBuffers : Synchronous callback for the camera HAL to return output buffers to the camera server. See returnStreamBuffers .

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 for isTorchModeSupported .

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 . See CONTROL_CAPTURE_INTENT_MOTION_TRACKING .
• Deprecates LENS_RADIAL_DISTORTION and adds LENS_DISTORTION in its place.
• Adds distortion correction modes in CaptureRequest . See DISTORTION_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 for sessionParameters 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 if RAW_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 to camera3_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 . Use get_vendor_tag_ops in camera_common.h instead.
• Deprecates register_stream_buffers . All gralloc buffers provided by framework to HAL in process_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 of process_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:

1. 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.
2. 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.
3. 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 and conflicting_devices fields should always be set in the camera_info structure returned by the get_camera_info call.
4. 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 to LIMITED 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 pass VideoNativeHandleMetadata in video buffers. ( kMetadataBufferTypeCameraSource is no longer supported on Android 7.0.) With VideoNativeHandleMetadata , 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 from CameraCharacteristics . See getKeysNeedingPermission .

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 perform configureStreams_3_5 and that the HAL must return all buffers of designated streams.
  • configureStreams_3_5 : Similar to ICameraDevice3.4.configureStreams , but in addition, the streamConfigCounter counter is provided to check for a race condition between the configureStreams_3_5 and signalStreamFlush calls.

Updates to ICameraDeviceCallback :

• requestStreamBuffers : Synchronous callback that the camera HAL calls to ask the camera server for buffers. See requestStreamBuffers .
• returnStreamBuffers : Synchronous callback for the camera HAL to return output buffers to the camera server. See returnStreamBuffers .

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 for isTorchModeSupported .

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 . See CONTROL_CAPTURE_INTENT_MOTION_TRACKING .
• Deprecates LENS_RADIAL_DISTORTION and adds LENS_DISTORTION in its place.
• Adds distortion correction modes in CaptureRequest . See DISTORTION_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 for sessionParameters 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 if RAW_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 to camera3_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 . Use get_vendor_tag_ops in camera_common.h instead.
• Deprecates register_stream_buffers . All gralloc buffers provided by framework to HAL in process_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 of process_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:

1. 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.
2. 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.
3. 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 and conflicting_devices fields should always be set in the camera_info structure returned by the get_camera_info call.
4. 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.