The ICaptureGraphBuilder interface enables you to build capture graphs, preview graphs, file recompression graphs, or even unusual custom graphs easily. See Recompress an AVI File for more information.
When to Implement
Do not implement this interface. DirectShow already does so.
When to Use
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, 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. |
Preallocates a capture file to a specified size.
HRESULT AllocCapFile(
LPCOLESTR lpwstr,
DWORDLONG dwlSize
);
Returns an HRESULT value that depends on the implementation of the interface.
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 95 platform than it will be on a Windows NT platform.
Sends stream control messages to the pin of the specified category on one or more capture filters in a graph.
HRESULT ControlStream(
const GUID *pCategory,
IBaseFilter *pFilter,
REFERENCE_TIME *pstart,
REFERENCE_TIME *pstop,
WORD wStartCookie,
WORD wStopCookie
);
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 destroying the filter graph to allow all samples to pass through the graph and be rendered. Otherwise, samples might be lost.
If a capture filter does not support the IAMStreamControl interface on its preview pin, the filter should return the failure code E_NOINTERFACE in response to a call to this method.
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.
Copies the valid media data from the preallocated capture file.
HRESULT CopyCaptureFile(
[in] LPOLESTR lpwstrOld,
[in] LPOLESTR lpwstrNew,
[in] int fAllowEscAbort,
[in] IAMCopyCaptureFileProgress *pCallback
);
Returns an HRESULT value that depends on the implementation of the interface.
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.
Looks for the specified interface on the filter, upstream and downstream from the filter, and, optionally, on the output pin of the given category.
HRESULT FindInterface(
const GUID *pCategory,
IBaseFilter *pf,
REFIID riid,
void **ppint
);
Returns an HRESULT value that depends on the implementation of the interface.
This method also looks upstream and downstream of the pin for the interface, to find interfaces on renderers, multiplexers, TV tuners, and so forth.
Retrieves the filter graph that the builder is using.
HRESULT GetFiltergraph(
IGraphBuilder **ppfg
);
Returns an HRESULT value that depends on the implementation of the interface.
This method increments the reference count on the IGraphBuilder interface; be sure to decrement the reference count on IGraphBuilder by calling the Release method.
Connects a source filter's pin, of an optionally specified category, to the rendering filter, and optionally through another filter.
HRESULT RenderStream(
const GUID *pCategory,
IMoniker *pMSource,
IUnknown *pSource,
IBaseFilter *pfCompressor,
IBaseFilter *pfRenderer
);
Returns an HRESULT value that depends on the implementation of the interface.
If you specify PIN_CATEGORY_CAPTURE for pCategory, a capture filter for pSource, and specify a moniker for pMSource, 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 pMSource and this method renders the stream from that pin.
If the source filter has only one output pin, specify NULL for pCategory.
All required filters must be present in the graph before the application calls this method.
Tells the graph builder object which filter graph to use.
HRESULT SetFiltergraph(
IGraphBuilder *pfg
);
Returns an HRESULT value that depends on the implementation of the interface.
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.
Creates the rendering section of the filter graph, which will save bits to disk with the specified file name.
HRESULT SetOutputFileName(
const GUID *pType,
LPCOLESTR lpwstrFile,
IBaseFilter **ppf,
IFileSinkFilter **pSink
);
&MEDIASUBTYPE_Avi
because AVI is currently the only supported output format.
| Value | Meaning |
| 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. |
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.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.