Extensions pour l'appareil photo

Les fabricants d'appareils peuvent exposer des extensions telles que le bokeh, le mode Nuit et la technologie HDR. aux développeurs tiers via l'interface "Extensions d'appareil photo" fournie par la bibliothèque des fournisseurs OEM. Les développeurs peuvent utiliser API Extensions de CameraX et l'API Extensions CameraX pour accéder aux extensions implémentées dans la bibliothèque du fournisseur OEM.

Pour obtenir la liste des extensions compatibles, qui est identique dans Camera2 et CameraX, consultez API Extensions CameraX : Pour ajouter une extension, signaler un bug avec le Issue Tracker :

Cette page explique comment implémenter et activer la bibliothèque de fournisseurs OEM sur appareils.

Architecture

Le schéma suivant décrit l'architecture des extensions Camera interface ou extensions-interface:

Figure 1 : Schéma de l'architecture des extensions Camera

Comme le montre le schéma, pour prendre en charge Camera Extensions, vous devez Implémentez l'extensions-interface fourni par la bibliothèque du fournisseur OEM. Votre La bibliothèque de fournisseurs OEM active deux API: API Extensions CameraX et API Extensions de CameraX, utilisés respectivement par les applications CameraX et Camera2 pour accéder les extensions de fournisseur.

Implémenter la bibliothèque de fournisseurs OEM

Pour implémenter la bibliothèque du fournisseur OEM, copiez la camera-extensions-stub des fichiers dans un projet de bibliothèque système. Ces fichiers définissent les extensions Camera de commande.

Remarque :Vous devez conserver les fichiers sous le androidx.camera.extensions.impl packages. Pour référence, consultez les exemple de projet.

camera-extensions-stub sont répartis dans les catégories suivantes:

Fichiers d'interface essentiels (ne pas modifier)

• PreviewExtenderImpl.java
• ImageCaptureExtenderImpl.java
• ExtenderStateListener.java
• ProcessorImpl.java
• PreviewImageProcessorImpl.java
• CaptureProcessorImpl.java
• CaptureStageImpl.java
• RequestUpdateProcessorImpl.java
• ProcessResultImpl.java
• advanced/AdvancedExtenderImpl.java
• advanced/Camera2OutputConfigImpl.java
• advanced/Camera2SessionConfigImpl.java
• advanced/ImageProcessorImpl.java
• advanced/ImageReaderOutputConfigImpl.java
• advanced/ImageReferenceImpl.java
• advanced/MultiResolutionImageReaderOutputConfigImpl.java
• advanced/OutputSurfaceImpl.java
• advanced/RequestProcessorImpl.java
• advanced/SessionProcessorImpl.java
• advanced/SurfaceOutputConfigImpl.java

Implémentations obligatoires (ajoutez votre implémentation)

• ExtensionVersionImpl.java
• InitializerImpl.java

Classes d'extendeurs Bokeh (à implémenter si l'extension Bokeh est compatible)

• BokehImageCaptureExtenderImpl.java
• BokehPreviewExtenderImpl.java
• advanced/BokehAdvancedExtenderImpl.java

Classes des répéteurs Nuit (à implémenter si l'extension Nuit est compatible)

• NightImageCaptureExtenderImpl.java
• NightPreviewExtenderImpl.java
• advanced/NightAdvancedExtenderImpl.java

Classes d'extensions automatiques (à implémenter si l'extension automatique est compatible)

• AutoImageCaptureExtenderImpl.java
• AutoPreviewExtenderImpl.java
• advanced/AutoAdvancedExtenderImpl.java

Classes d'extensions HDR (à implémenter si l'extension HDR est compatible)

• HdrImageCaptureExtenderImpl.java
• HdrPreviewExtenderImpl.java
• advanced/HdrAdvancedExtenderImpl.java

Classes d'extendeurs pour la retouche du visage (à implémenter si l'extension Retouche du visage est compatible)

• BeautyImageCaptureExtenderImpl.java
• BeautyPreviewExtenderImpl.java
• advanced/BeautyAdvancedExtenderImpl.java

Utilitaires (facultatif, peuvent être supprimés)

• advanced/Camera2OutputConfigImplBuilder.java
• advanced/Camera2SessionConfigImplBuilder.java

Vous n'êtes pas obligé de fournir une implémentation pour chaque extension. Si vous n'implémentez pas d'extension, définissez isExtensionAvailable() pour renvoyer false ou supprimer les classes Extender correspondantes. Extensions Camera2 et CameraX Les API signalent à l'application que l'extension n'est pas disponible.

Remarque :Étant donné que la bibliothèque du fournisseur OEM s'exécute dans le cadre d'un processus d'application tierce, la bibliothèque du fournisseur ne doit PAS nécessiter d'autorisations spéciales (telles que autorisations).

Voyons comment les API d'extensions Camera2 et CameraX interagissent avec les bibliothèque du fournisseur pour activer une extension. Le schéma suivant illustre les flux de bout en bout en utilisant l'extension Nuit comme exemple:

Figure 2. Implémentation d'une extension de nuit

Remarque :Pour plus de commodité, nous faisons référence aux API d'extensions Camera2 et CameraX. tel que Camera2/X.

1. Validation de la version:

   Camera2/X appelle ExtensionVersionImpl.checkApiVersion() pour s'assurer que La version extensions-interface implémentée par l'OEM est compatible avec Camera2/X. versions compatibles.

2. Initialisation de la bibliothèque fournisseur:

   InitializerImpl comporte une méthode init() qui initialise la bibliothèque du fournisseur. Camera2/X termine l'initialisation avant d'accéder aux classes Extender.

3. Instancier les classes Extender:

   Instancie les classes Extender pour l'extension. Deux extensions sont disponibles de base: Basic Extender et Advanced Extender. Vous devez en implémenter un Type d'extension pour toutes les extensions. Pour en savoir plus, consultez Basic Extender et Advanced Extender

   Camera2/X instancie les classes Extender et interagit avec elles pour récupérer et activer l'extension. Pour une extension donnée, Camera2/X peut instancier les classes Extender plusieurs fois. Par conséquent, ne faites pas une initialisation intensive dans le constructeur ou l'appel init(). Procédez comme suit : de faire du gros travail que lorsque la session photo est sur le point démarrer, par exemple lorsque onInit() est appelé dans Basic Extender, initSession() est appelé dans Advanced Extender.

   Pour l'extension Night, les classes Extender suivantes sont instanciées pour "Basic Extender" :

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   Pour le type "Advanced Extender" :

   • NightAdvancedExtenderImpl.java

4. Vérifier la disponibilité des extensions :

   Avant d'activer l'extension, isExtensionAvailable() vérifie si le est disponible pour l'ID de caméra spécifié via le répéteur Compute Engine.

5. Initialisez le répéteur avec les informations de l'appareil photo:

   Camera2/X appelle init() sur l'instance Extender et la transmet à la caméra ID et CameraCharacteristics.

6. Informations sur la requête:

   Elle appelle la classe Extender pour récupérer des informations telles que la latence estimée et les clés de requête provenant l'extension en vue de son activation.

