ICaptureGraphBuilder2::RenderStream method (strmif.h)

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The RenderStream method connects an output pin on a source filter to a sink filter, optionally through an intermediate filter.

Syntax

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

Parameters

[in] pCategory

A pointer to a GUID that specifies one of the pin categories listed in Pin Property Set. To match any pin, regardless of category, set this parameter to NULL. Typical values include the following.

• PIN_CATEGORY_CAPTURE
• PIN_CATEGORY_PREVIEW
• PIN_CATEGORY_CC

[in] pType

Pointer to a major-type GUID that specifies the media type of the output pin; or NULL to use any pin, regardless of media type. For a list of possible values, see Major Types.

[in] pSource

Specifies a pointer to the starting filter for the connection, or to an output pin.

[in] pfCompressor

Pointer to the IBaseFilter interface of an intermediate filter, such as a compression filter. Can be NULL.

[in] pfRenderer

Pointer to the IBaseFilter interface of a sink filter, such as a renderer or mux filter. If the value is NULL, the method uses a default renderer (see Remarks).

Return value

Returns an HRESULT value. Possible return values include the following.

Remarks

This method renders a stream by connecting two or more filters together in a chain:

• The pSource parameter specifies the start of the chain, either a filter or an output pin.
• The pIntermediate parameter specifies an intermediate filter, typically a compression filter. This parameter can be NULL.
• The pSink parameter specifies the filter at the end of the chain. Typically, this filter is either a renderer for preview, or a mux for file capture.

If the pSink parameter is NULL, the method tries to use a default renderer. For video it uses the Video Renderer, and for audio it uses the DirectSound Renderer.

If pSource is a filter, the method searches for an output pin on that filter. In that case, use the pCategory and pType parameters to narrow the search. For example, if a filter has separate pins for preview and capture, you can specify either PIN_CATEGORY_CAPTURE or PIN_CATEGORY_PREVIEW. If pSource is an output pin, set the pCategory and pType to NULL.

In all cases, the method searches for unconnected pins. If more than one pin meets the specified criteria, the method uses the first such pin that it finds.

Note that for DV capture, if the media type is MEDIATYPE_Interleaved and the pSink parameter is NULL, the method splits the interleaved stream into an audio stream and a video stream, and renders both of those streams.

The RenderStream method handles many of the details required for capture graphs:

Smart Tee. Some capture filters have a capture pin but no preview pin. To preview, the capture pin must be connected to the Smart Tee Filter. This filter splits the data into two streams, a capture stream and a preview stream. When you specify PIN_CATEGORY_PREVIEW or PIN_CATEGORY_CAPTURE, the method inserts a Smart Tee filter if one is needed. Then it renders the specified stream on the Smart Tee filter. If you render a preview stream and the method uses a Smart Tee filter, it returns VFW_S_NOPREVIEWPIN.

Closed Captioning. You can use this method to capture or preview closed captioning. Some capture filters deliver Vertical Blanking Interval (VBI) data, others deliver closed captioning data. To handle either case, call the method twice, once using PIN_CATEGORY_VBI and once using PIN_CATEGORY_CC. The method inserts any filters needed to convert VBI data to closed captioning. To preview the data, set the pSink parameter to NULL. To capture the data to a file, use the multiplexer filter's IBaseFilter interface pointer. You can capture and preview the data in the same graph. Call the method once using NULL and again using the multiplexer. Set the pIntermediate parameter to NULL.

Video Port Pins. Filters that work with video port extension (VPE) video capture hardware might have video port pins (PIN_CATEGORY_VIDEOPORT) instead of preview pins. For preview or capture to work, a video port pin must connect to the Overlay Mixer Filter. The method handles this detail. You do not have to specify PIN_CATEGORY_VIDEOPORT. Specify PIN_CATEGORY_PREVIEW or PIN_CATEGORY_CAPTURE, and the method will connect the pin correctly. In a similar way, some filters deliver VBI data using video port pins (PIN_CATEGORY_VIDEOPORT_VBI). As with PIN_CATEGORY_VIDEOPORT, the method handles this detail. You do not have to specify PIN_CATEGORY_VIDEOPORT_VBI.

Supporting Filters. If a capture device uses a Windows Driver Model (WDM) driver, the graph may require certain filters upstream from the WDM Video Capture Filter, such as a TV Tuner Filter or an Analog Video Crossbar Filter. If this method successfully renders the stream, it also inserts any WDM filters that are required in your graph. The method queries the input pins on the capture filter to determine what mediums they support, and connects them to matching filters.

Example Code

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

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

File Sources

A file source has one output pin, so set pCategory and pType to NULL. Call the method twice—once to render the video stream, and once to render the audio stream. The first call connects the source filter to a parser filter and renders one of the parser filter's output pins. The second call renders the parser's remaining output pin. If you are compressing one stream but not the other, make sure to specify the compressor filter in the first call. The method will automatically pick the correct stream based on the compression type.

pBuilder->RenderStream(NULL, NULL, pSrc, pCompressor, pMux);
pBuilder->RenderStream(NULL, NULL, pSrc, NULL, pMux);

Requirements

See also

Building Graphs with the Capture Graph Builder

Error and Success Codes

ICaptureGraphBuilder2 Interface

Video Capture