Exposición de la topología de filtro

Un controlador de minipuerto describe la topología interna de un filtro KS en términos de patillas, nodos y conexiones. Esta topología especifica las rutas de acceso de flujo de datos a través del filtro y también define las solicitudes de propiedades logical targets--pins y nodes--for. La topología dentro del filtro es una representación lógica de la estructura interna del dispositivo de hardware que subyace al filtro. El controlador de minipuerto describe esta topología con matrices estáticas de descriptores de anclaje, nodo y conexión.

• Los pines se especifican en una matriz estática de estructuras de PCPIN_DESCRIPTOR . Cada pin tiene un identificador que es su ordinal en la matriz.

• Los nodos se especifican en una matriz estática de estructuras de PCNODE_DESCRIPTOR . Cada nodo tiene un identificador que es su ordinal en la matriz.

• Las conexiones (pin-to-pin, pin-to-node o node-to-node) se especifican en una matriz estática de estructuras de PCCONNECTION_DESCRIPTOR .

El controlador de minipuerto expone estas tres matrices en la estructura PCFILTER_DESCRIPTOR que genera desde su método IMiniport::GetDescription .

Ejemplo

En el ejemplo de código siguiente se especifica la topología interna de un filtro KS simple que tiene un pin de entrada y un pin de salida. El filtro contiene un único nodo, que es un control de nivel de volumen.

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

En la ilustración siguiente se muestra la topología del filtro descrito por el código de ejemplo anterior.

Este filtro es un ejemplo sencillo de un filtro de topología, que un controlador de adaptador forma enlazando su objeto IMiniportTopology a un objeto IPortTopology que crea el controlador del sistema PortCls. Los pines de entrada (receptor) y salida (origen) del filtro se denominan KSPIN_WAVEOUT_SRC y KSPIN_SPEAKERS_DST. Ambos patillas llevan señales analógicas. La API de mezclador expone las conexiones a estas patillas como líneas mezcladoras de origen y destino (MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT y MIXERLINE_COMPONENTTYPE_DST_SPEAKERS), respectivamente.

En la tabla siguiente se muestra una posible fuente de confusión al analizar la asignación de patillas KS a líneas mezcladoras.

Nombre del pin	Terminología de la API de mezclador	Terminología del filtro KS
KSPIN_WAVEOUT_SRC	Línea mezcladora de origen	Anclaje receptor
KSPIN_SPEAKERS_DST	Línea mezcladora de destino	Pin de origen

Tenga en cuenta que KSPIN_WAVEOUT_SRC es una línea mezcladora de origen y KSPIN_SPEAKERS_DST es un pin de origen. Para obtener más información, consulte la explicación de la terminología de KS y de la línea mezcladora en Topología de streaming de kernel a traducción de API de mezclador de audio.

Tenga en cuenta también que el nombre "KSPIN_WAVEOUT_SRC" contiene "WAVEOUT" no porque el pin lleva datos digitales con formato de onda, sino porque lleva la señal analógica generada por un filtro de onda, que es un filtro de tipo WaveCíclica o WavePci. El filtro de onda representa la parte del hardware del adaptador de audio que convierte una secuencia de onda en una señal analógica. Anclar KSPIN_SPEAKERS_DST genera una señal analógica que controla un conjunto de altavoces.

El filtro contiene un solo nodo, KSNODE_WAVEOUT_VOLUME, que la API mezcladora representa como un control de volumen (MIXERCONTROL_CONTROLTYPE_VOLUME). El tipo de nodo KS para el control de volumen es KSNODETYPE_VOLUME. Todos los nodos de este tipo admiten la propiedad KSPROPERTY_AUDIO_VOLUMELEVEL , que un cliente del filtro usa para controlar el nivel de volumen.

El nodo de volumen tiene dos pines "lógicos", que se numeran 0 y 1. Las dos conexiones especificadas por la matriz MiniportConnections se representan en la figura mediante flechas discontinuas que apuntan en la dirección del flujo de datos. Cada conexión se describe mediante uno de los dos elementos de la matriz.

Las KSPIN_WAVEOUT_SRC y KSPIN_SPEAKERS_DST patillas son patillas de puente, lo que significa que representan conexiones cableadas en el adaptador. En el código de ejemplo anterior, los dos descriptores de patillas de la matriz MiniportPins especifican su dirección de flujo IRP como KSPIN_COMMUNICATION_NONE, que es adecuado porque los patillas de puente no envían ni reciben IRP. Los dos descriptores de pin también hacen referencia a una matriz PinDataRangePointersBridge, que se define de la siguiente manera:

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 matriz PinDataRangePointersBridge define el intervalo de datos de un pin de puente que lleva una señal de audio analógica. Para obtener más información, consulte la explicación de los pines de puente en gráficos de filtros de audio.

Para obtener un ejemplo de una topología más compleja, consulte Filtros de topología.