建立UWP裝置應用程式的相機驅動程式 MFT

發行項
02/14/2024

重要

本主題已被取代。如需更新的指引，請參閱裝置 MFT 設計指南。

UWP 裝置應用程式可讓裝置製造商使用相機驅動程式 MFT（媒體基礎轉換）在相機的視訊串流上套用自定義設定和特殊效果。本主題介紹驅動程式 MFT，並使用驅動程式 MFT 範例來示範如何建立一個驅動程式。若要深入瞭解一般 UWP 裝置應用程式，請參閱滿足 UWP 裝置應用程式。

驅動程式 MFT

本節說明您建立的媒體基礎轉換（MFT）將效果套用至來自相機的媒體擷取數據流。這是您針對色彩效果、配置模式和臉部追蹤效果提供轉換的方式，這些效果能真正區分相機與其他相機。此 MFT 稱為驅動程式 MFT，會先套用至 UWP 應用程式開始擷取視訊時，來自相機驅動程式的連線視訊串流。當該應用程式叫用相機選項 UI 時，Windows 會自動提供驅動程式 MFT 實作以控制其自定義效果的任何介面的存取權。

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

UWP 裝置應用程式不需要驅動程式 MFT。裝置製造商可以選擇在沒有驅動程式 MFT 的情況下實作 UWP 裝置應用程式，只要提供包含硬體商標的區別使用者介面，而不需要將自定義設定和特殊效果套用至視訊串流。

如何使用驅動程式 MFT

相機的 UWP 裝置應用程式會以不同於從相機 CaptureUI API 叫用它的 Microsoft Store 應用程式執行。若要讓 Microsoft Store 裝置應用程式控制驅動程式 MFT，必須發生跨不同進程空間的特定事件序列。

UWP app 想要擷取相片，因此它會呼叫 CaptureFileAsync 方法
Windows 要求驅動程式 MFT 指標和相機的裝置識別碼
驅動程式 MFT 指標會傳遞至設定主機
主機會查詢與相機相關聯之 Microsoft Store 裝置應用程式之應用程式識別碼的裝置屬性（每個裝置元數據）
如果找不到 UWP 裝置應用程式，預設飛出視窗會與擷取引擎互動
如果找到 UWP 裝置應用程式，則會啟動它，而設定主機會將驅動程式 MFT 指標傳遞給它
UWP 裝置應用程式會使用透過指標公開的介面控制驅動程式 MFT

the process interaction for invoking a windows store device app.

AvStream 驅動程式模型需求

相機的驅動程序必須使用 AvStream 驅動程式模型。如需AVStream驅動程式模型的詳細資訊，請參閱 AVStream Minidrivers設計指南。

驅動程式 MFT 如何公開至應用程式

驅動程式 MFT 會向 Windows 註冊為 COM 介面，以便將其實作的轉換套用至特定裝置所傳出的媒體串流，例如相機。

注意

驅動程式 MFT 不應該使用函 MFTRegister 式註冊，因為它是裝置特定的，而不是一般用途的 MFT。如需登錄機碼的資訊，請參閱本主題稍後的安裝和註冊驅動程式 MFT 一節。

當應用程式起始視訊擷取時，會具現化媒體基礎來源讀取器以提供視訊串流。此媒體來源會從裝置登錄機碼讀取登錄值。如果在登錄值中找到驅動程式 MFT COM 類別的 CLSID，來源讀取器就會具現化驅動程式 MFT，並將它插入媒體管線。

除了 UWP 裝置應用程式之外，當相關聯的裝置使用下列 API 來擷取視訊時，還可以存取驅動程式 MFT 功能：

在 UWP 應用程式中使用 HTML 的 HTML5 <影片> 標記。驅動程式 MFT 已啟用的轉換會影響使用 <影片元素播放的視> 訊，如下列程式代碼範例所示：
```
var video = document.getElementById('myvideo');
    video.src = URL.createObjectURL(fileItem);
    video.play();
```
使用 Windows 執行階段的 UWP 應用程式中的 Windows.Media.MediaCapture API。如需如何使用此 API 的詳細資訊，請參閱媒體擷取範例。
媒體基礎的來源讀取器，用於處理媒體數據的應用程式。呼叫時 IMFSourceReaderEx::GetTransformForStream，驅動程式 MFT 將會公開給應用程式作為第一個（0th） MFT。將傳回類別是 MFT_CATEGORY_VIDEO_EFFECT。

多針相機

如果您有三針或其他多針相機，請參閱多針式相機上的驅動程式 MFT 考慮。

驅動程式 MFT 實作

