Extensions pour l'appareil photo

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

Pour obtenir la liste des extensions compatibles, qui est la même pour Camera2 et CameraX, consultez l'API CameraX Extensions. Si vous souhaitez ajouter une extension, signalez un bug à l'aide de l'outil Issue Tracker.

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

Architecture

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

Figure 1 : Schéma de l'architecture des extensions pour l'appareil photo

Comme le montre le diagramme, pour prendre en charge les extensions d'appareil photo, vous devez implémenter le extensions-interface fourni par la bibliothèque du fournisseur OEM. Votre bibliothèque de fournisseurs OEM permet d'utiliser deux API : l'API Extensions de CameraX et l'API Extensions de Camera2. Elles sont utilisées respectivement par les applications CameraX et Camera2 pour accéder aux extensions du fournisseur.

Implémenter la bibliothèque de fournisseurs OEM

Pour implémenter la bibliothèque de fournisseurs OEM, copiez les fichiers camera-extensions-stub dans un projet de bibliothèque système. Ces fichiers définissent l'interface Camera Extensions.

Les fichiers 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'extension Bokeh (implémentez-les si l'extension Bokeh est compatible)

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

Classes d'extension de la nuit (à implémenter si l'extension de la nuit est prise en charge)

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

Classes d'extension automatique (à implémenter si l'extension automatique est acceptée)

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

Classes d'extension HDR (à implémenter si l'extension HDR est prise en charge)

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

Classes d'extension de retouche du visage (à implémenter si l'extension de retouche du visage est compatible)

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

Utilitaires (facultatif, peut être supprimé)

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

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

Voyons comment les API Camera2 et CameraX Extensions interagissent avec la bibliothèque du fournisseur pour activer une extension. Le schéma suivant illustre le flux de bout en bout à l'aide de l'extension Night comme exemple :

Figure 2. Implémentation de l'extension Nuit

1. Vérification de la version :

   Les appels Camera2/X ExtensionVersionImpl.checkApiVersion() permettent de s'assurer que la version extensions-interface implémentée par l'OEM est compatible avec les versions prises en charge par Camera2/X.

2. Initialisation de la bibliothèque du fournisseur :

   InitializerImpl dispose d'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. Il existe deux types d'extendeurs : l'extendeur de base et l'extendeur avancé. Vous devez implémenter un type d'extendeur pour toutes les extensions. Pour en savoir plus, consultez Extender de base et Extender avancé.

   Camera2/X instancie les classes Extender et interagit avec elles pour récupérer des informations et activer l'extension. Pour une extension donnée, Camera2/X peut instancier les classes Extender plusieurs fois. Par conséquent, n'effectuez pas d'initialisation lourde dans le constructeur ni dans l'appel init(). Effectuez les tâches lourdes uniquement lorsque la session de l'appareil photo est sur le point de démarrer, par exemple lorsque onInit() est appelé dans Basic Extender ou initSession() dans Advanced Extender.

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

   • NightImageCaptureExtenderImpl.java
   • NightPreviewExtenderImpl.java

   Pour le type "Advanced Extender" :

   • NightAdvancedExtenderImpl.java

4. Vérifiez la disponibilité de l'extension :

   Avant d'activer l'extension, isExtensionAvailable() vérifie si l'extension est disponible sur l'ID de caméra spécifié via l'instance Extender.

5. Initialisez le répéteur avec les informations de la caméra :

   Les appels Camera2/X init() sur l'instance Extender et lui transmettent l'ID de la caméra et CameraCharacteristics.

6. Informations sur la requête :

   Appelle la classe Extender pour récupérer des informations telles que les résolutions compatibles, la latence estimée de la capture d'image et les clés de requête de l'Extender en vue d'activer l'extension.

