ICaptureGraphBuilder2::RenderStream 方法 (strmif.h)

[与此页面关联的功能 DirectShow 是一项旧功能。 它已被 MediaPlayerIMFMediaEngine媒体基金会中的音频/视频捕获取代。 这些功能已针对Windows 10和Windows 11进行了优化。 Microsoft 强烈建议新代码尽可能使用 MediaPlayerIMFMediaEngineMedia Foundation 中的音频/视频捕获 ,而不是 DirectShow。 如果可能,Microsoft 建议重写使用旧 API 的现有代码以使用新 API。]

方法 RenderStream 可以选择通过中间筛选器将源筛选器上的输出引脚连接到接收器筛选器。

语法

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

参数

[in] pCategory

指向 GUID 的指针,该 GUID 指定 Pin 属性集中列出的固定类别之一。 若要匹配任何固定,而不考虑类别,请将此参数设置为 NULL。 典型值包括以下内容。

  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • PIN_CATEGORY_CC

[in] pType

指向主要类型 GUID 的指针,该 GUID 指定输出引脚的媒体类型;或 NULL 以使用任何引脚,而不考虑媒体类型。 有关可能值的列表,请参阅 主要类型

[in] pSource

指定指向连接的起始筛选器或输出引脚的指针。

[in] pfCompressor

指向中间筛选器(如压缩筛选器)的 IBaseFilter 接口的指针。 可以为 NULL

[in] pfRenderer

指向接收器筛选器的 IBaseFilter 接口的指针,例如呈现器或复用器筛选器。 如果值为 NULL,则该方法使用默认呈现器 (请参阅备注) 。

返回值

返回 HRESULT 值。 可能的返回值包括以下内容。

返回代码 说明
S_OK
成功。
VFW_S_NOPREVIEWPIN
预览是通过 智能 Tee 筛选器呈现的。
E_FAIL
失败。
E_INVALIDARG
无效的参数。
E_POINTER
NULL 指针参数。
VFW_E_NOT_IN_GRAPH
筛选器不在筛选器图中。 如果未调用 AddFilterpSource、pIntermediatepSink 添加到图形,则会发生此错误。 如果未调用 SetFiltergraph 将图形连接到捕获图形生成器,也可能发生此情况;在这种情况下,Capture Graph Builder 对象会自动创建自己的筛选器图。 请参阅 关于捕获图形生成器

注解

此方法通过在链中将两个或多个筛选器连接在一起来呈现流:

  • pSource 参数指定链的开头(筛选器或输出引脚)。
  • pIntermediate 参数指定中间筛选器,通常是压缩筛选器。 此参数可以为 NULL。
  • pSink 参数指定链末尾的筛选器。 通常,此筛选器是用于预览的呈现器,或者是用于文件捕获的复用器。
方法将 pSource 连接到 pIntermediate,然后将 pIntermediate 连接到 pSink。 如果 pIntermediateNULL,则该方法仅将 pSource 连接到 pSink。 在调用 方法之前,必须将 pSourcepIntermediatepSink 指定的所有筛选器添加到图中。 方法使用 智能连接,因此可能会向图中添加其他筛选器(如解码器)。

如果 pSink 参数为 NULL,该方法将尝试使用默认呈现器。 对于视频,它使用 视频呈现器,对于音频,它使用 DirectSound 呈现器

如果 pSource 是筛选器,该方法将搜索该筛选器上的输出引脚。 在这种情况下,请使用 pCategorypType 参数来缩小搜索范围。 例如,如果筛选器具有用于预览和捕获的单独引脚,则可以指定PIN_CATEGORY_CAPTURE或PIN_CATEGORY_PREVIEW。 如果 pSource 是输出引脚,请将 pCategorypType 设置为 NULL

在所有情况下, 方法都会搜索未连接的引脚。 如果多个引脚满足指定的条件,该方法将使用它找到的第一个此类引脚。

请注意,对于 DV 捕获,如果媒体类型为 MEDIATYPE_Interleaved 并且 pSink 参数为 NULL,则 方法会将交错的流拆分为音频流和视频流,并呈现这两个流。

方法 RenderStream 处理捕获图所需的许多详细信息:

Smart Tee。 某些捕获筛选器具有捕获引脚,但没有预览引脚。 若要预览,捕获引脚必须连接到 智能 Tee 筛选器。 此筛选器将数据拆分为两个流:捕获流和预览流。 指定PIN_CATEGORY_PREVIEW或PIN_CATEGORY_CAPTURE时, 方法将插入一个智能 Tee 筛选器(如果需要)。 然后,它会在 Smart Tee 筛选器上呈现指定的流。 如果呈现预览流,并且 方法使用 Smart Tee 筛选器,则返回VFW_S_NOPREVIEWPIN。

隐藏式字幕。 可以使用此方法捕获或预览隐藏式字幕。 一些捕获筛选器 (VBI) 数据提供垂直空白间隔,其他捕获筛选器提供隐藏式字幕数据。 若要处理任一情况,请调用 方法两次,一次使用 PIN_CATEGORY_VBI,一次使用 PIN_CATEGORY_CC。 方法插入将 VBI 数据转换为隐藏式字幕所需的任何筛选器。 若要预览数据,请将 pSink 参数设置为 NULL。 若要将数据捕获到文件,请使用多路复用器筛选器的 IBaseFilter 接口指针。 可以在同一图中捕获和预览数据。 使用 NULL 调用方法一次,再使用多路复用器调用一次。 将 pIntermediate 参数设置为 NULL

视频端口引脚。 使用视频端口扩展 (VPE) 视频捕获硬件的筛选器可能具有视频端口引脚 (PIN_CATEGORY_VIDEOPORT) 而不是预览引脚。 要使预览或捕获正常工作,视频端口引脚必须连接到 覆盖混音器筛选器。 方法处理此详细信息。 无需指定PIN_CATEGORY_VIDEOPORT。 指定PIN_CATEGORY_PREVIEW或PIN_CATEGORY_CAPTURE,该方法将正确连接引脚。 以类似的方式,某些筛选器使用视频端口引脚 (PIN_CATEGORY_VIDEOPORT_VBI) 传送 VBI 数据。 与 PIN_CATEGORY_VIDEOPORT 一样, 方法处理此详细信息。 无需指定PIN_CATEGORY_VIDEOPORT_VBI。

支持筛选器。 如果捕获设备使用 Windows 驱动程序模型 (WDM) 驱动程序,该图可能需要从 WDM 视频捕获筛选器上游某些筛选器,例如电视调谐器筛选器模拟视频交叉条筛选器。 如果此方法成功呈现流,它还会插入图形中所需的任何 WDM 筛选器。 方法查询捕获筛选器上的输入引脚以确定它们支持的介质,并将其连接到匹配的筛选器。

示例代码

对于典型的捕获图,请将预览图钉连接到默认呈现器,没有中间筛选器:
C++
// Video: 
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Video, 
    pCaptureFilter, NULL, NULL); 
// Audio:
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Audio, 
    pCaptureFilter, NULL, NULL); 
根据要输出的文件类型,将捕获引脚连接到复用筛选器或文件编写器筛选器。 对于 AVI 文件,请使用 AVI 复用器 筛选器。 对于 ASF 文件,请使用 WM ASF 编写器 筛选器。 通常,你将从 ICaptureGraphBuilder2::SetOutputFileName 方法的 ppf 参数获取指向此筛选器的指针。
C++
pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"C:\\Example.avi", 
    &ppf, &pSink);
pBuilder->RenderStream(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video,
    pCaptureFilter, NULL, ppf);

文件源

可以使用此方法转码或重新压缩文件。 下面的讨论假定文件最多有一个视频流和一个音频流,或者单个交错流。 否则,方法将无法正常工作。

文件源有一个输出引脚,因此请将 pCategorypType 设置为 NULL。 调用 方法两次-一次用于呈现视频流,一次用于呈现音频流。 第一次调用将源筛选器连接到分析程序筛选器,并呈现分析程序筛选器的输出引脚之一。 第二次调用呈现分析程序剩余的输出引脚。 如果要压缩一个流,但不压缩另一个流,请确保在第一次调用中指定压缩器筛选器。 方法将根据压缩类型自动选取正确的流。

C++
pBuilder->RenderStream(NULL, NULL, pSrc, pCompressor, pMux);
pBuilder->RenderStream(NULL, NULL, pSrc, NULL, pMux);
有关完整示例,请参阅 重新压缩 AVI 文件

要求

要求
目标平台 Windows
标头 strmif.h (包括 Dshow.h)
Library Strmiids.lib

另请参阅

使用捕获图形生成器生成图形

错误和成功代码

ICaptureGraphBuilder2 接口

视频捕获