Création d’un pilote MFT de caméra pour une application d’appareil UWP

Article
03/06/2024

Important

Cette rubrique est aujourd’hui obsolète. Consultez le guide de conception des MFT de périphérique pour des conseils mis à jour.

Les applications d’appareils UWP permettent aux fabricants d’appareils d’appliquer des paramètres personnalisés et des effets spéciaux sur le flux vidéo de la caméra avec un pilote MFT (media foundation transform) de caméra. Cette rubrique présente les MFT de pilote et utilise l’exemple de MFT de pilote pour montrer comment en créer un. Pour en savoir plus sur les applications d’appareils UWP en général, veuillez consulter la rubrique Découverte des applications d’appareils UWP.

Le MFT de pilote

Cette section décrit la Transformée de fondation multimédia (MFT) que vous créez pour appliquer des effets au flux de capture multimédia provenant de la caméra. C’est ainsi que vous fournissez des transformations pour les effets de couleur, les modes de schéma et les effets de suivi des visages qui distinguent vraiment votre caméra des autres. Ce MFT, connu sous le nom de MFT de pilote, est d’abord appliqué au flux vidéo connecté provenant du pilote de caméra lorsqu’une application UWP commence la capture vidéo. Lorsque cette application invoque l’interface utilisateur Options de la caméra, Windows fournit automatiquement l’accès à toutes les interfaces implémentées par le MFT de pilote pour contrôler ses effets personnalisés.

the camera driver mft helps a windows store device app provide custom effects.

Un MFT de pilote n’est pas nécessaire pour une application d’appareil UWP. Un fabricant d’appareils peut choisir de mettre en œuvre une application d’appareil UWP sans MFT de pilote, simplement pour fournir une interface utilisateur différenciée contenant une marque pour leur matériel, sans appliquer de paramètres personnalisés et d’effets spéciaux au flux vidéo.

Utilisation d’un MFT de pilote

L’application d’appareil UWP pour une caméra s’exécute dans un processus différent de l’application du Microsoft Store qui l’invoque à partir de l’API CameraCaptureUI. Pour que l’application du Microsoft Store puisse contrôler un MFT de pilote, une séquence spécifique d’événements à travers différents espaces de processus doit se produire.

Une application UWP veut capturer une photo, donc elle appelle la méthode CaptureFileAsync
Windows demande le pointeur MFT de pilote et l’identifiant de périphérique de la caméra
Le pointeur MFT de pilote est transmis à un hôte de paramètres
L’hôte interroge les propriétés du périphérique pour l’ID de l’application d’appareil du Microsoft Store associée à la caméra (par métadonnées du périphérique)
S’il n’y a pas d’application d’appareil UWP, le volet contextuel par défaut interagit avec le moteur de capture
Si une application d’appareil UWP est trouvée, elle est activée et l’hôte de paramètres transmet le pointeur MFT de pilote à celle-ci
L’application d’appareil UWP contrôle le MFT de pilote en utilisant l’interface exposée par le pointeur

the process interaction for invoking a windows store device app.

Exigence du modèle de pilote AvStream

Le pilote de votre caméra doit utiliser le modèle de pilote AvStream. Pour plus d’informations sur le modèle de pilote AVStream, veuillez consulter le Guide de conception des mini-pilotes AVStream.

Exposition du MFT de pilote aux applications

Un MFT de pilote est enregistré auprès de Windows en tant qu’interface COM afin que la transformation qu’il implémente puisse être appliquée au flux multimédia sortant d’un périphérique spécifique, comme une caméra.

Remarque

Un MFT de pilote ne doit pas être enregistré en utilisant la fonction MFTRegister en raison de sa spécificité à un périphérique et non d’un MFT général. Pour plus d’informations sur la clé de registre, veuillez consulter la section Installation et enregistrement du MFT de pilote plus loin dans ce sujet.

Lorsqu’une application lance une capture vidéo, un lecteur de source de fondation multimédia est instancié pour fournir le flux vidéo. Cette source multimédia lit une valeur de registre à partir de la clé de registre du périphérique. Si le CLSID de la classe COM du MFT de pilote est trouvé dans la valeur de registre, le lecteur de source instancie le MFT de pilote et l’insère dans le pipeline multimédia.

En plus des applications d’appareils UWP, la fonctionnalité MFT de pilote peut être accessible lorsque le périphérique associé est utilisé pour capturer une vidéo en utilisant les API suivantes :