7. Activez l'extension sur l'extendeur :

   La classe Extender fournit toutes les interfaces nécessaires pour activer la classe. Il offre un mécanisme permettant d'intégrer l'implémentation OEM dans le pipeline Camera2, par exemple en injectant des paramètres de requête de capture ou en activant un post-processeur.

   Pour le type d'extension avancée, Camera2/X interagit avec SessionProcessorImpl pour activer l'extension. Camera2/X récupère l'instance SessionProcessorImpl en appelant createSessionProcessor() sur l'extenseur.

Les sections suivantes décrivent plus en détail le flux d'extension.

Vérification de la version

Lors du chargement de la bibliothèque du fournisseur OEM à partir de l'appareil au moment de l'exécution, Camera2/X vérifie si la bibliothèque est compatible avec la version extensions-interface. extensions-interface utilise la gestion sémantique des versions, ou MAJEURE.MINEURE.CORRECTIF, par exemple, 1.1.0 ou 1.2.0. Toutefois, seules 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 la version extensions-interface compatible. Camera2/X utilise ensuite la version signalée par la bibliothèque OEM pour déterminer si l'extension peut être activée et quelles fonctionnalités elle doit appeler.

Compatibilité des versions majeures

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

Rétrocompatibilité.

Tant que la version majeure est identique, Camera2/X assure la rétrocompatibilité avec les bibliothèques de fournisseurs OEM conçues avec les versions extensions-interface antérieures. Par exemple, si Camera2/X est compatible avec extensions-interface 1.3.0, les bibliothèques de fournisseurs OEM qui ont implémenté les versions 1.0.0, 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 futures versions extension-interface.

Compatibilité ascendante

La compatibilité ascendante avec les bibliothèques de fournisseurs de extensions-interface plus récents dépend de vous, l'OEM. Si vous avez besoin de certaines fonctionnalités pour implémenter les extensions, vous pouvez les activer à partir d'une certaine version. Dans ce cas, vous pouvez renvoyer la version extensions-interface compatible lorsque la version de la bibliothèque Camera2/X répond aux exigences. Si les versions Camera2/X ne sont pas compatibles, 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 extensions-interface implémentée par la bibliothèque OEM, Camera2/X lance le processus d'initialisation. La méthode InitializerImpl.init() indique à la bibliothèque OEM qu'une application tente d'utiliser des extensions.

Camera2/X n'effectue aucun autre appel à la bibliothèque OEM (à l'exception de la vérification de la version) tant que la bibliothèque du fournisseur OEM n'appelle pas OnExtensionsInitializedCallback.onSuccess() pour notifier la fin de l'initialisation.

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

Prolongateur de base ou prolongateur avancé

Il existe deux types d'implémentation extensions-interface : l'extendeur de base et l'extendeur avancé. Advanced Extender est compatible depuis extensions-interface 1.2.0.

Implémentez BasicExtender pour les extensions qui traitent les images dans la HAL de l'appareil photo ou qui utilisent un post-processeur capable de traiter les flux YUV.

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

Consultez le tableau ci-dessous pour comparer les deux produits :

Flux d'application

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

Prolongateur de base

L'interface Basic Extender fournit des hooks à plusieurs endroits du pipeline de la caméra. Chaque type d'extension possède des classes Extender correspondantes que les OEM doivent implémenter.

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

Dans l'exemple suivant, nous utilisons PreviewExtenderImpl et ImageCaptureExtenderImpl comme espaces réservés. Remplacez-les par les noms des fichiers que vous implémentez.

L'extendeur de base offre les fonctionnalités suivantes :