7. Activer l'extension sur le répéteur:

   La classe Extender fournit toutes les interfaces nécessaires pour activer . Il offre un mécanisme pour accrocher l'OEM dans le pipeline Camera2, par exemple en injectant une requête de capture ou l'activation d'un post-traitement.

   Pour le type "Extender avancé", Camera2/X interagit avec SessionProcessorImpl pour activer l'extension Camera2/X récupère les l'instance SessionProcessorImpl en appelant createSessionProcessor() au niveau de la Prolongateur.

Les sections suivantes décrivent le flux des extensions plus en détail.

Vérification de la version

Lors du chargement de la bibliothèque du fournisseur OEM depuis l'appareil au moment de l'exécution, Camera2/X vérifie si la bibliothèque est compatible avec la version de extensions-interface. Le extensions-interface utilise la gestion sémantique des versions, ou MAJEURE.MINEURE.PATCH, par exemple, 1.1.0 ou 1.2.0. Toutefois, seul le paramètre les versions majeure et mineure sont utilisées lors de la vérification de la version.

Pour vérifier la version, Camera2/X appelle ExtensionVersionImpl.checkApiVersion() avec les Version extensions-interface. Camera2/X utilise ensuite la version indiquée par pour déterminer si l'extension peut être activée et quelles fonctionnalités il doit appeler.

Remarque :checkApiVersion() ne devrait pas renvoyer de version extensions-interface. qui est plus récente que la version compatible Camera2/X. Par exemple, si Camera2/X prend en charge la version 1.3.0 et la bibliothèque du fournisseur OEM prend en charge la version 1.4.0. doit renvoyer 1.3.0 au lieu de 1.4.0.

Compatibilité avec les versions majeures

Si les versions majeures de l'extension-interface sont différentes Camera2/X et la bibliothèque du fournisseur, il est considéré comme incompatible. l'extension est désactivée.

Rétrocompatibilité.

Tant que la version majeure est identique, Camera2/X assure rétrocompatibilité avec les bibliothèques des fournisseurs OEM créées avec des extensions-interface versions. Par exemple, si Camera2/X est compatible avec extensions-interface 1.3.0, les bibliothèques de fournisseurs OEM qui ont implémenté la version 1.0.0, Les versions 1.1.0 et 1.2.0 restent compatibles. Cela signifie également qu'après avoir implémenté une version spécifique de la bibliothèque du fournisseur, Camera2/X s'assure que la bibliothèque est rétrocompatible avec les prochaines versions de extension-interface.

Compatibilité ascendante

Compatibilité ascendante avec les bibliothèques de fournisseurs des versions plus récentes de extensions-interface cela dépend de vous, l'OEM. Si vous avez besoin de fonctionnalités pour implémenter les extensions, vous pouvez les activer à partir d'une certaine version. Dans ce vous pouvez renvoyer la version extensions-interface compatible lorsque La version de la bibliothèque Camera2/X répond aux exigences. Si les versions de Camera2/X ne sont pas prises en charge, vous pouvez renvoyer une version incompatible, telle que 99.0.0 pour désactiver les extensions.

Initialisation de la bibliothèque du fournisseur

Après avoir vérifié la version de extensions-interface implémentée par l'OEM Camera2/X lance le processus d'initialisation. La La méthode InitializerImpl.init() indique à la bibliothèque OEM qu'une application tente pour utiliser des extensions.

Camera2/X n'appelle aucun autre appel vers la bibliothèque OEM (à part la vérification de version). jusqu'à ce que la bibliothèque du fournisseur OEM appelle OnExtensionsInitializedCallback.onSuccess() pour signaler la fin de l'initialisation.

Vous devez implémenter InitializerImpl à partir de extensions-interface 1.1.0. Camera2/X ignore l'initialisation de la bibliothèque. si la bibliothèque du fournisseur OEM implémente extensions-interface 1.0.0.

Comparaison entre les modèles Basic Extender et Advanced Extender

Il existe deux types d'implémentations de extensions-interface: Basic Extender et Advanced Extender. Advanced Extender est pris en charge depuis extensions-interface 1.2.0.

Implémentez Basic Extender pour les extensions qui traitent des images dans le HAL de l'appareil photo ou utiliser un post-traitement capable de traiter les flux YUV.

Implémentez Advanced Extender pour les extensions qui doivent personnaliser l'appareil Camera2 la configuration de flux et envoyer des requêtes de capture si nécessaire.

Reportez-vous au tableau suivant pour comparer les performances:

	Répéteur de base	Extension avancée
Configurations de flux	Fixe Aperçu: PRIVATE ou YUV_420_888 (si un outil de traitement existe) Capturer l'image: JPEG ou YUV_420_888 (si le processeur existe)	Personnalisable par l'OEM.
Envoi d'une demande de capture	Seules Camera2/X peuvent envoyer des requêtes de capture. Vous pouvez définir les paramètres ces demandes. Lorsque le processeur est fourni pour la capture d'image, Camera2/X peut envoyer plusieurs demandes de capture et envoyer toutes les images les résultats au processeur.	Une instance RequestProcessorImpl vous est fournie pour la requête de capture camera2, et d'obtenir les résultats et l'image. Camera2/X appelle startRepeating et startCapture sur SessionProcessorImpl pour signaler à l'OEM de lancer la répétition d'aperçu et de démarrer la séquence de capture d'image fixe, respectivement.
Hooks dans le pipeline de la caméra	onPresetSession fournit des paramètres de session. onEnableSession envoie une seule requête juste après la configuration de CameraCaptureSession. onDisableSession n'envoie qu'une seule demande avant la fermeture de CameraCaptureSession.	initSession initialise et renvoie un appareil photo personnalisé2. configuration de session pour créer la session de capture. onCaptureSessionStart est appelé juste après la configuration de CameraCaptureSession. onCaptureSessionEnd est appelé avant la fermeture de CameraCaptureSession.
Adapté à	Extensions implémentées dans le HAL de la caméra ou dans un processeur qui traite Images YUV	Dispose d'implémentations basées sur Camera2 pour les extensions. Nécessite une configuration de flux personnalisée, telle qu'un flux RAW. Séquence de capture interactive requise.
Version d'API compatible	Extensions Camera2: Android 13 ou version ultérieure Extensions CameraX: camera-extensions 1.1.0 ou version ultérieure	Extensions Camera2: Android 12L ou version ultérieure Extensions CameraX: camera-extensions 1.2.0-alpha03 ou version ultérieure

Remarque :Si ExtensionVersionImpl.isAdvancedExtenderImplemented() renvoie true, vous devez implémenter toutes les extensions dans Advanced Extender. Si isAdvancedExtenderImplemented() renvoie false, vous devez implémenter toutes les dans Basic Extender.

Flux de l'application

Le tableau suivant présente trois types de flux d'application et leurs les appels d'API correspondants de l'API Camera Extensions. Bien que Camera2/X fournissent pour ces API, vous devez implémenter correctement la bibliothèque de fournisseurs pour les prendre en charge. que nous décrirons plus en détail dans une section ultérieure.

	Extensions Camera2	Extensions CameraX
