| Microsoft DirectX 8.1 (C++) |
The RenderStream method connects an output pin on a source filter to a sink filter, optionally through an intermediate filter.
Syntax
HRESULT RenderStream(
const GUID *pCategory,
const GUID *pType,
IUnknown *pSource,
IBaseFilter *pIntermediate,
IBaseFilter *pSink
);
Parameters
pCategory
[in] Pointer to a member of the AMPROPERTY_PIN_CATEGORY structure of the Pin Property Set property set, specifying a pin category; or NULL to use any pin, regardless of category. Typical values include the following.
pType
[in] 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.
pSource
[in] Specifies a pointer either to the IUnknown interface on the starting filter, or the IUnknown interface on an output pin.
pIntermediate
[in] Pointer to the IBaseFilter interface of an intermediate filter, such as a compression filter. Can be NULL.
pSink
[in] 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 Values
Returns an HRESULT value. Possible return values include the following.
| Return code | Description |
| S_OK | Success. |
| VFW_S_NOPREVIEWPIN | Preview was rendered through the Smart Tee Filter. |
| E_FAIL | Failure. |
| E_INVALIDARG | Invalid argument. |
| E_POINTER | NULL pointer argument. |
Remarks
This method renders a stream by connecting two or more filters together in a chain:
The method connects pSource to pIntermediate, and then connects pIntermediate to pSink. If pIntermediate is NULL, the method just connects pSource to pSink. All connections use Intelligent Connect, so additional filters are automatically added to the graph if needed.
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 its audio and video components, and renders both components.
The RenderStream method handles many of the details required for capture graphs. The following paragraphs describe these details:
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
For a typical capture graph, connect the preview pin to the default renderer, with no intermediate filter:
// Video:
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Video,
pCaptureFilter, NULL, NULL);
// Audio:
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Audio,
pCaptureFilter, NULL, NULL);
Connect the capture pin to a mux filter or file writer filter, depending on what type of file you wish to output. For AVI files, use the AVI Mux filter. For ASF files, use the ASF Writer filter. Typically, you will get a pointer to this filter from the ppf parameter of the ICaptureGraphBuilder2::SetOutputFileName method.
pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"C:\\Example.avi",
&ppf, &pSink);
pBuilder->RenderStream(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video,
pCaptureFilter, NULL, ppf);
For complete examples, see How to Write a Capture Application.
File Sources. You can use this method to transcode or recompress a file. The following discussion assumes that the file has at most one video stream and one audio stream, or else a single interleaved stream. Otherwise, the method will not work correctly.
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);
For a complete example, see Recompressing an AVI File.
See Also