Microsoft DirectX 8.0

Writing Analog TV Applications

This article contains the following sections:

Analog TV filter graphs are based on analog television tuner-capture cards. A single card will generally contain several devices: the tuner, zero or more crossbars for routing the signal, the analog-to-digital converter (also called the analog video decoder), and possibly a separate device for TV audio. The Microsoft® Windows® Driver Model (WDM) device drivers for each device on the card are supplied by the manufacturer or other third parties. These drivers work together with filters and plug-ins supplied by Microsoft to enable the devices to participate in a filter graph. The Microsoft-supplied components are the TV Tuner filter, the TV Audio filter, the Analog Video Crossbar filter, and the WDM Video Capture plug-in. In GraphEdit, these filters appear in the "WDM Streaming" categories; the friendly name of the filter will vary depending on the driver. Applications discover these filters using the System Device Enumerator. For details on how to discover these devices programmatically, see Enumerating Devices and Filters. For general information on using hardware devices in DirectShow, see How Hardware Devices Participate in the Filter Graph.

In addition to the device filters mentioned previously, an analog TV filter graph will also include kernel mode (KsProxy-based) and user mode filters supplied by Microsoft as part of DirectShow. These filters include the Tee/Sink-to-Sink Converter, VBI Surface Allocator, CC Decoder, Line 21 Decoder, Overlay Mixer, Video Renderer, and possibly others. These filters are discussed in more detail in a later section.

Classes of Analog TV Hardware Devices

In the context of building an analog TV filter graph, there are two basic classes of analog capture cards: (1) those that send the video data directly to video memory through a direct hardware connection called a video port, and (2) those that send the video data first to host memory via the PCI bus, or over a USB or IEEE 1394 connection, and then to the graphics card.

