Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. ICaptureGraphBuilder2 methods Description SetFiltergraph Specifies a filter graph for the capture graph builder to use. GetFiltergraph Retrieves the filter graph that the builder is using. SetOutputFileName Creates the file writing section of the filter graph. FindInterface Searches the graph for a specified interface, starting from a specified filter. RenderStream Connects an output pin on a source filter to a rendering filter, optionally through a compression filter. ControlStream Sets the start and stop times for one or more streams of captured data. AllocCapFile Preallocates a capture file to a specified size. CopyCaptureFile Copies the valid media data from a capture file. FindPin Retrieves a particular pin on a filter, or determines whether a given pin matches the specified criteria.
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 possibleideally, 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 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_FALSE At least one downstream renderer will not send a stop notification. S_OK Success. E_FAIL Could not find a matching pin, or the pin did not support stream control. E_POINTER NULL 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 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_FALSE User canceled the operation before it completed. S_OK Success. E_FAIL Failure. E_INVALIDARG Could not open the source file or destination file. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL 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 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_OK Success. E_FAIL Failure. E_NOINTERFACE No such interface supported. E_POINTER NULL 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.
- The filter
- The filter's pins
- All the downstream filters, including their pins
- All the upstream filters, including their pins
You can restrict the search by setting the pCategory and pType parameters.
- If pCategory equals &LOOK_UPSTREAM_ONLY, the search starts from the filter's input pins and continues upstream. It does not include the filter or anything downstream from the filter. The pType parameter is ignored.
- If pCategory equals &LOOK_DOWNSTREAM_ONLY, the search starts from the filter's output pins and continues downstream. It does not include the filter or anything upstream from the filter. The pType parameter is ignored.
- If pCategory specifies a pin category, the downstream portion of the search is restricted to output pins on the filter that match both the pin category and the media type given in the pType parameter. In this case, the method also searches the filter and everything upstream from the filter.
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 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 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_OK Success. E_POINTER NULL pointer argument. E_UNEXPECTED No 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 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_OK Success. VFW_S_NOPREVIEWPIN Preview was rendered through a Smart Tee filter. E_FAIL Failure. E_INVALIDARG Invalid argument. E_POINTER NULL 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 twiceonce 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 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_POINTER NULL pointer argument. E_UNEXPECTED Unexpected 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 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_Avi Audio-Video Interleaved (AVI) MEDIASUBTYPE_Asf Advanced 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_FAIL Failure. E_POINTER Null 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.