Disponibilité des extensions de requête	CameraExtensionCharacteristics .getSupportedExtensions	ExtensionsManager. isExtensionAvailable
Informations sur la requête	CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys	ExtensionsManager. getEstimatedCaptureLatencyRange CameraX gère le reste des informations dans la bibliothèque.
Prévisualiser et filmer avec l'extension activée	CameraDevice. createExtensionSession cameraExtensionsSession. setRepeatingRequest cameraExtensionsSession. capture	val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)

Répéteur de base

L'interface Basic Extender fournit des points d'ancrage à plusieurs endroits de la caméra pipeline. Chaque type d'extension est associé à des classes Extender dont les OEM ont besoin à mettre en œuvre.

Le tableau suivant répertorie les classes d'extension que les OEM doivent implémenter pour chaque extension:

	Classes d'extension à implémenter
Nuit	NightPreviewExtenderImpl.java NightImageCaptureExtenderImpl.java
HDR	HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
Automatique	AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java
Bokeh	BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java
Retouche du visage	BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java

Nous utilisons PreviewExtenderImpl et ImageCaptureExtenderImpl comme espaces réservés. dans l'exemple suivant. Remplacez-les par les noms fichiers que vous mettez en œuvre.

Remarque :Ces classes Extender peuvent être instanciées plusieurs fois si nécessaire. dans Camera2/X.

Basic Extender offre les fonctionnalités suivantes:

• Injectez des paramètres de session lors de la configuration de CameraCaptureSession ( onPresetSession).
• Vous avertir des événements de début et de fermeture de la session de capture, et envoyer un requête pour avertir le HAL avec les paramètres renvoyés (onEnableSession, onDisableSession).
• Injecter des paramètres de capture pour la requête (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• Ajoutez des processeurs pour l'aperçu tout en effectuant une capture pouvant être traitée. Flux YUV_420_888.

Remarque :Vous devez implémenter à la fois un aperçu et une capture d'écran pour les extensions que vous souhaitez activer. Par exemple, si vous souhaitez activer l'extension Nuit, vous devez implémenter NightPreviewExtenderImpl.java et NightCaptureExtenderImpl.java.

Voyons comment Camera2/X appelle extensions-interface pour atteindre les trois les flux d'application mentionnés ci-dessus.

Remarque :Camera2/X initialise toujours la bibliothèque du fournisseur. (InitializerImpl.init()) avant de démarrer l'un de ces flux d'application.

Parcours d'application 1: Vérifier la disponibilité des extensions

Figure 3. Flux d'application 1 sur Basic Extender

Dans ce flux, Camera2/X appelle directement la méthode isExtensionAvailable() de PreviewExtenderImpl et ImageCaptureExtenderImpl sans appeler init() Les deux classes d'extension doivent renvoyer true pour activer les extensions.

C'est souvent la première étape à effectuer pour vérifier si l'extension concernée est compatible avec un ID d'appareil photo donné avant d'activer l'extension. En effet, certaines extensions ne sont compatibles qu'avec certains identifiants de caméra.

Flux d'application 2: Informations sur les requêtes

Figure 4. Flux d'application 2 sur Basic Extender

Après avoir déterminé si l'extension est disponible, les applications doivent interroger les informations suivantes avant d'activer l'extension.

• Capturez tout de même la plage de latence: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange renvoie la plage de la latence de capture pour que l'application puisse évaluer s'il est adapté activer l'extension pour le scénario actuel.

• Tailles disponibles pour l'aperçu et la surface de capture: ImageCaptureExtenderImpl.getSupportedResolutions et PreviewExtenderImpl.getSupportedResolutions renvoie une liste de formats d'image et les tailles compatibles avec le format et la taille de la surface.

• Clés de requête et de résultat acceptées: Camera2/X invoque les méthodes suivantes pour récupérer la capture compatible clés de requête et de résultat issues de votre implémentation:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X appelle toujours init() d'abord sur ces classes Extender avant d'interroger pour en savoir plus.

Flux d'application 3: prévisualiser/capturer avec l'extension activée (implémentation HAL)

Figure 5. Flux d'application 3 sur Basic Extender

Le schéma ci-dessus illustre le flux principal d'activation de l'aperçu et avec une extension sans processeur. Cela signifie que le HAL de la caméra traite l'extension.

Dans ce flux, Camera2/X appelle d'abord init(), puis onInit, ce qui vous avertit qu'une session d'appareil photo est sur le point de commencer avec les extensions spécifiées. Vous pouvez effectuer une lourde initialisation dans onInit().

Lors de la configuration de CameraCaptureSession, Camera2/X appelle onPresetSession pour obtenir les paramètres de la session. Après la session de capture, la configuration a bien été effectuée, Camera2/X appelle onEnableSession et renvoie une CaptureStageImpl qui contient les paramètres de capture. Appareil photo 2/X envoie immédiatement une requête unique avec ces paramètres de capture pour avertir CARL. De même, avant la fermeture de la session de capture, Camera2/X appelle onDisableSession, puis envoie une seule requête avec la capture renvoyée paramètres.

La requête répétée déclenchée par Camera2/X contient les paramètres de requête renvoyé par PreviewExtenderImpl.getCaptureStage(). De plus, les images de capture contient les paramètres renvoyés par ImageCaptureExtenderImpl.getCaptureStages()

Enfin, Camera2/X appelle onDeInit() une fois la session d'appareil photo terminée. Vous pouvez libérer des ressources dans onDeinit().

Remarque :Plusieurs sessions d'appareil photo peuvent être ouvertes et fermées dans Camera2/X. onInit() et onDeInit(), bien que ce schéma ne montre qu'une seule session de caméra.

Prévisualiser le processeur

En plus du HAL de la caméra, vous pouvez également implémenter des extensions dans un processeur.

Implémenter PreviewExtenderImpl.getProcessorType pour spécifier le type de processeur comme expliqué ci-dessous:

• PROCESSOR_TYPE_NONE:aucun processeur. Les images sont traitées par l'appareil photo CARL.

• PROCESSOR_TYPE_REQUEST_UPDATE_ONLY:le type de processeur vous permet mettre à jour la requête récurrente avec les nouveaux paramètres de requête de capture en fonction dernier TotalCaptureResult.

  PreviewExtenderImpl.getProcessor doit renvoyer un RequestUpdateProcessorImpl qui traite l'instance TotalCaptureResult et renvoie une CaptureStageImpl pour mettre à jour la requête récurrente. PreviewExtenderImpl.getCaptureStage() doit également refléter le résultat de le traitement et renvoie la dernière version de CaptureStageImpl.

• PROCESSOR_TYPE_IMAGE_PROCESSOR:ce type vous permet d'implémenter un processeur pour traiter les images YUV_420_888 et écrire la sortie dans un Surface PRIVATE.

  Vous devez implémenter et renvoyer PreviewImageProcessorImpl dans PreviewExtenderImpl.getProcessor. Le sous-traitant est responsable permettant de traiter les images d'entrée YUV_420_888. La sortie doit être écrite dans Format d'aperçu PRIVATE. Camera2/X utilise à la place une surface YUV_420_888. de PRIVATE afin de configurer le CameraCaptureSession pour l'aperçu.

  Consultez l'illustration suivante pour le flux:

Figure 6. Prévisualiser le flux avec PreviewImageProcessorImpl

L'interface PreviewImageProcessorImpl étend ProcessImpl et comporte trois méthodes importantes:

• onOutputSurface(Surface surface, int imageFormat) définit la surface de sortie. pour le processeur. Pour PreviewImageProcessorImpl, imageFormat est un pixel. tel que PixelFormat.RGBA_8888.

• onResolutionUpdate(Size size) définit la taille de l'image d'entrée.

• onImageFormatUpdate(int imageFormat) définit le format d'image de l'entrée. l'image. Actuellement, il ne peut s'agir que de YUV_420_888.

Processeur de capture d'image

Pour la capture d'image, vous pouvez implémenter un processeur en renvoyant une CaptureProcessorImpl à l'aide de ImageCaptureExtenderImpl.getCaptureProcessor. Le processeur responsable du traitement d'une liste d'images YUV_420_888 capturées et TotalCaptureResult et écrivez la sortie sur une surface YUV_420_888.

Vous pouvez supposer que l'aperçu est activé et en cours d'exécution avant d'envoyer capture la requête.

Reportez-vous au schéma ci-dessous pour en savoir plus:

Figure 7. Capturer quand même le flux avec CaptureProcessorImpl

1. Camera2/X utilise une surface au format YUV_420_888 pour la capture fixe à configurer. la session de capture. Camera2/X prépare CaptureProcessorImpl en appelant:

   • CaptureProcessorImpl.onImageFormatUpdate() avec YUV_420_888.
   • CaptureProcessorImpl.onResolutionUpdate() par la taille de l'image d'entrée.
   • CaptureProcessorImpl.onOutputSurface() avec une YUV_420_888 de sortie sur la surface de l'écran.

2. ImageCaptureExtenderImpl.getCaptureStages renvoie une liste de CaptureStageImpl , où chaque élément correspond à une instance CaptureRequest avec des paramètres de capture envoyées par Camera2/X. Par exemple, si elle renvoie une liste de trois CaptureStageImpl instances, Camera2/X envoie trois requêtes de capture avec les paramètres de capture correspondants à l'aide de la méthode captureBurst API.

   Remarque :getCaptureStages() est autorisé à renvoyer plus d'un CaptureStageImpl uniquement lorsque getCaptureProcessor() renvoie une de l'instance.

3. Les images reçues et TotalCaptureResult instances sont regroupées et envoyées à CaptureProcessorImpl pour traitement.

4. CaptureProcessorImpl écrit l'image du résultat (format YUV_420_888) dans le surface de sortie spécifiée par l'appel onOutputSurface(). Camera2/X le convertit en images JPEG si nécessaire.

Prise en charge des clés et des résultats de demande de capture

En plus de l'aperçu et de la capture de l'appareil photo, les applications peuvent définir le zoom, des paramètres de flash ou de déclenchement d'un appui pour effectuer la mise au point. Il est possible que ces paramètres compatibles avec l'implémentation de votre extension.

Les méthodes suivantes ont été ajoutées à extensions-interface 1.3.0 pour permettre d'exposer les paramètres compatibles avec votre implémentation:

• ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() renvoie la les clés de demande de capture compatibles avec votre implémentation.
• ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() renvoie la les clés de résultat de capture contenues dans le résultat de la capture.

Si le HAL de l'appareil photo traite l'extension, Camera2/X récupère la capture. donne CameraCaptureSession.CaptureCallback. Toutefois, si le processeur est implémenté, puis Camera2/X récupère les résultats de la capture ProcessResultImpl , qui est transmis à process() dans PreviewImageProcessorImpl et CaptureProcessorImpl. Vous êtes responsable de la création de rapports le résultat de la capture via ProcessResultImpl vers Camera2/X.

Consultez la définition de l'interface CaptureProcessorImpl ci-dessous à titre d'exemple. Dans extensions-interface 1.3.0 ou version ultérieure, le deuxième appel process() est appelé:

Interface CaptureProcessorImpl extends ProcessorImpl {
    // invoked when extensions-interface version < 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results);
    // invoked when extensions-interface version >= 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results,
            ProcessResultImpl resultCallback, Executor executor);
}