本節提供實作驅動程式 MFT 的相關信息。如需與 UWP 裝置應用程式搭配運作的驅動程式 MFT 完整範例，請參閱驅動程式 MFT 範例。

開發工具

需要 Microsoft Visual Studio Professional 或 Microsoft Visual Studio Ultimate。

驅動程式 MFT 特性

驅動程式 MFT 會依數據流具現化。對於相機支援的每個數據流，MFT 的實例會具現化並連線到該數據流。驅動程式 MFT 預期會有單一輸入數據流和單一輸出數據流。驅動程式 MFT 可能是同步 MFT 或異步 MFT。

相機與驅動程式 MFT 之間的通訊

若要開啟媒體來源與驅動程式 MFT 之間的雙向通訊，來源資料流屬性存放區的指標會在驅動程式 MFT 的輸入資料流屬性存放區上設定為 MFT_CONNECTED_STREAM_ATTRIBUTE。這會透過您在驅動程式 MFT 中公開 MFT_ENUM_HARDWARE_URL_Attribute 來啟用的交握程式，如下列範例所示：

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

在此範例中， MFT_CONNECTED_STREAM_ATTRIBUTE 驅動程式 MFT 屬性存放區中的設定為指向裝置來源數據流的屬性存放區。如需相機與 MFT 如何設定通訊的進一步詳細數據，請參閱硬體交握序列。

如何存取裝置來源資訊

下列程式代碼範例示範驅動程式 MFT 如何從其輸入屬性存放區取得來源轉換的指標。驅動程式 MFT 接著可以使用來源指標來取得裝置來源資訊。

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

如何實作傳遞模式

若要將驅動程式 MFT 置於傳遞模式，請為輸入和輸出資料流指定相同的媒體類型。 ProcessInputProcessOutput和對 MFT 的呼叫仍會進行。驅動程式 MFT 實作會保留下來，以判斷是否在傳遞模式中發生任何處理。

要包含的頭檔

您必須包含驅動程式 MFT 必須實作之 IInspectable 和 IMFTransform 方法的標頭檔。如需要包含的頭檔清單，請參閱適用於相機範例之 UWP 裝置應用程式的 SampleMFT0 目錄中的 stdafx.h。

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

如何實作 IInspectable

要用於相機 UWP 裝置應用程式的驅動程式 MFT 必須實作的方法 IInspectable ，Microsoft Store 裝置應用程式可以在啟動時存取驅動程式 MFT 的指標。您的驅動程式 MFT 應該實作 IInspectable 的方法，如下所示：

IInspectable：：GetIids 應該在iids out 參數中傳回 null，並在 iidCount out 參數中傳回 0。
IInspectable：：GetRuntimeClassName 應該在 out 參數中傳回 null。
IInspectable：：GetRuntiGetTrustLevel 應該會在 out 參數中傳回 TrustLevel::BaseTrust 。

下列程式代碼範例示範如何在 IInspectable 範例驅動程式 MFT 中實作方法。您可以在範例的 SampleMFT0 目錄中的 Mft0.cpp 檔案中找到此程式代碼。

// 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 實作

驅動程式 MFT 實作的每個介面都應該實作並衍生自 IUnknown，以便正確地封送處理至相機的 UWP 裝置應用程式。以下是示範此動作之驅動程式 MFT 的範例 .idl 檔案。

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

注意

驅動程式 MFT 是可使用建立 CoCreateInstance的一般 COM 類別。您不應該使用函 MFTRegister 式來註冊它，因為它不是一般用途的 MFT。

建立 Proxy

驅動程式 MFT 是跨進程伺服器。若要在 UWP 裝置應用程式中使用它，您必須在 Proxy 中提供封送處理支援，以便跨進程界限使用驅動程式 MFT 介面。您可以在驅動程式 MFT 範例中找到此範例。此範例會使用 MIDL 編譯程式來產生無存根 Proxy。

將驅動程式 MFT 公開至應用程式

若要在 C# 或 JavaScript 撰寫與驅動程式 MFT 互動的 UWP 裝置應用程式，您必須在 Microsoft Store 裝置應用程式的 Microsoft Visual Studio 專案中建立其他元件。此元件是一種包裝函式，會在 Microsoft Store 裝置應用程式可見的 Windows 執行階段元件中公開驅動程式 MFT 介面。

適用於相機的 UWP 裝置應用程式中的包裝函式子專案範例提供如何將驅動程式 MFT 公開至 Windows 執行階段的範例，讓您能夠從 C# 或 JavaScript 中實作的 UWP 裝置應用程式使用它。其設計目的是要與驅動程式 MFT 範例搭配使用。如需安裝、執行和測試範例的逐步指南，請參閱驅動程式 MFT 範例頁面。

