Mirror - Mirror driver for mirroring GDI content

Description

The Mirror sample demonstrates a driver that performs video mirroring.

Theory of Operation

When video mirroring is active, each time the system draws to the primary video device at a location inside the mirrored area, a copy of the draw operation is run on the mirrored video device in real time. With this mirroring scheme, you can simultaneously draw the same output to several video devices. Because the driver allocates memory dynamically for targets, the number of display devices that your system can support depends on how much free memory you have at mirror time.

This sample is designed to provide information about a standard, generic method of mirroring. This eliminates the need for special case-by-case solutions that were used before this support was added to the system. The sample runs on the Microsoft Windows 2000 and later operating system versions, excluding Windows Millennium. It features commented source code that documents in detail how the code works, to make it easy to modify and extend. Note that this sample is the first version of the video mirror sample. Additional functionality might be added to the sample in future releases.

The sample consists of the following parts:

  • The display driver in, for example, CD C:\WINDDK\<build number>\src\video\displays\mirror\disp. The WINDDK location and build number can vary.

  • The video miniport driver in, for example, CD C:\WINDDK\<build number>\src\video\displays\mirror\mini. The miniport driver that is in this location is a skeleton. The miniport driver simply returns success status for all miniport driver calls that the operating system makes as there is no real hardware that is controlled by the mirror sample.

  • An application that is a sample user-mode service in, for example, CD C:\WINDDK\<build number>\src\video\displays\mirror\app.

Implementation and Design

The following sections describe implementation information about the Mirror sample:

Mirror Display Driver Requirements

A mirrored display driver must implement at least the following functions:

  • DrvEnableDriver [exported]

  • DrvEnablePDEV

  • DrvCompletePDEV

  • DrvDisablePDEV

  • DrvEnableSurface

  • DrvDisableSurface

  • DrvBitBlt

  • DrvCopyBits

  • DrvCreateDeviceBitmap

  • DrvDeleteDeviceBitmap

  • DrvTextOut

Mirror Miniport Driver Requirements

A mirrored miniport driver must implement at least the following functions:

  • DriverEntry [exported]

  • HwVidFindAdapter

  • HwVidInitialize

  • HwVidStartIO

Because there is no physical display device that is associated with a mirrored surface, these miniport driver functions can return positive results.

Building the Sample

  1. Change to the directory that contains the device source code (for example, CD C:\WINDDK\<build number>\src\video\displays\mirror\disp. The WINDDK location and build number can vary).

  2. Run build -ceZ, or use the BLD macro. This command calls the Microsoft make routines to build the components.

If the build succeeds, you will find the drivers, mirror.dll and mirror.sys, and the application, ddmlapp.exe, in the %_BuildArch% subdirectories of the %TARGETPATH% directories that you specified in the Sources files.

If it fails, you can find errors and warnings in the build error (.err) and warning (.wrn) log files, respectively (for example, buildfre_wlh_x86.err).

Installation

General

The Mirror sample provides the Mirror.inf file in, for example, CD C:\WINDDK\<build number>\src\video\displays\mirror\app, to install the sample.

End User

To install the sample, copy Mirror.dll to %winnt%\system32, and copy Mirror.sys to %winnt%\system32\drivers.

In the Device Manager click Action, click Add Legacy Hardware.

Select the Install the hardware that I manually select from a list (advanced) option and click Next.

Select Display Adapters and click Next. Click Have Disk..., browse to the folder that contains Mirror.inf and select it.

Select the Microsoft Mirror Driver and click Next.

The driver will be installed.

After the driver is installed, you should be able to see Microsoft Mirror Driver under Display Adapters category.

Testing

The following is a list of common tasks that you can perform when you run the mirrored driver on a mirrored device:

Change the mirrored device settings

To change the settings for your mirrored device, you must know the '\\.\DISPLAY#' name that is associated with your mirrored display. In the case of multiple instances of display adapters, '#' represents different numbers. These names can be found by iterating through the available display devices by using the EnumDisplayDevices function. For more information about EnumDisplayDevices, see the Microsoft Windows SDK documentation. For reference and testing only, these names can be found under the following key:

     HKLM\HARDWARE\DeviceMap\Video

Attach the mirrored device to the desktop pdev list

To attach the mirrored device to the desktop pdev list, add a registry value Attach.ToDesktop = 0x1. Subsequent calls to the ChangeDisplaySettings function will then dynamically load the mirrored display driver for use. For more information about ChangeDisplaySettings, see the Microsoft Windows SDK documentation.

HKLM\SYSTEM\CurrentControlSet\Hardware Profiles\Current\System\CurrentControlSet\

     Services\mirror [where 'mirror' is short name of mirrored surface]

          Device#\Attach.ToDesktop 0x1 (DWORD)

Detach the mirrored device from the desktop pdev list

To disable the attachment to the desktop pdev list, set Attach.ToDesktop to 0x0. If you do not detach the mirrored device from the desktop pdev list, your driver will be invoked again the next time the system boots. To save the other Default.Settings values that were saved under this key, call ChangeDisplaySettings with dwFlags set to CDS_UPDATEREGISTRY.

Create a DC or device-managed bitmap

To create a DC, device-managed bitmap, and so on by using the mirrored surface, use the ordinary GDI functions. To create the DC, call the CreateDC function as shown in the following example code. For more information about CreateDC, see the Microsoft Windows SDK documentation.

HDC hdc = CreateDC("DISPLAY", // driver name

     deviceName, // example 'mirror' device name

     NULL,

     NULL);

Code Tour

File Manifest

File Description

src\video\displays\mirror\app\ddmlapp.rc

This file defines resource information for the Mirror sample user-mode service application.

src\video\displays\mirror\app\main.cxx

The source code for the Mirror sample user-mode service application.

src\video\displays\mirror\app\makefile

This file redirects to the real makefile, which is shared by all of the components of the WDK.

src\video\displays\mirror\app\mirror.inf

Sample INF for installing the sample components.

src\video\displays\mirror\app\mirror.reg

This file contains registry entries for the Mirror sample.

src\video\displays\mirror\app\sources

Generic file that lists source files and all the build options.

src\video\displays\mirror\disp\debug.c and debug.h

Debug code.

src\video\displays\mirror\disp\driver.h

This file contains prototypes for the frame buffer driver.

src\video\displays\mirror\disp\enable.c

This file contains the functions that enable and disable the display driver, the pdev, and the surface.

src\video\displays\mirror\disp\mirror.rc

This file defines resource information for the Mirror sample display driver.

src\video\displays\mirror\disp\makefile

This file redirects to the real makefile, which is shared by all of the components of the WDK.

src\video\displays\mirror\disp\mirror.htm

Documentation for the Mirror sample.

src\video\displays\mirror\disp\screen.c

This file initializes the GDIINFO and DEVINFO structures for DrvEnablePDEV.

src\video\displays\mirror\disp\sources

Generic file that lists source files and all the build options.

src\video\displays\mirror\mini\makefile

This file redirects to the real makefile, which is shared by all of the components of the WDK.

src\video\displays\mirror\mini\mirror.c and mirror.h

These files contain the functions that control the video miniport driver.

src\video\displays\mirror\mini\mirror.def

This file lists the DriverEntry function that the driver exports.

src\video\displays\mirror\mini\mirror.rc

This file defines resource information for the Mirror sample video miniport driver.

src\video\displays\mirror\mini\sources

Generic file that lists source files and all the build options.

 

 

 

Send comments about this topic to Microsoft

Build date: 8/17/2012