Filtres de pilote de classe WDM

[La fonctionnalité associée à cette page, DirectShow, est une fonctionnalité héritée. Il a été remplacé par MediaPlayer, IMFMediaEngine et Audio/Video Capture in Media Foundation. Ces fonctionnalités ont été optimisées pour Windows 10 et Windows 11. Microsoft recommande vivement que le nouveau code utilise MediaPlayer, IMFMediaEngine et Audio/Video Capture dans Media Foundation au lieu de DirectShow, si possible. Microsoft suggère que le code existant qui utilise les API héritées soit réécrit pour utiliser les nouvelles API si possible.]

Si un périphérique de capture utilise un pilote WDM (Windows Driver Model), le graphique peut nécessiter certains filtres amont du filtre de capture. Ces filtres sont appelés filtres de pilotes de classe de flux ou filtres WDM. Ils prennent en charge les fonctionnalités supplémentaires fournies par le matériel. Par exemple, un tuner TV carte a des fonctions pour définir le canal. Le filtre correspondant est le filtre TV Tuner , qui expose l’interface IAMTVTuner . Pour mettre cette fonctionnalité à la disposition de l’application, vous devez connecter le filtre TV Tuner au filtre de capture.

L’interface ICaptureGraphBuilder2 offre le moyen le plus simple d’ajouter des filtres WDM au graphique. À un moment donné, lors de la création du graphe, appelez FindInterface ou RenderStream. L’une de ces méthodes recherche automatiquement les filtres WDM nécessaires et les connecte au filtre de capture. Le reste de cette section explique comment ajouter manuellement des filtres WDM. Toutefois, n’oubliez pas que l’approche recommandée consiste simplement à appeler l’une de ces méthodes ICaptureGraphBuilder2 .

Les broches d’un filtre WDM prennent en charge un ou plusieurs supports. Un support définit une méthode de communication, telle qu’un bus. Vous devez connecter des broches qui prennent en charge le même support. La structure REGPINMEDIUM , qui est équivalente à la structure KSPIN_MEDIUM utilisée pour les pilotes de diffusion en continu du noyau, définit un support dans DirectShow. Le membre clsMedium de la structure REGPINMEDIUM spécifie l’identificateur de classe (CLSID) pour le milieu. Pour récupérer le support d’une broche, appelez la méthode IKsPin::KsQueryMediums . Cette méthode retourne un pointeur vers un bloc de mémoire qui contient une structure KSMULTIPLE_ITEM , suivie de zéro ou plusieurs structures REGPINMEDIUM . Chaque structure REGPINMEDIUM identifie un support pris en charge par la broche.

Ne connectez pas une broche si le support a un CLSID de GUID_NULL ou KSMEDIUMSETID_Standard. Il s’agit de valeurs par défaut indiquant que l’épingle ne prend pas en charge les supports.

En outre, ne connectez pas une broche, sauf si le filtre nécessite exactement une instance connectée de cette broche. Sinon, votre application peut essayer de connecter différentes broches qui ne doivent pas avoir de connexions, ce qui peut entraîner l’arrêt de la réponse du programme. Pour connaître le nombre d’instances requises, récupérez le jeu de propriétés KSPROPERTY_PIN_NECESSARYINSTANCES, comme indiqué dans l’exemple de code suivant. (Par souci de concision, cet exemple ne teste aucun code de retour ni ne libère d’interfaces. Votre application doit faire les deux, bien sûr.)

// Obtain the pin factory identifier.
IKsPinFactory *pPinFactory;
hr = pPin->QueryInterface(IID_IKsPinFactory, (void **)&pPinFactory);

ULONG ulFactoryId;
hr = pPinFactory->KsPinFactory(&ulFactoryId);

// Get the "instance" property from the filter.
IKsControl *pKsControl;
hr = pFilter->QueryInterface(IID_IKsControl, (void **)&pKsControl);

KSP_PIN ksPin;
ksPin.Property.Set = KSPROPSETID_Pin;
ksPin.Property.Id = KSPROPERTY_PIN_NECESSARYINSTANCES;
ksPin.Property.Flags = KSPROPERTY_TYPE_GET;
ksPin.PinId = ulFactoryId;
ksPin.Reserved = 0; 

KSPROPERTY ksProp;
ULONG ulInstances, bytes;
pKsControl->KsProperty((PKSPROPERTY)&ksPin, sizeof(ksPin), 
    &ulInstances, sizeof(ULONG), &bytes);

if (hr == S_OK && bytes == sizeof(ULONG)) 
{
    if (ulInstances == 1) 
    {
        // Filter requires one instance of this pin.
        // This pin is OK.
    } 
}

Le pseudocode suivant est un aperçu extrêmement bref montrant comment rechercher et connecter les filtres WDM. Il omet de nombreux détails et n’est destiné qu’à afficher les étapes générales que votre application doit suivre.

Add supporting filters:
{
    foreach input pin:
        skip if (pin is connected)
    
        Get pin medium
        skip if (medium is GUID_NULL or KSMEDIUMSETID_Standard)
    
        Query filter for KSPROPERTY_PIN_NECESSARYINSTANCES property
        skip if (necessary instances != 1)

        Match an existing pin || Find a matching filter
}    

Match an existing pin:
{
    foreach filter in the graph
        foreach unconnected pin
            Get pin medium
            if (mediums match)
                connect the pins    
}

Find a matching filter:
{    
    Query the filter graph manager for IFilterMapper2.
    Find a filter with an output pin that matches the medium.
    Add the filter to the graph.
    Connect the pins.
    Add supporting filters. (Recursive call.)
}

Rubriques connexes

Rubriques de capture avancée