Remarque: Les CaptureRequest#JPEG_QUALITY et CaptureRequest#JPEG_ORIENTATION les clés sont toujours acceptées, qu'elles soient ajoutées ou non à la liste.

Pour les opérations courantes de l'appareil photo, comme le zoom, la mise au point tactile, le flash et l'exposition. contre rémunération, nous vous recommandons d'utiliser les clés suivantes résultat de la requête et de la capture:

• Zoom: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_ZOOM_RATIO
  • CaptureRequest#SCALER_CROP_REGION
• Appuyer pour effectuer la mise au point: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_AF_MODE
  • CaptureRequest#CONTROL_AF_TRIGGER
  • CaptureRequest#CONTROL_AF_REGIONS
  • CaptureRequest#CONTROL_AE_REGIONS
  • CaptureRequest#CONTROL_AWB_REGIONS
• Flash: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_AE_MODE
  • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
  • CaptureRequest#FLASH_MODE
• Correction d'exposition: <ph type="x-smartling-placeholder">
  </ph>
  • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Pour les répéteurs Basic qui implémentent la version 1.2.0 ou des versions antérieures, CameraX L'API Extensions accepte explicitement toutes les clés ci-dessus. Pour extensions-interface 1.3.0, CameraX et Camera2 respectent la liste renvoyée et n'accepte que les clés qu'il contient. Par exemple, si vous décidez de renvoyer uniquement CaptureRequest#CONTROL_ZOOM_RATIO et CaptureRequest#SCALER_CROP_REGION dans l'implémentation 1.3.0, alors que signifie que seul le zoom est pris en charge par l'application, tandis que la mise au point tactile, le flash et l'exposition sont acceptés. de rémunération ne sont pas autorisées.

Remarque :Les extensions Camera2 ne permettent de définir que des paramètres JPEG_QUALITY et JPEG_ORIENTATION sous Android 12 et Android 12L. Démarrage... Sur Android 13, l'API Extensions de Camera2 accepte d'autres paramètres, comme le zoom ou clignoter à condition que ces touches soient renvoyées par ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys chez votre fournisseur OEM bibliothèque qui implémente extensions-interface 1.3.0 ou version ultérieure.

Extension avancée

Advanced Extender est un type d'implémentation fournisseur basé sur l'API Camera2. Ce type d'extension a été ajouté dans extensions-interface 1.2.0. En fonction de du fabricant de l'appareil, les extensions peuvent être implémentées dans la couche d'application, qui dépend des facteurs suivants:

