Expondo topologia de filtro

Um driver de miniporto descreve a topologia interna de um filtro KS em termos de pinos, nós e conexões. Essa topologia especifica os caminhos de fluxo de dados por meio do filtro e também define os destinos lógicos – pinos e nós – para solicitações de propriedade. A topologia intrafiltro é uma representação lógica da estrutura interna do dispositivo de hardware que está por trás do filtro. O driver de miniporto descreve essa topologia com matrizes estáticas de descritores de pin, nó e conexão.

• Os pinos são especificados em uma matriz estática de estruturas de PCPIN_DESCRIPTOR . Cada pin tem uma ID que é ordinal na matriz.

• Os nós são especificados em uma matriz estática de estruturas de PCNODE_DESCRIPTOR . Cada nó tem uma ID que é seu ordinal na matriz.

• As conexões (fixar para fixar, fixar para nó ou nó a nó) são especificadas em uma matriz estática de estruturas de PCCONNECTION_DESCRIPTOR .

O driver de miniporto expõe essas três matrizes na estrutura PCFILTER_DESCRIPTOR que ele gera de seu método IMiniport::GetDescription .

Exemplo

O exemplo de código a seguir especifica a topologia interna de um filtro KS simples que tem um pino de entrada e um pino de saída. O filtro contém um único nó, que é um controle de nível de 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 }
};

A figura a seguir mostra a topologia do filtro descrita pelo código de exemplo anterior.

Esse filtro é um exemplo simples de um filtro de topologia, que um driver de adaptador forma associando seu objeto IMiniportTopology a um objeto IPortTopology que o driver do sistema PortCls cria. Os pinos de entrada (coletor) e saída (origem) do filtro são nomeados KSPIN_WAVEOUT_SRC e KSPIN_SPEAKERS_DST. Ambos os pinos carregam sinais analógicos. A API do mixer expõe as conexões a esses pinos como linhas de mixer de origem e destino (MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT e MIXERLINE_COMPONENTTYPE_DST_SPEAKERS), respectivamente.

A tabela a seguir ilustra uma possível fonte de confusão ao discutir o mapeamento de pinos KS para linhas de mixer.

Nome do pino	Terminologia da API do mixer	Terminologia do filtro KS
KSPIN_WAVEOUT_SRC	Linha do mixer de origem	Pino do coletor
KSPIN_SPEAKERS_DST	Linha do mixer de destino	Pino de origem

Observe que KSPIN_WAVEOUT_SRC é uma linha de mixer de origem e KSPIN_SPEAKERS_DST é um pino de origem. Para obter mais informações, consulte a discussão de KS e terminologia de linha de mixagem na Tradução de Topologia de Streaming de Kernel para API do Mixer de Áudio.

Observe também que o nome "KSPIN_WAVEOUT_SRC" contém "WAVEOUT" não porque o pino carrega dados digitais formatados em onda, mas porque ele carrega o sinal analógico gerado por um filtro de onda, que é um filtro do tipo WaveCyclic ou WavePci. O filtro de onda representa a parte do hardware do adaptador de áudio que converte um fluxo de onda em um sinal analógico. Fixar KSPIN_SPEAKERS_DST gera um sinal analógico que conduz um conjunto de alto-falantes.

O filtro contém um único nó, KSNODE_WAVEOUT_VOLUME, que a API do mixer representa como um controle de volume (MIXERCONTROL_CONTROLTYPE_VOLUME). O tipo de nó KS para o controle de volume é KSNODETYPE_VOLUME. Todos os nós desse tipo dão suporte à propriedade KSPROPERTY_AUDIO_VOLUMELEVEL , que um cliente do filtro usa para controlar o nível de volume.

O nó de volume tem dois pinos "lógicos", que são numerados como 0 e 1. As duas conexões especificadas pela matriz MiniportConnections são representadas na figura por setas tracejadas que apontam na direção do fluxo de dados. Cada conexão é descrita por um dos dois elementos na matriz.

Os pinos KSPIN_WAVEOUT_SRC e KSPIN_SPEAKERS_DST são ambos pinos de ponte, o que significa que eles representam conexões com fio no adaptador. No código de exemplo anterior, os dois descritores de pino na matriz MiniportPins especificam sua direção de fluxo IRP como KSPIN_COMMUNICATION_NONE, o que é apropriado porque os pinos de ponte não enviam nem recebem IRPs. Os dois descritores de pin também se referem a uma matriz PinDataRangePointersBridge, que é definida da seguinte maneira:

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

A matriz PinDataRangePointersBridge define o intervalo de dados para um pino de ponte que carrega um sinal de áudio analógico. Para obter mais informações, consulte a discussão de pinos de ponte em Grafos de Filtro de Áudio.

Para obter um exemplo de uma topologia mais complexa, consulte Filtros de topologia.