Condividi tramite

Creazione di un driver della fotocamera MFT per un'app per dispositivi UWP

Important

Questo articolo è deprecato. Per indicazioni aggiornate, vedere la guida alla progettazione MFT del dispositivo .

Important

I metadati del dispositivo sono deprecati e verranno rimossi in una versione futura di Windows. Per informazioni sulla sostituzione di questa funzionalità, vedere Driver Package Container Metadata.For information about the replacement for this functionality, see Driver Package Container Metadata.

Le app UWP per dispositivi consentono ai produttori di dispositivi di applicare impostazioni personalizzate ed effetti speciali sul flusso video della fotocamera con un MFT (Media Foundation Transform) driver della fotocamera. Per ulteriori informazioni sulle app per dispositivi UWP in generale, consulta Scopri le app per dispositivi UWP. To learn more about UWP device apps in general, see Meet UWP device apps.

Il driver MFT

In questa sezione viene descritta la trasformazione MFT (Media Foundation Transform) creata per applicare effetti al flusso di acquisizione multimediale proveniente dalla fotocamera. Questa trasformazione è il modo in cui fornisci effetti di colore, modalità di combinazione e effetti di tracciamento del viso che distinguono davvero la fotocamera dagli altri. Questo MFT, noto come driver MFT, viene prima applicato al flusso video connesso proveniente dal driver della fotocamera quando un'app UWP avvia l'acquisizione video. When that app invokes the Camera options UI, Windows automatically provides access to any interfaces the driver MFT implements for controlling its custom effects.

il driver della fotocamera mft consente a un'app per dispositivi Windows Store di fornire effetti personalizzati.

Un driver MFT non è necessario per un'app per dispositivi UWP. Un produttore di dispositivi potrebbe scegliere di implementare un'app per dispositivi UWP senza un driver MFT, semplicemente per fornire un'interfaccia utente differenziata contenente la personalizzazione per l'hardware, senza applicare impostazioni personalizzate ed effetti speciali al flusso video.

Come viene usato un driver 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. Affinché l'app per dispositivi di Microsoft Store controlli un driver MFT, deve verificarsi una sequenza specifica di eventi in spazi di processo diversi.

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

  2. Windows richiede il puntatore MFT del driver e l'ID dispositivo della fotocamera

  3. Il puntatore MFT del driver viene passato a un host delle impostazioni

  4. L'host interroga le proprietà del dispositivo per l'ID dell'app del dispositivo di Microsoft Store associata alla fotocamera in base ai metadati del dispositivo.

  5. Se non viene trovata alcuna app per dispositivi UWP, il popup predefinito interagisce con il motore di acquisizione

  6. Se viene trovata un'app per dispositivi UWP, viene attivata e l'host delle impostazioni passa il puntatore MFT al driver

  7. L'app per dispositivi UWP controlla il driver MFT usando l'interfaccia esposta tramite il puntatore

interazione del processo per richiamare un'app per dispositivi di Windows Store.

Requisito del modello di driver AvStream

Il driver della tua fotocamera deve utilizzare il modello di driver AvStream. Per altre informazioni sul modello di driver AVStream, vedere Guida alla progettazione dei minidriver AVStream.

Modalità di esposizione del driver MFT alle app

Un driver MFT viene registrato con Windows come interfaccia COM in modo che la trasformazione implementata possa essere applicata al flusso multimediale proveniente da un dispositivo specifico, ad esempio una fotocamera.

Note

Un driver MFT non deve essere registrato usando la MFTRegister funzione perché è specifico del dispositivo e non un MFT per utilizzo generico. Per informazioni sulla chiave del Registro di sistema, vedere la sezione Installazione e registrazione del driver MFT più avanti in questo articolo.

Quando un'app avvia un'acquisizione video, viene creata un'istanza di Media Foundation Source Reader per fornire il flusso video. Questa fonte multimediale legge un valore dalla chiave del Registro di sistema del dispositivo. Se il CLSID della classe COM del driver MFT viene trovato nel valore del Registro di sistema, il lettore di origine crea un'istanza del driver MFT e lo inserisce nella pipeline multimediale.

