Méthode ICaptureGraphBuilder2 ::RenderStream (strmif.h)

Article
03/04/2024

[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.]

La RenderStream méthode connecte une broche de sortie sur un filtre source à un filtre récepteur, éventuellement via un filtre intermédiaire.

Syntaxe

HRESULT RenderStream(
  [in] const GUID  *pCategory,
  [in] const GUID  *pType,
  [in] IUnknown    *pSource,
  [in] IBaseFilter *pfCompressor,
  [in] IBaseFilter *pfRenderer
);

Paramètres

[in] pCategory

Pointeur vers un GUID qui spécifie l’une des catégories d’épingles répertoriées dans Pin Property Set. Pour correspondre à n’importe quelle broche, quelle que soit la catégorie, définissez ce paramètre sur NULL. Les valeurs classiques sont les suivantes.

PIN_CATEGORY_CAPTURE
PIN_CATEGORY_PREVIEW
PIN_CATEGORY_CC

[in] pType

Pointeur vers un GUID de type principal qui spécifie le type de média de la broche de sortie ; ou NULL pour utiliser n’importe quelle broche, quel que soit le type de média. Pour obtenir la liste des valeurs possibles, consultez Types principaux.

[in] pSource

Spécifie un pointeur vers le filtre de départ de la connexion ou vers une broche de sortie.

[in] pfCompressor

Pointeur vers l’interface IBaseFilter d’un filtre intermédiaire, tel qu’un filtre de compression. Peut être NULL.

[in] pfRenderer

Pointeur vers l’interface IBaseFilter d’un filtre récepteur, tel qu’un renderer ou un filtre mux. Si la valeur est NULL, la méthode utilise un convertisseur par défaut (voir Remarques).

Valeur retournée

Retourne une valeur HRESULT . Les valeurs de retour possibles sont les suivantes.

Code de retour	Description
S_OK	Réussite.
VFW_S_NOPREVIEWPIN	L’aperçu a été rendu via le filtre Smart Tee.
E_FAIL	Échec.
E_INVALIDARG	Argument non valide.
E_POINTER	Argument pointeur NULL .
VFW_E_NOT_IN_GRAPH	Un filtre ne figure pas dans le graphique de filtre. Cette erreur peut se produire si vous n’avez pas appelé AddFilter pour ajouter pSource, pIntermediate ou pSink au graphique. Cela peut également se produire si vous n’avez pas appelé SetFiltergraph pour connecter votre graphe au Générateur de graphiques de capture ; dans ce cas, l’objet Générateur de graphiques de capture crée automatiquement son propre graphique de filtre. Consultez À propos du Générateur de graphiques de capture.

Remarques

Cette méthode restitue un flux en connectant deux filtres ou plus dans une chaîne :

Le paramètre pSource spécifie le début de la chaîne, soit un filtre, soit une broche de sortie.
Le paramètre pIntermediate spécifie un filtre intermédiaire, généralement un filtre de compression. Ce paramètre peut être NULL.
Le paramètre pSink spécifie le filtre à la fin de la chaîne. En règle générale, ce filtre est soit un convertisseur pour la préversion, soit un mux pour la capture de fichiers.

La méthode connecte pSource à pIntermediate, puis connecte pIntermediate à pSink. Si pIntermediate a la valeur NULL, la méthode connecte simplement pSource à pSink. Tous les filtres spécifiés par pSource, pIntermediate et pSink doivent être ajoutés au graphique avant d’appeler la méthode . La méthode utilise Intelligent Connect, de sorte que des filtres supplémentaires tels que des décodeurs peuvent être ajoutés au graphique.

Si le paramètre pSink a la valeur NULL, la méthode tente d’utiliser un convertisseur par défaut. Pour la vidéo, il utilise le convertisseur vidéo, et pour l’audio, il utilise le renderer DirectSound.

Si pSource est un filtre, la méthode recherche une broche de sortie sur ce filtre. Dans ce cas, utilisez les paramètres pCategory et pType pour affiner la recherche. Par exemple, si un filtre a des broches distinctes pour l’aperçu et la capture, vous pouvez spécifier PIN_CATEGORY_CAPTURE ou PIN_CATEGORY_PREVIEW. Si pSource est une broche de sortie, définissez pCategory et pType sur NULL.

Dans tous les cas, la méthode recherche des broches non connectées. Si plusieurs broches répondent aux critères spécifiés, la méthode utilise la première broche de ce type qu’elle trouve.

Notez que pour la capture DV, si le type de média est MEDIATYPE_Interleaved et que le paramètre pSink a la valeur NULL, la méthode fractionne le flux entrelacé en un flux audio et un flux vidéo, puis restitue ces deux flux.

La RenderStream méthode gère un grand nombre des détails requis pour les graphiques de capture :