Balises <vidéo> HTML5 dans une application UWP utilisant HTML. Les transformations activées par le MFT de pilote affecteront la vidéo qui est lue en utilisant l’élément <vidéo>, comme dans l’exemple de code suivant :
```
var video = document.getElementById('myvideo');
    video.src = URL.createObjectURL(fileItem);
    video.play();
```
API Windows.Media.MediaCapture dans une application UWP utilisant le runtime Windows. Pour plus d’informations sur l’utilisation de cette API, voir l’exemple de capture multimédia.
Lecteur de source de la fondation multimédia, pour les applications traitant les données multimédias. Le MFT de pilote sera exposé aux applications comme le premier (0e) MFT lors de l’appel de IMFSourceReaderEx::GetTransformForStream. La catégorie qui sera renvoyée est MFT_CATEGORY_VIDEO_EFFECT.

Caméras multi-broches

Si vous avez une caméra à trois broches ou d’autres caméras à broches multiples, veuillez consulter la section Considérations pour les MFT de pilote sur les caméras multi-broches.

Implémentation du MFT de pilote

Cette section fournit des informations sur la mise en œuvre de votre MFT de pilote. Pour un exemple complet d’un MFT de pilote qui fonctionne avec une application d’appareil UWP, voir l’exemple de MFT de pilote.

Outils de développement

Microsoft Visual Studio Professional ou Microsoft Visual Studio Ultimate est requis.

Caractéristiques du MFT de pilote

Le MFT de pilote est instancié par flux. Pour chaque flux pris en charge par la caméra, une instance du MFT est instanciée et connectée à celui-ci. Le MFT de pilote est censé avoir un seul flux d’entrée et un seul flux de sortie. Le MFT de pilote peut être soit un MFT synchrone, soit un MFT asynchrone.

Communication entre la caméra et le MFT de pilote

Pour permettre une communication bidirectionnelle entre la source multimédia et le MFT de pilote, le pointeur vers le magasin d’attributs du flux source est défini sur le magasin d’attributs du flux d’entrée du MFT de pilote comme MFT_CONNECTED_STREAM_ATTRIBUTE. Cela se produit par le biais d’un processus de poignée de main que vous activez en exposant MFT_ENUM_HARDWARE_URL_Attribute dans le MFT de pilote, comme dans l’exemple suivant :

HRESULT CDriverMft::GetAttributes(IMFAttributes** ppAttributes)
{
    HRESULT hr = S_OK;
    if (NULL == ppAttributes)
    {
       return E_POINTER; 
    };
        if(!m_pGlobalAttributes) {
           MFCreateAttributes(&m_pGlobalAttributes, 1);
           m_pGlobalAttributes-> 
             SetString(MFT_ENUM_HARDWARE_URL_Attribute, L"driverMFT");
        }
        *ppAttributes = m_pGlobalAttributes;
        (*ppAttributes)->AddRef();
        return S_OK;
}

Dans cet exemple, le MFT_CONNECTED_STREAM_ATTRIBUTE dans le magasin d’attributs du MFT de pilote est défini pour pointer vers le magasin d’attributs du flux source du périphérique. Veuillez consulter la rubrique Séquence de poignée de main matérielle pour plus de détails sur la façon dont la communication entre la caméra et le MFT est configurée.

Comment accéder aux informations de la source du périphérique

L’exemple de code suivant montre comment le MFT de pilote peut obtenir le pointeur vers la transformation source à partir de son magasin d’attributs d’entrée. Le MFT de pilote peut ensuite utiliser le pointeur source pour obtenir des informations sur la source du périphérique.

if(!m_pSourceTransform && m_pInputAttributes) {

          m_pInputAttributes->
              GetUnknown( MFT_CONNECTED_STREAM_ATTRIBUTE,
              IID_PPV_ARGS(&pSourceAttributes));
          pSourceAttributes-> 
              GetUnknown(
              MF_DEVICESTREAM_EXTENSION_PLUGIN_CONNECTION_POINT,            
              IID_PPV_ARGS(&pUnk)));
          pUnk->QueryInterface(__uuidof(IMFTransform), 
              (void**)&m_pSourceTransform));
      }
      if (m_pSourceTransform) {
         // Put code to get device source information here.         
      }

Comment mettre en œuvre le mode de transfert

