Migrer vers Camera2

Cette page identifie les différences entre le système de vue étendue (EVS) et Camera2. Elle explique également comment configurer votre implémentation Camera2.

Ouvrir et fermer la caméra

EVS

openCamera combine l'ouverture de l'appareil et la configuration d'un seul flux.

Camera2

Pour ouvrir et fermer un appareil avec Camera2 :

1. Sélectionnez l'un des modes suivants :

   • En mode exclusif, utilisez CameraManager.openCamera (Java) ou ACameraManager_openCamera sur le kit de développement natif (NDK).

   • En mode partagé, utilisez openSharedCamera ou ACameraManager_openSharedCamera. Lorsque vous activez le partage de la caméra, fournissez une configuration de session partagée.

2. Pour configurer les flux, créez une session de capture avec les surfaces de sortie appropriées. Par exemple, à partir d'un ImageReader ou d'une SurfaceView avec CameraDevice.createCaptureSession() (Java) ou ACameraDevice_createCaptureSession() (NDK).

   Camera2 est compatible avec les flux multiples simultanés. Créez plusieurs flux pour des besoins tels que l'aperçu, l'enregistrement et le traitement d'images. Les flux servent de pipelines parallèles, qui traitent séquentiellement les trames brutes de la caméra.

3. Pour fermer un appareil photo, utilisez CameraDevice.close() (Java) ou ACameraDevice_close() (NDK).

Considérez ces exemples d'extraits de code :

CameraManager manager = (CameraManager) getSystemService(Context.CAMERA_SERVICE);
try {
    manager.openCamera(cameraId, new CameraDevice.StateCallback() {
        @Override
        public void onOpened(@NonNull CameraDevice camera) {
            // Camera opened, now create session
        }
        @Override
        public void onDisconnected(@NonNull CameraDevice camera) {}
        @Override
        public void onError(@NonNull CameraDevice camera, int error) {}
    }, handler);
} catch (CameraAccessException e) {
    // Handle exception
}

ACameraManager *cameraManager = ACameraManager_create();
ACameraDevice *cameraDevice = nullptr;
camera_status_t status = ACameraManager_openCamera(
    cameraManager, cameraId, &deviceStateCallbacks, &cameraDevice);

Diffuser les données de la caméra

Cette section explique comment diffuser des données de caméras.

EVS

Sur EVS, pour :

1. Lancez le streaming à l'aide de startVideoStream.
2. Pour arrêter la diffusion, utilisez stopVideoStream.

Camera2

Dans Camera2, pour :

1. Créez un CaptureRequest adapté à l'aperçu, utilisez TEMPLATE_PREVIEW avec CameraDevice.createCaptureRequest() en Java ou ACameraDevice_createCaptureRequest() sur le NDK.

2. Pour envoyer une requête de streaming continu, utilisez CameraCaptureSession.setSingleRepeatingRequest (Java) ou ACameraCaptureSession_setRepeatingRequestV2 (NDK).

3. Pour arrêter le streaming, utilisez CameraCaptureSession.stopRepeating (Java) ou ACameraCaptureSession_stopRepeating (NDK).

Gestion du tampon

• Sur EVS, setMaxFramesInFlight contrôlait auparavant le nombre de tampons, qui pouvait potentiellement être modifié en cours de flux. Lorsque le flux de caméras a démarré, EVS a fourni un ID de tampon pour chaque image, qui correspondait à la même adresse de tampon matériel en mémoire.

• Sur Camera2, le nombre maximal d'images pour un AImageReader ou un ImageReader est défini avec AImageReader_new ou ImageReader.newInstance lorsqu'une session est initialisée. Ce paramètre ne peut pas être modifié de manière dynamique une fois la session démarrée. Pour obtenir un ID de tampon pour chaque frame, les clients peuvent conserver un mappage qui met en corrélation l'adresse du tampon matériel, obtenue à partir de l'objet Image, avec un identifiant unique.

Mettre en pause et reprendre le streaming

• EVS utilisé pauseVideoStream et resumeVideoStream.

• Camera2 n'a pas d'équivalent direct. Au lieu de :

  • Mettre en pause, utiliser stopRepeating
  • Reprendre, utiliser setSingleRepeatingRequest

Paramètres de la caméra

• EVS a utilisé des méthodes telles que setIntParameter pour modifier le paramètre de requête de capture de la caméra.

