ICaptureGraphBuilder2 Interface

The ICaptureGraphBuilder2 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.

This interface is just like ICaptureGraphBuilder, but it will work with Microsoft® Windows® Driver Model (WDM) capture drivers that can capture more than one media type, such as both audio and video. The original ICaptureGraphBuilder interface will not work with devices that use the same driver for both video and audio capture, so you will need to use this new interface if your application is to function properly with these new devices (which will be available beginning with Windows 2000).

For more information on using this interface see the Creating a Capture Application overview article.

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 methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
ICaptureGraphBuilder2 methodsDescription
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 using the specified file name.
FindInterface Looks for the specified interface on the filter, upstream from the filter, and downstream from the filter. Optionally, looks only downstream from the output pin of a given category.
RenderStream Connects a source filter 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.
FindPin Helper function to find a particular pin on a filter.

ICaptureGraphBuilder2::AllocCapFile

ICaptureGraphBuilder2 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.
dwlSize
[in] Size, in bytes, of the file to allocate.

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 an NT-based platform (Microsoft® Windows NT® 4.x or Windows 2000).

ICaptureGraphBuilder2::ControlStream

ICaptureGraphBuilder2 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,
    const GUID *pType, 
    IBaseFilter *pFilter,
    REFERENCE_TIME *pstart,
    REFERENCE_TIME *pstop,
    WORD wStartCookie,
    WORD wStopCookie
);

Parameters

pCategory
[in] Pointer to a GUID specifying the output pin category. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. This value cannot be NULL. Commonly used values include PIN_CATEGORY_CAPTURE and PIN_CATEGORY_PREVIEW.
pType
[in] Pointer to a GUID specifying the output pin media type. A filter might have more than one pin of the specified category, and this pointer will determine which pin you want to control. Specify a major type GUID for the media type. Typical values include &MEDIATYPE Video and &MEDIATYPE Audio. You can specify NULL for both pFilter and pType to control all pins of a certain category on every filter.
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. If you specify a filter, you should not use NULL for pType, or you may get unpredictable results by controlling the wrong pin.
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] Value to be sent when the start occurs.
wStopCookie
[in] Value to be sent when the stop occurs.

Return Value

Returns S_FALSE if ControlStream will send stop notification before the last sample sent by the capture filter has been rendered; otherwise, it returns S_OK.

If this method returns S_FALSE, you might want the application to wait before it stops the filter graph, in order to allow all samples to pass through the graph and be rendered. Otherwise, samples might be lost.

If no pins match the description you provide, or if stream control cannot be supported on all of the indicated pins, this method will return a failure code.

Remarks

Use this method for frame-accurate capture, or for individual control of capture and preview. For example, you can 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.

ICaptureGraphBuilder2::CopyCaptureFile

ICaptureGraphBuilder2 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 specifying whether pressing the ESC key aborts the copy operation. TRUE indicates that it does; FALSE indicates that this method will ignore the ESC key.
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 very large 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, this method will periodically call the IAMCopyCaptureFileProgress::Progress method with an integer between 0 and 100 representing the percentage complete.

ICaptureGraphBuilder2::FindInterface

ICaptureGraphBuilder2 Interface

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

Syntax

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

Parameters

pCategory
[in] Pointer to a GUID specifying the output pin category. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. Specify NULL to search all output pins regardless of category. Typical values include PIN_CATEGORY_CAPTURE and PIN_CATEGORY_PREVIEW.
pType
[in] Pointer to a GUID specifying the media type of the output pin. Specify a major type GUID for the media type. If you specify a category (pCategory), you should also specify a type. Typical values include the following.
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 to contain the address of a pointer to the 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, upstream from the filter, and downstream from the filter, unless a category is given. If a category is given, it looks only downstream from the output pin of that category. You can use this method to find interfaces on renderers, multiplexers, TV tuners, crossbars, and so forth.

If you are building a capture graph that uses a WDM capture filter, calling this method will also build the necessary upstream filters for you, as well as the downstream filters. For example, a crossbar or a TV tuner filter may be required in the graph for the capture filter to function properly. This method will handle these tasks, so that your application doesn't need to.

If pCategory equals &LOOK_UPSTREAM_ONLY, the graph builder will look upstream from the filter given in parameter pf, but not on the filter itself, nor downstream from the filter.

If pCategory equals &LOOK_DOWNSTREAM_ONLY, the graph builder will look downstream from the filter given in parameter pf, but not on the filter itself, nor upstream from the filter.

For example, a capture graph might have two crossbars, a video crossbar (upstream from the video capture filter) and an audio crossbar (upstream from 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);

Then you can find the IAMCrossbar filter of the audio crossbar as follows: 

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 IAMCrossbar, see AMCap Sample (DirectShow Capture Application), the capture sample in the SDK.

ICaptureGraphBuilder2::GetFiltergraph

ICaptureGraphBuilder2 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.

ICaptureGraphBuilder2::RenderStream

ICaptureGraphBuilder2 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,
    const GUID *pType,
    IUnknown *pSource,
    IBaseFilter *pfCompressor,
    IBaseFilter *pfRenderer
);

Parameters

