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

Les applications d’appareil 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 de caméra MFT (transformation de base multimédia). This article introduces driver MFTs and uses the Driver MFT sample to show how to create one. Pour en savoir plus sur les applications d’appareil UWP en général, consultez Meet UWP device apps.

Le pilote MFT

Cette section décrit la transformation Media Foundation (MFT) que vous créez pour appliquer des effets au flux de capture multimédia provenant de l’appareil photo. Cette transformation est la façon dont vous fournissez des effets de couleur, des modes de jeu et des effets de suivi des visages qui distinguent vraiment votre caméra des autres. Ce MFT, appelé pilote MFT, est d’abord appliqué au flux vidéo connecté provenant du pilote de caméra lorsqu’une application UWP commence la capture vidéo. When that app invokes the Camera options UI, Windows automatically provides access to any interfaces the driver MFT implements for controlling its custom effects.

Un pilote MFT n’est pas requis pour une application d’appareil UWP. Un fabricant d’appareils peut choisir d’implémenter une application d’appareil UWP sans pilote MFT, simplement pour fournir une interface utilisateur différenciée contenant la personnalisation de son matériel, sans appliquer de paramètres personnalisés et d’effets spéciaux au flux vidéo.

Utilisation d’un pilote MFT

The UWP device app for a camera runs in a different process than the Microsoft Store app that invokes it from the CameraCaptureUI API. Pour que l’application d’appareil du Microsoft Store contrôle un pilote MFT, une séquence spécifique d’événements sur différents espaces de processus doit se produire.

1. A UWP app wants to capture a photo, so it calls the CaptureFileAsync method

2. Windows demande le pointeur MFT du pilote et l’ID d’appareil photo

3. Le pointeur MFT du pilote est passé à un hôte de paramètres

4. L’hôte interroge les propriétés de l’appareil pour l’ID d’application de l’application d’appareil microsoft Store associée à l’appareil photo (par métadonnées d’appareil)

5. Si aucune application d’appareil UWP n’est trouvée, le menu volant par défaut interagit avec le moteur de capture

6. Si une application d’appareil UWP est trouvée, elle est activée et l’hôte des paramètres transmet le pointeur MFT du pilote à celui-ci

7. L’application d’appareil UWP contrôle le pilote MFT à l’aide de l’interface exposée via le pointeur

Configuration requise 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, consultez le Guide de conception des minidrivers AVStream.

Comment le pilote MFT est exposé aux applications

Un pilote MFT est inscrit 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 appareil spécifique, tel qu’une caméra.

Lorsqu’une application lance une capture vidéo, un lecteur source Media Foundation est instancié pour fournir le flux vidéo. Cette source multimédia lit une valeur de Registre à partir de la clé de Registre de l’appareil. Si le CLSID de la classe COM du pilote MFT se trouve dans la valeur de Registre, le lecteur source instancie le pilote MFT et l’insère dans le pipeline multimédia.

Outre les applications d’appareil UWP, la fonctionnalité MFT du pilote est accessible lorsque l’appareil associé à celui-ci est utilisé pour capturer la vidéo à l’aide des API suivantes :

• Balises vidéo> HTML5 <dans une application UWP à l’aide de HTML. Les transformations que le pilote MFT active affectent la vidéo en cours de lecture à l’aide de 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 à l’aide de Windows Runtime. For more info on how this API is used, see the Media Capture sample.

• Lecteur source de Media Foundation, pour les applications qui traitent des données multimédias. Le pilote MFT sera exposé aux applications en tant que premier (0e) MFT lors de l’appel IMFSourceReaderEx::GetTransformForStream. La catégorie retournée est MFT_CATEGORY_VIDEO_EFFECT.

  

Multi-pin cameras

Si vous disposez d’une caméra à trois broches ou d’autres caméras à broches multiples, consultez Considérations relatives aux modèles MFT de pilote sur des caméras à plusieurs broches.

Implémentation MFT du pilote

Cette section fournit des informations sur l’implémentation de votre pilote MFT. For a full example of a driver MFT that works together with a UWP device app, see the Driver MFT sample.

Development tools

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

Caractéristiques MFT du pilote

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

Communication entre la caméra et le pilote MFT

Pour activer la communication bidirectionnelle entre la source multimédia et le pilote MFT, le pointeur vers le magasin d’attributs du flux source est défini sur le magasin d’attributs de flux d’entrée du pilote MFT en tant que MFT_CONNECTED_STREAM_ATTRIBUTE. Cela se produit par le biais d’un processus de négociation que vous activez en exposant MFT_ENUM_HARDWARE_URL_Attribute dans le pilote MFT, 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 magasin d’attributs du pilote MFT est défini pour pointer vers le magasin d’attributs du flux source de l’appareil. Pour plus d’informations sur la façon dont la communication entre l’appareil photo et la MFT est configurée, consultez la séquence d’établissement d’une liaison matérielle .

Comment accéder aux informations de source de l’appareil

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

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 implémenter le mode passthrough