• Injectez les paramètres de session lors de la configuration de CameraCaptureSession (onPresetSession).
• Vous informe des événements de début et de fin de la session de capture, et envoie une seule requête pour informer le HAL avec les paramètres renvoyés (onEnableSession, onDisableSession).
• Injectez les paramètres de capture pour la requête (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
• Ajoutez des processeurs pour l'aperçu et la capture d'image fixe capables de traiter le flux YUV_420_888.

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

Flux d'application 1 : Vérifier la disponibilité de l'extension

Figure 3. Processus de l'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 Extender doivent renvoyer true pour activer les extensions.

Il s'agit souvent de la première étape pour les applications qui souhaitent vérifier si le type d'extension donné est compatible avec un ID d'appareil photo spécifique avant d'activer l'extension. En effet, certaines extensions ne sont compatibles qu'avec certains ID de caméras.

Flux d'application 2 : Interroger des informations

Figure 4. Flux d'application 2 sur l'extension de base

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

• Plage de latence de capture fixe : ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange renvoie la plage de latence de capture de l'application pour évaluer s'il est approprié d'activer l'extension pour le scénario actuel.

• Tailles acceptées pour la surface d'aperçu et de capture : ImageCaptureExtenderImpl.getSupportedResolutions et PreviewExtenderImpl.getSupportedResolutions renvoient une liste des formats d'image et des tailles acceptés pour le format et la taille de la surface.

• Clés de requête et de résultat compatibles : Camera2/X appelle les méthodes suivantes pour récupérer les clés de requête et de résultat de capture compatibles à partir de votre implémentation :

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
  • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X appelle toujours init() en premier sur ces classes Extender avant de demander plus d'informations.

Flux d'application 3 : Aperçu/capture d'image fixe avec extension activée (implémentation HAL)

Figure 5. Flux d'application 3 sur l'extendeur de base

Le diagramme ci-dessus illustre le flux principal d'activation de l'aperçu et de la capture d'images fixes avec une extension sans processeur. Cela signifie que le HAL de l'appareil photo traite l'extension.

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

Lors de la configuration de CameraCaptureSession, Camera2/X appelle onPresetSession pour obtenir les paramètres de session. Une fois la session de capture configurée, Camera2/X appelle onEnableSession et renvoie une instance CaptureStageImpl contenant les paramètres de capture. Camera2/X envoie immédiatement une seule requête avec ces paramètres de capture pour informer le HAL. De même, avant la fermeture de la session de capture, Camera2/X appelle onDisableSession, puis envoie une seule requête avec les paramètres de capture renvoyés.

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

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

Processeur d'aperçu

En plus de la HAL de l'appareil photo, vous pouvez également implémenter des extensions dans un processeur.

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

• PROCESSOR_TYPE_NONE : aucun processeur. Les images sont traitées dans le HAL de l'appareil photo.

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

  PreviewExtenderImpl.getProcessor doit renvoyer une instance RequestUpdateProcessorImpl qui traite l'instance TotalCaptureResult et renvoie une instance CaptureStageImpl pour mettre à jour la requête répétée. PreviewExtenderImpl.getCaptureStage() doit également refléter le résultat du traitement et renvoyer le dernier 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 sur une surface PRIVATE.

  Vous devez implémenter et renvoyer une instance PreviewImageProcessorImpl dans PreviewExtenderImpl.getProcessor. Le processeur est responsable du traitement des images d'entrée YUV_420_888. Il doit écrire la sortie au format PRIVATE de l'aperçu. Camera2/X utilise une surface YUV_420_888 au lieu de PRIVATE pour configurer CameraCaptureSession pour l'aperçu.

  Le schéma suivant illustre le flux :

Figure 6. Aperçu du 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 du processeur. Pour PreviewImageProcessorImpl, imageFormat est un format de 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'image d'entrée. Actuellement, seule la valeur YUV_420_888 est possible.

Processeur de capture d'images

Pour la capture d'images fixes, vous pouvez implémenter un processeur en renvoyant une instance CaptureProcessorImpl à l'aide de ImageCaptureExtenderImpl.getCaptureProcessor. Le processeur est chargé de traiter une liste d'images YUV_420_888 et d'instances TotalCaptureResult capturées, et d'écrire la sortie sur une surface YUV_420_888.

Vous pouvez partir du principe que l'aperçu est activé et en cours d'exécution avant d'envoyer la demande de capture d'image fixe.

Consultez le flux dans le diagramme ci-dessous :

Figure 7. Flux de capture d'images fixes avec CaptureProcessorImpl

1. Camera2/X utilise une surface au format YUV_420_888 pour la capture d'images fixes afin de 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 surface de sortie YUV_420_888.

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

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

4. CaptureProcessorImpl écrit l'image résultante (au format YUV_420_888) sur la surface de sortie spécifiée par l'appel onOutputSurface(). Camera2/X les convertit en images JPEG si nécessaire.

Accepter les clés et les résultats des demandes de capture

En plus de l'aperçu et de la capture de l'appareil photo, les applications peuvent définir le zoom et les paramètres du flash, ou déclencher la mise au point par pression. Ces paramètres peuvent ne pas être compatibles avec l'implémentation de votre extension.

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

• ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() renvoie les clés de demande de capture acceptées par votre implémentation.
• ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() renvoie les clés de résultat de capture contenues dans le résultat de capture.

Si le HAL de l'appareil photo traite l'extension, Camera2/X récupère les résultats de la capture dans CameraCaptureSession.CaptureCallback. Toutefois, si le processeur est implémenté, Camera2/X récupère les résultats de la capture dans ProcessResultImpl, qui est transmis à la méthode process() dans PreviewImageProcessorImpl et CaptureProcessorImpl. Il vous appartient de signaler le résultat de la capture via ProcessResultImpl à 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 invoqué :

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);
}

