## 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, 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, 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 the output pin regardless of category.
  - PIN_CATEGORY_CAPTURE
  - PIN_CATEGORY_PREVIEW
  - NULL
pf
  [in] Pointer to an IBaseFilter interface that is the capture 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 also looks upstream and downstream of the pin for the interface, to find interfaces on renderers, multiplexers, TV tuners, and so forth.

###

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.

###

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.

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