共用方式為

WDM 類別驅動程式篩選器

  • 發行項

[與此頁面相關的功能 DirectShow是舊版功能。 它已被 MediaPlayer、 IMFMediaEngine和 Media Foundation 中的音訊/視訊擷取取代。 這些功能已針對Windows 10和Windows 11進行優化。 Microsoft 強烈建議新程式碼盡可能使用 MediaPlayer、 IMFMediaEngine 和 音訊/視訊擷取 ，而不是 DirectShow。 Microsoft 建議使用舊版 API 的現有程式碼盡可能重寫為使用新的 API。

如果擷取裝置使用 Windows 驅動程式模型 (WDM) 驅動程式，圖表可能需要從擷取篩選器上游取得特定篩選。 這些篩選稱為 stream-class 驅動程式篩選準則或 WDM 篩選器。 它們支援硬體所提供的其他功能。 例如，電視微調卡具有設定頻道的功能。 對應的篩選是 電視微調器 篩選準則，其會公開 IAMTVTuner 介面。 若要讓此功能可供應用程式使用，您必須將電視微調器篩選器連線到擷取篩選器。

ICaptureGraphBuilder2介面提供將 WDM 篩選新增至圖表的最簡單方式。 在建置圖形時，請呼叫 FindInterface 或 RenderStream。 其中一種方法會自動找出必要的 WDM 篩選準則，並將其連線到擷取篩選器。 本節的其餘部分說明如何手動新增 WDM 篩選器。 不過，請注意，建議的方法只是呼叫其中一個 ICaptureGraphBuilder2 方法。

WDM 篩選器上的針腳支援一或多個媒體。 媒體會定義通訊方法，例如匯流排。 您必須連接支援相同媒體的針腳。 REGPINMEDIUM結構相當於用於核心串流驅動程式的 KSPIN_MEDIUM結構，會在 DirectShow 中定義媒體。 REGPINMEDIUM結構的clsMedium成員會指定媒體的類別識別碼 (CLSID) 。 若要擷取針腳的媒體，請呼叫 IKsPin：：KsQueryMediums 方法。 這個方法會傳回記憶體區塊的指標，其中包含 KSMULTIPLE_ITEM 結構，後面接著零個或多個 REGPINMEDIUM 結構。 每個 REGPINMEDIUM 結構都會識別針腳支援的媒體。

如果媒體的 CLSID 為 GUID_Null 或 KSMEDIUMSETID_Standard，請勿連接針腳。 這些是預設值，表示針腳不支援媒體。

此外，除非篩選只需要該針腳的一個連線實例，否則請勿連接針腳。 否則，您的應用程式可能會嘗試連接不應該有連線的各種針腳，這可能會導致程式停止回應。 若要找出必要的實例數目，請擷取KSPROPERTY_PIN_NECESSARYINSTANCES屬性集，如下列程式碼範例所示。 (為了簡潔起見，本範例不會測試任何傳回碼或釋放任何介面。您的應用程式應該同時執行，當然.) 

// Obtain the pin factory identifier.
IKsPinFactory *pPinFactory;
hr = pPin->QueryInterface(IID_IKsPinFactory, (void **)&pPinFactory);

ULONG ulFactoryId;
hr = pPinFactory->KsPinFactory(&ulFactoryId);

// Get the "instance" property from the filter.
IKsControl *pKsControl;
hr = pFilter->QueryInterface(IID_IKsControl, (void **)&pKsControl);

KSP_PIN ksPin;
ksPin.Property.Set = KSPROPSETID_Pin;
ksPin.Property.Id = KSPROPERTY_PIN_NECESSARYINSTANCES;
ksPin.Property.Flags = KSPROPERTY_TYPE_GET;
ksPin.PinId = ulFactoryId;
ksPin.Reserved = 0; 

KSPROPERTY ksProp;
ULONG ulInstances, bytes;
pKsControl->KsProperty((PKSPROPERTY)&ksPin, sizeof(ksPin), 
    &ulInstances, sizeof(ULONG), &bytes);

if (hr == S_OK && bytes == sizeof(ULONG)) 
{
    if (ulInstances == 1) 
    {
        // Filter requires one instance of this pin.
        // This pin is OK.
    } 
}

下列虛擬程式碼是一個非常簡短的大綱，顯示如何尋找及連接 WDM 篩選準則。 它省略許多詳細資料，只是為了顯示應用程式需要採取的一般步驟。

Add supporting filters:
{
    foreach input pin:
        skip if (pin is connected)
    
        Get pin medium
        skip if (medium is GUID_NULL or KSMEDIUMSETID_Standard)
    
        Query filter for KSPROPERTY_PIN_NECESSARYINSTANCES property
        skip if (necessary instances != 1)

        Match an existing pin || Find a matching filter
}    

Match an existing pin:
{
    foreach filter in the graph
        foreach unconnected pin
            Get pin medium
            if (mediums match)
                connect the pins    
}

Find a matching filter:
{    
    Query the filter graph manager for IFilterMapper2.
    Find a filter with an output pin that matches the medium.
    Add the filter to the graph.
    Connect the pins.
    Add supporting filters. (Recursive call.)
}

進階擷取主題