• Configuration des flux personnalisés:configurez des flux personnalisés, comme le flux RAW. ou avoir plusieurs flux pour différents identifiants de caméra physiques.

• Capacité à envoyer des requêtes Camera2:pour une interaction compliquée qui peut envoyer des requêtes de capture avec des paramètres basés sur les résultats de les demandes précédentes.

Advanced Extender fournit un wrapper, ou une couche intermédiaire, pour que vous puissiez personnaliser la configuration du flux et envoyer des requêtes de capture à la demande.

Remarque :L'API Camera2 Extensions est compatible avec Advanced Extender depuis Android. 12L. Pour l'API Extensions de CameraX, Advanced Extender est compatible depuis CameraX 1.2.0-alpha03.

Fichiers à implémenter

Pour passer à l'implémentation Advanced Extender, Méthode isAdvancedExtenderImplemented() dans ExtensionVersionImpl doit renvoyer true. Pour chaque type d'extension, les OEM doivent implémenter les classes Extender correspondantes. Les fichiers d'implémentation Advanced Extender sont dans le package advanced.

	Classes d'extension à implémenter
Nuit	advanced/NightAdvancedExtenderImpl.java
HDR	advanced/HdrAdvancedExtenderImpl.java
Automatique	advanced/AutoAdvancedExtenderImpl.java
Bokeh	advanced/BokehAdvancedExtenderImpl.java
Retouche du visage	advanced/BeautyAdvancedExtenderImpl.java

Nous utilisons AdvancedExtenderImpl comme espace réservé dans l'exemple suivant. Remplacez-le par le nom du fichier d'extension de l'extension la mise en œuvre.

Voyons comment Camera2/X appelle extensions-interface pour atteindre les trois les flux d'application.

Remarque :Camera2/X initialise toujours la bibliothèque du fournisseur ( InitializerImpl.init()) avant de démarrer l'un de ces flux d'application.

Parcours d'application 1: Vérifier la disponibilité des extensions

Figure 8. Flux d'application 1 sur Advanced Extender

Tout d'abord, l'application vérifie si l'extension donnée est compatible.

Remarque :L'application n'a pas besoin d'appeler AdvancedExtenderImpl.init(). avant d'appeler isExtensionAvailable().

Flux d'application 2: Informations sur les requêtes

Figure 9. Flux d'application 2 sur Advanced Extender

Après avoir appelé AdvancedExtenderImpl.init(), l'application peut interroger la en suivant les informations concernant AdvancedExtenderImpl:

• Estimation de la latence de capture des images fixes: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() renvoie la plage de la latence de capture pour que l'application puisse évaluer si elle est adaptée activer l'extension pour le scénario actuel.

• Résolutions compatibles pour l'aperçu et la capture fixe:

  • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() renvoie une carte. à la liste des tailles compatibles avec le format de la surface d'aperçu et la taille de l'image. Les OEM doivent au moins accepter le format PRIVATE.

  • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() renvoie la les formats et tailles compatibles pour capturer la surface. Les OEM doivent prendre en charge à la fois Sortie au format JPEG et YUV_420_888.

  • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() renvoie la tailles prises en charge pour un flux YUV_420_888 supplémentaire pour l'analyse d'images. Si le la surface YUV d'analyse d'image n'est pas prise en charge, getSupportedYuvAnalysisResolutions() doit renvoyer null ou une liste vide.

• Clés/résultats de requête de capture disponibles (ajoutés dans extensions-interface 1.3.0): Camera2/X invoque les méthodes suivantes pour récupérer la capture compatible clés de requête et de résultat issues de votre implémentation:

  • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
  • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Pour en savoir plus, consultez Prenez en charge les clés de demande et les résultats de capture.

Flux d'application 3: prévisualiser/enregistrer la vidéo avec l'extension activée

Figure 10. Flux d'application 3 sur Advanced Extender

Le schéma ci-dessus illustre le processus principal permettant de démarrer l'aperçu et de capturer le type "Advanced Extender". Passons en revue chaque étape.

1. Instance SessionProcessorImpl

   L'implémentation principale de Advanced Extender se trouve dans SessionProcessorImpl, qui est chargé de fournir une configuration de session personnalisée et d'envoyer les requêtes de capture pour lancer la requête de prévisualisation et de capture. AdvancedExtenderImpl.createSessionProcessor() est appelé pour renvoyer la SessionProcessorImpl instance.

   Remarque :Une session d'appareil photo peut utiliser une instance SessionProcessorImpl plusieurs fois. Par conséquent, l'implémentation doit pouvoir prendre en charge plusieurs initSession() et deInitSession() appellent une seule instance SessionProcessorImpl.

2. initSession

   SessionProcessorImpl.initSession() initialise la session pour l'extension. C'est ici que vous allouez des ressources et renvoyez une configuration de session pour en préparant un CameraCaptureSession.

   Pour les paramètres d'entrée, Camera2/X spécifie les configurations de la surface de sortie. pour obtenir un aperçu, une capture fixe et, éventuellement, une analyse d'image YUV. Cette sortie la configuration de la surface (OutputSurfaceImpl) contient la surface, la taille et l'image format unique récupéré par les méthodes suivantes dans AdvancedExtenderImpl:

   • getSupportedPreviewOutputResolutions()
   • getSupportedCaptureOutputResolutions()
   • getSupportedYuvAnalysisResolutions()

   Vous devez renvoyer une instance Camera2SessionConfigImpl, qui se compose d'un Liste de Camera2OutputConfigImpl instances et des paramètres de session utilisés pour configurer CameraCaptureSession. Vous êtes responsable les bonnes images de caméra vers les surfaces de sortie transmises par Appareil photo 2/X. Voici quelques options pour activer le résultat:

   • Traitement dans la HAL de la caméra:vous pouvez ajouter directement les surfaces de sortie à CameraCaptureSession avec un SurfaceOutputConfigImpl la mise en œuvre. La surface de sortie fournie est configurée sur la caméra. et permet au HAL de la caméra de traiter l'image.

   • Traitement d'une surface ImageReader intermédiaire (RAW, YUV, etc.) : ajoutez la les surfaces intermédiaires ImageReader à CameraCaptureSession avec une ImageReaderOutputConfigImpl.

     Vous devez traiter les images intermédiaires et écrire l'image de résultat dans la surface de sortie.

   Remarque :Camera2/X crée et gère les instances ImageReader à votre place. Toi vous pouvez définir une instance ImageProcessorImpl pour récupérer l'image.
   • Utiliser le partage de surface Camera2:utiliser le partage de surface avec une autre surface en ajoutant une instance Camera2OutputConfigImpl au Méthode getSurfaceSharingOutputConfigs() d'une autre Camera2OutputConfigImpl. Le format et la taille de la surface doivent être identiques.

   Toutes les Camera2OutputConfigImpl, y compris SurfaceOutputConfigImpl et ImageReaderOutputConfigImpl doit avoir un identifiant unique (getId()), qui est utilisé pour spécifier la surface cible et récupérer l'image ImageReaderOutputConfigImpl