From an application's point of view, there are two basic differences in the filter graphs for video port devices and PCI/USB/1394 devices:

  1. Graphs based on video port devices will require an extra filter, the VBI Surface Allocator. This filter is needed to allocate extra video memory on the video graphics adapter for the VBI bitmaps. It connects to the VPVBI output pin on the capture filter. On PCI devices the Overlay Mixer can allocate this memory, so the VBI Surface Allocator is not needed.
  2. Graphs based on video port devices will use the Bt829 capture filter and graphs based on PCI (and 1394/USB) devices will use the Bt848 capture filter. Graphs using the Bt848 filter will not use the VBI Surface Allocator.

    Analog TV Filter Graph

    The following illustration shows an analog TV filter graph based on the ATI All-In-Wonder card. This graph renders video, audio, and closed-captioned text, and also captures the video and audio to an uncompressed AVI file. (Although this filter graph is somewhat complex, it can be created using the capture graph builder with only a few lines of code. Graph building is discussed later in this section.)

    ATI All-In-Wonder Filter Graph

    TV Tuner: This filter is always the first filter in the graph, although no data actually passes through it. Applications use its IAMTVTuner interface to set the channel-to-frequency mappings, perform channel selection and to obtain information about which video standard the hardware supports.

    Analog Video Crossbar: The crossbar filter is a routing device that applications use to set up the correct data paths for the input signals on the hardware. This filter supports the IAMCrossbar interface. The input pins on this filter represent the physical input from the antenna, cable, and/or auxiliary lines (such as a VCR). Any of the input signals can be routed to one or more of the outputs. The ATI graph illustrated previously has two crossbar filters. The upstream crossbar is for external inputs, and the second is for multiple inputs to the hardware video decoder (also called the analog-to-digital converter), which is represented by the capture filter in the graph. Other cards may have different crossbar configurations.

    Video Capture Filter: This kernel-mode filter represents the analog-to-digital converter on the hardware. It is the first filter in the graph that actually processes the video signal. Microsoft provides the driver that supports the Brooktree 829 capture chip used in video port devices, and IHVs supply drivers for the Brooktree 848, 878, and other video chips. All these drivers use the WDM Video Capture plug-in to provide property pages and expose their COM interfaces. The drivers and the plug-in appear as a single "filter" to applications. Applications use the IAMAnalogVideoDecoder interface on this filter to get and set the supported analog video format, the status of the horizontal sync, and the output bus. The capture filter is capable of creating two separate video streams for output, one for rendering and one for capture. The rendering pin (named VP for Video Port) always connects to input pin zero on the Overlay Mixer. The Overlay Mixer reference page contains more information about video port connections.

    The capture filter outputs the VBI data on a separate pin; some cards may output raw VBI data and some perform the VBI decoding in hardware. All the Microsoft VBI filters correctly handle both raw and decoded data. Since the All-In-Wonder card has a video port, the Bt829 capture filter is used; it has an output pin to the VBI Surface Allocator, which will correctly configure the video memory for the CC overlays that will be provided by the Line 21 Decoder. This filter connects to input pin 1 or greater on the Overlay Mixer.

    AVI Decompressor: The AVI Decompressor filter is a wrapper filter for Video Compression Manager codecs. In an analog TV capture graph, it wraps the MSYUV color space converter which converts the video stream from UYVY to RGB before sending it to the AVI Multiplexer.

    Audio Capture: The Audio Capture filter receives the digitized audio from the Audio Decoder output pin on the crossbar. Note that the data is received on the CD Audio input pin of the Audio Capture filter. This pin actually represents the internal input on the sound card, which can be from any internal source on the host system, not just the CD drive. The other input pins on the Audio Capture filter generally represent the analog inputs for external devices such as microphones, tape players, and so on. The exact pin configuration and pin names might vary on different sound cards. In the graph shown previously, the Audio Capture filter delivers the audio data to the AVI Mux filter.

    Note that this graph does not contain an Audio Renderer filter; this filter is not necessary when the TV card is connected to the sound card by an external cable (or "dongle") to the sound card's input jack. If this cable is not used, then the graph shown above would use the Smart Tee filter downstream from the Audio Capture filter to deliver audio to the Default DirectSound Device as well as to the AVI Mux.

    Tee/Sink-to-Sink Converter: This filter accepts the VBI information from the capture filter and splits it into separate streams for each of the data services present on the signal. Microsoft provides VBI codecs for Closed Caption, NABTS, and World Standard Teletext (WST). In the previous graph, the only service being captured is Closed Caption.

    CC Decoder: The CC VBI decoder is a kernel-mode stream class filter. It has two input pins, VBI and HWCC. It has up to eight output pins, each of which can select their own lines and substreams. Its job is to process captured VBI lines and deliver decoded CC data to the Line 21 Decoder and/or to interested applications. The first output pin is connected to the Line 21 Decoder.

    Line 21 Decoder: The Line 21 Decoder accepts decoded closed-captioned data from the CC Decoder and generates the bitmaps which will be overlaid on top of the video rectangle. This data is then passed to the Overlay Mixer.

    NABTS/FEC VBI Codec Filter (Not shown): The NABTS/FEC VBI Codec is a ring-0 stream class filter. It has two input pins, VBI and HWNABTS. It has up to eight output pins, each of which can select their own VBI scan lines and substreams. Its job is to process captured VBI lines and to distribute decoded and/or forward-error-corrected NABTS data to the BDA SLIP Deframer filter and then to BDA IP Sink, which makes the IP data available to any application via Winsock.

    WST Codec and WST Decoder filters (Not shown): These filters are ring-0 stream class filters that handle teletext data on PAL systems. The WST Codec has one input pin which receives raw VBI data. It has up to eight output pins, each of which can select their own lines and substreams. Its job is to process captured VBI lines and to distribute decoded teletext data to interested applications. The first output pin is connected to the WST Decoder which creates the bitmaps for the hardware overlay in the same way as the Line21 Decoder works for closed-captioned data.

    Overlay Mixer: This DirectShow filter performs the actual rendering of the video onto the system's video memory. It is used with both video port and non-video port types of hardware.

    Video Renderer: In all graphs that use the Overlay Mixer to render the video, the Video Renderer acts merely as a window manager that informs the Overlay Mixer where on the screen to place the video rectangle.

    Building The Graph

    An analog TV graph is simply one type of WDM video capture graph. It can be built using the capture graph builder, as discussed in the article How to Write a Capture Application and demonstrated in the AMCap sample application. As demonstrated in AMCap, the basic principle is to start with the capture filter and then add the downstream filters for each of its pins that you wish to render or capture. The upstream filters are added last. Although AMCap does show how to pull in the CC Decoder and Line 21 Decoder filters to render closed-captioned data, it does not demonstrate how to pull in other VBI-related filters for capturing NABTS or teletext data.

    Capturing VBI Data

    DirectShow provides kernel-mode filters for capturing NABTS, Line 21, and World Standard Teletext (WST) data (for PAL signals) from the vertical blanking interval (VBI) of an analog TV broadcast signal. These filters appear in GraphEdit under the WDM Streaming VBI Codecs category. The capture filter has an output pin that delivers raw VBI data to the Tee/Sink-to-Sink Converter, which examines the data for any NABTS IP data, Line 21 closed captioning, or teletext information that may be present on the signal, and creates an output pin for each data type. To add the filters for decoding closed-captioned or teletext data, use the ICaptureGraphBuilder2::RenderStream method on the appropriate output pin of the MSTee filter. The previous illustration shows the filters for capturing and rendering CC data, and the AMCap sample demonstrates how to add the closed-captioned filters to the graph. For NABTS IP data (such as interactive TV enhancements including Web pages and images), you must manually add and connect the chain of filters downstream from the Video Capture filter. The following illustration shows the VBI segment of a graph that handles both NABTS data and closed captions. Note the addition of the Tee/Sink-to-Sink Converter filter to split the VBI data into two streams.

    NABTS and closed captioning filter graph segment

    There are no application-callable interfaces on these kernel-mode filters. They simply function as a data pipeline that extracts SLIP-encoded IP packets from the VBI signal and passes them on to Winsock.

    For teletext data, the filters appear as shown in the following illustration.

    World Standard Teletext filter graph segment

    Some capture devices perform NABTS, teletext or CC decoding in hardware. When this is the case, the capture filter will expose a special output pin and the downstream decoder simply passes the data through without modifying it. No special programming is required by the application developer.

    Line 21 of the VBI contains not only closed-captioned text but can also contain URLs for Web pages associated with the current broadcast. This is described as "Transport B" in the ATVEF specification.

    Analog TV Tuning

    The basic order of operations when controlling the TV tuner is as follows:

    1. If necessary, establish a video path from the tuner through a crossbar to the video digitizer (capture filter) using the IAMCrossbar interface on the Analog Video Crossbar filter.
    2. Call the IAMTuner::put_Mode method to set the tuner card to the type of broadcast to be received (TV, AM radio, FM radio, and so on).
    3. Set the country code with IAMTuner::put_CountryCode to establish the correct TV channel-to-frequency mappings. See International Analog TV Tuning for more information on country codes.
    4. For each input on the tuner, call IAMTVTuner::put_InputType to set the input type to cable or antenna. Use IAMTVTuner::put_ConnectInput to select one of the available tuner inputs.
    5. Call IAMTVTuner::get_TVFormat to retrieve the current video format, and then use this value to set the Capture Filter with a call to IAMAnalogVideoDecoder::put_TVFormat.
    6. Call IAMTuner::put_Channel to begin viewing.