Pour les opérations courantes de l'appareil photo, comme le zoom, la mise au point par appuyer pour faire la mise au point, le flash et la compensation de l'exposition, nous vous recommandons de prendre en charge les clés suivantes pour la requête de capture et le résultat de la capture :

• Zoom :
  • CaptureRequest#CONTROL_ZOOM_RATIO
  • CaptureRequest#SCALER_CROP_REGION
• Appuyer pour faire la mise au point :
  • CaptureRequest#CONTROL_AF_MODE
  • CaptureRequest#CONTROL_AF_TRIGGER
  • CaptureRequest#CONTROL_AF_REGIONS
  • CaptureRequest#CONTROL_AE_REGIONS
  • CaptureRequest#CONTROL_AWB_REGIONS
• Flash :
  • CaptureRequest#CONTROL_AE_MODE
  • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
  • CaptureRequest#FLASH_MODE
• Correction d'exposition :
  • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Pour les extensions de base qui implémentent la version 1.2.0 ou antérieure, l'API CameraX Extensions est explicitement compatible avec toutes les clés ci-dessus. Pour extensions-interface 1.3.0, CameraX et Camera2 respectent la liste renvoyée et n'acceptent que les clés qu'elle contient. Par exemple, si vous décidez de ne renvoyer que CaptureRequest#CONTROL_ZOOM_RATIO et CaptureRequest#SCALER_CROP_REGION dans l'implémentation 1.3.0, cela signifie que seul le zoom est pris en charge pour l'application, tandis que la mise au point par toucher, le flash et la compensation de l'exposition ne sont pas autorisés.

Advanced Extender

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

• Configuration de flux personnalisée : configurez des flux personnalisés tels que le flux RAW ou utilisez plusieurs flux pour différents ID de caméras physiques.

• Capacité à envoyer des requêtes Camera2 : prend en charge une logique d'interaction complexe qui peut envoyer des requêtes de capture avec des paramètres basés sur les résultats des requêtes précédentes.

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

Fichiers à implémenter

Pour passer à l'implémentation de l'extension avancée, la 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 se trouvent dans le package advanced.

Dans l'exemple suivant, nous utilisons AdvancedExtenderImpl comme espace réservé. Remplacez-le par le nom du fichier Extender de l'extension que vous implémentez.

Voyons comment Camera2/X invoque extensions-interface pour réaliser les trois flux d'application.

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

Figure 8. Déroulement des opérations de l'application 1 sur Advanced Extender

L'application vérifie d'abord si l'extension donnée est prise en charge.

Flux d'application 2 : Interroger des informations

Figure 9. Flux d'application 2 sur Advanced Extender

Après avoir appelé AdvancedExtenderImpl.init(), l'application peut interroger les informations suivantes sur AdvancedExtenderImpl :

