Partager via

Filtres de pilotes de classe WDM

[La fonctionnalité associée à cette page, DirectShow, est une fonctionnalité héritée. Il a été remplacé par MediaPlayer, IMFMediaEngineet audio/vidéo capture dans 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 capture audio/vidéo dans Media Foundation au lieu de directShow, lorsque cela est 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 en amont à partir du filtre de capture. Ces filtres sont appelés filtres de pilotes de classe de flux ou filtres WDM. Ils prennent en charge des fonctionnalités supplémentaires fournies par le matériel. Par exemple, une carte de réglage tv a des fonctions pour définir le canal. Le filtre correspondant est le filtre tv Tuner, qui expose l’interface IAMTVTuner. Pour rendre cette fonctionnalité disponible pour 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 graphique, appelez FindInterface ou RenderStream. L’une de ces méthodes localisera automatiquement les filtres WDM nécessaires et les connectera au filtre de capture. Le reste de cette section décrit comment ajouter manuellement des filtres WDM. Toutefois, sachez 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 structureREGPINMEDIUM, qui équivaut à la structure KSPIN_MEDIUM utilisée pour les pilotes de streaming de noyau, définit un support dans DirectShow. Le membre clsMedium de la structure REGPINMEDIUM spécifie l’identificateur de classe (CLSID) pour le support. 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 plus structures REGPINMEDIUM. Chaque REGPINMEDIUM structure identifie un support de broche.

Ne connectez pas une broche si le support a un CLSID de GUID_NULL ou de 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 du programme. Pour connaître le nombre d’instances requises, récupérez le jeu de propriétés KSPROPERTY_PIN_NECESSARYINSTANCES, comme illustré dans l’exemple de code suivant. (Par souci de concision, cet exemple ne teste aucun code de retour ni ne libère aucune interface. 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 bref aperçu montrant comment rechercher et connecter les filtres WDM. Il omet de nombreux détails et est destiné uniquement à 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 de capture avancée