3. onCaptureSessionStart et RequestProcessorImpl

   Lorsque CameraCaptureSession démarre et que le framework Camera appelle onConfigured(), puis Camera2/X appelle SessionProcessorImpl.onCaptureSessionStart() avec la requête Camera2 le wrapper RequestProcessImpl. Camera2/X implémente RequestProcessImpl, qui vous permet d'exécuter les requêtes de capture et récupérer des images si ImageReaderOutputConfigImpl est utilisé.

   Les API RequestProcessImpl sont semblables à Camera2 CameraCaptureSession en termes d'exécution de requêtes. Les différences sont les suivantes:

   • La surface cible est spécifiée par l'identifiant Instance Camera2OutputConfigImpl.
   • Possibilité de récupérer l'image de ImageReader.

   Vous pouvez appeler RequestProcessorImpl.setImageProcessor() avec un ID Camera2OutputConfigImpl dans lequel enregistrer une instance ImageProcessorImpl recevoir des images.

   L'instance RequestProcessImpl n'est plus valide après les appels Camera2/X SessionProcessorImpl.onCaptureSessionEnd()

4. Lancer l'aperçu et prendre une photo

   Dans l'implémentation Advanced Extender, vous pouvez envoyer des requêtes de capture via l'interface RequestProcessorImpl. Camera2/X vous invite à lancer la requête répétée d'aperçu ou la séquence de capture d'image fixe en procédant comme suit : appeler SessionProcessorImpl#startRepeating et SessionProcessorImpl#startCapture respectivement. Vous devez envoyer une capture pour satisfaire ces demandes d'aperçu et de capture d'écran.

   Camera2/X définit également les paramètres de requête de capture via SessionProcessorImpl#setParameters Vous devez définir ces paramètres de requête (si les paramètres sont pris en charge) sur les requêtes répétées et uniques.

   Vous devez accepter au moins CaptureRequest.JPEG_ORIENTATION et CaptureRequest.JPEG_QUALITY extensions-interface 1.3.0 prend en charge les requêtes et les clés de résultat, qui sont exposées par les méthodes suivantes:

   • AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
   • AdvancedExtenderImpl.getAvailableCaptureResultKeys()

   Lorsque les développeurs définissent les clés dans la liste getAvailableCaptureRequestKeys, vous devez activer les paramètres et vous assurer que la capture Le résultat contient les clés de la liste getAvailableCaptureResultKeys.

5. startTrigger

   SessionProcessorImpl.startTrigger() est appelé pour démarrer le déclencheur, en tant que CaptureRequest.CONTROL_AF_TRIGGER et CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER Vous pouvez ignorer les les clés de demande de capture qui n'étaient pas annoncées dans AdvancedExtenderImpl.getAvailableCaptureRequestKeys()

   startTrigger() est compatible depuis extensions-interface 1.3.0. Il permet aux applications d'implémenter la mise au point tactile et le flash avec des extensions.

6. Nettoyage

   À la fin d'une session de capture, SessionProcessorImpl.onCaptureSessionEnd() est appelé avant la fermeture. CameraCaptureSession Une fois la session de capture terminée, deInitSession() effectue le nettoyage.

Prise en charge de l'aperçu, de la capture fixe et de l'analyse d'images

Vous devez appliquer l'extension à la fois pour l'aperçu et pour capturer les cas d'utilisation. Toutefois, si la latence est trop élevée pour que l'aperçu s'affiche correctement, vous pouvez n'applique l'extension que pour la capture fixe.

Pour le type d'extension de base, que l'aperçu soit activé ou non, vous devez implémenter ImageCaptureExtenderImpl et PreviewExtenderImpl pour une extension donnée. Souvent, une application utilise aussi un flux YUV pour analyser comme la recherche de codes QR ou de texte. Pour mieux prendre en charge ce cas d'utilisation , vous devez prendre en charge la combinaison de flux (aperçu, capture d'image fixe et Flux YUV_420_888 pour configurer CameraCaptureSession. Cela signifie que si vous implémentez un processeur, vous devez prendre en charge le flux combinaison de trois flux YUV_420_888.

Pour Advanced Extender, Camera2/X transmet trois surfaces de sortie au SessionProcessorImpl.initSession() appel. Ces surfaces de sortie sont destinées à la prévisualisation , la capture fixe et l'analyse d'image, respectivement. Vous devez vous assurer que l'aperçu tout en capturant les surfaces de sortie affichent une sortie valide. Toutefois, pour l'image de sortie de l'analyse, assurez-vous qu'elle fonctionne uniquement lorsqu'elle n'est pas nulle. Si votre n'est pas compatible avec le flux d'analyse d'images, vous pouvez renvoyer une dans AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Ce garantit que la surface de sortie de l'analyse d'image est toujours nulle dans SessionProcessorImpl.initSession()

Remarque :Vous n'êtes pas obligé d'appliquer l'extension à l'analyse de l'image. flux. De plus, l'API Extensions Camera2 ne permet de configurer que deux sur différentes surfaces: prévisualiser et prendre une photo.

Prendre en charge la capture vidéo

L'architecture actuelle des extensions de l'appareil photo n'est compatible qu'avec l'aperçu et permettent de capturer des cas d'utilisation. L'extension n'est pas compatible avec MediaCodec ou MediaRecorder pour enregistrer la vidéo. Toutefois, il est possible pour que les applications enregistrent l'aperçu.

La compatibilité des surfaces MediaCodec et MediaRecorder est en cours d'examen.

Métadonnées spécifiques aux extensions

Pour Android 14 ou version ultérieure, métadonnées spécifiques aux extensions permet aux clients de l'extension d'appareil photo de définir et de recevoir une capture spécifique à l'extension les paramètres et les résultats des requêtes. Plus précisément, l'extension d'appareil photo les clients peuvent utiliser le paramètre de demande de capture EXTENSION_STRENGTH pour contrôler l'intensité de l'extension et le résultat de la capture EXTENSION_CURRENT_TYPE pour indiquent le type d'extension activé.

Demandes de capture

La EXTENSION_STRENGTH Paramètre de requête de capture contrôle l'intensité de l'effet de post-traitement de l'extension. La colonne Le résultat de la capture inclut la valeur de force par défaut si ce paramètre n'est pas défini explicitement par le client. Ce paramètre peut être appliqué comme suit pour ces types d'extensions:

• BOKEH: contrôle le niveau de flou.
• HDR et NIGHT: contrôle la quantité d'images fusionnées et la luminosité des l'image finale.
• FACE_RETOUCH: contrôle le niveau d'amélioration esthétique et de peau lissage.

La plage acceptée pour le paramètre EXTENSION_STRENGTH est comprise entre 0 et 100, 0 indiquant qu'il n'y a pas de traitement des extensions ni de passthrough simple. 100 indiquant l'intensité d'extension maximale de l'effet de traitement.

Pour ajouter la prise en charge de EXTENSION_STRENGTH, utilisez le fournisseur API de paramètres spécifiques introduites dans la version 1.3.0 de la bibliothèque d'extensions de commande. Pour en savoir plus, consultez getAvailableCaptureRequestKeys().

