Source Filter Basics

Source Filter Basics

As explained in the previous section, a source filter usually pushes its media samples to the input pin of a downstream filter. (The exception is file source filters.) Live sources, such as capture source filters, are always push sources because the data is generated somewhere outside the filter graph (such as in a camera or a microphone) and presented through a driver to the filter as a continuous stream of data. The PushSource filter covered in this chapter also pushes media samples to downstream filters, but these samples are generated in system memory rather than from a capture device.

A source filter generally doesn t have any input pins, but it can have as many output pins as desired. As an example, a source filter could have both capture and preview pins, or video and audio pins, or color and black-and-white pins. Because the output pins on a source filter are the ultimate source of media samples in the filter graph, the source filter fundamentally controls the execution of the filter graph. Filters downstream of a source filter will not begin execution until they receive samples from the source filter. If the source filter stops pushing samples downstream, the downstream filters will empty their buffers of media samples and then wait for more media samples to arrive.

The DirectShow filter graph has at least two execution threads: one or more streaming threads and the application thread. The application thread is created by the Filter Graph Manager and handles messages associated with filter graph execution, such as run, pause, and stop. You ll have one streaming thread per source filter in the filter graph, so a filter graph with separate source filters to capture audio and video would have at least two streaming threads. A streaming thread is typically shared by all the filters downstream of the source filter that creates it (although downstream filters can create their own threads for special processing needs, as parsers do regularly), and it s on these threads that transforms and rendering occur.

Once the streaming thread has been created, it enters a loop with the following steps. A free (that is, empty) sample is acquired from the allocator. This sample is then filled with data, timestamped, and delivered downstream. If no samples are available, the thread blocks until a sample becomes available. This loop is iterated as quickly as possible while the filter graph is executing, but the renderer filter can throttle execution of the filter graph. If a renderer s sample buffers fill up, filters upstream are forced to wait while their buffers fill up, a delay that could eventually propagate all the way back to the source filter. A renderer might block the streaming thread for one of two reasons: the filter graph could be paused, in which case the renderer is not rendering media samples (and the graph backs up with samples); or the renderer could be purposely slowing the flow of samples through the filter graph to ensure that each sample is presented at the appropriate time. When the renderer doesn t care about presentation time such as in the case of a filter that renders to a file the streaming thread runs as quickly as possible.

Seeking functionality should be implemented by the source filters where appropriate. Downstream filters and the Filter Graph Manager can use the IMedia Seeking interface to rewind or fast-forward through a stream. Seeking a live stream doesn t have to be implemented (it could be useful, such as in the case of a TV broadcast), but source filters should be able to seek as appropriate. When a seek command is issued, the Filter Graph Manager distributes it to all the filters in the filter graph. The command propagates upstream across the filter graph, from input pin to output pin, until a filter that can accept and process the seek command is found. Typically, the filter that creates the streaming thread implements the seek command because that filter is the one providing the graph with media samples and therefore can be sent requests for earlier or later samples. This is generally a source filter, although it can also be a parser transform filter.

When a source filter responds to a seek command, the media samples flowing through the filter graph change abruptly and discontinuously. The filter graph needs to flush all the data residing in the buffers of all downstream filters because all the data in the filter graph has become stale ; that is, no longer synchronized with the new position in the media stream. The source filter flushes the data by issuing an IPin::BeginFlush call on the pin immediately downstream of the filter. This command forces the downstream filter to flush its buffers, and that downstream filter propagates the IPin::BeginFlush command further downstream until it encounters a renderer filter. The whole process of seeking and flushing looks like that shown in Figure 12-4. Both seek and flush commands are executed on the application thread, independent of the streaming thread.

Figure 12-4. Seek and flush commands move in opposite directions across the filter graph