フィルタートポロジの公開

[アーティクル]
04/01/2024

ミニポートドライバーでは、ピン、ノード、接続の観点から KS フィルターの内部トポロジが記述されています。このトポロジは、フィルターを介したデータフローパスを指定し、プロパティ要求の論理ターゲット (ピンとノード) も定義します。フィルター内トポロジは、フィルターの基になるハードウェアデバイスの内部構造を論理的に表したものです。ミニポートドライバーは、ピン、ノード、および接続記述子の静的配列を持つこのトポロジを記述します。

ピンは、PCPIN_DESCRIPTOR 構造体の静的配列で指定されます。各ピンには、配列内での序数となっている ID があります。
ノードは、PCNODE_DESCRIPTOR 構造体の静的配列で指定されます。各ノードには、配列内での序数となっている ID があります。
接続 (ピン間、ピンとノード間、またはノード間) は、PCCONNECTION_DESCRIPTOR 構造体の静的配列で指定されます。

ミニポートドライバーは、IMiniport::GetDescription メソッドから出力する PCFILTER_DESCRIPTOR 構造体でこれら 3 つの配列を公開します。

例

次のコード例では、1 つの入力ピンと 1 つの出力ピンを持つ単純な KS フィルターの内部トポロジを指定しています。フィルターには、音量レベルのコントロールである 1 つのノードが含まれています。

#define KSPIN_WAVEOUT_SRC  0
#define KSPIN_SPEAKERS_DST  1

PCPIN_DESCRIPTOR 
MiniportPins[] =
{
    {   // Pin 0 -- KSPIN_WAVEOUT_SRC
        0,0,0,  // InstanceCount
        NULL,   // AutomationTable
        {       // KsPinDescriptor
            0,                                          // InterfacesCount
            NULL,                                       // Interfaces
            0,                                          // MediumsCount
            NULL,                                       // Mediums
            SIZEOF_ARRAY(PinDataRangePointersBridge),   // DataRangesCount
            PinDataRangePointersBridge,                 // DataRanges
            KSPIN_DATAFLOW_IN,                          // DataFlow
            KSPIN_COMMUNICATION_NONE,                   // Communication
            &KSNODETYPE_LEGACY_AUDIO_CONNECTOR,         // Category
            NULL,                                       // Name
            0                                           // Reserved
        }
    },
    {   // Pin 1 -- KSPIN_SPEAKERS_DST
        0,0,0,  // InstanceCount
        NULL,   // AutomationTable
        {       // KsPinDescriptor
            0,                                          // InterfacesCount
            NULL,                                       // Interfaces
            0,                                          // MediumsCount
            NULL,                                       // Mediums
            SIZEOF_ARRAY(PinDataRangePointersBridge),   // DataRangesCount
            PinDataRangePointersBridge,                 // DataRanges
            KSPIN_DATAFLOW_OUT,                         // DataFlow
            KSPIN_COMMUNICATION_NONE,                   // Communication
            &KSNODETYPE_SPEAKER,                        // Category
            &KSAUDFNAME_VOLUME_CONTROL,                 // Name (This name shows up as the 
                                                        // playback panel name in SndVol32)
            0                                           // Reserved
        }
    }
};

#define KSNODE_WAVEOUT_VOLUME  0

PCNODE_DESCRIPTOR TopologyNodes[] =
{
    {   // KSNODE_WAVEOUT_VOLUME
        0,                      // Flags
        &AutomationVolume,      // AutomationTable
        &KSNODETYPE_VOLUME,     // Type
        &KSAUDFNAME_WAVE_VOLUME // Name
    }
};

PCCONNECTION_DESCRIPTOR MiniportConnections[] =
{ //FromNode---------------FromPin------------ToNode-----------------ToPin
  { PCFILTER_NODE,         KSPIN_WAVEOUT_SRC, KSNODE_WAVEOUT_VOLUME, 1 },
  { KSNODE_WAVEOUT_VOLUME, 0,                 PCFILTER_NODE,         KSPIN_SPEAKERS_DST }
};

次の図は、前のコード例で記述されているフィルターのトポロジを示しています。

Diagram illustrating a simple filter topology with one input pin, one output pin, and a volume-level control node.