pCategory
[in] Pointer to a GUID specifying which output pin of the source filter to connect, based on the pin category. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. NULL indicates any pin, regardless of category, so only pass NULL if there is exactly one unconnected output pin. Typical values include the following.
pType
[in] Pointer to a GUID specifying which output pin of the source filter to connect based on its media type. Specify a major type GUID for the media type. NULL indicates any pin, regardless of type, so only pass NULL when there is no ambiguity. Typical values include &MEDIATYPE Video and &MEDIATYPE Audio.
pSource
[in] Pointer to an IBaseFilter or IPin interface representing either the source filter or an output pin. A source filter is 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 ICaptureGraphBuilder2::SetOutputFileName to supply this value.

Return Value

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

Remarks

If you specify a category for pCategory and a capture filter for pSource, this method instantiates and connects any additional upstream filters that may be required. (For example, the graph may need a crossbar filter or a TV tuner filter in order for the capture filter to function properly. The method will handle this, so your application doesn't need to worry about it.) It then renders the capture pin of pSource.

If pSource is a pin, specify NULL for pCategory. This method will render the stream from that pin.

If the source filter has only one output pin, specify NULL for both pCategory and pType.

Some capture filters that work with new WDM VPE (Video Port Extension) video capture hardware have PIN_CATEGORY_VIDEOPORT pins instead of PIN_CATEGORY_PREVIEW pins meant for previewing. These PIN_CATEGORY_VIDEOPORT pins do not connect directly to a video renderer, but instead to a special filter called the Overlay Mixer. Your application does not need special code to handle this detail. Simply call RenderStream with &PIN_CATEGORY_PREVIEW, and the capture graph builder will correctly render the PIN_CATEGORY_VIDEOPORT pin through an overlay mixer if necessary.

If you render a capture pin or preview pin of a video capture filter (using &PIN_CATEGORY_CAPTURE or &PIN_CATEGORY_PREVIEW for the pCategory parameter) and the capture filter has a capture pin but no preview pin, this method will automatically use the Smart Tee filter (Qcap.dll) to allow simultaneous capture and preview. For example, calling RenderStream with &PIN_CATEGORY_CAPTURE will 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 render the preview pin of the Smart Tee. If a call to RenderStream with &PIN_CATEGORY_PREVIEW results in using the capture pin and a Smart Tee filter, the method will return VFW_S_NOPREVIEWPIN. Thus, if FindInterface fails to find a preview interface, you might 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 from the capture pin of the capture filter. For an example of a capture application that uses this interface, see the AMCap SDK sample.

You can use this interface to watch and capture closed captioning information with new devices that support it. Some devices have a pin category of PIN_CATEGORY_VBI and some have PIN_CATEGORY_CC, so trying to render both of those categories (using NULL for pfCompressor and pfRenderer) will build a graph that enables you to watch closed captioning. If you want to record the closed-captioning information (into an AVI file, for instance), use the ppf (multiplexer) parameter from SetOutputFileName to supply a value for pfRenderer, instead of using NULL. If you want to preview closed captioning while it is recording to a file, call RenderStream with PIN_CATEGORY_VBI or PIN_CATEGORY_CC twice, once with pfRenderer set to NULL, and once with pfRenderer set to a multiplexer filter, and a graph will be built to record the closed captioning and preview it at the same time. Again, see the AMCap sample for an example of how to do this.

ICaptureGraphBuilder2::SetFiltergraph

ICaptureGraphBuilder2 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.

ICaptureGraphBuilder2::SetOutputFileName

ICaptureGraphBuilder2 Interface

Creates the rendering section of the filter graph, which will save bits to disk using 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 when you are done with the filter you must decrement the reference count by calling the Release method on this parameter.
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 when you are done with the filter you must decrement the reference count by calling Release.

Return Value

Returns an HRESULT value indicating the status of the operation. Typical values include:
E_FAIL Failure.
E_INVALIDARG Invalid argument. Audio-Video Interleaved (AVI) is currently 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 this method.

ICaptureGraphBuilder2::FindPin

ICaptureGraphBuilder2 Interface

Retrieves a particular pin on a filter.

Syntax

HRESULT FindPin(
    IUnknown *pSource,
    PIN_DIRECTION pindir,
    const GUID *pCategory,
    const GUID *pType,
    BOOL fUnconnected,
    int num,
    IPin **ppPin
);

Parameters

pSource
[in] Pointer to the IBaseFilter interface of the filter to look at. Can also be a pointer to an IPin interface, in which case the method will use the filter attached to that pin to search for the desired pin.
pindir
[in] Value from the PIN_DIRECTION enumeration specifying whether you want an input or an output pin.
pCategory
[in] Pointer to a GUID specifying which category of pin you want. NULL indicates any pin, regardless of category. See AMPROPERTY_PIN_CATEGORY for a list of all pin categories. Typical values include the following.
pType
[in] Pointer to a GUID specifying which pin you want, based on its media type. Specify a major type GUID for the media type. NULL indicates any pin, regardless of type. Typical values include the following.
fUnconnected
[in] Value specifying whether the pin must be unconnected in order to be returned. If FALSE, it won't matter if the pin is connected or not.
num
[in] More than one pin might meet the criteria you specify, so you can specify an index to retrieve, starting with zero.
ppPin
[out] Address of a pointer to an IPin interface on a matching pin.

Return Value

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

Remarks

Use this method for advanced operations and graph building, where RenderStream cannot build the graph for you. This method will help you get the desired pin from a capture filter, and you can then build a complex graph manually. Typical applications will not need to use this method.

Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.