Grabber 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 "SampleGrabber Example," to indicate that it is an example implementation.
- The CLSID has been changed to CLSID_GrabberSample.
- The filter supports a new interface, IGrabberSample.
Path
Source: (SDK root)\Samples\C++\DirectShow\Filters\Grabber
Sample Description
The Grabber is a 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.
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 Grabber filter source code provides an opportunity for developers to make improvements and modifications suited for their own needs.
Recommendations for Use
When you are using the Grabber sample filter, 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.
- The filter does not synchronize itself with the main application thread, so the application must handle multithreading issues.
- Unlike the Sample Grabber filter, the Grabber sample does not buffer the data or support "one-shot" mode.
For more information, see How To Get Data from a Microsoft DirectShow Filter Graph at the MSDN Web site.
See Also