• Sur Camera2, pour modifier les paramètres, appelez l'API set pour le compilateur CaptureRequest, puis envoyez-le.

Considérez ces exemples de code :

CaptureRequest.Builder builder = cameraDevice.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);
builder.set(CaptureRequest.CONTROL_EFFECT_MODE, CaptureRequest.CONTROL_EFFECT_MODE_MONO);
// Submit this request

ACaptureRequest_setEntry_i32(captureRequest, ACAMERA_CONTROL_EFFECT_MODE, 1, &effectMode);

Caméras logiques

• EVS : pour les caméras logiques, telles que la caméra de vision panoramique, le gestionnaire EVS ouvrait toutes les caméras physiques associées, lançait les flux vidéo et fournissait un ensemble cohérent d'images.

• Camera2 : lorsque des fonctionnalités similaires sont nécessaires avec Camera2, les applications doivent gérer les caméras logiques, ce qui vous oblige à :

  • Identifiez les sous-caméras physiques associées à une caméra logique.
  • Ouvrez chaque caméra physique nécessaire.
  • Lancez les flux sur chaque caméra.
  • Synchronisez les images, si nécessaire. Idéalement, cette opération est gérée au niveau de la HAL pour la synchronisation matérielle.

Nous fournirons une bibliothèque de compatibilité (couche shim) aux clients EVS existants pour faciliter la transition. L'objectif est de prendre en charge les API Camera2 avec un minimum de modifications du code.

Autorisations

Cette section décrit les modifications apportées aux autorisations.

EVS

L'accès est limité aux identifiants uniques (UID) privilégiés. Par exemple, AID_AUTOMOTIVE_EVS. Les autorisations obsolètes incluent android.car.permission.USE_CAR_EVS_CAMERA.

Camera2

Camera2 nécessite android.permission.CAMERA. Pour les cas particuliers :

• android.permission.SYSTEM_CAMERA : pour accéder aux caméras masquées dans les applications tierces. Nécessite également l'autorisation CAMERA. Pour en savoir plus, consultez Caméras système.

• android.permission.CAMERA_HEADLESS_SYSTEM_USER : permet d'accéder à User 0, ce qui est essentiel pour les services tels que les caméras de recul qui doivent fonctionner lors des changements d'utilisateur. Nécessite une autorisation CAMERA accordée au préalable.

• android.permission.CAMERA_PRIVACY_ALLOWLIST : permet aux OEM d'exempter certaines applications critiques pour la sécurité du bouton bascule de confidentialité de l'appareil photo contrôlé par l'utilisateur.

Les applications de caméras critiques pour la sécurité doivent respecter les règles Google intégrées avant l'octroi d'autorisations fournies dans Concevoir pour la conduite.

Clients principaux et secondaires

Pour l'accès partagé à la caméra :

• EVS proposait des API explicites, setPrimaryClient et forcePrimaryClient, pour gérer le client principal, qui était autorisé à modifier les paramètres.

