Sample Grabber Filter
[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]
Note
[Deprecated. This API may be removed from future releases of Windows.]
The Sample Grabber filter provides a way to retrieve samples as they pass through the filter graph. It is a transform filter with one input pin and one output pin. It passes all samples downstream unchanged, so you can insert it into a filter graph without altering the data stream. Your application can then retrieve individual samples from the filter by calling methods on the ISampleGrabber interface.
If you want to retrieve samples without rendering the data, connect the Sample Grabber filter to the Null Renderer filter.
| Label | Value |
|---|---|
| Filter interfaces | IBaseFilter, ISampleGrabber |
| Input pin media types | Any media type. |
| Input pin interfaces | IMemInputPin, IPin, IQualityControl |
| Output pin media types | Any media type. Matches input media type. |
| Output pin interfaces | IMediaPosition, IMediaSeeking, IPin, IQualityControl |
| Filter CLSID | CLSID_SampleGrabber |
| Property Page CLSID | No property page. |
| Executable | Qedit.dll |
| Merit | MERIT_DO_NOT_USE |
| Filter Category | CLSID_LegacyAmFilterCategory |
Remarks
To use this filter, add it to the filter graph and call ISampleGrabber::SetMediaType with the desired media type. This method specifies the media type for the filter's input and output pin connections. Then connect the filter to other filters in the graph.
If you call ISampleGrabber::SetBufferSamples with the value TRUE, the filter buffers each sample that it receives before passing it downstream. Call the ISampleGrabber::GetCurrentBuffer method to retrieve the current contents of the buffer. Alternatively, you can call ISampleGrabber::SetCallback to have the filter invoke a callback function whenever it receives a sample.
The filter has the following limitations for video formats:
- It does not support video types with top-down orientation (negative biHeight).
- It does not support the VIDEOINFOHEADER2 format structure (format type equal to FORMAT_VideoInfo2).
- It rejects any video type where the surface stride does not match the video width.
As a result, the Sample Grabber will not connect to the Video Mixing Renderer (VMR) for some video types.
Requirements
| Requirement | Value |
|---|---|
| Header |
|
See also