Microsoft DirectX 8.0

ICaptureGraphBuilder2 Interface

This interface provides methods for building capture graphs, preview graphs, and file recompression graphs. The capture graph builder implements this interface.

This interface replaces the ICaptureGraphBuilder interface. It works 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 does not work with devices that use the same driver for both video and audio capture.

For more information on using this interface, see How to Write a Capture Application and Recompressing an AVI File.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
ICaptureGraphBuilder2 methodsDescription
SetFiltergraphSpecifies a filter graph for the capture graph builder to use.
GetFiltergraphRetrieves the filter graph that the builder is using.
SetOutputFileNameCreates the file writing section of the filter graph.
FindInterfaceSearches the graph for a specified interface, starting from a specified filter.
RenderStreamConnects an output pin on a source filter to a rendering filter, optionally through a compression filter.
ControlStreamSets the start and stop times for one or more streams of captured data.
AllocCapFilePreallocates a capture file to a specified size.
CopyCaptureFileCopies the valid media data from a capture file.
FindPinRetrieves a particular pin on a filter, or determines whether a given pin matches the specified criteria.

ICaptureGraphBuilder2::AllocCapFile

ICaptureGraphBuilder2 Interface

Preallocates a capture file to a specified size. For best results, always capture to a defragmented, preallocated capture file that is larger than the size of the capture data.

Syntax

HRESULT AllocCapFile(
    LPCOLESTR lpwstr,
    DWORDLONG dwlSize
);

Parameters

lpwstr
[in] Pointer to a Unicode™ string that contains the name of the file to create or resize.
dwlSize
[in] Size of the file to allocate, in bytes.

Return Value

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.

Remarks

This method fails if the file is read-only.

It is best to allocate as much space as possible—ideally, more than needed. However, this can result in a very large file that contains relatively little data. For example, a 1-gigabyte (GB) capture file might contain a few megabytes of captured video. Use the CopyCaptureFile method to copy the data into a new file. That method copies only the data and ignores the empty portion of the original file.

Note  The AllocCapFile method takes longer on Microsoft® Windows NT® 4.x or Microsoft® Windows® 2000 than it does on other Windows platforms, because the method must write over the entire preallocated file. However, it is still recommended that you use this method, because it results in better capture performance.

ICaptureGraphBuilder2::ControlStream

ICaptureGraphBuilder2 Interface

Sets the start and stop times for one or more streams of captured data.

This method locates output pins on capture filters, using search criteria that you supply in the method call. Then it calls IAMStreamControl methods on those pins. This method enables an application to control streams without the application needing to enumerate the filters and pins in the graph.

Use this method for frame-accurate capture, or for individual control of capture and preview. For example, you can stop capturing to disk but leave video preview running.

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 member of the AMPROPERTY_PIN_CATEGORY property set, specifying the pin category. The value of this parameter cannot be NULL.
pType
[in] Pointer to a major type GUID that specifies the media type, or NULL. If this parameter is NULL, set the pFilter parameter to NULL as well. Otherwise, you might control the wrong pin and get unpredictable results.
pFilter
[in] Pointer to an IBaseFilter interface that specifies which filter to control. To control all the capture filters in the graph, set this parameter to NULL.
pstart
[in] Pointer to a variable that contains the start time. To start immediately, set the value to NULL. To cancel the previous start request, set the value to MAX_TIME. If there is no previous request, the value MAX_TIME has no effect.
pstop
[in] Pointer to a variable that contains the stop time. To stop immediately, set the value to NULL. To cancel the previous stop request, set the value to MAX_TIME. If there is no previous request, the value MAX_TIME has no effect.
wStartCookie
[in] Value that is sent as the second parameter of the EC_STREAM_CONTROL_STARTED event notification. See Remarks for more information.
wStopCookie
[in] Value that is sent as the second parameter of the EC_STREAM_CONTROL_STOPPED event notification. See Remarks for more information.

Return Value

Returns an HRESULT value. Possible values include the following:

