Verfügbarmachen der Filtertopologie

Ein Miniporttreiber beschreibt die interne Topologie eines KS-Filters in Bezug auf Pins, Knoten und Verbindungen. Diese Topologie gibt die Datenflusspfade durch den Filter an und definiert auch die logischen Ziele (Pins und Knoten) für Eigenschaftenanforderungen. Die Filterinterntopologie ist eine logische Darstellung der internen Struktur des Hardwaregeräts, das dem Filter zugrunde liegt. Der Miniporttreiber beschreibt diese Topologie mit statischen Arrays von Pin-, Knoten- und Verbindungsdeskriptoren.

• Pins werden in einem statischen Array von PCPIN_DESCRIPTOR-Strukturen angegeben. Jeder Pin hat eine ID, die seine Ordnungszahl im Array darstellt.

• Knoten werden in einem statischen Array von PCNODE_DESCRIPTOR-Strukturen angegeben. Jeder Knoten verfügt über eine ID, die seine Ordnungszahl im Array darstellt.

• Verbindungen (pin-to-pin, pin-to-node oder node-to-node) werden in einem statischen Array von PCCONNECTION_DESCRIPTOR-Strukturen angegeben.

Der Miniporttreiber macht diese drei Arrays in der PCFILTER_DESCRIPTOR-Struktur verfügbar, die er von seiner IMiniport::GetDescription-Methode ausgibt.

Beispiel

Im folgenden Codebeispiel wird die interne Topologie eines einfachen KS-Filters angegeben, der über einen Eingabe- und einen Ausgabepin verfügt. Der Filter enthält einen einzelnen Knoten, bei dem es sich um ein Steuerelement auf Volumeebene handelt.

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

Die folgende Abbildung zeigt die Topologie des Filters, die im vorherigen Beispielcode beschrieben wird.

Dieser Filter ist ein einfaches Beispiel für einen Topologiefilter, den ein Adaptertreiber bildet, indem er sein IMiniportTopology-Objekt an ein IPortTopology-Objekt bindet, das vom PortCls-Systemtreiber erstellt wird. Die Eingabe-Pins (Senke) und Ausgabe (Quelle) des Filters werden KSPIN_WAVEOUT_SRC und KSPIN_SPEAKERS_DST genannt. Beide Pins tragen analoge Signale. Die Mixer-API macht die Verbindungen mit diesen Pins als Quell- und Zielmixerzeilen (MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT und MIXERLINE_COMPONENTTYPE_DST_SPEAKERS) verfügbar.

Die folgende Tabelle veranschaulicht ein potenzielles Verwechslungspotential, wenn die Zuordnung von KS-Pins zu Mischerlinien erläutert wird.

Pinname	Terminologie der Mixer-API	KS-Filterterminologie
KSPIN_WAVEOUT_SRC	Quellmixerlinie	Senkennadel
KSPIN_SPEAKERS_DST	Zielmixerlinie	Quellnadel

Beachten Sie, dass KSPIN_WAVEOUT_SRC eine Quellmixerlinie und KSPIN_SPEAKERS_DST ein Quellstecker ist. Weitere Informationen finden Sie in der Erläuterung der KS- und Mixer-Line-Terminologie unter Übersetzung der Kernelstreamingtopologie zu Audiomixer-API.

Beachten Sie auch, dass der Name "KSPIN_WAVEOUT_SRC" "WAVEOUT" enthält, nicht weil der Pin wellenformatierte digitale Daten enthält, sondern weil er das analoge Signal enthält, das von einem Wellenfilter generiert wird, bei dem es sich um einen Filter vom Typ WaveCyclic oder WavePci handelt. Der Wellenfilter stellt den Teil der Hardware des Audioadapters dar, der einen Wellenstrom in ein analoges Signal konvertiert. Anheften KSPIN_SPEAKERS_DST gibt ein analoges Signal aus, das eine Reihe von Lautsprechern antreibt.

Der Filter enthält einen einzelnen Knoten, KSNODE_WAVEOUT_VOLUME, den die Mixer-API als Lautstärkeregelung (MIXERCONTROL_CONTROLTYPE_VOLUME) darstellt. Der KS-Knotentyp für die Lautstärkeregelung ist KSNODETYPE_VOLUME. Alle Knoten dieses Typs unterstützen die eigenschaft KSPROPERTY_AUDIO_VOLUMELEVEL , die ein Client des Filters verwendet, um die Volumeebene zu steuern.

Der Volumeknoten verfügt über zwei "logische" Pins, die 0 und 1 nummeriert sind. Die beiden Verbindungen, die vom MiniportConnections-Array angegeben werden, werden in der Abbildung durch gestrichelte Pfeile dargestellt, die in Richtung des Datenflusses zeigen. Jede Verbindung wird durch eines der beiden Elemente im Array beschrieben.

Die KSPIN_WAVEOUT_SRC und KSPIN_SPEAKERS_DST Pins sind beide Brückenstifte, d. h. sie stellen festverkabelte Verbindungen im Adapter dar. Im vorherigen Beispielcode geben die beiden Stiftdeskriptoren im MiniportPins-Array ihre IRP-Flussrichtung als KSPIN_COMMUNICATION_NONE an, was geeignet ist, da Bridge-Pins weder IRPs senden noch empfangen. Die beiden Pindeskriptoren beziehen sich auch auf ein PinDataRangePointersBridge-Array, das wie folgt definiert ist:

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

Das PinDataRangePointersBridge-Array definiert den Datenbereich für einen Bridge-Pin, der ein analoges Audiosignal überträgt. Weitere Informationen finden Sie in der Diskussion über Bridge-Pins in Audiofiltergraphen.

Ein Beispiel für eine komplexere Topologie finden Sie unter Topologiefilter.