Au-delà des fonctionnalités individuelles : garantir les combinaisons de fonctionnalités avec CameraX 1.5

Les applications d'appareil photo modernes se caractérisent par des fonctionnalités puissantes qui se chevauchent. Les utilisateurs s'attendent à pouvoir enregistrer des vidéos avec un HDR époustouflant, capturer des mouvements fluides à 60 FPS et obtenir des images d'une fluidité exceptionnelle grâce à la stabilisation de l'aperçu, souvent tout cela en même temps.

En tant que développeurs, nous savons que la réalité est plus complexe. Comment pouvez-vous garantir qu'un appareil spécifique est compatible avec une combinaison donnée ? Jusqu'à présent, l'activation de plusieurs fonctionnalités était souvent un pari risqué. Vous pouvez vérifier la compatibilité de chaque fonctionnalité, mais les combiner peut entraîner un comportement non défini ou, pire, l'échec d'une session de l'appareil photo. Cette incertitude oblige les développeurs à être prudents, ce qui empêche les utilisateurs d'appareils performants de bénéficier de la meilleure expérience possible.

Par exemple, très peu d'appareils haut de gamme sont capables de lire de manière fiable des vidéos HDR à 60 FPS. Par conséquent, la plupart des applications évitent d'activer les deux en même temps pour ne pas dégrader l'expérience utilisateur sur la majorité des téléphones.

Pour résoudre ce problème, nous lançons Feature Group dans CameraX, une nouvelle API conçue pour éliminer ces approximations. Vous pouvez désormais vérifier si une combinaison spécifique de fonctionnalités est compatible avant de configurer la caméra, ou simplement indiquer vos priorités à CameraX et le laisser activer la combinaison la mieux prise en charge.

Pour les nouveaux utilisateurs de CameraX

Avant de nous intéresser à la nouvelle API Feature Group, rappelons brièvement ce qu'est CameraX. CameraX est une bibliothèque d'assistance Jetpack conçue pour vous aider à développer plus facilement des applications d'appareil photo. Elle fournit une surface d'API cohérente et facile à utiliser qui fonctionne sur la plupart des appareils Android, ainsi qu'une rétrocompatibilité avec Android 6.0 (niveau d'API 23). Si vous ne connaissez pas CameraX, nous vous recommandons de consulter la documentation officielle et d'essayer l'atelier de programmation pour commencer.

Ce que vous pouvez créer avec l'API Feature Group

Vous n'avez plus besoin de parier sur des combinaisons de fonctionnalités et pouvez proposer en toute confiance les meilleures expériences d'appareil photo possibles, comme la vidéo HDR et 60 FPS simultanée sur du matériel compatible (par exemple, un Pixel 10 Pro), tout en évitant les erreurs sur les appareils qui ne sont pas compatibles avec cette combinaison.

L'API Feature Group vous permet d'effectuer les opérations suivantes :

• Créez des interfaces utilisateur plus intelligentes et dynamiques : activez ou désactivez intelligemment les paramètres de votre interface utilisateur en fonction de la compatibilité matérielle en temps réel. Par exemple, si un utilisateur active le HDR, vous pouvez instantanément griser et désactiver l'option 60 FPS si la combinaison n'est pas compatible avec cet appareil. 

• Proposer un mode "Haute qualité" fiable  : configurez la caméra avec une liste hiérarchisée des fonctionnalités souhaitées. CameraX trouve et active automatiquement la combinaison la mieux prise en charge pour un appareil donné, ce qui garantit un résultat optimal sans logique complexe spécifique à l'appareil.
• Éviter les échecs de session de l'appareil photo : en vérifiant la compatibilité au préalable, vous empêchez l'appareil photo d'essayer de configurer une combinaison non compatible, ce qui élimine une source courante de plantages et offre une expérience utilisateur fluide.

Fonctionnement : les composants principaux

La nouvelle API est axée sur les ajouts clés à SessionConfig et CameraInfo.

