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

  • Articolo

Importante

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

Le app per dispositivi UWP consentono ai produttori di dispositivi di applicare impostazioni personalizzate ed effetti speciali sul flusso video della fotocamera con un driver della fotocamera MFT (trasformazione media foundation). In questo argomento vengono presentate le MFT driver e viene usato l'esempio driver MFT per illustrare come crearne uno. Per altre informazioni sulle app per dispositivi UWP in generale, vedi Soddisfare le app per dispositivi UWP.

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. Questo è il modo in cui fornisci trasformazioni per effetti di colore, modalità di combinazione e effetti di tracciamento del viso che distinguono realmente 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. Quando tale app richiama l'interfaccia utente delle opzioni Fotocamera, Windows fornisce automaticamente l'accesso a qualsiasi interfaccia implementata dal driver MFT per controllare i relativi effetti personalizzati.

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

Un driver MFT non è necessario per un'app per dispositivi UWP. Un produttore di dispositivi può 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

L'app per dispositivi UWP per una fotocamera viene eseguita in un processo diverso rispetto all'app di Microsoft Store che lo richiama dall'API Fotocamera CaptureUI. 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. Un'app UWP vuole acquisire una foto, quindi chiama il metodo CaptureFileAsync

  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 esegue una query sulle proprietà del dispositivo per l'ID app dell'app di Microsoft Store associata alla fotocamera (per metadati del dispositivo)

  5. Se non viene trovata alcuna app per dispositivi UWP, il riquadro a comparsa 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

the process interaction for invoking a windows store device app.

Requisito del modello di driver AvStream

Il driver della fotocamera deve usare il modello di driver AvStream. Per altre info sul modello di driver AVStream, vedi 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.

Nota

Un driver MFT non deve essere registrato usando la funzione perché è specifico del MFTRegister 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 argomento.

Quando un'app avvia un'acquisizione video, viene creata un'istanza di Media Foundation Source Reader per fornire il flusso video. Questa origine multimediale legge un valore del Registro di sistema 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 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 Windows.Media.MediaCapture in un'app UWP usando Windows Runtime. Per altre info sull'uso di questa API, vedi l'esempio di acquisizione multimediale.

  • 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 che verrà restituita è MFT_CATEGORY_VIDEO_EFFECT.

    source reader's role in media capture.

Fotocamere a più pin

Se si dispone di una fotocamera a tre pin o di un'altra fotocamera multi-pin, vedi Considerazioni per le mft driver su fotocamere multi-pin.

Implementazione MFT del driver

Questa sezione fornisce informazioni sull'implementazione del driver MFT. Per un esempio completo di driver MFT che funziona insieme a un'app per dispositivi UWP, vedi l'esempio driver MFT .

Strumenti di sviluppo

È 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 IInspectable metodi e IMFTransform che il driver MFT deve implementare. Per un elenco di file di intestazione da includere, vedi stdafx.h nella directory SampleMFT0 dell'app per dispositivi UWP per l'esempio di fotocamera .

// 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 deve restituire null nel parametro out iids e restituire 0 nel parametro out iidCount .

  • IInspectable::GetRuntimeClassName deve restituire null nel parametro out.

  • IInspectable::GetRuntiGetTrustLevel deve restituire TrustLevel::BaseTrust nel parametro out.

Nell'esempio di codice seguente viene illustrato come i IInspectable metodi vengono implementati nel driver di esempio MFT. Questo codice è disponibile nel file Mft0.cpp , nella directory SampleMFT0 dell'esempio.

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

Implementazione COM

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. Di seguito è riportato un file con estensione idl di esempio per un driver MFT che illustra questa operazione.

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

Nota

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. È possibile trovare un esempio di questo esempio nell'esempio driver MFT . 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 componente aggiuntivo 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. È progettato per lavorare insieme all'esempio Driver MFT . Vedere la pagina di esempio driver MFT per una guida dettagliata all'installazione, all'esecuzione e al test degli esempi.

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%\Programmi\

  2. Il programma di installazione della fotocamera registra il driver MFT chiamando regsvr32 nella DLL MFT del driver o fornendo un file manifesto del driver (man) per la DLL usata dal programma di installazione per la registrazione.

  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 CameraPostProcessingPluginCLSID valore sul 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}"

Nota

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.

Aggiornamenti

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. L'utente deve scaricare altri aggiornamenti delle app da Microsoft Store, perché l'app viene installata automaticamente solo al primo collegamento. La pagina principale dell'app per dispositivi UWP può fornire notifiche che gli aggiornamenti sono disponibili e fornire collegamenti per scaricare gli aggiornamenti.

Importante

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

Fotocamere multiple

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. L'app include la logica per determinare quale fotocamera è in uso e può mostrare un'interfaccia utente diversa per ogni fotocamera nell'esperienza Altre opzioni . Per altre info sulla personalizzazione di tale esperienza, vedi Come personalizzare le opzioni della fotocamera.

Telecamere interne

Le app per dispositivi UWP per fotocamere interne sono idonee per l'installazione automatica da Microsoft Store, ma è consigliabile preinstallare per l'esperienza utente più facile. Sono necessari passaggi aggiuntivi per supportare le fotocamere interne e associare un'app per dispositivi UWP a tali fotocamere. Per altre info, vedi Identificazione della posizione delle fotocamere interne.

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 opk, nel caso di fotocamere interne), oltre all'app stessa, dovrai fornire metadati contenenti quanto segue:

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

Compilazione di app per dispositivi UWP

Installazione automatica per le app per dispositivi UWP

Sequenza di handshake hardware (MFT hardware)

Guida alla progettazione dei minidriver AVStream

App per dispositivi UWP per l'esempio di fotocamera

Esempio di driver MFT