Smart Tee. Certains filtres de capture ont une broche de capture, mais pas d’épingle d’aperçu. Pour afficher un aperçu, la broche de capture doit être connectée au filtre Smart Tee. Ce filtre fractionne les données en deux flux, un flux de capture et un flux d’aperçu. Lorsque vous spécifiez PIN_CATEGORY_PREVIEW ou PIN_CATEGORY_CAPTURE, la méthode insère un filtre Smart Tee si nécessaire. Ensuite, il restitue le flux spécifié sur le filtre Smart Tee. Si vous affichez un flux d’aperçu et que la méthode utilise un filtre Smart Tee, elle retourne VFW_S_NOPREVIEWPIN.

Sous-titrage. Vous pouvez utiliser cette méthode pour capturer ou afficher un aperçu du sous-titrage. Certains filtres de capture fournissent des données vBI (Vertical Blanking Interval), d’autres fournissent des données de sous-titrage. Pour gérer les deux cas, appelez la méthode deux fois, une fois à l’aide de PIN_CATEGORY_VBI et une fois en utilisant PIN_CATEGORY_CC. La méthode insère tous les filtres nécessaires pour convertir les données VBI en sous-titrage. Pour afficher un aperçu des données, définissez le paramètre pSink sur NULL. Pour capturer les données dans un fichier, utilisez le pointeur d’interface IBaseFilter du filtre de multiplexeur. Vous pouvez capturer et afficher un aperçu des données dans le même graphique. Appelez la méthode une fois à l’aide de NULL et de nouveau à l’aide du multiplexeur. Définissez le paramètre pIntermediate sur NULL.

Broches de port vidéo. Les filtres qui fonctionnent avec le matériel de capture vidéo VPE (Video Port Extension) peuvent avoir des broches de port vidéo (PIN_CATEGORY_VIDEOPORT) au lieu de broches d’aperçu. Pour que l’aperçu ou la capture fonctionnent, une broche de port vidéo doit se connecter au filtre de mélangeur de superposition. La méthode gère ce détail. Vous n’êtes pas obligé de spécifier PIN_CATEGORY_VIDEOPORT. Spécifiez PIN_CATEGORY_PREVIEW ou PIN_CATEGORY_CAPTURE, et la méthode connecte correctement l’épingle. De la même façon, certains filtres fournissent des données VBI à l’aide de broches de port vidéo (PIN_CATEGORY_VIDEOPORT_VBI). Comme avec PIN_CATEGORY_VIDEOPORT, la méthode gère ce détail. Vous n’avez pas besoin de spécifier PIN_CATEGORY_VIDEOPORT_VBI.

Filtres de prise en charge. Si un périphérique de capture utilise un pilote WDM (Windows Driver Model), le graphique peut nécessiter certains filtres amont à partir du filtre de capture vidéo WDM, par exemple un filtre de tuner TV ou un filtre de barre croisée vidéo analogique. Si cette méthode restitue correctement le flux, elle insère également les filtres WDM requis dans votre graphique. La méthode interroge les broches d’entrée sur le filtre de capture pour déterminer les supports qu’elles prennent en charge et les connecte aux filtres correspondants.

Exemple de code

Pour un graphique de capture classique, connectez l’épingle d’aperçu au convertisseur par défaut, sans filtre intermédiaire :

C++
// Video: pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Video, pCaptureFilter, NULL, NULL); // Audio: pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Audio, pCaptureFilter, NULL, NULL);

C++

// Video: 
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Video, 
    pCaptureFilter, NULL, NULL); 
// Audio:
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Audio, 
    pCaptureFilter, NULL, NULL);

Connectez la broche de capture à un filtre mux ou à un filtre d’enregistreur de fichiers, en fonction du type de fichier que vous souhaitez générer. Pour les fichiers AVI, utilisez le filtre AVI Mux . Pour les fichiers ASF, utilisez le filtre Enregistreur ASF WM . En règle générale, vous obtenez un pointeur vers ce filtre à partir du paramètre ppf de la méthode ICaptureGraphBuilder2 ::SetOutputFileName .

C++
pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"C:\\Example.avi", &ppf, &pSink); pBuilder->RenderStream(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video, pCaptureFilter, NULL, ppf);

Sources de fichiers

Vous pouvez utiliser cette méthode pour transcoder ou recompresser un fichier. La discussion suivante suppose que le fichier a au plus un flux vidéo et un seul flux audio, ou bien un seul flux entrelacé. Sinon, la méthode ne fonctionnera pas correctement.

Une source de fichier ayant une broche de sortie, définissez pCategory et pType sur NULL. Appelez la méthode deux fois : une fois pour afficher le flux vidéo et une fois pour restituer le flux audio. Le premier appel connecte le filtre source à un filtre d’analyseur et restitue l’une des broches de sortie du filtre d’analyseur. Le deuxième appel restitue la broche de sortie restante de l’analyseur. Si vous compressez un flux, mais pas l’autre, veillez à spécifier le filtre du compresseur dans le premier appel. La méthode sélectionne automatiquement le flux approprié en fonction du type de compression.