Metodo ICaptureGraphBuilder2::RenderStream (strmif.h)

Articolo
03/05/2024

[La funzionalità associata a questa pagina, DirectShow, è una funzionalità legacy. È stata sostituita da MediaPlayer, IMFMediaEngine e Audio/Video Capture in Media Foundation. Queste funzionalità sono state ottimizzate per Windows 10 e Windows 11. Microsoft consiglia vivamente che il nuovo codice usi MediaPlayer, IMFMediaEngine e Audio/Video Capture in Media Foundation invece di DirectShow, quando possibile. Microsoft suggerisce che il codice esistente che usa le API legacy venga riscritto per usare le nuove API, se possibile.

Il RenderStream metodo connette un pin di output su un filtro di origine a un filtro sink, facoltativamente tramite un filtro intermedio.

Sintassi

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

Parametri

[in] pCategory

Puntatore a un GUID che specifica una delle categorie di pin elencate in Pin Property Set. Per trovare la corrispondenza con qualsiasi pin, indipendentemente dalla categoria, impostare questo parametro su NULL. I valori tipici includono quanto segue.

PIN_CATEGORY_CAPTURE
PIN_CATEGORY_PREVIEW
PIN_CATEGORY_CC

[in] pType

Puntatore a un GUID di tipo principale che specifica il tipo di supporto del pin di output; o NULL per usare qualsiasi pin, indipendentemente dal tipo di supporto. Per un elenco dei valori possibili, vedere Tipi principali.

[in] pSource

Specifica un puntatore al filtro iniziale per la connessione o a un pin di output.

[in] pfCompressor

Puntatore all'interfaccia IBaseFilter di un filtro intermedio, ad esempio un filtro di compressione. Può essere NULL.

[in] pfRenderer

Puntatore all'interfaccia IBaseFilter di un filtro sink, ad esempio un renderer o un filtro mux. Se il valore è NULL, il metodo usa un renderer predefinito (vedere la sezione Osservazioni).

Valore restituito

Restituisce un valore HRESULT . I valori restituiti possibili includono quanto segue.

Codice restituito	Descrizione
S_OK	Operazione completata.
VFW_S_NOPREVIEWPIN	Il rendering dell'anteprima è stato eseguito tramite il filtro Tee intelligente.
E_FAIL	Esito negativo.
E_INVALIDARG	Argomento non valido.
E_POINTER	Argomento puntatore NULL.
VFW_E_NOT_IN_GRAPH	Un filtro non è incluso nel grafico dei filtri. Questo errore può verificarsi se non è stato chiamato AddFilter per aggiungere pSource, pIntermediate o pSink al grafico. Può verificarsi anche se non è stato chiamato SetFiltergraph per connettere il grafico a Capture Graph Builder; in questo caso, l'oggetto Capture Graph Builder crea automaticamente un proprio grafico di filtro. Vedere Informazioni su Capture Graph Builder.

Commenti

Questo metodo esegue il rendering di un flusso connettendo due o più filtri in una catena:

Il parametro pSource specifica l'inizio della catena, ovvero un filtro o un pin di output.
Il parametro pIntermediate specifica un filtro intermedio, in genere un filtro di compressione. Questo parametro può essere NULL.
Il parametro pSink specifica il filtro alla fine della catena. In genere, questo filtro è un renderer per l'anteprima o un mux per l'acquisizione di file.

Il metodo connette pSource a pIntermediate e quindi connette pIntermediate a pSink. Se pIntermediate è NULL, il metodo connette semplicemente pSource a pSink. Tutti i filtri specificati da pSource, pIntermediate e pSink devono essere aggiunti al grafico prima di chiamare il metodo . Il metodo usa Intelligent Connect, quindi è possibile aggiungere altri filtri, ad esempio decodificatori, al grafico.

Se il parametro pSink è NULL, il metodo tenta di usare un renderer predefinito. Per il video usa il Renderer video e per l'audio usa directSound Renderer.

Se pSource è un filtro, il metodo cerca un pin di output in tale filtro. In tal caso, usare i parametri pCategory e pType per restringere la ricerca. Ad esempio, se un filtro include pin separati per l'anteprima e l'acquisizione, è possibile specificare PIN_CATEGORY_CAPTURE o PIN_CATEGORY_PREVIEW. Se pSource è un pin di output, impostare pCategory e pType su NULL.

In tutti i casi, il metodo cerca pin non connessi. Se più pin soddisfano i criteri specificati, il metodo usa il primo pin di questo tipo trovato.

Si noti che per l'acquisizione DV, se il tipo di supporto è MEDIATYPE_Interleaved e il parametro pSink è NULL, il metodo suddivide il flusso interleaved in un flusso audio e un flusso video ed esegue il rendering di entrambi i flussi.

Il RenderStream metodo gestisce molti dei dettagli necessari per i grafici di acquisizione:

Tee intelligente. Alcuni filtri di acquisizione hanno un pin di acquisizione, ma non un pin di anteprima. Per visualizzare l'anteprima, il pin di acquisizione deve essere connesso al filtro Smart Tee. Questo filtro suddivide i dati in due flussi, un flusso di acquisizione e un flusso di anteprima. Quando si specifica PIN_CATEGORY_PREVIEW o PIN_CATEGORY_CAPTURE, il metodo inserisce un filtro Tee intelligente, se necessario. Esegue quindi il rendering del flusso specificato nel filtro Smart Tee. Se si esegue il rendering di un flusso di anteprima e il metodo usa un filtro Smart Tee, restituisce VFW_S_NOPREVIEWPIN.

Didascalia chiusa. È possibile usare questo metodo per acquisire o visualizzare in anteprima la didascalia chiusa. Alcuni filtri di acquisizione recapitano dati con intervallo di spaziatura verticale (VBI), altri recapitano dati di sottotitoli codificati. Per gestire entrambi i casi, chiamare il metodo due volte, una volta usando PIN_CATEGORY_VBI e una volta usando PIN_CATEGORY_CC. Il metodo inserisce tutti i filtri necessari per convertire i dati VBI in sottotitoli. Per visualizzare in anteprima i dati, impostare il parametro pSink su NULL. Per acquisire i dati in un file, usare il puntatore all'interfaccia IBaseFilter del filtro multiplexer. È possibile acquisire e visualizzare in anteprima i dati nello stesso grafico. Chiamare il metodo una volta usando NULL e di nuovo usando il multiplexer. Impostare il parametro pIntermediate su NULL.

Pin porta video. I filtri che funzionano con l'hardware di acquisizione video dell'estensione per le porte video (VPE) potrebbero avere pin di porta video (PIN_CATEGORY_VIDEOPORT) invece dei pin di anteprima. Per il funzionamento dell'anteprima o dell'acquisizione, un pin di porta video deve connettersi al filtro mixer di sovrapposizione. Il metodo gestisce questo dettaglio. Non è necessario specificare PIN_CATEGORY_VIDEOPORT. Specificare PIN_CATEGORY_PREVIEW o PIN_CATEGORY_CAPTURE e il metodo connetterà correttamente il pin. In modo analogo, alcuni filtri forniscono dati VBI usando pin di porta video (PIN_CATEGORY_VIDEOPORT_VBI). Come per PIN_CATEGORY_VIDEOPORT, il metodo gestisce questo dettaglio. Non è necessario specificare PIN_CATEGORY_VIDEOPORT_VBI.

Filtri di supporto. Se un dispositivo di acquisizione usa un driver WDM (Windows Driver Model), il grafico potrebbe richiedere determinati filtri upstream dal filtro di acquisizione video WDM, ad esempio un filtro di tuner TV o un filtro barra incrociata video analogico. Se questo metodo esegue correttamente il rendering del flusso, inserisce anche eventuali filtri WDM necessari nel grafico. Il metodo esegue una query sui pin di input nel filtro di acquisizione per determinare quali supporti supportano e li connette ai filtri corrispondenti.

Codice di esempio

Per un tipico grafico di acquisizione, connettere il pin di anteprima al renderer predefinito, senza filtro intermedio:

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);

Connettere il pin di acquisizione a un filtro mux o a un filtro del writer di file, a seconda del tipo di file da restituire. Per i file AVI, usare il filtro Mux AVI . Per i file ASF, usare il filtro WM ASF Writer . In genere, si otterrà un puntatore a questo filtro dal parametro ppf del metodo ICaptureGraphBuilder2::SetOutputFileName .

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

Origini file

È possibile usare questo metodo per transcodificare o ricomprimere un file. La discussione seguente presuppone che il file abbia al massimo un flusso video e un flusso audio oppure un singolo flusso interleaved. In caso contrario, il metodo non funzionerà correttamente.

Un'origine file ha un pin di output, quindi impostare pCategory e pType su NULL. Chiamare il metodo due volte, una volta per eseguire il rendering del flusso video e una volta per eseguire il rendering del flusso audio. La prima chiamata connette il filtro di origine a un filtro parser ed esegue il rendering di uno dei pin di output del filtro parser. La seconda chiamata esegue il rendering del pin di output rimanente del parser. Se si comprime un flusso ma non l'altro, assicurarsi di specificare il filtro del compressore nella prima chiamata. Il metodo selezionerà automaticamente il flusso corretto in base al tipo di compressione.