Freigeben über

Erstellen eines Kameratreibers MFT für eine UWP-Geräte-App

  • Artikel

Wichtig

Dieses Thema ist veraltet. Aktualisierte Anleitungen finden Sie im Geräte-MFT-Entwurfshandbuch.

Mit UWP-Geräte-Apps können Gerätehersteller benutzerdefinierte Einstellungen und Spezialeffekte auf den Videostream der Kamera mit einem Kameratreiber MFT (Media Foundation Transform) anwenden. In diesem Thema werden Treiber-MFTs vorgestellt und das Beispiel Driver MFT verwendet, um zu zeigen, wie eine erstellt wird. Weitere Informationen zu UWP-Geräte-Apps im Allgemeinen finden Sie unter UWP-Geräte-Apps kennenlernen.

Der Treiber MFT

In diesem Abschnitt wird die Media Foundation Transform (MFT) beschrieben, die Sie erstellen, um Effekte auf den Medienaufnahmedatenstream anzuwenden, der von der Kamera stammt. So stellen Sie Transformationen für Farbeffekte, Schemamodi und Gesichtsverfolgungseffekte bereit, die Ihre Kamera wirklich von anderen unterscheiden. Diese MFT, auch Treiber-MFT genannt, wird zunächst auf den verbundenen Videostream angewendet, der vom Kameratreiber kommt, wenn eine UWP-App mit der Videoaufnahme beginnt. Wenn diese App die Kamera Options-UI aufruft, bietet Windows automatisch Zugriff auf alle Schnittstellen, die der Treiber MFT zur Steuerung seiner benutzerdefinierten Effekte implementiert.

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

Ein Treiber-MFT ist für eine UWP-Geräte-App nicht erforderlich. Ein Gerätehersteller kann sich dafür entscheiden, eine UWP-Geräte-App ohne Treiber-MFT zu implementieren, um lediglich eine differenzierte Benutzeroberfläche mit Branding für seine Hardware bereitzustellen, ohne benutzerdefinierte Einstellungen und Spezialeffekte auf den Videostream anzuwenden.

Wie wird ein Treiber-MFT verwendet?

Die UWP-Geräte-App für eine Kamera wird in einem anderen Prozess als die Microsoft Store-App ausgeführt, die sie aus der Kamera CaptureUI-API aufruft. Damit die Microsoft Store-Geräte-App eine Treiber-MFT steuern kann, muss eine bestimmte Abfolge von Ereignissen über verschiedene Prozessräume hinweg erfolgen.

  1. Eine UWP-App möchte ein Foto aufnehmen, sodass sie die CaptureFileAsync-Methode aufruft.

  2. Windows fordert den MFT-Zeiger des Treibers und die Geräte-ID der Kamera an.

  3. Der MFT-Treiberzeiger wird an einen Einstellungshost übergeben.

  4. Der Host fragt Geräteeigenschaften für die App-ID der Microsoft Store-Geräte-App ab, die der Kamera zugeordnet ist (pro Gerätemetadaten).

  5. Wenn keine UWP-Geräte-App gefunden wird, interagiert das Standard-Flyout mit dem Aufnahmemodul.

  6. Wenn eine UWP-Geräte-App gefunden wird, wird sie aktiviert, und der Einstellungshost übergibt den MFT-Treiberzeiger an die App.

  7. Die UWP-Geräte-App steuert den Treiber MFT mithilfe der Schnittstelle, die über den Zeiger verfügbar gemacht wird.

the process interaction for invoking a windows store device app.

AvStream-Treibermodellanforderung

Der Kameratreiber muss das AvStream-Treibermodell verwenden. Weitere Informationen zum AVStream-Treibermodell finden Sie im Designleitfaden für AVStream Minidrivers.

Wie der Treiber MFT für Apps verfügbar gemacht wird

Ein Treiber-MFT wird bei Windows als COM-Schnittstelle registriert, sodass die von ihm implementierte Transformation auf den Medienstream angewendet werden kann, der von einem bestimmten Gerät, beispielsweise einer Kamera, kommt.

Hinweis

Ein Treiber-MFT sollte nicht mithilfe der MFTRegister Funktion registriert werden, da er gerätespezifisch und kein allgemeiner MFT ist. Informationen zum Registrierungsschlüssel finden Sie im Abschnitt Installieren und Registrieren des Treibers MFT weiter unten in diesem Thema.