• Latence de capture estimée : AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() renvoie la plage de latence de capture de l'application pour évaluer s'il est approprié d'activer l'extension pour le scénario actuel.

• Résolutions compatibles pour la prévisualisation et la capture d'images fixes :

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

  • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() renvoie les formats et tailles acceptés pour la surface de capture d'images fixes. Les OEM doivent prendre en charge les formats de sortie JPEG et YUV_420_888.

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

• Clés/résultats de demande de capture disponibles (ajoutés dans extensions-interface 1.3.0) : Camera2/X appelle les méthodes suivantes pour récupérer les clés de demande de capture et les clés de résultat compatibles à partir de votre implémentation :

  • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
  • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Pour en savoir plus, consultez Prise en charge des clés et des résultats des demandes de capture.

Flux d'application 3 : Aperçu/capture d'image fixe avec extension activée

Figure 10. Flux d'application 3 sur l'Advanced Extender

Le diagramme ci-dessus illustre le flux principal pour démarrer l'aperçu et la capture d'image pour le type Advanced Extender. Passons en revue chaque étape.

1. instance SessionProcessorImpl

   L'implémentation de base d'Advanced Extender se trouve dans SessionProcessorImpl, qui est responsable de la configuration de session personnalisée et de l'envoi de requêtes de capture pour lancer la prévisualisation et la capture d'image fixe. AdvancedExtenderImpl.createSessionProcessor() est appelé pour renvoyer l'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 préparer un CameraCaptureSession.

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

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

   Vous devez renvoyer une instance Camera2SessionConfigImpl, qui se compose d'une liste d'instances Camera2OutputConfigImpl et des paramètres de session utilisés pour configurer CameraCaptureSession. Vous êtes responsable de la sortie des images de caméra correctes vers les surfaces de sortie transmises par Camera2/X. Voici quelques options pour activer la sortie :

   • Traitement dans le HAL de l'appareil photo : vous pouvez ajouter directement les surfaces de sortie à CameraCaptureSession avec une implémentation SurfaceOutputConfigImpl. Cela configure la surface de sortie fournie sur le pipeline de l'appareil photo et permet au HAL de l'appareil photo de traiter l'image.

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

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

   • Utiliser le partage de surface Camera2 : utilisez le partage de surface avec une autre surface en ajoutant une instance Camera2OutputConfigImpl à la méthode getSurfaceSharingOutputConfigs() d'une autre instance Camera2OutputConfigImpl. Le format et la taille de la surface doivent être identiques.

   Tous les Camera2OutputConfigImpl, y compris SurfaceOutputConfigImpl et ImageReaderOutputConfigImpl, doivent avoir un ID unique (getId()), qui est utilisé pour spécifier la surface cible et récupérer l'image à partir de ImageReaderOutputConfigImpl.

3. onCaptureSessionStart et RequestProcessorImpl

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

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

   • La surface cible est spécifiée par l'ID de l'instance Camera2OutputConfigImpl.
   • La capacité de récupérer l'image de ImageReader.

   Vous pouvez appeler RequestProcessorImpl.setImageProcessor() avec un ID Camera2OutputConfigImpl spécifié pour enregistrer une instance ImageProcessorImpl afin de recevoir des images.

   L'instance RequestProcessImpl devient non valide après les appels Camera2/X SessionProcessorImpl.onCaptureSessionEnd().

4. Démarrer l'aperçu et prendre une photo

   Dans l'implémentation Advanced Extender, vous pouvez envoyer des demandes de capture via l'interface RequestProcessorImpl. Camera2/X vous invite à démarrer la requête répétée pour l'aperçu ou la séquence de capture d'image fixe en appelant respectivement SessionProcessorImpl#startRepeating et SessionProcessorImpl#startCapture. Vous devez envoyer des requêtes de capture pour répondre à ces demandes de prévisualisation et de capture d'image fixe.

   Camera2/X définit également les paramètres de la demande de capture via SessionProcessorImpl#setParameters. Vous devez définir ces paramètres de requête (s'ils sont acceptés) à la fois pour les demandes uniques et récurrentes.

   Vous devez accepter au moins CaptureRequest.JPEG_ORIENTATION et CaptureRequest.JPEG_QUALITY. extensions-interface 1.3.0 est compatible avec les clés de requête et 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 le résultat de la capture contient les clés de la liste getAvailableCaptureResultKeys.