Pour mettre le MFT de pilote en mode de transfert, spécifiez le même type de support pour le flux d’entrée et de sortie. ProcessInput et ProcessOutput les appels sur le MFT seront toujours effectués. Il revient à votre implémentation de MFT de pilote de déterminer si un traitement a lieu en mode de transfert ou non.

Fichiers d’en-tête à inclure

Vous devrez inclure des fichiers d’en-tête pour les méthodes IInspectable et IMFTransform que le MFT de pilote doit implémenter. Pour une liste des fichiers d’en-tête à inclure, voir stdafx.h dans le répertoire SampleMFT0 de l’exemple d’application d’appareil UWP pour caméra.

// required for IInspectable
#include <inspectable.h>

Comment implémenter IInspectable

Un MFT de pilote destiné à être utilisé à partir d’une application d’appareil UWP d’une caméra doit implémenter les méthodes de IInspectable de sorte que l’application d’appareil du Microsoft Store puisse accéder à un pointeur vers le MFT de pilote lors de son lancement. Votre MFT de pilote doit implémenter les méthodes de IInspectable comme ceci :

IInspectable ::GetIids doit renvoyer null dans le paramètre out iids, et retourner 0 dans le out paramètre out iidCount.
IInspectable ::GetRuntimeClassName doit renvoyer null dans le paramètre out.
IInspectable ::GetRuntiGetTrustLevel doit renvoyer TrustLevel::BaseTrust dans le paramètre out.

L’exemple de code suivant montre comment les méthodes IInspectable sont implémentées dans l’exemple de MFT de pilote. Ce code peut être trouvé dans le fichier Mft0.cpp, dans le répertoire SampleMFT0 de l’exemple.

// Mft0.cpp
STDMETHODIMP CMft0::GetIids( 
    /* [out] */ __RPC__out ULONG *iidCount,
    /* [size_is][size_is][out] */ __RPC__deref_out_ecount_full_opt(*iidCount) IID **iids)
{
    HRESULT hr = S_OK;
    do {
        CHK_NULL_PTR_BRK(iidCount);
        CHK_NULL_PTR_BRK(iids);
        *iids = NULL;
        *iidCount = 0;
    } while (FALSE);

    return hr;
}

STDMETHODIMP CMft0::GetRuntimeClassName( 
    /* [out] */ __RPC__deref_out_opt HSTRING *className)
{
    HRESULT hr = S_OK;
    do {
        CHK_NULL_PTR_BRK(className);
        *className = NULL;
    } while (FALSE);

    return hr;
}

STDMETHODIMP CMft0::GetTrustLevel( 
    /* [out] */ __RPC__out TrustLevel *trustLevel)
{
    HRESULT hr = S_OK;
    do {
        CHK_NULL_PTR_BRK(trustLevel);
        *trustLevel = TrustLevel::BaseTrust;
    } while (FALSE);

    return hr;
}

Implémentation de COM

Chaque interface implémentée par votre MFT de pilote doit implémenter et dériver de IUnknown, afin d’être correctement marshalée vers l’application d’appareil UWP de la caméra. Le suivant est un exemple de fichier .idl pour un MFT de pilote qui démontre cela.

// SampleMft0.idl : IDL source for SampleMft0
//

// This file will be processed by the MIDL tool to
// produce the type library (SampleMft0.tlb) and marshalling code.

import "oaidl.idl";
import "ocidl.idl";
import "Inspectable.idl";
import "mftransform.idl";
[
    object,
    uuid(F5208B72-A37A-457E-A309-AE3060780E21),
    oleautomation,
    nonextensible,
    pointer_default(unique)
]
interface IMft0 : IUnknown{
    [id(1)] HRESULT UpdateDsp([in] UINT32 uiPercentOfScreen);
    [id(2)] HRESULT Enable(void);
    [id(3)] HRESULT Disable(void);
    [id(4)] HRESULT GetDspSetting([out] UINT* puiPercentOfScreen, [out] BOOL* pIsEnabled);
};
[
    uuid(DE05674A-C564-4C0E-9B7C-E1519F7AA767),
    version(1.0),
]
library SampleMft0Lib
{
    importlib("stdole2.tlb");
    [
        uuid(7BB640D9-33A4-4759-B290-F41A31DCF848)      
    ]
    coclass Mft0
    {
        [default] interface IMft0;
        interface IInspectable;
        interface IMFTransform;
    };
};

Remarque

