The AVSHwS sample provides a pin-centric AVStream capture driver for a simulated piece of hardware. The
driver performs captures at 320x240 in either an RGB24 or YUV422 format via
direct DMA into capture buffers. 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.
This sample features enhanced
parameter validation and overflow detection.
Build the sample by typing build -cez in either the standard
checked or free WDK build environment. A successful build produces AVSHwS.sys.
The sample works on
32-bit x86 and 64-bit amd64 platforms running Vista Beta 2 or higher, Windows XP
SP2, Windows Server 2003 SP1 and Windows 2000 (If DirectX 8 or higher is
installed on the system)
Installation
instructions:
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. In PnPStart
the driver creates the KS Filter for this device dynamically by calling KsCreateFilterFactory.
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 video
capture pin 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). Image synthesis and overlay code is
also here. The supplied objects provide image synthesis (pixel, color-bar,
etc...) to RGB24 and UYVY buffers as well as software string overlay into these
buffers. The Image.cpp file, including data,
must exist in locked segments.
See comments in all .cpp files. Also see complete AVStream
documentation in the WDK documentation.
Once
installation is complete, access the driver through the graphedt
tool. Graphedt.exe
is available in the Tools directory of the WDK. In the Graphedt application, click the Graph menu and select
Insert Filters. The sample appears under "WDM Streaming Capture
Devices" as "avshws Source." Click
Insert Filter and the sample appears in the graph as a single filter labelled as ”avshws
Source”. There is one output pin which is the video capture pin. It sends out
video in YUY2 format. Attach this filter to either a DirectShow Video Renderer or the VMR default video renderer
and click Play.
The output produced by
the sample is a 320x240 image of standard EIA-189-A color bars. In the middle
of the image near the bottom, a clock appears over the image. This clock
displays the elapsed time since the graph was introduced into the run state
following the last stop. The clock shows MINUTES:SECONDS.HUNDREDTHS.
In the top left corner of
the image, a counter counts the number of frames that have been dropped since
the graph was introduced into the run state after the last stop.
For more
information on AVStream, see the WDK documentation.
File Description
AVSHwS.htm The Sample Tour documentation for this sample (this file).Sources The generic file for building the code sample.AVSHwS.inf A sample installation file.
AVSHwS.h The main header file for the sample.
device.cpp DriverEntry, Plug and Play handling, initialization, device level code.
device.h Header file for above.
filter.cpp Filter level code for the capture filter.
filter.h Header file for above.
capture.cpp Pin level code for the capture pin, DMA handling.
capture.h Header file for above.
hwsim.cpp Hardware simulation code, filling scatter/gather mappings, etc.
hwsim.h Header file for above.
image.cpp RGB24 and UYVY image synthesis and overlay code.
image.h Header file for above.
purecall.c Purecall stub for virtual function usage
AVSHwS.rc Resource file mainly for version.