Capturer les résultats

La EXTENSION_CURRENT_TYPE permet aux implémentations d'extension d'informer les clients de l'état type d'extension.

Étant donné que les extensions qui utilisent le type AUTO passent d'une extension à l'autre de manière dynamique, tels que HDR et NIGHT en fonction des conditions de scène, de la caméra extensions que les applications peuvent utiliser EXTENSION_CURRENT_TYPE pour afficher des informations sur l'extension actuelle sélectionnée par l'extension AUTO.

Estimation de la latence de capture en temps réel

Pour Android 14 ou version ultérieure, les clients de l'extension d'appareil photo Vous pouvez interroger en temps réel les estimations de latence en fonction de la scène des conditions d'environnement à l'aide getRealtimeStillCaptureLatency() Ce fournit des estimations plus précises que la méthode statique getEstimatedCaptureLatencyRangeMillis() . En fonction de l'estimation de la latence, les applications peuvent décider d'ignorer l'extension en cours de traitement ou pour informer les utilisateurs d'une longue opération en cours d'exécution.

CameraExtensionSession.StillCaptureLatency latency;

latency = extensionSession.getRealtimeStillCaptureLatency();

// The capture latency from ExtensionCaptureCallback#onCaptureStarted() until ExtensionCaptureCallback#onCaptureProcessStarted().

latency.getCaptureLatency();

// The processing latency from  ExtensionCaptureCallback#onCaptureProcessStarted() until  the processed frame returns to the client.

latency.getProcessingLatency();

Pour prendre en charge les estimations de latence en temps réel, implémentez les éléments suivants:

• Extensions standards: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
• Extensions avancées: SessionProcessorImpl.getRealtimeCaptureLatency

Capturer les rappels de progression du traitement

Pour Android 14 ou version ultérieure, les clients de l'extension d'appareil photo peut recevoir des rappels pour la progression du traitement des captures d'écrans de longue durée. opérations. Les applications peuvent afficher les progrès actuels des utilisateurs afin d'améliorer l'expérience utilisateur globale.

Les applications peuvent utiliser le code suivant pour intégrer cette fonctionnalité:

import android.hardware.camera2.CameraExtensionSession.
ExtensionCaptureCallback;

{
…
  class AppCallbackImpl extends ExtensionCaptureCallback {
…
    @Override
    public void onCaptureProcessProgressed(
      @NonNull CameraExtensionSession session,
      @NonNull CaptureRequest request,
      @IntRange(from = 0, to = 100) int progress) {
      // Update app UI with current progress
    }
  }
…
}

Pour prendre en charge les rappels de progression du traitement de la capture, votre fournisseur d'extension doit appeler les rappels suivants avec la progression actuelle :

• Extensions de base: ProcessResultImpl.onCaptureProcessProgressed()
• Extensions avancées: CaptureCallback.onCaptureProcessProgressed()

Capture d'écran fixe après affichage

Pour Android 14 ou version ultérieure, les extensions d'appareil photo peuvent fournir un postview (image d'aperçu) à l'aide de setPostviewOutputConfiguration Pour améliorer l'expérience utilisateur, les applications peuvent afficher une image "postview" lorsqu'une extension connaît une latence de traitement accrue, et remplacer l'image lorsqu'elle est disponible. Les applications peuvent configurer et émettez des requêtes de capture après affichage à l'aide du code de référence suivant:

{
…
if (!CameraExtensionCharacteristics.isPostviewAvailable()) {
    continue;
}
…
ExtensionSessionConfiguration extensionConfiguration = new
        ExtensionSessionConfiguration(
                CameraExtensionCharacteristics.EXTENSION_NIGHT,
                outputConfig,
                backgroundExecutor,
                extensionSessionStateCallback
    );

extensionConfiguration.setPostviewOutputConfiguration(
    postviewImageOutput);
…
CaptureRequest.Builder captureRequestBuilder =
    cameraDevice.createCaptureRequest(
        CameraDevice.TEMPLATE_STILL_CAPTURE);
captureRequestBuilder.addTarget(stillImageReader.getSurface());
captureRequestBuilder.addTarget(postviewImageSurface);

CaptureRequest captureRequest = captureRequestBuilder.build();
…
}

Pour permettre la capture d'écran fixe après affichage, votre implémentation du fournisseur doit implémenter suivantes:

• Extensions standards: CaptureProcessorImpl.onPostviewOutputSurface et CaptureProcessorImpl.processWithPostview

• Extensions avancées: SessionProcessorImpl.startCaptureWithPostview

Prendre en charge la sortie SurfaceView

Pour Android 14 ou version ultérieure, les clients de l'extension d'appareil photo vous pouvez utiliser des chemins d'affichage d'aperçu optimisés pour la puissance et les performances en enregistrant un SurfaceView une instance de sortie de prévisualisation pour les requêtes récurrentes.

Pour accepter le résultat SurfaceView, l'implémentation de votre extension de fournisseur doit être capable de diffuser un aperçu et de générer un aperçu vers SurfaceView instances. À vérifiez qu'il est compatible, exécutez la commande SurfaceViewExtensionPreviewTest.java module CTS.

Types de sessions spécifiques au fournisseur

Cette fonctionnalité permet aux implémentations d'extensions de fournisseur de sélectionner un type de session spécifique au fournisseur qui sera défini dans la session de capture interne de l'appareil photo au lieu de la valeur par défaut.

Cette fonctionnalité s'intègre entièrement dans le framework et la pile de fournisseurs, et n'a aucun impact visible sur le client ou le public sur les API.

Pour sélectionner un type de session spécifique au fournisseur, implémentez les éléments suivants pour vos bibliothèques d'extensions: * ExtenderStateListener.onSessionType() pour les extensions de base * Camera2SessionConfigImpl.getSessionType() pour les extensions avancées

Historique des versions de l'interface des extensions

Le tableau suivant présente l'historique des versions de l'interface de l'extension Camera. Toi doit toujours implémenter la bibliothèque du fournisseur avec la dernière version.

Version	Fonctionnalités supplémentaires
Version 1.0.0	Vérification de la version <ph type="x-smartling-placeholder"> </ph> ExtensionVersionImpl Répéteur de base <ph type="x-smartling-placeholder"> </ph> PreviewExtenderImpl ImageCaptureExtenderImpl Processor PreviewImageProcessorImpl CaptureProcessorImpl RequestUpdateProcessorImpl
1.1.0	Initialisation de la bibliothèque <ph type="x-smartling-placeholder"> </ph> InitializerImpl Exposer les résolutions compatibles <ph type="x-smartling-placeholder"> </ph> PreviewExtenderImpl.getSupportedResolutions ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0	AdvancedExtender AdvancedExtenderImpl SessionProcessorImpl Obtenir une estimation de la latence de capture ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0	Exposer les clés de requête de capture/de résultats compatibles ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys et getAvailableCaptureResultKeys AdvancedExtenderImpl.getAvailableCaptureRequestKeys et getAvailableCaptureResultKeys Nouvel appel process() qui prend ProcessResultImpl dans PreviewImageProcessorImpl et CaptureProcessorImpl Demande de type de déclencheur de prise en charge AdvancedExtenderImpl.startTrigger
1.4.0	Métadonnées spécifiques aux extensions Capture dynamique des estimations de latence Capturer les rappels de progression du traitement Capture d'écran fixe après affichage Prise en charge de la sortie SurfaceView Types de sessions spécifiques au fournisseur

