Utilisation du mappeur de filtre

  • Article

[La fonctionnalité associée à cette page, DirectShow, est une fonctionnalité héritée. Il a été remplacé par MediaPlayer, IMFMediaEngine et Audio/Video Capture dans Media Foundation. Ces fonctionnalités ont été optimisées pour Windows 10 et Windows 11. Microsoft recommande vivement au nouveau code d’utiliser MediaPlayer, IMFMediaEngine et La 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.]

Le mappeur de filtre est un objet COM qui énumère les filtres DirectShow en fonction de différents critères de recherche. Le mappeur de filtre peut être moins efficace que l’énumérateur d’appareils système. Par conséquent, si vous avez besoin de filtres d’une catégorie particulière, vous devez utiliser l’énumérateur d’appareil système. Toutefois, si vous avez besoin de localiser un filtre qui prend en charge une certaine combinaison de types de médias, mais qui n’entre pas dans une catégorie claire, vous devrez peut-être utiliser le Mappeur de filtre. (Par exemple, un filtre de convertisseur ou un filtre de décodeur.)

Le mappeur de filtre expose l’interface IFilterMapper2 . Pour rechercher un filtre, appelez la méthode IFilterMapper2::EnumMatchingFilters . Cette méthode prend plusieurs paramètres qui définissent les critères de recherche et retourne un énumérateur pour les filtres correspondants. L’énumérateur prend en charge l’interface IEnumMoniker et fournit un moniker unique pour chaque filtre correspondant.

L’exemple suivant énumère les filtres qui acceptent l’entrée vidéo numérique (DV) et ont au moins une broche de sortie, de n’importe quel type de média. (Le filtre DV Video Decoder correspond à ces critères.)

IFilterMapper2 *pMapper = NULL;
IEnumMoniker *pEnum = NULL;

hr = CoCreateInstance(CLSID_FilterMapper2, 
    NULL, CLSCTX_INPROC, IID_IFilterMapper2, 
    (void **) &pMapper);

if (FAILED(hr))
{
    // Error handling omitted for clarity.
}

GUID arrayInTypes[2];
arrayInTypes[0] = MEDIATYPE_Video;
arrayInTypes[1] = MEDIASUBTYPE_dvsd;

hr = pMapper->EnumMatchingFilters(
        &pEnum,
        0,                  // Reserved.
        TRUE,               // Use exact match?
        MERIT_DO_NOT_USE+1, // Minimum merit.
        TRUE,               // At least one input pin?
        1,                  // Number of major type/subtype pairs for input.
        arrayInTypes,       // Array of major type/subtype pairs for input.
        NULL,               // Input medium.
        NULL,               // Input pin category.
        FALSE,              // Must be a renderer?
        TRUE,               // At least one output pin?
        0,                  // Number of major type/subtype pairs for output.
        NULL,               // Array of major type/subtype pairs for output.
        NULL,               // Output medium.
        NULL);              // Output pin category.

// Enumerate the monikers.
IMoniker *pMoniker;
ULONG cFetched;
while (pEnum->Next(1, &pMoniker, &cFetched) == S_OK)
{
    IPropertyBag *pPropBag = NULL;
    hr = pMoniker->BindToStorage(0, 0, IID_IPropertyBag, 
       (void **)&pPropBag);

    if (SUCCEEDED(hr))
    {
        // To retrieve the friendly name of the filter, do the following:
        VARIANT varName;
        VariantInit(&varName);
        hr = pPropBag->Read(L"FriendlyName", &varName, 0);
        if (SUCCEEDED(hr))
        {
            // Display the name in your UI somehow.
        }
        VariantClear(&varName);

        // To create an instance of the filter, do the following:
        IBaseFilter *pFilter;
        hr = pMoniker->BindToObject(NULL, NULL, IID_IBaseFilter, (void**)&pFilter);
        // Now add the filter to the graph. Remember to release pFilter later.
    
        // Clean up.
        pPropBag->Release();
    }
    pMoniker->Release();
}

// Clean up.
pMapper->Release();
pEnum->Release();

La méthode EnumMatchingFilters a un assez grand nombre de paramètres, qui sont commentés dans l’exemple. Les principaux de cet exemple sont les suivants :

  • Valeur de mérite minimale : le filtre doit avoir une valeur de mérite supérieure à MERIT_DO_NOT_USE.
  • Types d’entrée : l’appelant transmet un tableau contenant des paires de types principaux et de sous-types. Seuls les filtres qui prennent en charge au moins une de ces paires correspondront.
  • Correspondance exacte : un filtre peut inscrire des valeurs NULL pour le type principal, le sous-type, la catégorie de broche ou le support. Sauf si vous spécifiez une correspondance exacte, une valeur NULL agit comme un caractère générique, correspondant à toute valeur que vous spécifiez. Avec une correspondance exacte, le filtre doit correspondre exactement à vos critères. Toutefois, si vous donnez un paramètre NULL dans les critères de recherche, il agit toujours comme une valeur générique ou « don’t care », correspondant à n’importe quel filtre.

Énumération d’appareils et de filtres

Connexion intelligente