Esposizione della topologia filtro

Un driver miniport descrive la topologia interna di un filtro KS in termini di pin, nodi e connessioni. Questa topologia specifica i percorsi del flusso di dati tramite il filtro e definisce anche le destinazioni logiche e i nodi per le richieste di proprietà. La topologia intra-filtro è una rappresentazione logica della struttura interna del dispositivo hardware che sottolizza il filtro. Il driver miniport descrive questa topologia con matrici statiche di descrittori di pin, nodo e descrittori di connessione.

• I pin vengono specificati in una matrice statica di strutture PCPIN_DESCRIPTOR . Ogni pin ha un ID che è il relativo ordinale nella matrice.

• I nodi vengono specificati in una matrice statica di strutture PCNODE_DESCRIPTOR . Ogni nodo ha un ID che è il relativo ordinale nella matrice.

• Le connessioni (pin-to-pin, pin-to-node o node-to-node) vengono specificate in una matrice statica di strutture PCCONNECTION_DESCRIPTOR .

Il driver miniport espone queste tre matrici nella struttura PCFILTER_DESCRIPTOR che restituisce dal relativo metodo IMiniport::GetDescription .

Esempio

Nell'esempio di codice seguente viene specificata la topologia interna di un semplice filtro KS con un pin di input e un pin di output. Il filtro contiene un singolo nodo, ovvero un controllo a livello di volume.

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

Nella figura seguente viene illustrata la topologia del filtro descritto dal codice di esempio precedente.

Questo filtro è un semplice esempio di filtro topologia, che un driver dell'adapter forma associando l'oggetto IMiniportTo topologia a un oggetto IPortTopology creato dal driver di sistema PortCls. I pin di input (sink) e output (origine) del filtro sono denominati KSPIN_WAVEOUT_SRC e KSPIN_SPEAKERS_DST. Entrambi i pin portano segnali analogici. L'API mixer espone rispettivamente le connessioni a questi pin come linee di mixer di origine e destinazione (MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT e MIXERLINE_COMPONENTTYPE_DST_SPEAKERS).

La tabella seguente illustra una potenziale fonte di confusione durante la discussione del mapping dei pin KS alle linee di mixer.

Si noti che KSPIN_WAVEOUT_SRC è una linea di mixer di origine e KSPIN_SPEAKERS_DST è un pin di origine. Per altre informazioni, vedere la discussione sulla terminologia della riga KS e del mixer nella topologia di streaming del kernel alla traduzione API Audio Mixer.

Si noti anche che il nome "KSPIN_WAVEOUT_SRC" contiene "WAVEOUT" non perché il pin trasporta dati digitali formattati a onda, ma perché trasporta il segnale analogico generato da un filtro di onda, ovvero un filtro di tipo WaveCyclic o WavePci. Il filtro onda rappresenta la parte dell'hardware dell'adattatore audio che converte un flusso di onda in un segnale analogico. Pin KSPIN_SPEAKERS_DST restituisce un segnale analogico che determina un set di altoparlanti.

Il filtro contiene un singolo nodo, KSNODE_WAVEOUT_VOLUME, che l'API mixer rappresenta come controllo del volume (MIXERCONTROL_CONTROLTYPE_VOLUME). Il tipo di nodo KS per il controllo del volume è KSNODETYPE_VOLUME. Tutti i nodi di questo tipo supportano la proprietà KSPROPERTY_AUDIO_VOLUMELEVEL , che un client del filtro usa per controllare il livello del volume.

Il nodo del volume ha due pin "logici", numerati 0 e 1. Le due connessioni specificate dalla matrice MiniportConnections sono rappresentate nella figura con frecce tratteggiate che puntano nella direzione del flusso di dati. Ogni connessione viene descritta da uno dei due elementi della matrice.

I pin KSPIN_WAVEOUT_SRC e KSPIN_SPEAKERS_DST sono entrambi pin bridge, che significa che rappresentano connessioni hardwired nell'adattatore. Nel codice di esempio precedente, i due descrittori di pin nella matrice MiniportPins specificano entrambe la direzione del flusso IRP come KSPIN_COMMUNICATION_NONE, che è appropriata perché i pin del bridge non inviano né ricevono ip di integrazione. I due descrittori pin fanno riferimento anche a una matrice PinDataRangePointersBridge, definita come indicato di seguito:

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

La matrice PinDataRangePointersBridge definisce l'intervallo di dati per un pin bridge che trasporta un segnale audio analogico. Per altre informazioni, vedere la discussione sui pin bridge in Grafici di filtro audio.

Per un esempio di topologia più complessa, vedere Filtri topologia.