S_FALSEAt least one downstream renderer will not send a stop notification.
S_OKSuccess.
E_FAILCould not find a matching pin, or the pin did not support stream control.
E_POINTERNULL pointer argument.

Remarks

The first three parameters specify which pins to control. A capture graph can have more than one capture filter. For example, it might have filters for video, audio, and closed captioning data. Also, a capture filter can have more than one output pin. Some capture filters have separate pins for preview and capture, or separate pins for video-only data and audio-video interleaved data. To control video preview, for example, specify PIN_CATEGORY_PREVIEW for pCategory and MEDIATYPE_Video for pType.

To control a pin, this method calls the IAMStreamControl::StartAt and IAMStreamControl::StopAt methods. Each pin sends an EC_STREAM_CONTROL_STARTED event notification when it starts. The second parameter of the event notification is the value given in wStartCookie. When the pin stops, it sends an EC_STREAM_CONTROL_STOPPED event notification. The second parameter of that event notification is the value given in wStopCookie.

When this method locates a matching pin, it searches downstream for another filter that supports IAMStreamControl (typically a multiplexer). If it finds one, it also sets the start and stop times on that filter. This generates two pairs of stop notifications: one for the capture filter, and one for the downstream filter. Only the stop notification from the downstream filter uses the wStopCookie parameter. Waiting for this event guarantees that the downstream filter receives the last sample.

If no downstream filter supports IAMStreamControl, the method returns S_FALSE. In that case, you might receive the stop notification before the last sample is rendered.

ICaptureGraphBuilder2::CopyCaptureFile

ICaptureGraphBuilder2 Interface

Copies the valid media data from a capture file.

Typically, you will first capture to a large preallocated file. This method copies just the valid data to a new file. As a result, the new file can be much smaller than the original file.

Syntax

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

Parameters

lpwstrOld
[in] Pointer to a Unicode™ string that contains the source file name.
lpwstrNew
[in] Pointer to a Unicode string that contains the destination file name. Valid data is copied to this file.
fAllowEscAbort
[in] Boolean value that specifies whether pressing the ESC key cancels the copy operation. If the value is TRUE and the user presses the ESC key, the operation halts. If the value is FALSE, the method ignores the ESC key.
pCallback
[in] Pointer to an IAMCopyCaptureFileProgress interface to display progress information, or NULL. See Remarks for more information.

Return Value

Returns an HRESULT value. Possible values include the following:

S_FALSEUser canceled the operation before it completed.
S_OKSuccess.
E_FAILFailure.
E_INVALIDARGCould not open the source file or destination file.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.

Remarks

The source and destination files must be AVI files. Other file types are not supported.

To display the progress of the copy operation, implement the IAMCopyCaptureFileProgress interface and pass a pointer to the interface in the pCallback parameter. If pCallback is non-NULL, this method periodically calls the IAMCopyCaptureFileProgress::Progress method with an integer between 0 and 100 that specifies the percentage complete.

ICaptureGraphBuilder2::FindInterface

ICaptureGraphBuilder2 Interface

Searches the graph for a specified interface, starting from a specified filter. You can restrict the search to a section of the graph upstream or downstream of the filter, or restrict it to a particular pin category or media type.

Syntax

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

Parameters

pCategory
[in] Pointer to a GUID that specifies the search criteria. See Remarks for more information. The following values are possible:
  • LOOK_UPSTREAM_ONLY
  • LOOK_DOWNSTREAM_ONLY
  • Member of the AMPROPERTY_PIN_CATEGORY property set, specifying a pin category.
  • NULL
pType
[in] Pointer to a major type GUID that specifies the media type of an output pin, or NULL.
pf
[in] Pointer to the IBaseFilter interface of the filter.
riid
[in] Reference identifier (ID) of the interface.
ppint
[out] Address of a variable that receives the interface pointer. Be sure to release the retrieved interface pointer when you are done with the interface.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_FAILFailure.
E_NOINTERFACENo such interface supported.
E_POINTERNULL pointer argument.

Remarks