Oltre alle app per dispositivi UWP, è possibile accedere alla funzionalità MFT del driver quando il dispositivo associato a esso viene usato per acquisire video usando le API seguenti:

  • Tag video< HTML5 >in un'app UWP con HTML. Le trasformazioni abilitate dal driver MFT influiscono sul video riprodotto usando l'elemento <video> , come nell'esempio di codice seguente:

    var video = document.getElementById('myvideo');
    video.src = URL.createObjectURL(fileItem);
    video.play();

  • API MediaCapture di Windows.Media in un'app UWP utilizzando Windows Runtime. For more info on how this API is used, see the Media Capture sample.

  • Lettore di origine di Media Foundation, per le app che elaborano i dati multimediali. Il driver MFT verrà esposto alle applicazioni come primo (0°) MFT quando si chiama IMFSourceReaderEx::GetTransformForStream. La categoria restituita è MFT_CATEGORY_VIDEO_EFFECT.

    ruolo del lettore di origine nell'acquisizione multimediale.

Multi-pin cameras

Se hai una fotocamera a tre pin o un'altra fotocamera multi-pin, consulta Considerazioni per i driver MFT su fotocamere multi-pin.

Implementazione MFT del driver

Questa sezione fornisce informazioni sull'implementazione del driver MFT. For a full example of a driver MFT that works together with a UWP device app, see the Driver MFT sample.

Development tools

È necessario Microsoft Visual Studio Professional o Microsoft Visual Studio Ultimate.

Caratteristiche MFT driver

Viene creata un'istanza del driver MFT per ogni flusso. Per ogni flusso supportato dalla fotocamera, viene creata un'istanza di MFT e connessa a essa. Il driver MFT dovrebbe avere un singolo flusso di input e un singolo flusso di output. Il driver MFT può essere un MFT sincrono o un MFT asincrono.

Comunicazione tra la fotocamera e il driver MFT

Per abilitare la comunicazione bidirezionale tra l'origine multimediale e il driver MFT, il puntatore all'archivio attributi del flusso di origine viene impostato nell'archivio attributi del flusso di input del driver MFT come MFT_CONNECTED_STREAM_ATTRIBUTE. Ciò avviene tramite un processo di handshake abilitato esponendo MFT_ENUM_HARDWARE_URL_Attribute nel driver MFT, come nell'esempio seguente:

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

In questo esempio, MFT_CONNECTED_STREAM_ATTRIBUTE nell'archivio attributi del driver MFT è impostato in modo che punti all'archivio attributi del flusso di origine del dispositivo. Vedi Sequenza di handshake hardware per altri dettagli sulla modalità di configurazione della comunicazione tra la fotocamera e MFT.

Come accedere alle informazioni sull'origine del dispositivo

L'esempio di codice seguente mostra come il driver MFT può ottenere il puntatore alla trasformazione di origine dall'archivio attributi di input. Il driver MFT può quindi usare il puntatore di origine per ottenere informazioni sull'origine del dispositivo.

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.         
      }

Come implementare la modalità pass-through

Per inserire il driver MFT in modalità pass-through, specificare lo stesso tipo di supporto per il flusso di input e output. ProcessInput e ProcessOutput le chiamate sul MFT saranno ancora effettuate. Viene lasciata all'implementazione MFT del driver per determinare se si verifica o meno un'elaborazione in modalità pass-through.

File di intestazione da includere

Sarà necessario includere i file di intestazione per i metodi IInspectable e IMFTransform che il driver MFT deve implementare. 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>

Come implementare IInspectable

Un driver MFT destinato all'uso da un'app per dispositivi UWP di una fotocamera deve implementare i metodi di IInspectable in modo che l'app per dispositivi di Microsoft Store possa accedere a un puntatore al driver MFT all'avvio. Il driver MFT deve implementare i metodi di come indicato di IInspectable seguito:

  • 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.

Nell'esempio di codice seguente viene illustrato come i IInspectable metodi vengono implementati nel driver di esempio 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

Ogni interfaccia implementata dal driver MFT deve implementare e derivare da IUnknown, per essere sottoposto correttamente al marshalling nell'app per dispositivi UWP della fotocamera. 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;
    };
};

Note

Il driver MFT è una normale classe COM che può essere creata usando CoCreateInstance. Non è consigliabile usare la MFTRegister funzione per registrarla perché non è un MFT per utilizzo generico.

Creazione di un proxy

