GrabberSample Filter Sample

This sample provides modified source code for the Sample Grabber filter. To prevent conflicts with the existing Sample Grabber, the following changes have been made:

• This sample filter has been renamed "GrabberSample," to indicate that it is an example implementation.
• The CLSID has been changed.

Path

Source: (SDK root)\Samples\Multimedia\DirectShow\Filters\Grabber

Sample Description

The Sample Grabber Example is a transform filter that captures data traveling through a stream and notifies the application through a callback. It performs an in-place transform, so it does not require additional buffers or copying. However, if your callback function takes a long time to process, this benefit will be greatly reduced.

This filter has the following limitations:

• It does not synchronize itself with the main application thread, so the application must handle multithreading issues. 
• It does not buffer the data. (As a consequence, it does not support the Sample Grabber filter's "one-shot mode.")

Ideas for Enhancing the Filter

The following is a list of ideas for enhancing this filter:

• Copy samples to a buffer and call the application on a background thread.
• Negotiate pin connections to force either an upstream or downstream allocator to be used.
• Discard pre-roll samples and zero-length samples.
• Write a COM object that wraps the filter graph and enables an application to pull samples synchronously from a stream. (The MediaDet object in DirectShow Editing Services uses this approach.)

Limitations of the Original Sample Grabber Filter

The Sample Grabber that ships with DirectX has some limitations:

• For video types, it requires a VIDEOINFOHEADER format. It cannot connect to filters that require other format types, such as VIDEOINFOHEADER2 or DVINFO. Therefore, it is not compatible with MPEG-2 or DV video, or with field-based video.
• One-shot mode does not work correctly in some circumstances, such as when the upstream filter queues samples on a worker thread.
• It must be connected to a renderer filter, even when the application does not require one (hence the Null Renderer filter).

The GrabberSample source code provides an opportunity for developers to make improvements and modifications suited for their own needs.

Recommendations for Use

When you are using either the original Sample Grabber filter, or the new GrabberSample sample, follow these guidelines:

• Do not call IGraphBuilder::RenderFile and assume that the Filter Graph Manager has inserted the filter in the correct place within a chain of filters. Verify that the filter is connected properly and is using the expected media type.
• You must connect the filter's output pin to a downstream filter. If you want to retrieve data from the streams without rendering it, use the Null Renderer filter.
• You can turn off the graph reference clock to make the filter graph run as quickly as possible. Call the IMediaFilter::SetSyncSource method with the value NULL.