In a capture graph, various filters and pins might expose interfaces for setting properties such as compression parameters (IAMVideoCompression) or stream formats (IAMStreamConfig). Depending on the capture device, other useful interfaces might include IAMCrossbar, which routes analog signals, or IAMTVTuner, which controls a TV tuner device. You can use this method to find an interface, without writing special code that traverses the graph.

Important  Do not call this method to obtain an IVideoWindow interface pointer. Always query the filter graph manager for this interface. Otherwise, the filter graph manager will not respond correctly to changes in screen resolution and other events.

If the pCategory parameter is NULL, this method searches the entire graph for the requested interface. Starting from the filter specified by the pf parameter, it queries the following objects in the graph.

You can restrict the search by setting the pCategory and pType parameters.

Pin categories are useful for finding pin interfaces on capture filters. For example, a capture filter might have separate pins for capture and preview. If you specify a pin category, you should also specify the media type, to make certain the method selects the correct filter and pin.

Some video capture filters have a video port pin (PIN_CATEGORY_VIDEOPORT) instead of a preview pin. If you specify PIN_CATEGORY_PREVIEW and MEDIATYPE_Video, the method treats any video port pins as preview pins. Your application does not have to test for this possibility.

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 your graph requires any of these WDM filters, this method automatically inserts them into the graph. The method queries the input pins on the capture filter to determine what mediums they support, and connects them to matching filters.

ICaptureGraphBuilder2::FindPin

ICaptureGraphBuilder2 Interface

Retrieves a particular pin on a filter, or determines whether a given pin matches the specified criteria.

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 an interface on a filter, or to an interface on a pin.
pindir
[in] Member of the PIN_DIRECTION enumeration that specifies the pin direction (input or output).
pCategory
[in] Pointer to a member of the AMPROPERTY_PIN_CATEGORY property set, specifying a pin category. Use NULL to match any category.
pType
[in] Pointer to a major type GUID that specifies the media type. Use NULL to match any media type.
fUnconnected
[in] Boolean value that specifies whether the pin must be unconnected. If TRUE, the pin must be unconnected. If FALSE, the pin can be connected or unconnected.
num
[in] Zero-based index of the pin to retrieve, from the set of matching pins. If pSource is a pointer to a filter, and more than one pin matches the search criteria, this parameter specifies which pin to retrieve. If pSource is a pointer to a pin, this parameter is ignored.
ppPin
[out] Address of a pointer to receive the IPin interface of the matching pin.

Return Value

Returns S_OK if a matching pin is found, or E_FAIL otherwise.

Remarks

If pSource is a pointer to a filter, the method searches for the nth pin on that filter that matches the search criteria, where n is given by the num parameter. If the method finds a matching pin, it returns a pointer to the pin in the ppPin parameter.

If pSource is a pointer to a pin, the method tests that pin against the search criteria. If the pin matches the criteria, the method returns S_OK, and returns a pointer to the pin's IPin interface in the ppPin parameter. Otherwise, it returns E_FAIL.

In either case, if the method succeeds, the IPin interface returned in the ppPin parameter has an outstanding reference count. Be sure to release the interface when you are done using it.

Typically, an application will not need to use this method. It is provided for unusually complex tasks, when the RenderStream method cannot build the filter graph. Use this method to retrieve a desired pin from a capture filter, and then build the rest of the graph manually.

ICaptureGraphBuilder2::GetFiltergraph

ICaptureGraphBuilder2 Interface

Retrieves the filter graph that the capture graph builder is using.

Syntax

HRESULT GetFiltergraph(
    IGraphBuilder **ppfg
);

Parameters

ppfg
[out] Address of a variable that receives an IGraphBuilder interface pointer.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_POINTERNULL pointer argument.
E_UNEXPECTEDNo filter graph.

Remarks

This method increments the reference count on the IGraphBuilder interface. Be sure to release the interface when you are done with it.

ICaptureGraphBuilder2::RenderStream

ICaptureGraphBuilder2 Interface

Connects an output pin on a source filter to a rendering filter, optionally through a compression filter.