1. GroupableFeature : cette API introduit un ensemble de fonctionnalités groupables prédéfinies, telles que HDR_HLG10, FPS_60, PREVIEW_STABILIZATION et IMAGE_ULTRA_HDR. En raison de limites de calcul, seul un ensemble spécifique de caractéristiques peut être regroupé avec le haut degré de fiabilité fourni par cette API. Nous mettons tout en œuvre pour élargir cette liste et nous ajouterons la prise en charge d'autres fonctionnalités dans les prochaines versions.
    
2. Nouveaux paramètres SessionConfig : cette classe, utilisée pour démarrer une session de caméra, accepte désormais deux nouveaux paramètres :
   • requiredFeatureGroup : utilisez cette option pour les fonctionnalités qui doivent être compatibles pour que la configuration aboutisse. Cette option est idéale pour les fonctionnalités qu'un utilisateur active explicitement, comme l'activation d'un bouton "HDR". Pour garantir une expérience déterministe et cohérente, l'appel bindToLifecycle génère une IllegalArgumentException si la combinaison demandée n'est pas compatible, plutôt que d'ignorer silencieusement une demande de fonctionnalité. L'API CameraInfo#isFeatureGroupSupported (voir les détails ci-dessous) doit être utilisée pour interroger ce résultat au préalable.
   • preferredFeatureGroup : utilisez cette option pour les fonctionnalités souhaitables, mais facultatives, par exemple lorsque vous souhaitez implémenter un mode "Haute qualité" par défaut. Vous fournissez une liste des fonctionnalités souhaitées classées selon vos priorités, et CameraX active automatiquement la combinaison de priorité la plus élevée compatible avec l'appareil.
3. CameraInfo#isFeatureGroupSupported() : il s'agit de la méthode de requête principale permettant de vérifier explicitement si un groupe de fonctionnalités est compatible. Elle est idéale pour ne proposer que des options de fonctionnalités compatibles aux utilisateurs dans l'UI de votre application. Vous lui transmettez un SessionConfig, et il renvoie une valeur booléenne indiquant si la combinaison est compatible. Si vous avez l'intention de lier un SessionConfig avec les fonctionnalités requises, vous devez d'abord utiliser cette API pour vous assurer qu'il est compatible. 

Implémentation en pratique

Voyons comment utiliser ces composants pour améliorer l'expérience avec l'appareil photo.

Scénario 1 : Mode haute qualité "Best Effort"

Si vous souhaitez activer les meilleures fonctionnalités possibles par défaut, vous pouvez fournir une liste classée par ordre de priorité à preferredFeatureGroup. Dans cet exemple, nous indiquons à CameraX de donner la priorité au HDR, puis à 60 FPS et enfin à la stabilisation de l'aperçu. CameraX gère la complexité de la vérification de toutes les combinaisons possibles et choisit la meilleure prise en charge par l'appareil.

Par exemple, si un appareil peut gérer le HDR et 60 FPS ensemble, mais pas avec la stabilisation de l'aperçu, CameraX activera les deux premiers et ignorera le troisième. Vous bénéficiez ainsi de la meilleure expérience possible sans avoir à écrire de vérifications complexes spécifiques à l'appareil.

cameraProvider.bindToLifecycle(

    lifecycleOwner,

    cameraSelector,

    SessionConfig(

        useCases = listOf(preview, videoCapture),

        // The order of features in this list determines their priority. 

        // CameraX will enable the best-supported combination based on these

        // priorities: HDR_HLG10 > FPS_60 > Preview Stabilization.  

        preferredFeatureGroup =

           listOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION),

    ).apply {

        // (Optional) Get a callback with the enabled features

        // to update your UI. 

        setFeatureSelectionListener { selectedFeatures ->

            updateUiIndicators(selectedFeatures)

        }

    }

)

Pour cet extrait de code, CameraX tentera d'activer les combinaisons de fonctionnalités dans l'ordre de priorité suivant, en sélectionnant la première entièrement compatible avec l'appareil :