Wenn eine App eine Videoaufnahme initiiert, wird ein Media Foundation Source Reader instanziiert, um den Videostream bereitzustellen. Diese Medienquelle liest einen Registrierungswert aus dem Geräteregistrierungsschlüssel. Wenn die CLSID der COM-Klasse des Treibers MFT im Registrierungswert gefunden wird, instanziiert der Quellleser den Treiber MFT und fügt sie in die Medienpipeline ein.

Zusätzlich zu UWP-Geräte-Apps kann auf die MFT-Funktionalität des Treibers zugegriffen werden, wenn das damit verbundene Gerät zum Aufnehmen von Videos mithilfe der folgenden APIs verwendet wird:

  • HTML5-<Videotags> in einer UWP-App mit HTML. Transformationen, die der Treiber MFT aktiviert hat, wirken sich auf Videos aus, die mit dem <Videoelement> wiedergegeben werden, wie im folgenden Codebeispiel gezeigt:

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

  • Windows.Media.MediaCapture-API in einer UWP-App mit Verwendung von Windows-Runtime. Weitere Informationen zur Verwendung dieser API finden Sie im Beispiel für die Medienaufnahme .

  • Media Foundation Source Reader, für Apps, die Mediendaten verarbeiten. Der Treiber-MFT wird beim Aufruf von IMFSourceReaderEx::GetTransformForStream als erster (0.) MFT für Anwendungen verfügbar gemacht. Die Kategorie, die zurückgegeben wird, ist MFT_CATEGORY_VIDEO_EFFECT.

    source reader's role in media capture.

Multi-Pin-Kameras

Wenn Sie eine Drei-Pin- oder eine andere Multi-Pin-Kamera haben, lesen Sie Überlegungen zu Treiber-MFTs bei Multi-Pin-Kameras.

MFT-Treiber-Implementierung

Dieser Abschnitt enthält Informationen zur Implementierung des MFT-Treibers. Ein vollständiges Beispiel für einen Treiber-MFT, der zusammen mit einer UWP-Geräte-App funktioniert, finden Sie im Beispiel Treiber MFT.

Entwicklungstools

Microsoft Visual Studio Professional oder Microsoft Visual Studio Ultimate ist erforderlich.

Treiber-MFT-Eigenschaften

Der Treiber-MFT wird pro Datenstrom instanziiert. Für jeden Datenstrom, den die Kamera unterstützt, wird eine Instanz des MFT instanziiert und damit verbunden. Der Treiber-MFT wird erwartet, dass ein einzelner Eingabedatenstrom und ein einzelner Ausgabedatenstrom vorhanden sind. Der Treiber-MFT kann entweder ein synchroner MFT oder ein asynchroner MFT sein.

Kommunikation zwischen Kamera und Treiber-MFT

Um die bidirektionale Kommunikation zwischen der Medienquelle und dem Treiber-MFT zu ermöglichen, wird der Zeiger auf den Attributspeicher des Quelldatenstroms im Eingabedatenstrom-Attributspeicher des Treiber-MFT als MFT_CONNECTED_STREAM_ATTRIBUTE festgelegt. Dies geschieht durch einen Handshake-Prozess, den Sie aktivieren, indem Sie den Treiber-MFT verfügbarmachen MFT_ENUM_HARDWARE_URL_Attribute , wie im folgenden Beispiel:

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 diesem Beispiel ist die MFT_CONNECTED_STREAM_ATTRIBUTE im Attributspeicher des Treiber-MFT so eingestellt, dass sie auf den Attributspeicher des Gerätequellstreams verweist. Weitere Informationen zur Einrichtung der Kommunikation zwischen der Kamera und dem MFT finden Sie unter Hardware Handshake Sequence .

Zugreifen auf Gerätequelleninformationen

Das folgende Codebeispiel zeigt, wie der Treiber-MFT den Zeiger auf die Quelltransformation aus dem Eingabeattributespeicher abrufen kann. Der Treiber-MFT kann dann den Quellzeiger verwenden, um Gerätequelleninformationen abzurufen.

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

Implementieren des Passthroughmodus

