Exposition de la topologie de filtre

Un pilote miniport décrit la topologie interne d’un filtre KS en termes d’épingles, de nœuds et de connexions. Cette topologie spécifie les chemins de flux de données via le filtre et définit également les cibles logiques (épingles et nœuds) pour les demandes de propriété. La topologie intrafiltre est une représentation logique de la structure interne de l’appareil matériel qui sous-tend le filtre. Le pilote miniport décrit cette topologie avec des tableaux statiques de descripteurs d’épingle, de nœud et de connexion.

• Les broches sont spécifiées dans un tableau statique de structures PCPIN_DESCRIPTOR . Chaque broche a un ID qui est son ordinal dans le tableau.

• Les nœuds sont spécifiés dans un tableau statique de structures PCNODE_DESCRIPTOR . Chaque nœud a un ID qui est son ordinal dans le tableau.

• Les connexions (épingle à épingle, pin-à-nœud ou nœud à nœud) sont spécifiées dans un tableau statique de structures PCCONNECTION_DESCRIPTOR .

Le pilote miniport expose ces trois tableaux dans la structure PCFILTER_DESCRIPTOR qu’il génère à partir de sa méthode IMiniport ::GetDescription .

Exemple

L’exemple de code suivant spécifie la topologie interne d’un filtre KS simple qui a une broche d’entrée et une broche de sortie. Le filtre contient un seul nœud, qui est un contrôle au niveau du 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 }
};

La figure suivante montre la topologie du filtre décrit par l’exemple de code précédent.

Ce filtre est un exemple simple de filtre de topologie, qu’un pilote d’adaptateur forme en liant son objet IMiniportTopology à un objet IPortTopology créé par le pilote système PortCls. Les broches d’entrée (récepteur) et de sortie (source) du filtre sont nommées KSPIN_WAVEOUT_SRC et KSPIN_SPEAKERS_DST. Les deux broches transportent des signaux analogiques. L’API mixer expose les connexions à ces broches en tant que lignes de mélangeur source et de destination (MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT et MIXERLINE_COMPONENTTYPE_DST_SPEAKERS), respectivement.

Le tableau suivant illustre une source potentielle de confusion lors de la discussion du mappage des broches KS aux lignes de mélangeur.

Notez que KSPIN_WAVEOUT_SRC est une ligne de mélangeur source et KSPIN_SPEAKERS_DST est une broche source. Pour plus d’informations, consultez la discussion sur la terminologie KS et mixer-line dans Kernel Streaming Topologie to Audio Mixer API Translation.

Notez également que le nom « KSPIN_WAVEOUT_SRC » contient « WAVEOUT » non pas parce que la broche contient des données numériques au format onde, mais parce qu’elle transporte le signal analogique généré par un filtre d’ondes, qui est un filtre de type WaveCyclique ou WavePci. Le filtre d’ondes représente la partie du matériel de l’adaptateur audio qui convertit un flux d’ondes en signal analogique. Épingler KSPIN_SPEAKERS_DST génère un signal analogique qui pilote un ensemble de haut-parleurs.

Le filtre contient un nœud unique, KSNODE_WAVEOUT_VOLUME, que l’API mixer représente en tant que contrôle de volume (MIXERCONTROL_CONTROLTYPE_VOLUME). Le type de nœud KS pour le contrôle de volume est KSNODETYPE_VOLUME. Tous les nœuds de ce type prennent en charge la propriété KSPROPERTY_AUDIO_VOLUMELEVEL , qu’un client du filtre utilise pour contrôler le niveau du volume.

Le nœud de volume a deux broches « logiques », numérotées 0 et 1. Les deux connexions spécifiées par le tableau MiniportConnections sont représentées dans la figure par des flèches en pointillés qui pointent dans la direction du flux de données. Chaque connexion est décrite par l’un des deux éléments du tableau.

Les broches KSPIN_WAVEOUT_SRC et KSPIN_SPEAKERS_DST sont toutes deux des broches de pont, ce qui signifie qu’elles représentent des connexions câblées dans l’adaptateur. Dans l’exemple de code précédent, les deux descripteurs de broches dans le tableau MiniportPins spécifient tous les deux leur direction de flux IRP en tant que KSPIN_COMMUNICATION_NONE, ce qui est approprié, car les broches de pont n’envoient ni ne reçoivent les irps. Les deux descripteurs de broche font également référence à un tableau PinDataRangePointersBridge, qui est défini comme suit :

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

Le tableau PinDataRangePointersBridge définit la plage de données d’une broche de pont qui transporte un signal audio analogique. Pour plus d’informations, consultez la discussion sur les broches de pont dans les graphiques de filtre audio.

Pour obtenir un exemple de topologie plus complexe, consultez Filtres de topologie.