このフィルターは、PortCls システムドライバーが作成する IPortTopology オブジェクトに IMiniportTopology オブジェクトをバインドすることによって、アダプタードライバーが形成するトポロジフィルターの簡単な例です。フィルターの入力 (シンク) ピンと出力 (ソース) ピンの名前は、KSPIN_WAVEOUT_SRC と KSPIN_SPEAKERS_DST です。どちらのピンもアナログ信号を伝送します。 ミキサー API は、これらのピンへの接続をそれぞれソースミキサーラインと宛先ミキサーライン (MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT および MIXERLINE_COMPONENTTYPE_DST_SPEAKERS) として公開します。

次の表は、KS ピンとミキサーラインのマッピングを説明する際に混乱が生じる可能性のあるものを示しています。

ピン名	ミキサー API の用語	KS フィルターの用語
KSPIN_WAVEOUT_SRC	ソースミキサーライン	シンクピン
KSPIN_SPEAKERS_DST	宛先ミキサーライン	ソースピン

KSPIN_WAVEOUT_SRC はソースミキサーラインであり、KSPIN_SPEAKERS_DST はソースピンであることに注意してください。詳細については、「カーネルストリーミングトポロジからオーディオミキサー API への変換」の KS とミキサーラインの用語の説明を参照してください。

また、"KSPIN_WAVEOUT_SRC" という名前に "WAVEOUT" が含まれているのは、ピンに Wave 形式のデジタルデータが含まれているためではなく、WaveCyclic 型または WavePci 型のフィルターであるウェーブフィルターによって生成されるアナログ信号が含まれているためであることに注意してください。ウェーブフィルターは、ウェーブストリームをアナログ信号に変換するオーディオアダプターのハードウェアの部分を表します。ピン KSPIN_SPEAKERS_DST は、一連のスピーカーを駆動するアナログ信号を出力します。

フィルターには、ミキサー API が音量コントロール (MIXERCONTROL_CONTROLTYPE_VOLUME) として表す単一のノード (KSNODE_WAVEOUT_VOLUME) が含まれています。音量コントロールの KS ノードタイプは、KSNODETYPE_VOLUME です。このタイプのすべてのノードは、フィルターのクライアントがボリュームレベルの制御に使用する KSPROPERTY_AUDIO_VOLUMELEVEL プロパティをサポートします。

ボリュームノードには、 0 と 1 の番号が付いている 2 つの "論理" ピンがあります。 MiniportConnections 配列で指定された 2 つの接続は、図の中で、データフローの方向を指す破線の矢印で表されています。各接続は、配列内の 2 つの要素のいずれかによって記述されます。

KSPIN_WAVEOUT_SRC ピンと KSPIN_SPEAKERS_DST ピンは両方ともブリッジピンです。これは、アダプターのハードワイヤー接続を表していることを意味しています。前のコード例では、MiniportPins 配列の 2 つのピン記述子は、どちらもそれぞれの IRP フローの方向を KSPIN_COMMUNICATION_NONE として指定しています。これは、ブリッジピンが IRP を送も受信しないため、適切です。 2 つのピン記述子は、次のように定義されている PinDataRangePointersBridge 配列も参照します。

static KSDATARANGE PinDataRangesBridge[] =
{
   {
      sizeof(KSDATARANGE),
      0, 0, 0,
      STATICGUIDOF(KSDATAFORMAT_TYPE_AUDIO),
      STATICGUIDOF(KSDATAFORMAT_SUBTYPE_ANALOG),
      STATICGUIDOF(KSDATAFORMAT_SPECIFIER_NONE)
   }
};

static PKSDATARANGE PinDataRangePointersBridge[] =
{
    &PinDataRangesBridge[0]
};

PinDataRangePointersBridge 配列は、アナログオーディオ信号を伝送するブリッジピンのデータ範囲を定義します。詳細については、「オーディオフィルターグラフ」のブリッジピンの説明を参照してください。

より複雑なトポロジの例については、「トポロジフィルター」を参照してください。

次の方法で共有

フィルタートポロジの公開

例

フィードバック

その他のリソース

次の方法で共有

フィルター トポロジの公開

例

フィードバック

その他のリソース

フィルタートポロジの公開