Tips and Tricks for Testing Windows CE .NET Display Drivers

Gary Daniels
Microsoft Corporation

October 2003

Applies to:
    Microsoft® Windows® CE .NET 4.0
    Microsoft Windows CE .NET 4.1
    Microsoft Windows CE .NET 4.2

Abstract

This article describes common display driver problems and explains how you can use the Graphics Device Interface (GDI) test in the Windows CE .NET Test Kit (CETK).

Contents

Introduction
GDI CETK Architecture
Common Display Driver Problems
Additional Resources

Introduction

The Graphics Device Interface (GDI) Microsoft® Windows® CE .NET Test Kit (CETK) is a collection of tests developed by the internal Windows CE .NET Quality Assurance (QA) team to test GDI and display drivers. Although this test suite does not contain all the tests used by the internal QA team, it contains a very large percentage of the tests. Along with the binary versions of the tests, the source code for the GDI CETK is also shipped to assist with debugging. In this article, I'll be going over some tricks for using the GDI CETK efficiently, reviewing common display driver problems, and explaining how to use the GDI CETK to expose these common problems.

GDI CETK Architecture

The CETK framework has two useful features for debugging driver failures. First, while running the CETK tests with a debug connection to Platform Builder, the test output should go to the Debug Output window in platform builder. This is helpful when debugging test failures as you can see which tests are currently running, and you can also see test output when stepping through the test cases. Second, the CETK also gives you the ability to manipulate the command line parameters that are passed to the test suite when it is run.

The GDI CETK is Tux-based (like many of the other CETK tests), so it will take the normal Tux parameters to list the available tests, select the individual test to run, and to set the random seed used to more efficiently reproduce random failures. A feature with Tux that you may not be aware of is the –c option, which will pass the string directly following the option into the test suite selected. The string following the –c option should be in quotes so it is passed exactly as it is given into the test suite.

Generic Verification Functions

The GDI test suite has two generic verification functions; one is the "CheckScreenHalves" which compares the left half of the screen to the right half. The other is the "SurfaceVerification" which compares the image on the primary screen to the image created by the test display driver. The 4.2 version of the GDI CETK will accept a –c "o" option to output bitmaps on either of those failures to the flat release directory, assuming a debug connection is available. The QFE for the 4.2 GDI CETK adds the ability to specify the destination of the bitmap outputted as –c "/O <optional destination>." This is useful for debugging failures on a device that doesn't have a debug connection.

Using the shared source to step through test cases can help you determine the reason for a failure. Within the shared source directory for the CETK, there will be a \private\test\gwes\gdi\gdiapi directory. Within this directory, the files are split into the same categories that the Tux text table is split, drawing, fonts, text, regions, and so on. The main entry point for a test case will be the test name with a _T appended, and it will be in the file matching the test category. For example, BitBlt is a test under drawing, thus the main BitBlt test case is in draw.cpp and the function name is BitBlt_T(…). After you understand the source locations within the test suite, setting breakpoints within the tests is easy and invaluable.

Now that you have an idea about the architecture of the GDI CETK, let's look at some common display driver problems and how the test suite tests them.

Common Display Driver Problems

Some of the most common problem areas in display drivers are with overlapped blits, improperly initialized video memory, hardware line drawing differences, mangled text characters, improper flipping and mirroring of StretchBlt, and the display driver not rotating some drawing operations when rotated.

Overlapped Blits

When doing a BitBlt using a single surface, you can hit scenarios where blits are overlapped and the display driver can overwrite its source while writing the destination. To handle this sort of problem, the driver should adjust its starting point and blitting direction to compensate for the overlap. To verify that the compensation is done, there is a subtest in each of the blitting application programming interface (API) test suites called "BitBltSuite" which goes through a variety of combinations of clipped and overlapped rectangles to test for this problem. As every raster operation (ROP) may be accelerated differently, each could be a separate code path in the driver and would be susceptible to this problem, so the "BitBltSuite" runs the same set of test cases on all the commonly accelerated ROPs.

Improperly Initialized Video Memory

Improperly initialized video memory, or problems with the Peripheral Component Interconnect (PCI) bus accessing video memory is another common display driver problem. Each drawing API has tests which draw on the primary, redraw on a video memory surface, and then compare the two. For BitBlt, StretchBlt, and so on, this test is called GetSetOffscreen.

Hardware Line Drawing Differences

Hardware line drawing sometimes mismatches the software line drawing used within GPE. To compare hardware and software line drawing, the test suite relies on the test verification driver. Small differences between the hardware and GPE are reasonable, so the test suite has a threshold of differences in the comparison. If you see failures in the line drawing tests, outputting bitmaps to compare the software and hardware is extraordinarily useful for determining whether or not the problem is serious.

Mangled Text Characters

Text is passed into the display driver with different bit depths of a mask depending on whether it's ClearType®, antialiased, or draft. If the display driver treats a ClearType mask as an antialiased mask, it can cause problems. The GDI CETK will detect this problem when comparing to the verification driver and will fail. Outputting bitmaps will also help with diagnosing this failure and determining whether or not the problem is serious.

Improper Flipping and Mirroring of StretchBlt

Flipping and mirroring with StretchBlt are done by sending out of order coordinates into the display driver. Occasionally, drivers reorder the coordinates and ignore the flip and mirror. In the StretchBlt test suite, there is a "StretchBltFlipMirror" test which does flipping and mirroring of an image and compares it to a known image.

Rotating Drawing Operations

When rotating the display, the display driver in use rotates the operations on the primary display surface, which is what the user sees on the screen. Off-screen surfaces are left in the normal orientation, which results in Device Independent Bitmaps (DIBs) working as expected with no special manipulation of the surface pointers required. When the primary display is copied to an off-screen surface, GDI handles the rotation back to normal orientation.

The GDI test suite loads a second display driver, which does not support rotation and automatically sets the width and height for its virtual "primary" to match the real primary display. It then duplicates all operations on both display drivers. When the screen comparison is done, the contents of the virtual "primary" (which is not rotated) and the real rotated primary are copied to a DIB that puts them both in the same orientation. The result is a direct comparison of the primary display when rotated to a nonrotated secondary display which has no hardware or software optimizations. This technique will find any instances where a rotation-enabled display driver does not handle the rotation of drawing operations correctly. Because the main cause of test suite failures in this scenario will be drawing differences between the real primary and the nonvisible secondary display driver, outputting bitmaps will be very useful when debugging failures.

Additional Resources

For more information about Windows CE .NET, see the Windows Embedded Web site.

For online documentation and context-sensitive Help included with Windows CE .NET, see the Windows CE .NET product documentation.

For more information about the CETK, and the Tux test harness, consult the Windows CE .NET 4.2 product documentation.