• Avec Camera2, lorsque l'appareil photo est ouvert en mode partagé (Android 16 et versions ultérieures), la priorité du client accédant à l'appareil photo détermine le client principal. Le client ayant la priorité la plus élevée (généralement l'application au premier plan) peut modifier les paramètres de la requête de capture. Aucune API directe n'est utilisée pour forcer l'état principal. L'état principal est géré par le framework.

Caméras système

Pour restreindre l'accès à un appareil photo aux applications système ou propriétaires uniquement, déclarez la fonctionnalité ANDROID_REQUEST_AVAILABLE_CAPABILITIES_SYSTEM_CAMERA dans le HAL de l'appareil photo pour cet appareil. Les clients doivent disposer de android.permission.SYSTEM_CAMERA et de android.permission.CAMERA connectés à cette caméra.

Caméra de recul

EVS

L'EVS permettait auparavant d'accéder à la caméra avant le démarrage d'Android, un événement essentiel pour des fonctionnalités telles que les caméras de recul. Les OEM de véhicules sont responsables de la conformité et de la certification aux réglementations fournies dans la norme fédérale de sécurité des véhicules automobiles (FMVSS), n° 111, sur la visibilité arrière. De plus, les OEM de véhicules doivent respecter d'autres réglementations concernant les caméras de recul.

La conformité dépend du matériel, de l'implémentation HAL et de l'intégration globale du système. Après un démarrage Android de la plate-forme de référence, l'EVS a généralement besoin de quatre à six secondes pour devenir opérationnel et accorder l'accès à la caméra.

Camera2

Un client privilégié, identifié par AID_AUTOMOTIVE_EVS UID, peut utiliser les API Camera2 pour accéder à la caméra avant la fin du processus de démarrage d'Android. Cet accès anticipé est limité aux caméras système situées à l'extérieur du véhicule. Camera2 répond aux mêmes KPI de performances pour l'accès anticipé à la caméra que l'EVS, qui est généralement disponible quatre à six secondes après le démarrage d'Android.

Pour que la caméra de recul s'affiche de manière cohérente et sans obstruction, en particulier lors des transitions utilisateur ou lorsque d'autres applications peuvent masquer l'aperçu, nous vous recommandons de suivre ces consignes lorsque vous implémentez la caméra de recul avec Camera2 :

1. Désignez la caméra de recul comme caméra système pour limiter l'accès des applications tierces.

2. Exécutez le service ou l'application qui accède à l'appareil photo en tant que User 0 à l'aide de l'autorisation CAMERA_HEADLESS_SYSTEM_USER. Cela garantit un flux vidéo ininterrompu, quelle que soit la façon dont l'utilisateur passe au premier plan.

3. Ajoutez l'application à la liste d'autorisation de confidentialité de l'appareil photo pour lui accorder l'accès à l'appareil photo même lorsque le bouton de confidentialité de l'appareil photo contrôlé par l'utilisateur est activé.

CarEVSManager et CarEVSService

CarEVSManager fournissait auparavant des applications Java avec accès à l'appareil photo. La transition vers Camera2 remplace cette fonctionnalité par standard android.hardware.camera2.CameraManager.

Nous prévoyons d'abandonner CarEVSService, un service facultatif qui surveille la propriété GEAR_SELECTION VHAL et qui était utilisé pour démarrer une activité de caméra de recul spécifiée par l'OEM. Les OEM qui utilisent cette fonctionnalité doivent transférer la logique associée vers une application qu'ils possèdent.

• Surveillez la propriété GEAR_SELECTION VHAL.
• Lancer l'activité de la caméra de recul lorsque la marche arrière est activée.
• Utilisez les API Camera2 pour afficher le flux de la caméra.

Rendu de l'écran

Service d'affichage EVS et service d'affichage automobile

Ces états sont obsolètes.

Camera2

Utilisez les méthodes de rendu Android standards avec Surface, android.hardware.display.DisplayManager et android.view.Display.

Pour les scénarios nécessitant un affichage précoce de la caméra, ImageReader Camera2 peut fournir un accès direct au tampon matériel afin que vous puissiez l'intégrer aux implémentations d'affichage existantes basées sur DRM pour le rendu.

Cet accès anticipé à la caméra est exclusivement autorisé pour les clients privilégiés qui disposent de AID_AUTOMOTIVE_EVS_UID et est limité aux caméras système situées à l'extérieur d'un véhicule.

HAL de l'émulateur (HAL de simulation EVS)

Nous prévoyons d'abandonner EVS Mock HAL. Les OEM doivent plutôt utiliser le HAL de caméra émulé Camera2, hardware/google/camera/devices/EmulatedCamera/, dans lequel nous prévoyons de prendre en charge :

• Nombre de caméras configurable.
• Modèles de test de barre colorée.
• Émulation de fichiers vidéo

Pour inclure ce HAL dans la compilation :

# In device.mk
PRODUCT_SOONG_NAMESPACES += hardware/google/camera/devices/EmulatedCamera
PRODUCT_PACKAGES += com.google.emulated.camera.provider.hal

Des règles SELinux (Security-Enhanced Linux) appropriées sont également requises pour permettre à cameraserver d'interagir avec le service HAL de la caméra émulée.

HAL de la caméra V4L2 UVC

Nous prévoyons d'abandonner EVS V4L2 HAL. Utilisez la compatibilité des appareils photo externes Camera2 pour les caméras USB (UVC). Pour en savoir plus, consultez Appareils photo USB externes.

API Ultrasonics

Nous prévoyons d'abandonner les API EVS Ultrasonics. Utilisez plutôt ces propriétés VHAL introduites dans Android 15 pour les détections de capteurs à ultrasons.