5. startTrigger

   SessionProcessorImpl.startTrigger() est appelé pour démarrer le déclencheur tel que CaptureRequest.CONTROL_AF_TRIGGER et CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER. Vous pouvez ignorer les clés de demande de capture qui n'ont pas été 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 par toucher et le flash avec des extensions.

6. Nettoyage

   Lorsqu'une session de capture se termine, SessionProcessorImpl.onCaptureSessionEnd() est appelé avant la fermeture de CameraCaptureSession. Une fois la session de capture fermée, deInitSession() effectue le nettoyage.

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

Vous devez appliquer l'extension pour les cas d'utilisation de l'aperçu et de la capture d'image fixe. Toutefois, si la latence est trop élevée pour afficher l'aperçu de manière fluide, vous pouvez appliquer l'extension uniquement pour la capture d'images fixes.

Pour le type d'extension de base, quelle que soit l'activation de l'extension pour l'aperçu, vous devez implémenter ImageCaptureExtenderImpl et PreviewExtenderImpl pour une extension donnée. Souvent, une application utilise également un flux YUV pour analyser le contenu de l'image, par exemple pour trouver des codes QR ou du texte. Pour mieux prendre en charge ce cas d'utilisation, vous devez prendre en charge la combinaison de flux d'aperçu, de capture d'image fixe et de flux YUV_420_888 pour configurer CameraCaptureSession. Cela signifie que si vous implémentez un processeur, vous devez prendre en charge la combinaison de flux de trois flux YUV_420_888.

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

Prise en charge de la capture vidéo

L'architecture actuelle de l'extension de l'appareil photo ne prend en charge que les cas d'utilisation de l'aperçu et de la capture d'images fixes. Nous n'autorisons pas l'activation de l'extension sur les surfaces MediaCodec ou MediaRecorder pour enregistrer la vidéo. Toutefois, il est possible que les applications enregistrent la sortie de l'aperçu.

Nous étudions la possibilité de prendre en charge les surfaces MediaCodec et MediaRecorder.

Métadonnées spécifiques aux extensions

Pour Android 14 et versions ultérieures, les métadonnées spécifiques à l'extension permettent aux clients d'extension de l'appareil photo de définir et de recevoir des paramètres et des résultats de requête de capture spécifiques à l'extension. Plus précisément, les clients d'extension de caméra peuvent utiliser le paramètre de requête de capture EXTENSION_STRENGTH pour contrôler l'intensité de l'extension et le résultat de capture EXTENSION_CURRENT_TYPE pour indiquer le type d'extension activé.

Capturer les requêtes

Le paramètre de requête de capture EXTENSION_STRENGTH contrôle l'intensité de l'effet de post-traitement de l'extension. Le résultat de la capture correspondant inclut la valeur d'intensité 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 l'intensité du flou.
• HDR et NIGHT : contrôlent le nombre d'images fusionnées et la luminosité de l'image finale.
• FACE_RETOUCH : contrôle le degré d'amélioration esthétique et de lissage de la peau.

La plage acceptée pour le paramètre EXTENSION_STRENGTH est comprise entre 0 et 100. 0 indique qu'aucun traitement d'extension ni aucun transfert simple n'est appliqué, tandis que 100 indique l'intensité maximale de l'effet de traitement.

Pour ajouter la compatibilité avec EXTENSION_STRENGTH, utilisez les API de paramètres spécifiques au fournisseur introduites dans la version 1.3.0 de l'interface de la bibliothèque d'extension. Pour en savoir plus, consultez getAvailableCaptureRequestKeys().