1. HDR + 60 FPS + stabilisation de l'aperçu
2. HDR + 60 FPS
3. HDR + stabilisation de l'aperçu
4. HDR
5. 60 FPS + stabilisation de l'aperçu
6. 60 FPS
7. Stabilisation de l'aperçu
8. Aucune des fonctionnalités ci-dessus

Scénario 2 : Créer une UI réactive

Pour créer une UI qui répond aux sélections des utilisateurs et les empêche de sélectionner une combinaison de fonctionnalités non compatible, vous pouvez interroger directement la compatibilité. La fonction ci-dessous vérifie quelles fonctionnalités sont incompatibles avec les sélections actuelles de l'utilisateur, ce qui vous permet de désactiver les éléments d'interface utilisateur correspondants.

/**

 * Returns a list of features that are NOT supported in combination

 * with the currently selected features.

 */

fun getUnsupportedFeatures(

    currentFeatures: Set<GroupableFeature>

): Set<GroupableFeature> {

    val unsupportedFeatures = mutableSetOf<GroupableFeature>()

    val appFeatureOptions = setOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION)


    // Iterate over every available feature option in your app. 

    appFeatureOptions.forEach { featureOption ->

        // Skip features the user has already selected. 

        if (currentFeatures.contains(featureOption)) return@forEach


        // Check if adding this new feature is supported. 

        val isSupported = cameraInfo.isFeatureGroupSupported(

            SessionConfig(

                useCases = useCases,

                // Check the new feature on top of existing ones.

                requiredFeatureGroup = currentFeatures + featureOption

            )

        )


        if (!isSupported) {

            unsupportedFeatures.add(featureOption)

        }

    }


    return unsupportedFeatures

}

Vous pouvez ensuite intégrer cette logique à votre ViewModel ou à votre contrôleur d'interface utilisateur pour réagir aux entrées utilisateur et relier la caméra à une configuration dont le fonctionnement est garanti.

// Invoked when user turns some feature on/off.

fun onFeatureChange(currentFeatures: Set<GroupableFeature>) {

    // Identify features that are unsupported with the current selection.

    val unsupportedFeatures = getUnsupportedFeatures(currentFeatures)



    // Update app UI so that users can't enable them.

    updateDisabledFeatures(unsupportedFeatures)



    // Since the UI now only allows selecting supported feature combinations, 

    // `currentFeatures` is always valid. This allows setting

    // `requiredFeatureGroup` directly, without needing to re-check for

    // support or set a feature selection listener.  

    cameraProvider.bindToLifecycle(

        lifecycleOwner,

        cameraSelector,

        SessionConfig(

            useCases = listOf(preview, videoCapture),

            requiredFeatureGroup = currentFeatures,

        )

    )

}

Pour voir ces concepts dans une application opérationnelle, vous pouvez explorer notre application de test interne. Elle fournit une implémentation complète des scénarios "best effort" et "UI réactive" décrits ci-dessus.

Remarque : Il s'agit d'une application de test et non d'un exemple officiellement pris en charge. Bien qu'il s'agisse d'une excellente référence pour l'API Feature Group, il n'a pas été optimisé pour une utilisation en production.

Lancez-vous dès maintenant

L'API Feature Group lève toute ambiguïté concernant l'utilisation des fonctionnalités avancées de l'appareil photo. En fournissant un moyen déterministe d'interroger la compatibilité des fonctionnalités, vous pouvez créer des applications d'appareil photo plus puissantes et plus fiables en toute confiance.

L'API est disponible en version expérimentale dans CameraX 1.5 et devrait devenir entièrement stable dans la version 1.6, avec d'autres améliorations et une meilleure compatibilité à venir.

Pour en savoir plus, consultez la documentation officielle. Nous avons hâte de découvrir vos créations et de connaître votre avis. Merci de nous donner votre avis et de signaler les problèmes via les canaux suivants :

• Groupe de discussion des développeurs CameraX
• Signaler un bug