Le MFT de pilote est une classe COM classique qui peut être créée en utilisant CoCreateInstance. Vous ne devez pas utiliser la fonction MFTRegister pour l’enregistrer car il ne s’agit pas d’un MFT à usage général.

Création d’un proxy

Le MFT de pilote est un serveur hors processus. Pour l’utiliser dans une application d’appareil UWP, vous devez fournir un support de marshaling dans un proxy afin que votre interface de MFT de pilote puisse être utilisée à travers les limites de processus. Vous pouvez trouver un exemple de cela dans l’exemple de MFT de pilote. L’échantillon utilise le compilateur MIDL pour générer un proxy sans stub.

Exposition du MFT de pilote aux applications

Pour écrire une application d’appareil UWP en C# ou JavaScript qui interagit avec un MFT de pilote, vous devez créer un composant supplémentaire dans le projet Visual Studio du Microsoft Store de l’application de Microsoft Store. Ce composant est un wrapper qui expose les interfaces du MFT de pilote dans un composant Windows Runtime visible pour l’application de Microsoft Store.

Le sous-projet Wrapper dans l’exemple d’application d’appareil UWP pour caméra fournit un exemple de manière d’exposer votre MFT de pilote à l’interface Windows Runtime afin que vous puissiez l’utiliser à partir d’une application d’appareil UWP implémentée en C# ou JavaScript. Il est conçu pour fonctionner en collaboration avec l’exemple de MFT de pilote. Consultez la page de l’exemple de MFT de pilote pour un guide pas à pas sur l’installation, l’exécution et les tests des exemples.

Installation et enregistrement du MFT de pilote

Cette section répertorie les étapes d’installation du MFT de pilote :

Le fichier DLL du MFT de pilote doit être installé dans un sous-répertoire dans l’emplacement suivant :
- %SystemDrive%\Program Files\
Votre programme d’installation de la caméra enregistre le MFT de pilote en appelant sur votre fichier DLL de MFT de pilote, ou en fournissant un fichier de manifeste de pilote (.man) pour le DLL que le programme d’installation utilise pour l’enregistrement.
Définissez la valeur CameraPostProcessingPluginCLSID dans la clé de registre pour votre caméra. Votre fichier INF doit spécifier le CLSID du MFT de pilote dans la clé de registre de la classe de périphérique pour le périphérique, en définissant la valeur CameraPostProcessingPluginCLSID sur le GUID CLSID de la classe de MFT de pilote. Veuillez trouver ci-après un exemple d’une entrée de fichier INF qui peuple les clés de registre pour une caméra :

KSCATEGORY_VIDEO_CAMERA:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{E5323777-F976-4f5b-9B55-B94699C46E44}\##?#USB#VID_045E&PID_075D&MI_00#8&23C3DB65&0&0000#{E5323777-F976-4f5b-9B55-B94699C46E44}\#GLOBAL\Device Parameters]
"CLSID"="{17CCA71B-ECD7-11D0-B908-00A0C9223196}"
"FriendlyName"="USB Video Device"
"RTCFlags"=dword:00000010
"CameraPostProcessingPluginCLSID"="{3456A71B-ECD7-11D0-B908-00A0C9223196}"

KSCATEGORY_CAPTURE:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\DeviceClasses\{ 65E8773D-8F56-11D0-A3B9-00A0C9223196}\##?#USB#VID_045E&PID_075D&MI_00#8&23C3DB65&0&0000#{65E8773D-8F56-11D0-A3B9-00A0C9223196}\#GLOBAL\Device Parameters]
"CLSID"="{17CCA71B-ECD7-11D0-B908-00A0C9223196}"
"FriendlyName"="USB Video Device"
"RTCFlags"=dword:00000010
"CameraPostProcessingPluginCLSID"="{3456A71B-ECD7-11D0-B908-00A0C9223196}"

Remarque

KSCATEGORY_VIDEO_CAMERA est recommandé pour les caméras. Vous n’aurez généralement besoin que d’une seule des clés de registre, en fonction de la manière dont le périphérique est enregistré.

Associez votre application avec la caméra

Cette section contient des informations sur les étapes nécessaires pour identifier votre caméra dans les métadonnées de périphérique et dans le registre Windows. Ces métadonnées vous permettent d’associer votre application d’appareil UWP et d’identifier votre application afin qu’elle puisse être téléchargée de manière transparente la première fois que la caméra est connectée.

Mises à jour