Il driver MFT è un server out-of-process. Per usarlo in un'app per dispositivi UWP, devi fornire supporto per il marshalling in un proxy in modo che l'interfaccia MFT del driver possa essere usata attraverso i limiti del processo. You can find an example of this in the Driver MFT sample. L'esempio usa il compilatore MIDL per generare un proxy senza stub.

Esposizione del driver MFT alle app

Per scrivere un'app per dispositivi UWP in C# o JavaScript che interagisce con un driver MFT, devi creare un altro componente nel progetto Microsoft Visual Studio dell'app per dispositivi di Microsoft Store. Questo componente è un wrapper che espone le interfacce MFT del driver in un componente Windows Runtime visibile all'app per dispositivi di Microsoft Store.

Il sottoprogetto Wrapper nell'app per dispositivi UWP per fotocamera fornisce un esempio di come esporre il driver MFT a Windows Runtime in modo da poterlo usare da un'app per dispositivi UWP implementata in C# o JavaScript. See the Driver MFT sample page for a step-by-step guide to installing, running, and testing the samples. See the Driver MFT sample page for a step-by-step guide to installing, running, and testing the samples.

Installazione e registrazione del driver MFT

Questa sezione elenca i passaggi per l'installazione del driver MFT:

  1. La DLL MFT del driver deve essere installata in una sottodirectory nel percorso seguente:

    • %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. Impostare il CameraPostProcessingPluginCLSID valore nella chiave del Registro di sistema per la fotocamera. Il file INF deve specificare il CLSID del Driver MFT nella chiave del Registro di sistema della classe di dispositivo per il dispositivo, impostando il valore CameraPostProcessingPluginCLSID al GUID CLSID della classe MFT del driver. Di seguito è riportato un esempio di una voce di file INF che popola le chiavi del Registro di sistema per una fotocamera:

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}"

Note

KSCATEGORY_VIDEO_CAMERA è consigliato per le fotocamere. In genere è necessaria solo una delle chiavi del Registro di sistema, a seconda della modalità di registrazione del dispositivo.

Associare l'app alla fotocamera

Questa sezione contiene informazioni sui passaggi necessari per identificare la fotocamera nei metadati del dispositivo e nel Registro di sistema di Windows. Questi metadati consentono di associare l'app del dispositivo UWP e di identificare l'app in modo che possa essere scaricata senza problemi la prima volta che la fotocamera è connessa.

Updates

Dopo la prima installazione dell'app, se l'utente scarica una versione aggiornata dell'app, gli aggiornamenti vengono integrati automaticamente nell'esperienza di acquisizione della fotocamera. Tuttavia, gli aggiornamenti non vengono scaricati automaticamente. La pagina principale dell'app per dispositivi UWP può fornire notifiche che gli aggiornamenti sono disponibili e fornire collegamenti per scaricare gli aggiornamenti. The main page of your UWP device app can provide notifications that updates are available and provide links to download updates.

Important

L'app aggiornata dovrebbe funzionare con tutti i driver aggiornati distribuiti tramite Windows Update.

Multiple cameras

Più modelli di fotocamera possono dichiarare la stessa app per dispositivi UWP nei metadati del dispositivo. Se un sistema ha più di una fotocamera incorporata internamente, le fotocamere devono condividere la stessa app per dispositivi 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. Per altre info sulla personalizzazione di tale esperienza, vedi Come personalizzare le opzioni della fotocamera.

Internal cameras

Sono necessari altri passaggi per supportare fotocamere interne e associare un'app per dispositivi UWP a tali fotocamere. Per altre info, vedi Identificazione della posizione delle fotocamere interne. For more info, see Identifying the location of internal cameras.

Creazione del pacchetto di metadati del dispositivo

Per fotocamere interne ed esterne, è necessario creare un pacchetto di metadati del dispositivo. Quando invii l'app per dispositivi UWP della fotocamera a Microsoft Store (o preinstallala usando la chiave opk, nel caso di fotocamere interne), oltre all'app stessa, devi fornire metadati contenenti:

  • Nome dell'autore dell'applicazione
  • Nome pacchetto dell'applicazione
  • Identificatore dell'elemento dell'applicazione
  • Identificatore dell'esperienza del dispositivo

Per altre info su come usare i metadati del dispositivo per associare l'app al dispositivo, vedi Creazione di app per dispositivi UWP.

  • Last updated on