Syntax

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

Parameters

pCategory
[in] Pointer to a member of the AMPROPERTY_PIN_CATEGORY 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.
pSource
[in] Pointer to an interface on a source filter, or to an interface on an output pin.
pfCompressor
[in] Optional pointer to the IBaseFilter interface of a compression filter.
pfRenderer
[in] Optional pointer to the IBaseFilter interface of a renderer filter or multiplexer filter.

Return Value

Returns an HRESULT value. Possible return values include the following:

S_OKSuccess.
VFW_S_NOPREVIEWPINPreview was rendered through a Smart Tee filter.
E_FAILFailure.
E_INVALIDARGInvalid argument.
E_POINTERNULL pointer argument.

Remarks

This method renders a stream, either for preview or for writing to a file. The method automatically handles many of the complexities of capture graphs.

The pSource parameter specifies an output pin or a filter. If you specify an output pin, the method renders the stream from that pin. Set the pCategory and pType parameters to NULL in this case. If you specify a filter, the method searches the filter for an output pin whose pin category matches the pCategory parameter, and whose media type matches the pType parameter.

The pfRenderer parameter specifies a sink filter, typically either the File Writer filter or a multiplexer filter such as the AVI Mux. You can obtain a pointer to the multiplexer by calling the SetOutputFileName method. The pointer is returned in the ppf parameter of that method.

If pfRenderer is NULL, the method uses a default renderer: the Video Renderer for video, or the Default DirectSound Device for audio.

The pfCompressor parameter specifies a compression filter, or in general any transform filter. If you don't want to compress the stream, set this parameter to NULL.

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 pfRenderer 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 pfCompressor 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 a 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.

File Sources. Although this method is designed for building capture graphs, another use for it is 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 (the pfCompressor parameter) in the first call. If pfCompressor is NULL in the first call, the method might render either stream (video or audio). For a complete example, see Recompressing an AVI File.

ICaptureGraphBuilder2::SetFiltergraph

ICaptureGraphBuilder2 Interface

Specifies a filter graph for the capture graph builder to use.

Syntax

HRESULT SetFiltergraph(
    IGraphBuilder *pfg
);

Parameters

pfg
[in] Pointer to the filter graph's IGraphBuilder interface.

Return Value

Returns an HRESULT value. Possible values include the following:

E_POINTERNULL pointer argument.
E_UNEXPECTEDUnexpected error.

Remarks

If you do not call this method, the capture graph builder automatically creates a filter graph when it needs one. If the capture graph builder already has a filter graph, this method returns E_UNEXPECTED.

ICaptureGraphBuilder2::SetOutputFileName

ICaptureGraphBuilder2 Interface

Creates the file writing section of the filter graph.

Syntax

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

Parameters

pType
[in] Pointer to a GUID that represents either the media subtype of the output or the class identifier (CLSID) of a multiplexer filter or file writer filter. If you specify a media subtype, it must be one of the following:
MEDIASUBTYPE_AviAudio-Video Interleaved (AVI)
MEDIASUBTYPE_AsfAdvanced Streaming Format (ASF)
lpwstrFile
[in] Pointer to a Unicode™ string that contains the output file name.
ppf
[out] Address of a pointer that receives the multiplexer's IBaseFilter interface.
pSink
[out] Address of a pointer that receives the file writer's IFileSinkFilter interface. Can be NULL.

Return Value

Returns an HRESULT value. Possible values include the following:
S_OK Success.
E_FAILFailure.
E_POINTERNull pointer argument.

Remarks

This method inserts the multiplexer and the File Writer filter into the filter graph. It also calls IFileSinkFilter::SetFileName to set the output file name.

You can use the pointer to the multiplexer filter, returned in the ppf parameter, as the pfRenderer parameter in the RenderStream method.

If the method succeeds, the IBaseFilter interface returned in the ppf parameter has an outstanding reference count. If the method succeeds and pSink is not NULL, the IFileSinkFilter interface also has an outstanding reference count. Be sure to release both interfaces when you are done using them.