Um den Treiber-MFT im Passthroughmodus zu platzieren, geben Sie denselben Medientyp für den Eingabe- und Ausgabedatenstrom an. ProcessInput und ProcessOutput ruft MFT wird weiterhin aufgerufen. Sie bleibt bis zur Treiber-MFT Implementierung, um zu bestimmen, ob eine Verarbeitung im Passthroughmodus erfolgt oder nicht.

Einzubindende Header-Dateien

Sie müssen Headerdateien für die IInspectable und IMFTransform Methoden einschließen, die vom Treiber-MFT implementiert werden müssen. Eine Liste der einzuschließenden Headerdateien finden Sie unter stdafx.h im SampleMFT0-Verzeichnis der UWP-Geräte-App für das Kamerabeispiel .

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

Implementieren von IInspectable

Ein Treiber-MFT, der für die Verwendung über die UWP-Geräte-App einer Kamera vorgesehen ist, muss die Methoden IInspectable implementieren, damit die Microsoft Store-Geräte-App beim Start auf einen Zeiger auf den Treiber MFT zugreifen kann. Ihr TreiberMFT sollte die folgenden Methoden IInspectable implementieren:

  • IInspectable::GetIids sollte Null im iids-Out-Parameter zurückgeben und "0" im iidCount-Out-Parameter zurückgeben.

  • IInspectable::GetRuntimeClassName sollte Null im Out-Parameter zurückgeben.

  • IInspectable::GetRuntiGetTrustLevel sollte im Out-Parameter zurückgegeben werden TrustLevel::BaseTrust .

Das folgende Codebeispiel zeigt, wie die IInspectable Methoden im Beispieltreiber MFT implementiert werden. Dieser Code befindet sich in der Mft0.cpp-Datei im SampleMFT0-Verzeichnis des Beispiels.

// 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-Implementierung

Jede Schnittstelle, die Ihr Treiber-MFT implementiert, sollte implementiert und abgeleitet IUnknownwerden, um ordnungsgemäß an die UWP-Geräte-App der Kamera gemarstet zu werden. Im Folgenden finden Sie eine Beispieldatei .idl für eine Treiber-MFT, die dies demonstriert.

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

Hinweis

Der Treiber-MFT ist eine normale COM-Klasse, die mit CoCreateInstance erstellt werden kann. Sie sollten die MFTRegister Funktion nicht verwenden, um sie zu registrieren, da es sich nicht um einen allgemeinen MFT handelt.

Erstellen eines Proxys

Der Treiber-MFT ist ein Out-of-Process-Server. Um es in einer UWP-Geräte-App zu verwenden, müssen Sie Marshalling-Unterstützung in einem Proxy bereitstellen, damit Ihre Treiber-MFT-Schnittstelle über Prozessgrenzen hinweg verwendet werden kann. Ein Beispiel hierfür finden Sie im Beispiel Treiber-MFT. Im Beispiel wird der MIDL-Compiler verwendet, um einen stublosen Proxy zu generieren.

Bereitstellen des Treiber-MFT für Apps

Um eine UWP-Geräte-App in C# oder JavaScript zu schreiben, die mit einem Treiber MFT interagiert, müssen Sie eine zusätzliche Komponente im Microsoft Visual Studio-Projekt der Microsoft Store-Geräte-App erstellen. Diese Komponente ist ein Wrapper, der die MFT-Treiberschnittstellen in einer Windows-Runtime Komponente verfügbar macht, die für die Microsoft Store-Geräte-App sichtbar ist.

Das Wrapper-Unterprojekt im Beispiel UWP-Geräte-App für Kamera bietet ein Beispiel dafür, wie Sie Ihren Treiber-MFT der Windows-Runtime zur Verfügung stellen, damit Sie ihn von einer in C# oder JavaScript implementierten UWP-Geräte-App aus verwenden können. Es wurde entwickelt, um mit dem Treiber-MFT-Beispiel zusammenzuarbeiten. Eine schrittweise Anleitung zum Installieren, Ausführen und Testen der Beispiele finden Sie auf der Treiber-MFT-Beispielseite .

Installieren und Registrieren der Treiber-MFT

