ICaptureGraphBuilder Interface

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

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 Values

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 95 platform than it will be on a Windows NT 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.

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. NULL indicates control all capture filters in the graph.

• PIN_CATEGORY_CAPTURE
• PIN_CATEGORY_PREVIEW
• NULL

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 Values

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.

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.

HRESULT CopyCaptureFile(
  [in] LPOLESTR lpwstrOld,
  [in] LPOLESTR lpwstrNew,
  [in] int fAllowEscAbort,
  [in] 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] TRUE indicates that pressing the ESC key aborts the copy operation, 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 Values

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.

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 an 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 Values

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 IAMCrossbar 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();

See AMCAP, the capture sample in the SDK for an example of how to use interface.

---

ICaptureGraphBuilder::GetFiltergraph

ICaptureGraphBuilder Interface

Retrieves the filter graph that the builder is using.

HRESULT GetFiltergraph(
  IGraphBuilder **ppfg
  );

Parameters

ppfg

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

Return Values

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.

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 Values

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

Remarks

If you specify PIN_CATEGORY_CAPTURE 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.

All required filters must be present in the graph before the application calls this method.

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 only 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, since the preview interface may 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.

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 Values

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.

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 Values

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.

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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page