Windows Virtual Display Driver

This directory contains a code and a visual studio solution for a driver which instantiates and controls virtual displays on a host machine.

See: Virtual Displays for Automated Tests and GSoC 2023 project Proposal

The client-side controller for this driver lives in: //third_party/win_virtual_display/controller.

Prerequisites

Driver Development Kit

1. Download the windows Enterprise Windows Driver Kit (Windows 11, version 22H2 required).
2. Mount the ISO.
3. (Optionally) Copy the contents of the mounted ISO to a directory on C:/ (e.g. C:/wdk)
4. Open LaunchBuildEnv.cmd in the root of the EWDK directory.

Building

Note that the following instructions are for use with the EWDK and the command line. Building from Visual Studio is not covered here.

Building the Driver

The build steps must be completed in an environment from LaunchBuildEnv.cmd in the Driver Development Kit section above.

cd third_party\win_virtual_display\driver
msbuild /t:build /property:Platform=x64

Installing the Driver

After Building the Driver, the driver package will be located in x64\Debug\ChromiumVirtualDisplayDriver.

Install the driver:

In an Elevated command prompt:

cd x64\Debug\ChromiumVirtualDisplayDriver
pnputil /add-driver *.inf /install /subdirs

Note: During development, the driver may fail to install due to an untrusted development certificate. To allow the install, add the certificate as a trusted authority:

1. Open the certificate “ChromiumVirtualDisplayDriver.cer” in x64\Debug.
2. Click Install Certificate.
3. Select “Local Machine”.
4. “Place all certificates in the following store”, click “Browse...”.
5. Select “Trusted Root Certification Authorities”, click OK.
6. Click Next.
7. Click Finish.

Running the Sample Executable

The sample executable code is located in //third_party/win_virtual_display/controller. It can be built and ran with the following commands:

autoninja -C out/Default display_driver_controller_executable
./out/Default/display_driver_controller_executable

Note that running the executable (second command above) requires an an elevated command prompt.

Running the executable will instantiate a software device (driver) which will run the driver code to create the virtual displays. After running the executable, you should expect to see several more displays appear in the Windows display settings panel. Note that this does not work over Remote Desktop and you must use another solution like Chrome Remote Desktop.

Tracing / Debugging

Tracing is achieved with the In-flight Trace Recorder. Tracing can be added to Driver.cpp using TraceLog. Example:

TraceEvents(TRACE_LEVEL_ERROR, TRACE_DRIVER , "WdfDriverCreate failed, %!STATUS!", ntStatus);

Note that the file which includes TraceEvents must have the appropriate flags set in the .vcxproj:

<ClCompile Include="Driver.cpp">
<WppEnabled>true</WppEnabled>
<WppRecorderEnabled>true</WppRecorderEnabled>
<WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
</ClCompile>

In order to view the logs, use the TraceView tool included in the windows SDK. For example it might be located here:

C:\wdk\Program Files\Windows Kits\10\Tools\10.0.22621.0\x64\traceview.exe

Once TraceView is running:

1. File -> Create New Log Session.
2. Select “PDB (Debug Information) File” and click “...”.
3. (Must build the solution first). Select ChromiumVirtualDisplayDriver.pdb file (located in x64/Debug/ChromiumVirtualDisplayDriver.pdb).
4. Click OK.
5. click Next.
6. Click Finish.

Now the drivers log events will appear in the window.