Pour placer le pilote MFT en mode passthrough, spécifiez le même type de média pour le flux d’entrée et de sortie. ProcessInput et ProcessOutput les appels sur le MFT seront toujours effectués. Il est laissé à votre implémentation MFT du pilote pour déterminer si un traitement se produit en mode passthrough.

Fichiers d’en-tête à inclure

Vous devez inclure des fichiers d’en-tête pour les méthodes et IMFTransform les IInspectable méthodes que le pilote MFT doit implémenter. For a list of header files to include, see stdafx.h in the SampleMFT0 directory of the UWP device app for camera sample.

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

Comment implémenter IInspectable

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

• IInspectable::GetIids should return null in the iids out parameter, and return 0 in the iidCount out parameter.

• IInspectable::GetRuntimeClassName should return null in the out parameter.

• IInspectable::GetRuntiGetTrustLevel should return TrustLevel::BaseTrust in the out parameter.

L’exemple de code suivant montre comment les IInspectable méthodes sont implémentées dans l’exemple de pilote MFT. This code can be found in the Mft0.cpp file, in the SampleMFT0 directory of the sample.

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

COM implementation

Chaque interface que votre pilote implémente MFT doit implémenter et dériver IUnknown, afin d’être correctement marshalée vers l’application d’appareil UWP de la caméra. The following is an example .idl file for a driver MFT that demonstrates this.

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

Création d’un proxy

Le pilote MFT est un serveur hors processus. Pour l’utiliser dans une application d’appareil UWP, vous devez fournir la prise en charge du marshaling dans un proxy afin que votre interface MFT de pilote puisse être utilisée entre les limites de processus. You can find an example of this in the Driver MFT sample. L’exemple utilise le compilateur MIDL pour générer un proxy sans stub.

Exposition du pilote MFT aux applications

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

Le sous-projet Wrapper dans l’application d’appareil UWP pour l’exemple de caméra fournit un exemple d’exposition de votre pilote MFT à Windows Runtime afin de pouvoir l’utiliser à partir d’une application d’appareil UWP implémentée en C# ou JavaScript. It's designed to work together with the Driver MFT sample. See the Driver MFT sample page for a step-by-step guide to installing, running, and testing the samples.

Installation et inscription du pilote MFT

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

1. La DLL MFT du pilote doit être installée dans un sous-répertoire à l’emplacement suivant :

   • %SystemDrive%\Program Files\

2. Your camera installer registers the driver MFT by calling regsvr32 on your driver MFT DLL, or by providing a driver manifest (.man) file for the DLL that the installer uses for registration.

3. Définissez la CameraPostProcessingPluginCLSID valeur dans la clé de Registre de votre appareil photo. Votre fichier INF doit spécifier le CLSID du pilote MFT dans la clé de Registre de classe d’appareil pour l’appareil, en définissant la CameraPostProcessingPluginCLSID valeur sur le GUID CLSID de la classe MFT du pilote. Voici un exemple d’entrée de fichier INF qui remplit les clés de Registre d’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}"

Associer votre application à la caméra

Cette section contient des informations sur les étapes requises pour identifier votre appareil photo dans les métadonnées de l’appareil et dans le Registre Windows. Ces métadonnées vous permettent de coupler votre application d’appareil UWP et d’identifier votre application afin qu’elle puisse être téléchargée en toute transparence la première fois que la caméra est connectée.

Updates

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 à l’expérience de capture de caméra. Toutefois, les mises à jour ne sont pas téléchargées automatiquement. The user must download more app updates from the Microsoft Store, because the app is automatically installed only on first connect. La page principale de votre application d’appareil UWP peut fournir des notifications indiquant que les mises à jour sont disponibles et fournissent des liens pour télécharger les mises à jour.

Multiple cameras

Plusieurs modèles d’appareil photo peuvent déclarer la même application d’appareil UWP dans leurs métadonnées d’appareil. Si un système a plusieurs caméras incorporées en interne, les caméras doivent partager la même application d’appareil UWP. The app includes logic for determining which camera is in use and can show different UI for each camera in its More options experience. Pour plus d’informations sur la personnalisation de cette expérience, consultez Comment personnaliser les options de caméra.

Internal cameras

UWP device apps for internal cameras are eligible for Automatic installation from the Microsoft Store, but it's recommended that they be preinstalled for the most seamless user experience. Il existe d’autres étapes nécessaires pour prendre en charge les caméras internes et associer une application d’appareil UWP à celles-ci. Pour plus d’informations, consultez Identification de l’emplacement des caméras internes.

Création du package de métadonnées d’appareil

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

• Nom de l’éditeur d’application
• Nom du package d’application
• Identificateur d’élément d’application
• Identificateur de l’expérience de l’appareil

Pour plus d’informations sur l’utilisation des métadonnées d’appareil pour associer votre application à votre appareil, consultez Création d’applications d’appareil UWP.

Related articles

• Création d’applications d’appareil UWP
• Installation automatique des applications UWP pour périphériques
• Séquence de négociation matérielle (MFT matériel)
• Guide de conception des minidrivers AVStream
• Application d’appareil UWP pour l’exemple de caméra
• Exemple MFT du pilote