Après la première installation de l’application, si l’utilisateur télécharge une version mise à jour de l’application, les mises à jour sont automatiquement intégrées dans l’expérience de capture de la caméra. Cependant, les mises à jour ne sont pas téléchargées automatiquement. L’utilisateur doit télécharger les mises à jour supplémentaires de l’application depuis le Microsoft Store, car l’application est automatiquement installée uniquement lors de la première connexion. La page principale de votre application d’appareil UWP peut fournir des notifications indiquant que des mises à jour sont disponibles et fournir des liens pour télécharger les mises à jour.

Important

Votre application mise à jour devrait fonctionner avec des pilotes mis à jour distribués via Windows Update.

Caméras multiples

Plusieurs modèles de caméras peuvent déclarer la même application d’appareil UWP dans leurs métadonnées de périphérique. Si un système a plus d’une caméra intégrée en interne, les caméras doivent partager la même application d’appareil UWP. L’application inclut une logique pour déterminer quelle caméra est utilisée et peut afficher une interface utilisateur différente pour chaque caméra dans Plus d’options. Pour plus d’informations sur la personnalisation de cette expérience, veuillez consulter la rubrique Comment personnaliser les options de la caméra.

Caméras internes

Les applications d’appareils UWP pour les caméras internes sont éligibles à l’installation automatique à partir de Microsoft Store, mais il est recommandé de les préinstaller pour une expérience utilisateur la plus transparente. Des étapes supplémentaires sont nécessaires pour prendre en charge les caméras internes et associer une application d’appareil UWP à celles-ci. Pour plus d’informations, veuillez consulter la rubrique Identification de l’emplacement des caméras internes.

Création du package de métadonnées de périphérique

Pour les caméras internes et externes, vous devez créer un package de métadonnées de périphérique. Lorsque vous soumettez votre application d’appareil UWP de caméra au Microsoft Store (ou que vous la préinstallez à l’aide de l’OPK, dans le cas des caméras internes), en plus de l’application elle-même, vous devez fournir des métadonnées contenant les informations suivantes :

Nom de l’éditeur de l’application
Nom de package de l’application
Identifiant de l’élément de l’application
Identifiant de performances du périphérique

Pour plus d’informations sur la façon d’utiliser les métadonnées de périphérique pour associer votre application à votre périphérique, veuillez consulter la section Construire des applications d’appareils UWP.

Développement d’applications UWP pour périphériques

Installation automatique pour les applications d’appareils UWP

Séquence de poignée de main matérielle (MFT matériels)

Guide de conception des minipilotes AVStream

Exemple d’application d’appareil UWP pour caméra

Exemple de MFT de pilote

Partager via

Création d’un pilote MFT de caméra pour une application d’appareil UWP

Le MFT de pilote

Utilisation d’un MFT de pilote

Exigence du modèle de pilote AvStream

Exposition du MFT de pilote aux applications

Caméras multi-broches

Implémentation du MFT de pilote

Outils de développement

Caractéristiques du MFT de pilote

Communication entre la caméra et le MFT de pilote

Comment accéder aux informations de la source du périphérique

Comment mettre en œuvre le mode de transfert

Fichiers d’en-tête à inclure

Comment implémenter IInspectable

Implémentation de COM

Création d’un proxy

Exposition du MFT de pilote aux applications

Installation et enregistrement du MFT de pilote

Associez votre application avec la caméra

Mises à jour

Caméras multiples

Caméras internes

Création du package de métadonnées de périphérique

Commentaires

Ressources supplémentaires

Partager via

Création d’un pilote MFT de caméra pour une application d’appareil UWP

Le MFT de pilote

Utilisation d’un MFT de pilote

Exigence du modèle de pilote AvStream

Exposition du MFT de pilote aux applications

Caméras multi-broches

Implémentation du MFT de pilote

Outils de développement

Caractéristiques du MFT de pilote

Communication entre la caméra et le MFT de pilote

Comment accéder aux informations de la source du périphérique

Comment mettre en œuvre le mode de transfert

Fichiers d’en-tête à inclure

Comment implémenter IInspectable

Implémentation de COM

Création d’un proxy

Exposition du MFT de pilote aux applications

Installation et enregistrement du MFT de pilote

Associez votre application avec la caméra

Mises à jour

Caméras multiples

Caméras internes

Création du package de métadonnées de périphérique

Rubriques connexes

Commentaires

Ressources supplémentaires