ICaptureGraphBuilder2::RenderStream
This method connects an output pin on a source filter to a sink filter, optionally through an intermediate filter.
HRESULT RenderStream(
const GUID* pCategory,
const GUID* pType,
IUnknown* pSource,
IBaseFilter* pIntermediate,
IBaseFilter* pSink
);
Parameters
- pCategory
[in] A pointer to a pin category from the AMPROPERTY_PIN_CATEGORY property set (see Pin Property Set). Use NULL to match any category. The following list shows typical categories.- PIN_CATEGORY_CAPTURE
- PIN_CATEGORY_PREVIEW
- PIN_CATEGORY_CC
- 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 Media Types. - pSource
[in] Specifies a pointer to the starting filter for the connection, or to 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. |
| VFW_E_NOT_IN_GRAPH | A filter is not in the filter graph. This error can occur if you did not call AddFilter to add pSource, pIntermediate, or pSink to the graph. It can also occur if you did not call SetFiltergraph to connect your graph to the Capture Graph Builder; in this case, the Capture Graph Builder object automatically creates its own filter graph. See Capture Graph Builder. |
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.
The method connects pSource to pIntermediate, and then connects pIntermediate to pSink. If pIntermediate is NULL, the method just connects pSource to pSink. All of the filters specified by pSource, pIntermediate, and pSink must be added to the graph prior to calling the method. The method uses Intelligent Connect, so additional filters such as decoders might be added to the graph.
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 Waveform Audio 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.
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.
The following code shows a typical capture graph that connects 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 WM 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 more examples, see Video Capture.
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.
Requirements
DirectShow applications and DirectShow filters have different include file and link library requirements.
For more information, see Setting Up the Build Environment.
Pocket PC: Windows Mobile 5.0 and later
Smartphone: Windows Mobile 5.0 and later
OS Versions: Windows CE 5.01 and later
Header:
See Also
ICaptureGraphBuilder2 Interface | Pin Property Set | Media Types | IBaseFilter interface | Smart Tee Filter | Capture Graph Builder | Waveform Audio Renderer | ICaptureGraphBuilder2::SetOutputFileName
Send Feedback on this topic to the authors