In diesem Abschnitt werden die Schritte zum Installieren der Treiber-MFT aufgeführt:

  1. Die Treiber-MFT-DLL muss in einem Unterverzeichnis am folgenden Speicherort installiert werden:

    • %SystemDrive%\Programme\

  2. Ihr Kamerainstallationsprogramm registriert den Treiber MFT durch Aufrufen von regsvr32 auf der Treiber-MFT-DLL oder durch Bereitstellen einer Treibermanifestdatei (.man) für die DLL, die das Installationsprogramm für die Registrierung verwendet.

  3. Legen Sie den CameraPostProcessingPluginCLSID Wert im Registrierungsschlüssel für Ihre Kamera fest. Ihre INF-Datei sollte die CLSID des Treiber-MFT im Registrierungsschlüssel der Geräteklasse für das Gerät angeben, indem Sie den CameraPostProcessingPluginCLSID Wert auf die CLSID-GUID der Treiber-MFT-Klasse festlegen. Es folgt ein Beispiel aus einem INF-Dateieintrag, der die Registrierungsschlüssel für eine Kamera auffüllt:

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

Hinweis

KSCATEGORY_VIDEO_CAMERA wird für Kameras empfohlen. Normalerweise benötigen Sie nur einen der Registrierungsschlüssel, je nachdem, wie das Gerät registriert ist.

Zuordnen Ihrer App zur Kamera

Dieser Abschnitt enthält Informationen zu den Schritten, die erforderlich sind, um Ihre Kamera in Gerätemetadaten und in der Windows-Registrierung zu identifizieren. Mit diesen Metadaten können Sie Ihre UWP-Geräte-App koppeln und Ihre App identifizieren, damit sie nahtlos heruntergeladen werden kann, wenn die Kamera zum ersten Mal verbunden ist.

Updates

Wenn der Benutzer nach der ersten Installation der App eine aktualisierte Version der App herunterlädt, werden die Updates automatisch in das Kameraaufnahmeerlebnis integriert. Updates werden jedoch nicht automatisch heruntergeladen. Der Benutzer muss zusätzliche App-Updates aus dem Microsoft Store herunterladen, da die App nur bei der ersten Verbindung automatisch installiert wird. Die Standard Seite Ihrer UWP-Geräte-App kann Benachrichtigungen bereitstellen, dass Updates verfügbar sind, und Links zum Herunterladen von Updates bereitstellen.

Wichtig

Ihre aktualisierte App sollte mit allen aktualisierten Treibern arbeiten, die über Windows Update verteilt werden.

Mehrere Kameras

Mehrere Kameramodelle können dieselbe UWP-Geräte-App in ihren Gerätemetadaten deklarieren. Wenn ein System über mehrere intern eingebettete Kameras verfügt, müssen die Kameras dieselbe UWP-Geräte-App verwenden. Die App enthält Logik zum Bestimmen der verwendeten Kamera und kann für jede Kamera unterschiedliche Ui-Elemente in der Benutzeroberfläche Weitere Optionen anzeigen. Weitere Informationen zum Anpassen dieser Oberfläche finden Sie unter Anpassen von Kameraoptionen.

Interne Kameras

UWP-Geräte-Apps für interne Kameras sind für die automatische Installation aus dem Microsoft Store berechtigt, es wird jedoch empfohlen, dass sie für die nahtlose Benutzererfahrung vorinstalliert sind. Es sind zusätzliche Schritte erforderlich, um interne Kameras zu unterstützen und eine UWP-Geräte-App zuzuordnen. Weitere Informationen finden Sie unter Identifizieren der Position interner Kameras.

Erstellen des Gerätemetadatenpakets

Für interne und externe Kameras müssen Sie ein Gerätemetadatenpaket erstellen. Wenn Sie die UWP-Geräte-App Ihrer Kamera an den Microsoft Store übermitteln (oder mit dem OPK vorinstallieren, im Falle interner Kameras), müssen Sie zusätzlich zur App selbst Metadaten bereitstellen, die Folgendes enthalten:

  • Name des Anwendungsherausgebers

  • Anwendungspaketname

  • Anwendungselementbezeichner

  • Gerätedarstellungs-ID

Weitere Informationen zur Verwendung von Gerätemetadaten zum Zuordnen Ihrer App zu Ihrem Gerät finden Sie unter Erstellen von UWP-Geräte-Apps.

Erstellen von UWP-Geräte-Apps

Automatische Installation für UWP-Geräte-Apps

Hardware Handshake Sequence (Hardware MFTs)

Designhandbuch für AVStream Minidrivers

UWP-Geräte-App für Kamerabeispiel

Beispiel-MFT-Treiber