ICaptureGraphBuilder Interface

The ICaptureGraphBuilder interface enables you to easily build capture graphs, preview graphs, file recompression graphs, or even unusual custom graphs. For more information, see Recompress an AVI File.

When you use this interface to build a capture graph that uses WDM filters, you need to add additional upstream filters, such as TV tuners and CrossBar filters, to the graph. These filters are brought into the filter graph when you call the RenderStream method to render a pin of a capture filter or when you call the FindInterface method on a capture filter.

For more information on using this interface, see Creating a Capture Application.

Do not implement this interface. Microsoft® DirectShow® implements it for you.

Use this interface in your capture and recompression applications to make it easier to build filter graphs.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

ICaptureGraphBuilder methods Description
SetFiltergraph Tells the graph builder object which filter graph to use.
GetFiltergraph Retrieves the filter graph that the builder is using.
SetOutputFileName Creates the rendering section of the filter graph, which will save bits to disk with the specified file name.
FindInterface Looks for the specified interface on the filter, upstream and downstream from the filter, and, optionally, only on the output pin of the given category.
RenderStream Connects a source filter's pin, of an optionally specified category, to the rendering filter, and optionally through another filter.
ControlStream Sends stream control messages to the pin of the specified category on one or more capture filters in a graph.
AllocCapFile Preallocates a capture file to a specified size.
CopyCaptureFile Copies the valid media data from the preallocated capture file.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
ICaptureGraphBuilder methods	Description
SetFiltergraph	Tells the graph builder object which filter graph to use.
GetFiltergraph	Retrieves the filter graph that the builder is using.
SetOutputFileName	Creates the rendering section of the filter graph, which will save bits to disk with the specified file name.
FindInterface	Looks for the specified interface on the filter, upstream and downstream from the filter, and, optionally, only on the output pin of the given category.
RenderStream	Connects a source filter's pin, of an optionally specified category, to the rendering filter, and optionally through another filter.
ControlStream	Sends stream control messages to the pin of the specified category on one or more capture filters in a graph.
AllocCapFile	Preallocates a capture file to a specified size.
CopyCaptureFile	Copies the valid media data from the preallocated capture file.

ICaptureGraphBuilder::AllocCapFile

ICaptureGraphBuilder Interface

Preallocates a capture file to a specified size.

Syntax

HRESULT AllocCapFile(
    LPCOLESTR lpwstr,
    DWORDLONG dwlSize
);

Parameters

lpwstr
[in] Pointer to a Unicode™ string containing the name of the file to create or resize.
dwSize
[in] Size, in bytes, of the file to be allocated.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The call will fail if the file is read-only. For best capture results, always capture to a defragmented, preallocated capture file that is larger than the size of the capture data.
Note that under the current DirectShow implementation of this interface, a call to this method will be much quicker on a Windows 9x platform than it will be on a Windows NT® 4.x or Windows 2000 platform.

ICaptureGraphBuilder::ControlStream

ICaptureGraphBuilder Interface

Sends stream control messages to the pin of the specified category on one or more capture filters in a graph.

Syntax

HRESULT ControlStream(
    const GUID *pCategory,
    IBaseFilter *pFilter,
    REFERENCE_TIME *pstart,
    REFERENCE_TIME *pstop,
    WORD wStartCookie,
    WORD wStopCookie
);

Parameters

pCategory
[in] Pointer to a GUID specifying the output pin category. Typical values include the following. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. This value cannot be NULL.
PIN_CATEGORY_CAPTURE
PIN_CATEGORY_PREVIEW

pFilter
[in] Pointer to an IBaseFilter interface on the filter to control. Specifying NULL controls all capture filters in the graph. You will get one notification for each capture filter.
pstart
[in] Pointer to the start time for capture. NULL means start now. MAX_TIME means cancel previous request, or take no action if there is no previous request.
pstop
[in] Pointer to the stop time for capture. NULL means stop now. MAX_TIME means cancel previous request, or take no action if there is no previous request.
wStartCookie
[in] Specifies a particular value to be sent when the start occurs.
wStopCookie
[in] Specifies a particular value to be sent when the stop occurs.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns S_FALSE if the stop notification is sent before the last sample sent by the capture filter is rendered, otherwise returns S_OK.
If this method returns S_FALSE, the application might want to wait before stopping the filter graph to allow all samples to pass through the graph and be rendered. Otherwise, samples might be lost.
If there are no pins matching the description you provide, or if stream control cannot be supported on all of the indicated pins, this function will return a failure code.

Remarks

Use this method for frame-accurate capture, or for individual control of capture and preview. For example, you could turn off writing of the captured image to disk if you only want to preview the captured image.
This method calls the IAMStreamControl interface on the pins.
This method sends one notification for each filter found with a pin of the specified category.

ICaptureGraphBuilder::CopyCaptureFile

ICaptureGraphBuilder Interface

Copies the valid media data from the preallocated capture file.

Syntax

HRESULT CopyCaptureFile(
    LPOLESTR lpwstrOld,
    LPOLESTR lpwstrNew,
    int fAllowEscAbort,
    IAMCopyCaptureFileProgress *pCallback
);

