[This is
preliminary documentation and subject to change.]
The BDACap sample is
based on the AVSHwS sample provided in the AVStream samples directory.
Modifications were made to allow the original AVSHwS sample to work the the
BDATuner sample. The purpose of the
sample is to demonstrate how to write a pin-centric AVStream minidriver. The
sample also shows how to implement DMA by using the related functionality
provided by AVStream.
The driver is designed to
be used with the BDA sample software tuner driver (BDATuner.sys).
Build the sample by
typing build -cz in either the standard checked
or free build environment. A successful build produces BDACap.sys.
To use the driver you
should build both BDACap.sys and BDATuner.sys.
Copy these files along with the BDA sample tuner INF (BDATuner.inf), the
BDA sample capture INF (BDACap.inf), and the software receiver INF
(BDASWRcv.inf) to an installation directory on the target machine. To start installation of the drivers, right
click on BDASWRcv.inf and select Install.
The sample works on x86
platforms and builds correctly using Microsoft® Visual C® 6.0. The driver uses
Plug and Play.
This sample runs on
Microsoft® Windows® 2000 and Windows XP®.
DriverEntry in device.cpp is the
initial point of entry. This routine passes control to AVStream through a call
to KsInitializeDriver. In this call, the minidriver passes the device
descriptor, an AVStream structure that recursively defines the AVStream object
hierarchy for a driver. This is common behavior for an AVStream minidriver.
At device start time (see
the CcaptureDevice::PnpStart method in device.cpp), a simulated
piece of capture hardware is created (the ChardwareSimulation class), a DMA adapter is acquired from the operating system and is
registered with AVStream through a call to KsDeviceRegisterAdapterObject.
This call is required for a sample that performs DMA directly into the capture
buffers, instead of using DMA to write to a common buffer.
Filter.cpp is where the sample lays out the
KSPIN_DESCRIPTOR_EX structure for the single capture pin. In addition, a
KSFILTER_DISPATCH structure and a KSFILTER_DESCRIPTOR structure are provided in
this source file. The filter dispatch provides only a create dispatch, a
routine that is included in Filter.cpp. The process dispatch is provided
on the pin, since this is a pin-centric sample.
Capture.cpp contains source for the transport
input and output pins on the capture filter. This is where the KSPIN_DISPATCH
structure for the unique pin is provided. This dispatch structure specifies a
Process callback routine, also defined in this source file. This routine is
where stream pointer manipulation and cloning occurs.
The process callback is
one of two routines of interest in Capture.cpp that demonstrate how to do
DMA transfers using AVStream functionality. The other is CCapturePin::CompleteMappings.
These two methods show how to use the queue, obtain clone pointers, use
scatter/gather lists, and perform other DMA-related tasks.
Hwsim.cpp contains the hardware simulation
code and also code that fills the scatter/gather mappings. This source file
includes the Start, Pause and Stop methods for the hardware simulation class
(CHardwaresimulation). Transport synthesis code is also here. The supplied
objects provide a framework for synthesizing transport data.
See comments in all .cpp
files. Also see complete AVStream documentation in the DDK documentation.
Once
installation is complete, access the driver through the graphedt tool. Graphedt.exe is available
in the Tools directory of the DDK. In the Graphedt application, click
the Graph menu and select Insert Filters. Click Insert Filter and the sample appears under “Bda Receiver Component” as a single filter
labelled as “Sample BDA Capture”. Then insert a Network Provider (ATSC) , connect it the the “Sample BDA Tuner”, and attach the
output of the Sample BDA Tuner filter to the input of the Sample BDA Capture
Filter. The Sample BDA Tuner Filter appears under the category “BDA Source
Filters”. Finally attach the output of the capture filter to the input pin of
the MPEG-2 Demultiplexer filter.
The sample BDA capture
appears under "BDA Receiver Components" as "Sample BDA
Capture". The sample BDA tuner
appears under “BDA Source Filters” as “Sample BDA Tuner Filter”. The MPEG-2 demultiplexer appears under
“DirectShow Filters” as “MPEG-2 Demultiplexer”.
For more
information on AVStream, see the DDK documentation.
File Description