Expondo topologia de filtro

Um driver de miniporta 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 através 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 subjacente ao filtro. O driver de miniporta descreve essa topologia com matrizes estáticas de descritores de pinos, nós e conexões.

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

• Os nós são especificados em uma matriz estática de estruturas PCNODE_DESCRIPTOR. Cada nó tem uma identificação que corresponde à sua posição na matriz.

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

O driver de miniporta expõe estas três matrizes na estrutura de PCFILTER_DESCRIPTOR que ele gera a partir do 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 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.

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

A tabela a seguir ilustra uma fonte potencial de confusão ao discutir o mapeamento de pinos KS para linhas misturadoras.

Observe que KSPIN_WAVEOUT_SRC é uma linha de mistura de fonte e KSPIN_SPEAKERS_DST é um pino de saída. Para obter mais informações, consulte a discussão sobre KS e a terminologia de linha de mixagem em Tradução da Topologia de Kernel Streaming para API de Misturador 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 que é 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. Pin KSPIN_SPEAKERS_DST emite um sinal analógico que aciona um conjunto de alto-falantes.

O filtro contém um único nó, KSNODE_WAVEOUT_VOLUME, que a API do misturador representa como um controlo de volume (MIXERCONTROL_CONTROLTYPE_VOLUME). O tipo de nó KS para o controle de volume é KSNODETYPE_VOLUME. Todos os nós desse tipo suportam a 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 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 pinos de ponte, o que significa que representam conexões fixas no adaptador. No código de exemplo anterior, os dois descritores de pinos 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 pinos também se referem a uma matriz PinDataRangePointersBridge, que é definida da seguinte forma:

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 sobre pinos de ligação em Gráficos de filtro de áudio.

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