Parameters

lpwstrOld
[in] Pointer to a Unicode string containing the source file name.
lpwstrNew
[in] Pointer to a Unicode string containing the destination file name. Valid data is copied to this file.
fAllowEscAbort
[in] Value indicating whether pressing the ESC key will abort the copy operation. TRUE indicates that it will; FALSE indicates that this method will ignore that keystroke.
pCallback
[in] Optional pointer to an IAMCopyCaptureFileProgress interface that you implement to show the progress (percentage complete) of the copy operation.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The new file will contain only valid data and therefore can be much shorter than the source file. Typically, you will always capture to the same huge preallocated file and use this method to copy the data you want to save from each capture to a new file.
If you specify pCallback, the Progress method on the IAMCopyCaptureFileProgress interface will be called periodically with an integer between 0 and 100 representing the percentage complete.

ICaptureGraphBuilder::FindInterface

ICaptureGraphBuilder Interface

Looks for the specified interface on the filter, upstream and downstream from the filter, and, optionally, only on the output pin of the given category.

Syntax

HRESULT FindInterface(
    const GUID *pCategory,
    IBaseFilter *pf,
    REFIID riid,
    void **ppint
);

Parameters

pCategory
[in] Pointer to a GUID specifying the output pin category. Typical values include the following. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. NULL indicates search all the output pins regardless of category.
PIN_CATEGORY_CAPTURE
PIN_CATEGORY_PREVIEW
NULL

pf
[in] Pointer to the IBaseFilter interface of the filter.
riid
[in] Reference ID of the desired interface.
ppint
[out] Address of a void pointer. If the interface was found, this method initializes ppint so that it contains the address of a pointer to the found interface. Call the Release method to decrement the reference count when you're done with the interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method looks for the interface on the filter, and upstream and downstream of the filter, unless a category is given. If a category is given, it only looks downstream of the output pin of that category. It can be used to find interfaces on renderers, multiplexers, TV tuners, crossbars, and so forth.
If pCategory == &LOOK_UPSTREAM_ONLY, then the graph builder will look upstream of the filter given in parameter pf, but not on the filter itself, nor downstream of the filter.
If pCategory == &LOOK_DOWNSTREAM_ONLY, then the graph builder will look downstream of the filter given in parameter pf, but not on the filter itself, nor upstream of the filter.
For example, capture graphs can have two crossbars in them, a video crossbar (upstream of the video capture filter) and an audio crossbar (upstream of the video crossbar). You can find the video crossbar filter that implements the IAMCrossbar interface, as shown in the following code.
IAMCrossbar *pVideoCrossbar;
FindInterface(NULL, pVideoCaptureFilter, IID_IAMCrossbar, (void **)&pVideoCrossbar);
You can then find the IAMCrossbar filter of the audio crossbar, as shown in the following code.
IBaseFilter *pBaseFilter;
IAMCrossbar *pAudioCrossbar;
pVideoCrossbar->QueryInterface(IID_IBaseFilter, (void **)pBaseFilter);
FindInterface(
    &LOOK_UPSTREAM_ONLY, pBaseFilter, IID_IAMCrossbar, (void **)&pAudioCrossbar);
pBaseFilter->Release();
For an example of how to use this interface, see AMCap, the capture sample in the SDK.

ICaptureGraphBuilder::GetFiltergraph

ICaptureGraphBuilder Interface

Retrieves the filter graph that the builder is using.

Syntax

HRESULT GetFiltergraph(
    IGraphBuilder **ppfg
);

Parameters

ppfg
[out] Address of a pointer to an IGraphBuilder interface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method increments the reference count on the IGraphBuilder interface; be sure to decrement the reference count on IGraphBuilder by calling the Release method.

ICaptureGraphBuilder::RenderStream

ICaptureGraphBuilder Interface

Connects a source filter's pin, of an optionally specified category, to the rendering filter, and optionally through another filter.

Syntax

HRESULT RenderStream(
    const GUID *pCategory,
    IUnknown *pSource,
    IBaseFilter *pfCompressor,
    IBaseFilter *pfRenderer
);

Parameters

pCategory
[in] Pointer to a GUID specifying which output pin of the source filter to connect. Typical values include the following. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. NULL indicates render the only output pin, regardless of category.
PIN_CATEGORY_CAPTURE
PIN_CATEGORY_PREVIEW
NULL

pSource
[in] Pointer to an IBaseFilter or an IPin interface representing either the source filter or an output pin. Source filters are typically a file source filter, such as an AVI file source filter or a capture filter.
pfCompressor
[in] Pointer to an IBaseFilter interface representing the optional compression filter.
pfRenderer
[in] Pointer to an IBaseFilter interface representing the renderer. You can use the ppf (multiplexer) parameter from ICaptureGraphBuilder::SetOutputFileName to supply this value.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. Returns VFW_S_NOPREVIEWPIN if the capture filter has a capture pin but no preview pin, and you call RenderStream with the &PIN_CATEGORY_PREVIEW category on the capture pin. In this case, RenderStream will render the preview pin of the Smart Tee filter. For more information, see Remarks.