Résultats de la capture

Le résultat de capture EXTENSION_CURRENT_TYPE permet aux implémentations d'extension d'informer les clients du type d'extension actif.

Étant donné que les extensions utilisant le type AUTO basculent dynamiquement entre les types d'extension tels que HDR et NIGHT en fonction des conditions de la scène, les applications d'extension de l'appareil photo peuvent utiliser EXTENSION_CURRENT_TYPE pour afficher des informations sur l'extension actuellement sélectionnée par l'extension AUTO.

Estimation de la latence de capture d'image fixe en temps réel

Pour Android 14 et les versions ultérieures, les clients d'extension de l'appareil photo peuvent interroger les estimations de latence de capture d'image fixe en temps réel en fonction des conditions de scène et d'environnement à l'aide de getRealtimeStillCaptureLatency(). Cette méthode 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 le traitement des extensions ou d'afficher une indication pour informer les utilisateurs d'une opération de longue durée.

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 de capture d'images fixes en temps réel, implémentez les éléments suivants :

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

Capturer les rappels de progression du traitement

Pour Android 14 et les versions ultérieures, les clients d'extension de l'appareil photo peuvent recevoir des rappels pour la progression des opérations de traitement de capture d'image fixe de longue durée. Les applications peuvent afficher la progression actuelle aux utilisateurs pour 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, l'implémentation de votre fournisseur d'extension doit appeler les rappels suivants avec la valeur de progression actuelle :

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

Capture d'écran après affichage

Pour Android 14 et versions ultérieures, les extensions d'appareil photo peuvent fournir une postview (image d'aperçu) à l'aide de setPostviewOutputConfiguration. Pour améliorer l'expérience utilisateur, les applications peuvent afficher une image post-view en tant qu'espace réservé lorsqu'une extension connaît une latence de traitement accrue, et remplacer l'image lorsque l'image finale est disponible. Les applications peuvent configurer et émettre des demandes de capture post-view à 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 prendre en charge la capture d'images fixes post-visualisation, votre implémentation du fournisseur doit implémenter les éléments suivants :

• Extensions de base : CaptureProcessorImpl.onPostviewOutputSurface et CaptureProcessorImpl.processWithPostview

• Extensions avancées : SessionProcessorImpl.startCaptureWithPostview

Prise en charge de la sortie SurfaceView

Pour Android 14 et versions ultérieures, les clients d'extension de l'appareil photo peuvent utiliser des chemins de rendu d'aperçu optimisés en termes de puissance et de performances en enregistrant une instance SurfaceView pour la sortie d'aperçu pour les requêtes répétées.

Pour prendre en charge la sortie SurfaceView, l'implémentation de votre extension de fournisseur doit être capable de diffuser et de générer un aperçu sur les instances SurfaceView. Pour vérifier que cela est pris en charge, exécutez le module CTS SurfaceViewExtensionPreviewTest.java.

Types de sessions spécifiques aux fournisseurs

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 de la caméra interne au lieu de la valeur par défaut.

Cette fonctionnalité fonctionne entièrement dans le framework et la pile de fournisseurs, et n'a aucun impact sur les API visibles par le client/publiques.

Pour sélectionner un type de session spécifique à un 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 Camera Extension. Vous devez toujours implémenter la bibliothèque du fournisseur avec la dernière version.

Implémentation de référence

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

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

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

• service_based_sample : implémentation qui montre comment héberger des extensions d'appareil photo dans un Service. Cette implémentation contient les composants suivants :

  • oem_library : bibliothèque OEM Camera Extensions pour les API Camera2 et CameraX Extensions qui implémente Extensions-Interface. Il sert de transfert et transmet les appels de Extensions-Interface au service. Cette bibliothèque fournit également des fichiers AIDL et des classes wrapper pour communiquer avec le service.

    L'option "Advanced Extender" (Répéteur avancé) est activée par défaut. Pour activer l'extension de base, remplacez ExtensionsVersionImpl#isAdvancedExtenderImplemented par false.

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