Implémentation de référence

Les implémentations de bibliothèque de fournisseurs OEM suivantes sont disponibles dans frameworks/ex

• advancedSample: implémentation de base de Advanced Extender.

• sample: implémentation de base de Basic Extender.

• service_based_sample: implémentation qui montre comment héberger Extensions d'appareil photo Service Cette implémentation contient les composants suivants:

  • oem_library: Bibliothèque OEM d'extensions Camera pour les API d'extensions Camera2 et CameraX. qui implémente Extensions-Interface. Il s'agit d'un passthrough transfère les appels de Extensions-Interface vers le service. Cette bibliothèque fournit également des fichiers AIDL et des classes wrapper pour communiquer avec Google Cloud.

    Advanced Extender est activé par défaut. Pour activer Basic Extender, modifiez ExtensionsVersionImpl#isAdvancedExtenderImplemented pour revenir false

  • extensions_service: Exemple d'implémentation du service d'extensions Ajouter votre implémentation ici. L'interface à implémenter dans le service est similaire à Extensions-Interface. Par exemple, l'implémentation IAdvancedExtenderImpl.Stub effectue les mêmes opérations que AdvancedExtenderImpl ImageWrapper et TotalCaptureResultWrapper sont nécessaires pour que les champs Image et TotalCaptureResult puissent être morcelés.

Configurer la bibliothèque sous-revendeur sur un appareil

La bibliothèque du fournisseur OEM n'est pas intégrée à une application. elle est chargée depuis l'appareil au moment de l'exécution par Camera2/X. Dans CameraX, la balise <uses-library> déclare que la bibliothèque androidx.camera.extensions.impl, qui est définie dans AndroidManifest.xml de la bibliothèque camera-extensions, est une dépendance de CameraX et doit être lors de l'exécution. Dans Camera2, le framework charge un service d'extensions déclare également que <uses-library> charge le même androidx.camera.extensions.impl lors de l'exécution.

Cela permet aux applications tierces utilisant des extensions de charger automatiquement l'OEM bibliothèque du fournisseur. La bibliothèque OEM est marquée comme facultative afin que les applications puissent s'exécuter sur des appareils qui n'ont pas cette bibliothèque sur l'appareil. Camera2/X gère automatiquement ce comportement lorsqu'une appli tente d'utiliser un appareil photo. à condition que le fabricant de l'appareil place la bibliothèque OEM sur le appareil afin qu'il soit détecté par l'application.

Pour configurer la bibliothèque OEM sur un appareil, procédez comme suit:

1. Ajoutez un fichier d'autorisation requis par la balise <uses-library>. en utilisant le format suivant: /etc/permissions/ANY_FILENAME.xml Pour Exemple : /etc/permissions/camera_extensions.xml. Les fichiers contenus dans fournit un mappage de la bibliothèque nommée dans <uses-library> avec chemin d'accès réel au fichier sur l'appareil.

2. Utilisez l'exemple ci-dessous pour ajouter les informations requises au fichier.

   • name doit être androidx.camera.extensions.impl, car la bibliothèque recherchée par CameraX.
   • file est le chemin absolu du fichier contenant le l'implémentation des extensions (par exemple, /system/framework/androidx.camera.extensions.impl.jar).

   <?xml version="1.0" encoding="utf-8"?>
   <permissions>
       <library name="androidx.camera.extensions.impl"
                file="OEM_IMPLEMENTED_JAR" />
   </permissions>
   

Sous Android 12 ou version ultérieure, les appareils compatibles avec CameraX la propriété ro.camerax.extensions.enabled des extensions doit être définie sur true, qui permet de demander si un appareil prend en charge les extensions. Pour ce faire, ajoutez la ligne suivante au fichier de création de l'appareil:

PRODUCT_VENDOR_PROPERTIES += \
    ro.camerax.extensions.enabled=true \

Validation

Pour tester votre mise en œuvre de la bibliothèque du fournisseur OEM pendant la de développement, utilisez l'exemple d'application androidx-main/camera/integration-tests/extensionstestapp/ qui passe par différentes extensions de fournisseurs.

Une fois l'implémentation terminée, utilisez la méthode outil de validation extensions appareil photo d'exécuter des tests automatisés et manuels afin de vérifier que la bibliothèque du fournisseur est correctement implémentée.

Mode Scène étendu et extensions d'appareil photo

Pour l'extension bokeh, en plus de l'exposer à l'aide d'extensions de caméra, peut exposer l'extension à l'aide du mode Scène étendu, activé via la CONTROL_EXTENDED_SCENE_MODE . Pour en savoir plus sur l'implémentation, consultez Bokeh de la caméra.

Le mode Scène étendu présente moins de restrictions que les extensions d'appareil photo pour appareil photo2. Par exemple, vous pouvez activer le mode Scène étendue dans Une instance CameraCaptureSession standard compatible avec les flux flexibles et les paramètres de requête de capture. À l'inverse, les extensions d'appareil photo n'acceptent qu'un ensemble fixe de types de flux et offrent une compatibilité limitée pour la capture paramètres de requête.

L'inconvénient du mode Scène étendue est que vous ne pouvez l'implémenter que dans le la caméra HAL, ce qui signifie qu'elle doit être validée pour fonctionner les contrôles orthogonaux à la disposition des développeurs d'applications.

Nous vous recommandons d'exposer le bokeh à l'aide du mode Scène étendu et de l'appareil photo. Extensions, car les applications peuvent préférer utiliser une API particulière pour activer le bokeh. Nous vous recommandons d'utiliser d'abord le mode Scène étendue, car il s'agit moyen flexible pour les applications d'activer l'extension bokeh. Vous pouvez ensuite implémenter l'interface des extensions de l'appareil photo basée sur le mode Scène étendu. Si vous mettez en œuvre bokeh dans le HAL de la caméra, par exemple, car il nécessite un poteau s'exécute dans la couche d'application pour traiter les images, nous vous recommandons l'extension bokeh à l'aide de l'interface Camera Extensions.

Questions fréquentes

Existe-t-il des restrictions concernant les niveaux d'API ?

Oui. Cela dépend de l'ensemble de fonctionnalités de l'API Android requis par l'OEM. de la bibliothèque de fournisseurs. Par exemple : ExtenderStateListener.onPresetSession() utilise les SessionConfiguration.setSessionParameters() pour définir un ensemble de tags de référence. Cet appel n'est disponible qu'au niveau de l'API. 28 et versions ultérieures. Pour en savoir plus sur des méthodes d'interface spécifiques, consultez la Documentation de référence de l'API