Remarks

If you specify a non-NULL AMPROPERTY_PIN_CATEGORY for pCategory and a capture filter for pSource, this method instantiates and connects additional required upstream filters, such as TV tuners and crossbars. It then renders the capture pin of pSource.
If pSource is a pin, then specify NULL for pCategory and this method renders the stream from that pin.
If the source filter has only one output pin, specify NULL for pCategory.
pSource, pfCompressor, and pfRenderer filters given as parameters must be present in the graph before this method is called.
If you are building a capture graph that is using WDM capture filters, this method will build all necessary upstream filters as well as the downstream filters.
Some capture filters that work with new WDM VPE (Video Port Extension) video capture hardware have VIDEO PORT pins instead of PREVIEW pins meant for previewing. These VIDEO PORT pins do not connect directly to a video renderer, but instead to a special filter called the Overlay Mixer. Your application does not need to worry about this. All you have to do is call RenderStream with &PIN_CATEGORY_PREVIEW and the capture graph builder will correctly render the VIDEO PORT pin through an overlay mixer if that is what is necessary.
When you render a capture or preview pin of a video capture filter (using RenderStream with the &PIN_CATEGORY_CAPTURE or &PIN_CATEGORY_PREVIEW category) and the capture filter has a capture pin but no preview pin, the Smart Tee filter (Qcap.dll) will be used automatically to allow simultaneous capture and preview. For example, calling RenderStream with the &PIN_CATEGORY_CAPTURE category will actually connect a Smart Tee filter to the capture pin of the filter, and then render the capture pin of the Smart Tee. If you then call RenderStream with the &PIN_CATEGORY_PREVIEW category on the capture pin, it will actually render the preview pin of the Smart Tee. If calling RenderStream with &PIN_CATEGORY_PREVIEW results in using the capture pin and a Smart Tee filter, RenderStream will return VFW_S_NOPREVIEWPIN to indicate this. Thus, if FindInterface fails to find a preview interface, you may need to call FindInterface with the &PIN_CATEGORY_PREVIEW category and with the &PIN_CATEGORY_CAPTURE category, because the preview interface can be found by looking downstream of the capture pin of the capture filter. See the Amcap.cpp sample for an example of using this interface and writing a capture application.

ICaptureGraphBuilder::SetFiltergraph

ICaptureGraphBuilder Interface

Tells the graph builder object which filter graph to use.

Syntax

HRESULT SetFiltergraph(
    IGraphBuilder *pfg
);

Parameters

pfg
[in] Pointer to an IGraphBuilder interface that specifies the filter graph to use for subsequent calls to the IFilterGraph::AddFilter method.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The graph builder will automatically create a filter graph if you don't call this method. If you call this method after the graph builder has created its own filter graph, the call will fail.

ICaptureGraphBuilder::SetOutputFileName

ICaptureGraphBuilder Interface

Creates the rendering section of the filter graph, which will save bits to disk with the specified file name.

Syntax

HRESULT SetOutputFileName(
    const GUID *pType,
    LPCOLESTR lpwstrFile,
    IBaseFilter **ppf,
    IFileSinkFilter **pSink
);

Parameters

pType
[in] Pointer to a GUID representing the media subtype. Must be &MEDIASUBTYPE_Avi because AVI is currently the only supported output format.
lpwstrFile
[in] Pointer to a Unicode string containing the output file name.
ppf
[out] Address of a pointer to an IBaseFilter interface representing the multiplexer filter. This method increments the reference count on the IBaseFilter interface so you must decrement the reference count by using the Release method on this parameter when done using the filter.
pSink
[out] Address of a pointer to an IFileSinkFilter interface representing the file writer. This method increments the reference count on the IFileSinkFilter interface so you must decrement the reference count using Release when done using the filter.

Return Value

Returns an HRESULT value indicating the status of the operation.

E_FAIL Failure.
E_INVALIDARG Invalid argument. Audio-Video Interleaved (AVI) is the only supported output format.
E_OUTOFMEMORY Out of memory.
E_POINTER Null pointer argument.
E_UNEXPECTED Unexpected error occurred.
NOERROR Success.
S_OK Instance of the AVI multiplexer filter was successfully created.

Remarks

This method inserts the multiplexer and the file writer into the filter graph and calls IFileSinkFilter::SetFileName to set the output file name.
You can use the ppf parameter returned by this method as the pfRenderer parameter in calls to RenderStream.
You can use the pSink parameter from this method in a call to SetFileName to change the file name set by ICaptureGraphBuilder::SetOutputFileName.

E_FAIL	Failure.
E_INVALIDARG	Invalid argument. Audio-Video Interleaved (AVI) is the only supported output format.
E_OUTOFMEMORY	Out of memory.
E_POINTER	Null pointer argument.
E_UNEXPECTED	Unexpected error occurred.
NOERROR	Success.
S_OK	Instance of the AVI multiplexer filter was successfully created.