Chapter 11: Using the Sample Grabber Filter

Chapter 11

Using the Sample Grabber Filter

Although many Microsoft DirectShow applications will benefit from the creation of a transform filter, transform filters can be difficult to test. Often, a programmer needs to construct a second filter just to test the output from his first one. The DirectShow Sample Grabber filter answers this need, although as we will see in this chapter, it can be used for much more than testing purposes.

The Sample Grabber is a standard transform filter that, in itself, does nothing to the media samples that pass through it. However, it exposes the ISampleGrabber interfaces to any DirectShow application that instantiates it. This interface allows you to hook your application into the media stream as it passes through the Sample Grabber. You can use the Sample Grabber to examine output from nearly any upstream filter because there are few restrictions on where the Sample Grabber is placed within the media stream. (It is neither a source nor a renderer filter, however, and any filter graph with the Sample Grabber must have both source and renderer filters.) The Sample Grabber allows a DirectShow application unrestricted access to the stream of media samples, in any media format that can be generated by a filter graph.

The Microsoft DirectX SDK actually contains two filters that expose the filter graph s media samples to an application: the Sample Grabber, a pre-built DirectShow filter; and the Grabber Sample, a sample Microsoft Visual C++ project. Although both perform essentially the same function, there are some interface differences between them, which would be reflected in the implementation of an application that used one or the other. In the first half of this chapter, we ll examine how you could use the Sample Grabber in a DirectShow application. In the second half, we ll explore the construction of the Grabber Sample and learn how a filter can connect to your applications.

The Sample Grabber delivers a powerful capability that can be employed in at least two ways. First, the Sample Grabber provides a mechanism with which on-the-fly analysis of a media stream can be performed. You can peek into a stream as it flows across the filter graph. For example, you might want to get audio levels from an audio track, so you could track the loudest sounds in a recording. Second, the Sample Grabber allows you to perform in-place transformations on the sample data. As long as the data that the Sample Grabber sends to you is returned in the same media sample, the Sample Grabber doesn t care what the application does with it. So, the application could silence audio data, replace a video stream with a test pattern, or, in the case of the Histogram application examined in this chapter, perform an analysis of each video frame, adjusting the visible qualities of the image. You can create an application with all the capabilities of a DirectShow filter (within the limits of an in-place transform) without having to create a filter.

When dropped into a filter graph, such as the one created by the Histogram application, the Sample Grabber looks just like any other transform filter, as shown in Figure 11-1.

Figure 11-1. The Sample Grabber filter, which fits into the media stream as a normal transform filter

However, this filter graph doesn t tell the whole story because data is flowing from the Sample Grabber up to the Histogram application and back down again, as shown in Figure 11-2.

Figure 11-2. The Sample Grabber passing media samples to the Histogram application for processing

Every time the Sample Grabber receives a media sample to process, it signals to the Histogram (through a callback routine registered by the Histogram application when the Sample Grabber is instantiated) that a sample is ready. The Histogram processes the sample during the callback and returns control to the Sample Grabber when complete. The media sample is then presented on the output pin of the Sample Grabber and continues downstream.