安裝和註冊驅動程式 MFT

本節列出安裝驅動程式 MFT 的步驟：

驅動程式 MFT DLL 必須安裝在下列位置的子目錄中：
- %SystemDrive%\Program Files\
相機安裝程式會在驅動程式 MFT DLL 上呼叫 regsvr32 ，或為安裝程式用於註冊的 DLL 提供驅動程式指令清單（.man）檔案來註冊驅動程式 MFT。
CameraPostProcessingPluginCLSID設定相機登錄機碼中的值。您的 INF 檔案應該藉由將驅動程式 MFT 類別的 CLSID 設定 CameraPostProcessingPluginCLSID 為驅動程式 MFT 類別的 CLSID GUID，在裝置的裝置類別登錄機碼中指定 CLSID。以下是 INF 檔案項目中填入相機登錄機碼的範例：

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

注意

KSCATEGORY_VIDEO_CAMERA 建議用於相機。根據裝置的註冊方式，您通常只需要其中一個登錄機碼。

將您的應用程式與相機產生關聯

本節包含識別裝置元數據和 Windows 登錄中相機所需步驟的相關信息。此元數據可讓您配對 UWP 裝置應用程式並識別您的應用程式，以便在相機第一次連線時順暢地下載它。

更新

第一次安裝應用程式之後，如果使用者下載應用程式的更新版本，則更新會自動整合到相機擷取體驗中。不過，不會自動下載更新。用戶必須從 Microsoft Store 下載其他應用程式更新，因為應用程式只會在第一次連線時自動安裝。 UWP 裝置應用程式的主頁面可以提供更新可用通知，並提供下載更新的連結。

重要

更新的應用程式應該使用透過 Windows Update 散發的任何更新驅動程式。

多個相機

多個相機模型可以在其裝置元數據中宣告相同的 UWP 裝置應用程式。如果系統有多個內部內嵌相機，相機必須共用相同的 UWP 裝置應用程式。應用程式包含用來判斷使用哪部相機的邏輯，並可在其 [更多選項] 體驗中顯示每個相機的不同UI。如需自定義該體驗的詳細資訊，請參閱如何自定義相機選項。

內部相機

適用於內部相機的 UWP 裝置應用程式有資格從 Microsoft Store 自動安裝，但建議預安裝，以取得最順暢的用戶體驗。支援內部相機並建立UWP裝置應用程式與其關聯的額外步驟。如需詳細資訊，請參閱識別內部相機的位置。

建立裝置元數據套件

針對內部和外部相機，您必須建立裝置元數據套件。當您將相機的 UWP 裝置應用程式提交至 Microsoft Store 時，除了應用程式本身之外，您還需要提供包含下列專案的元數據：

應用程式發行者名稱
應用程式套件名稱
應用程式項目識別碼
裝置體驗標識碼

如需如何使用裝置元數據來關聯您的應用程式與裝置的詳細資訊，請參閱建置 UWP 裝置應用程式。

建置 UWP 裝置應用程式

自動安裝 UWP 裝置應用程式

硬體交握順序（硬體 MFT）

AVStream Minidrivers 設計指南

相機範例的 UWP 裝置應用程式

驅動程式 MFT 範例

共用方式為

建立UWP裝置應用程式的相機驅動程式 MFT

驅動程式 MFT

如何使用驅動程式 MFT

AvStream 驅動程式模型需求

驅動程式 MFT 如何公開至應用程式

多針相機

驅動程式 MFT 實作

開發工具

驅動程式 MFT 特性

相機與驅動程式 MFT 之間的通訊

如何存取裝置來源資訊

如何實作傳遞模式

要包含的頭檔

如何實作 IInspectable

COM 實作

建立 Proxy

將驅動程式 MFT 公開至應用程式

安裝和註冊驅動程式 MFT

將您的應用程式與相機產生關聯

更新

多個相機

內部相機

建立裝置元數據套件

意見反應

其他資源

共用方式為

建立UWP裝置應用程式的相機驅動程式 MFT

驅動程式 MFT

如何使用驅動程式 MFT

AvStream 驅動程式模型需求

驅動程式 MFT 如何公開至應用程式

多針相機

驅動程式 MFT 實作

開發工具

驅動程式 MFT 特性

相機與驅動程式 MFT 之間的通訊

如何存取裝置來源資訊

如何實作傳遞模式

要包含的頭檔

如何實作 IInspectable

COM 實作

建立 Proxy

將驅動程式 MFT 公開至應用程式

安裝和註冊驅動程式 MFT

將您的應用程式與相機產生關聯

更新

多個相機

內部相機

建立裝置元數據套件

相關主題

意見反應

其他資源