DirectShow Video Capture Filters

Microsoft DirectShow 9.0

DirectShow Video Capture Filters

Capture filters in DirectShow have some features that distinguish them from other kinds of filters. Although the Capture Graph Builder hides many of the details, it is a good idea to read this section, in order to have a general understanding of DirectShow capture graphs.

Pin Categories

A capture filter often has two or more output pins that deliver the same kind of data — for example, a preview pin and a capture pin. Therefore, media types are not a good way to distinguish the pins. Instead, the pins are distinguished by their functionality, which is identified using a GUID, called the pin category.

For a discussion of how to query pins for their category, see Working with Pin Categories. For most applications, however, you will not have to query pins directly. Instead, various ICaptureGraphBuilder2 methods take parameters that specify the pin category on which to operate. The Capture Graph Builder automatically locates the correct pin.

Preview Pins and Capture Pins

Some video capture devices have separate output pins for preview and capture. The preview pin is used to render video to the screen, while the capture pin is used to write video to a file.

A preview pin and a capture pin have the following differences:

  • A preview pin drops frames as needed to maintain throughput on the capture pin.
  • Each frame from a capture pin is time-stamped with the stream time when the frame was captured. A preview pin does not time stamp the samples it delivers. 

The reason that preview frames do not have time stamps is that the filter graph introduces a small amount of latency into the stream. If the capture time is used as the presentation time, the video renderer treats every sample as being slightly late. This can cause the video renderer to drop frames while it tries to catch up. Removing the time stamps ensures that the renderer presents each sample when it arrives, without dropping frames.

The pin category for preview pins is PIN_CATEGORY_PREVIEW. The category for capture pins is PIN_CATEGORY_CAPTURE.

Video Port Pins

A video port is a hardware connection between a video device (such as an analog TV tuner) and the video card. A video port enables the device to send video data directly to the graphics card. The video is displayed on the screen using a hardware overlay. A video port might be an actual cable that connects two devices on separate cards; or it might be a hard-wired connection on the same card.

The advantage of a video port is that the video goes directly into video memory, without any work by the CPU. However, video ports have some drawbacks:

  • A video port always uses the overlay surface during capture, regardless of whether you want to preview the video.
  • Flipping between frames occurs automatically, which makes it difficult to synchronize the flip with other video operations.

If a capture device uses a video port, the capture filter has a video port pin instead of a preview pin. The pin category for video port pins is PIN_CATEGORY_VIDEOPORT.

Every capture filter has at least one capture pin. In addition it might have a preview pin or a video port pin, but never both. Filters can have multiple capture pins and preview pins, each delivering a separate media type. Thus, a single filter could have a video capture pin, a video preview pin, an audio capture pin, and an audio preview pin. (There is nothing equivalent to a video port for audio, however.)

Upstream WDM Filters

Windows Driver Model (WDM) devices may require some additional filters upstream from the capture filter. These filters include the following:

  • TV Tuner Filter. Controls tuning for analog TV tuners.
  • TV Audio Filter. Controls audio settings for analog TV tuners.
  • Analog Video Crossbar Filter. Routes video and audio signals through the hardware device. For example, a device might have multiple inputs, such as S-Video and composite video. The crossbar filter enables the application to select the input.

Although these are separate filters in DirectShow, they typically represent the same hardware device. Each filter controls a different function of the device. The filters are connected by pins, but no media data moves across the pin connections. Therefore, the pins on these filters do not connect by establishing a media type. Instead, they use GUID values called mediums. Medium GUIDs are uniquely defined for a given device minidriver. For example, the TV Tuner filter and the Video Capture filter for the same TV card will both support the same medium, which enables the application to build the graph correctly.

In practice, as long as you are using ICaptureGraphBuilder2 to build your capture graphs, these filters are added to the graph automatically. For a more detailed discussion, see WDM Class Driver Filters.