Configurer la bibliothèque de fournisseurs sur un appareil

La bibliothèque de fournisseurs OEM n'est pas intégrée à une application. Elle est chargée à partir de 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, définie dans le fichier AndroidManifest.xml de la bibliothèque camera-extensions, est une dépendance de CameraX et doit être chargée lors de l'exécution. Dans Camera2, le framework charge un service d'extensions qui déclare également que <uses-library> charge la même bibliothèque androidx.camera.extensions.impl au moment de l'exécution.

Cela permet aux applications tierces utilisant des extensions de charger automatiquement la bibliothèque du fournisseur OEM. La bibliothèque OEM est marquée comme facultative afin que les applications puissent s'exécuter sur des appareils sur lesquels elle n'est pas installée. Camera2/X gère automatiquement ce comportement lorsqu'une application tente d'utiliser une extension de caméra, à condition que le fabricant de l'appareil place la bibliothèque OEM sur l'appareil afin qu'elle puisse être détectée 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. Par exemple, /etc/permissions/camera_extensions.xml. Les fichiers de ce répertoire fournissent un mappage de la bibliothèque nommée dans <uses-library> au 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 il s'agit de la bibliothèque que CameraX recherche.
   • file correspond au chemin d'accès absolu du fichier contenant 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>

Dans Android 12 ou version ultérieure, les appareils compatibles avec les extensions CameraX doivent avoir la propriété ro.camerax.extensions.enabled définie sur true, ce qui permet de vérifier si un appareil est compatible avec les extensions. Pour ce faire, ajoutez la ligne suivante dans le fichier de configuration de l'appareil :

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

Validation

Pour tester votre implémentation de la bibliothèque de fournisseurs OEM lors de la phase de développement, utilisez l'exemple d'application à l'adresse androidx-main/camera/integration-tests/extensionstestapp/, qui exécute différentes extensions de fournisseur.

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

Mode Scène étendu ou extensions de caméra

Pour l'extension bokeh, en plus de l'exposer à l'aide des extensions de caméra, vous pouvez l'exposer à l'aide du mode scène étendu, qui est activé par la clé CONTROL_EXTENDED_SCENE_MODE. Pour en savoir plus sur l'implémentation, consultez Effet bokeh de l'appareil photo.

Le mode scène étendu présente moins de restrictions que les extensions de caméras pour les applications camera2. Par exemple, vous pouvez activer le mode scène étendu dans une instance CameraCaptureSession standard compatible avec les combinaisons de flux flexibles et les paramètres de requête de capture. En revanche, les extensions d'appareil photo ne sont compatibles qu'avec un ensemble fixe de types de flux et offrent une compatibilité limitée avec les paramètres de requête de capture.

L'inconvénient du mode scène étendu est que vous ne pouvez l'implémenter que dans la HAL de l'appareil photo, ce qui signifie qu'il doit être vérifié pour fonctionner avec tous les contrôles orthogonaux disponibles pour les développeurs d'applications.

Nous vous recommandons d'exposer le bokeh à l'aide du mode scène étendu et des extensions d'appareil photo, 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 étendu, car il s'agit du moyen le plus flexible pour les applications d'activer l'extension Bokeh. Vous pouvez ensuite implémenter l'interface des extensions de caméras en fonction du mode scène étendu. Si l'implémentation du bokeh dans la HAL de l'appareil photo est difficile, par exemple parce qu'elle nécessite un post-processeur s'exécutant dans la couche d'application pour traiter les images, nous vous recommandons d'implémenter 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'implémentation de la bibliothèque du fournisseur OEM. Par exemple, ExtenderStateListener.onPresetSession() utilise l'appel SessionConfiguration.setSessionParameters() pour définir un ensemble de tags de référence. Cet appel n'est disponible qu'au niveau d'API 28 et supérieur. Pour en savoir plus sur des méthodes d'interface spécifiques, consultez la documentation de référence sur les API.