testcap

Testcap – A WDM Streaming Video Capture Driver which requires no Hardware

SUMMARY

Testcap is a prototypical sample WDM stream class video capture driver which does not require any hardware for operation. The driver simulates the front-end components of a PC/TV, including input selection, TvTuning, TvAudio control, and finally, digital video streaming.

The TvTuner component supports tuning modes of Analog TV (NTSC/PAL/SECAM), AM/FM Radio, as well as ATSC (American Broadcast Digital Television).

Testcap manifests itself in a DirectShow graph as four separate filters:

Testcap Capture
Testcap TvTuner
Testcap TVAudio
Testcap Crossbar

The capture portion produces five output streams, two of which are Capture and Preview which produce a variety of colorbars and grayscale patterns depending on the video input selected on the crossbar. The capture and preview streams contain video samples in either RGB24 or YUV422 color spaces and offer a large number of different image dimensions. The other three capture streams are VBI, HWCC, and HWNABTS. These three are VBI streams, and offer simulated CC and NABTS waveforms for decoding, and simulated hardware decoded CC and NABTS.

This driver contains sample implementations for almost all of the property sets involved in WDM video capture. Since Testcap doesn't control actual hardware, most of the property set implementations are useful only as prototypes which you can borrow for your own implementations. This driver represents one extreme of combining all functionality representing the front end of a PC/TV into a single driver. The other extreme is to create a separate driver each element: TvTuner, TvAudio, Crossbar, and Capture.

Keywords: Video capture, WDM, stream class, TvTuner, driver, VBI.

BUILDING THE SAMPLE

The sample is built with the standard DDK BUILD utility in the standard checked or free DDK build environment. Testcap is completely contained in one directory. The resulting binary from the build process is Testcap.sys, which is compatible on x86 and Alpha platforms.

Testcap is not a PnP driver, since no hardware is involved, and it must be installed manually:

My Computer.Properties.Hardware.Hardware Wizard.Add new hardware.
"To install hardware which is not Plug and Play compatible, click Next."
"No, I want to select the hardware from a list."
"What type of hardware do you want to install"
Sound, Video, and Game Controllers
"Have Disk…"
Browse to find "Testcap.inf"
Browse to find "Testcap.sys" when requested

RESOURCES

This driver has been tested with the following applicatons: Graphedt.exe, AMCap.exe, WebTV for Windows.

This website contains general information on driver and hardware development:

http://www.microsoft.com/hwdev

This website contains information on DirectShow:

http://www.microsoft.com/directx

CODE TOUR

File Manifest

File	Description
Testcap.htm	The Sample Tour documentation for this sample (this file).
SOURCES	The generic file for building the code sample.
Testcap.inf	A sample installation file.
CapStrm.h	Declarations of streams and formats supported by the driver.
CapMain.c	DriverEntry(), initialize, un-initialize, and adapter SRB processing.
CapMain.h	Header file for above.
CapVideo.c	Stream SRB processing.
CapVideo.h	Header file for above.
CapXfer.c	Synthesizes images.
CapXfer.h	Header file for above.
CapIRQ.c	Sample IRQ routines.
CapProp.c	Process all adapter property sets including TvTuner, Crossbar, VideoProcAmp, and CameraControl properties.
CapProp.h	Header file for above.
CapVBI.c	Stream SRB processing for VBI pins
CapVBI.h	Header file for above.
DDraw.c	Sample functions for handling kernel DDraw interfaces. Not actually used by this driver at present.
Mediums.h	Describes topological connections for the streams.
Testcap.rc	Resource file mainly for version
VBIdata.c	Contains typical VBI waveforms.
VBIdata.h	Header file for above.
VBIXfer.c	Synthesizes VBI data.
VBIXfer.h	Header file for above.

Programming Tour

DriverEntry() is the initial point of entry for the driver. It initializes the hardware initialization structure and registers the secondary entry point functions.

HwReceivePacket field describes the entry point for receiving SRBs (Stream Request Packet) from stream class driver. Here is a possible sequence of SRBs that this driver may receive.

SRB_INITIALIZE_DEVICE to initialize the device, and called after DriverEntry().
SRB_GET_STREAM_INFO to get supported stream format.
SRB_GET_DATA_INTERSECTION to query a supported format given some key fields.
SRB_OPEN_STREAM to open a stream with supply format from SRB_GET_DATA_INTERSECTION. Two additional entry point functions are register for this stream for controlling the streaming state (Srb->StreamObject->ReceiveControlPacket) and for streaming data (Srb->StreamObject->ReceiveDataPacket).
SRB_CLOSE_STREAM to close the open stream.
SRB_UNINITIALIZE_DEVICE to indicate that a device has been unloaded or removed.

This driver also register entry points for canceling packets (HwCancelPacket) and for notifying if a packet has timeout (HwRequestTimeoutHandler).

Clocks

Testcap, like most video capture drivers, does not act as clock source for a filter graph.

Frame rate and dropped frames

Digital cameras support discrete frame rates; however, a client application can request to stream at any rate. It is required by WDM video capture driver to either match or select the next lower frame rate available. Over sampling can cause synchronization problems.

The dropped frame information is calculated instead of actual count, and it is based on the capture rate and the actual counts of frames captured.

Work items

Testcap is not persisting TvTuner, Crossbar, VideoProcAmp and CameraControl property settings between reboots. For an example of how this should be handled, look at the 1394 digital video conferencing camera driver (1394dcam, capprop.c), also in this DDK.

Top of page