Touch Driver Verification Tool (Compact 2013)
3/26/2014
CETouchView is a tool that aids in the verification of single-touch and multi-touch hardware platforms. You can use this tool to verify that the touch driver for your device is producing accurate touch events and that GWES is using the touch events to produce the correct gesture messages. In addition you can record a touch session so that you can analyze or play it back later.
Test Prerequisites
Your device must meet the following requirements before you run this test.
The following prerequisites must be met to run this test.
Hardware Prerequisites
The target device needs to have a touch screen. CETouchView can work with single-touch, symmetric multi-touch, and true multi-touch screens.
Software Prerequisites
The following table shows the software requirements for the Windows Embedded Compact-based device that will be running CETouchView.
Requirement |
Description |
|---|---|
Streaming Touch Driver |
CETouchView only works with devices that use the updated touch driver model introduced in Windows Embedded Compact 7. The old driver model was incapable of producing multiple touch points. |
CETouchView.exe |
This is the device-side application which displays the touch points and gestures. It provides several ways to display the touch and gesture data. |
CETouchFilter.dll |
This is the DLL that is used in place of tchproxy.dll, allowing CETouchView to intercept the touch events directly from the touch driver. This DLL sits between the touch driver and GWES. It is also capable of recording touch data in a human-readable format which can also be played back. |
Subtests
This test has no subtests.
Setting Up the Test
If you are only interested in viewing gesture messages, you can just run CETouchView.exe. None of the raw touch data functionality of the tool will do anything in this case.
In order to view both raw touch data and gesture messages:
1. Under HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP\TOUCH create a new string value "DriverExName" and then copy the value from "DriverName" into it.
2. Set the string value "DriverExName" to be "CETouchFilter.dll"
3. Put CETouchView.exe and CETouchFilter.dll in either image or release folder
4. Reboot the device
5. Run CETouchView.exe
Running the Test
CETouchView runs full-screen on the device, covering up any other applications. The content region of the screen displays a graphical representation of the touch data. There is also a Data Window in the screen which displays useful data about the most recent touch and gestures events that CETouchView has received. Finally, there is a button that brings up the Options Dialog which can be used to configure CETouchView, changing the location of controls, changing what information gets displayed, changing how touch and gesture data gets displayed in the content region, and controlling the recording and playback modes.
To use CETouchView, just tap and gesture within the content region. With the initial settings, Black dots show raw touch points, colored dots show the gesture points of single-touch gestures, and circles show the gesture points of multi-touch gestures.
Within the Options Dialog there are the following panes detailed below.
Note: Each one of these settings can also be set via registry, using the keys specified at the end of the setting description. All of the registry keys are located here: HKLM\SOFTWARE\Microsoft\CETouchView
Display Mode
This pane contains radio buttons for Raw, Gesture, Raw + Gesture, Text, and Bar
* Raw: Show data from CETouchFilter. If the filter is not installed, this option is disabled (DisplayMode=1)
* Gesture: Show data from GWES (WM_GESTURE). If the filter is not installed, and current setting is Raw or Raw + Gesture, this should be selected (DisplayMode=2)
* Raw + Gesture: Show both Raw and Gesture data. If the filter not installed, this option is disabled (DisplayMode=3)
* Text: Display sample text in middle of screen that can be stretched and pinched. (DisplayMode=4)
* Bar: Display a horizontal bar that can be moved, stretched and pinched. (DisplayMode=5)
This pane also contains checkboxes for Trailing, Contact, Data and Statistics
* Trailing: Do not erase previous touch data if checked. If unchecked, screen will be cleared after each touch session (GID_END is received). (ShowTrailing=0/1)
* Contact: Show contact area rectangle if checked. This option is disabled if the filter is not installed, or if Text or Bar is selected. Raw data will appear as a rectangle instead of a dot if contact area information is valid from the driver. (ShowContact=0/1)
* Data: Display Statistics, Warning, Gesture and Raw data in display area onscreen if checked. If you uncheck this option, CETouchView will display a message box informing that warning and statistics data will not be shown if they are enabled. (ShowData=0/1)
* Statistics: If check box is checked, UI will display statistics data after each gesture session in the Data Window. (ShowStatistics=0/1)
Display Offset
This pane allows you to specify an offset between the actual touch point and where the dot is displayed in the UI. This means that you can draw the dot such that your finger is not covering it.
* X and Y offset when displaying Raw dot. Values entered are added to X and Y coordinates when actually displayed to be able to see the Raw dot as the person is touching the screen. These textboxes are disabled when filter is not installed. Default: 0, -15 (RawOffsetX/RawOffsetY)
* X and Y offset when displaying Gesture dot. Values entered are added to X and Y coordinates when actually displaying to be able to see the GWES dot as the person is touching the screen. Default: 0, -10 (GestureOffsetX/GestureOffsetY)
User Interface
This pane allows you to specify the position of the button (used to bring up the Options Dialog) and of the Data Window. This can be useful if their default positions are covering a portion of the screen which you want to test.
* X and Y coordinates for the button. This will be the button to press to bring up the Options Dialog or to Stop recording touch data. (ButtonX/ButtonY, default: bottom-left of screen w/margin)
* X and Y coordinates for Data Window. (WindowX/WindowY, default: top-center of screen w/margin)
This pane also allows you to specify the background for CETouchView.
* Image: If selected, the image named in the edit control is used as the background image. (BkMode=1, BkImage)
* Color: If selected, the color value in the edit control is used as the background color. (The value is specified in base 16, BBGGRR). (BkMode = 0, BkColor)
* None: If selected, use a white background
Gesture
This pane allows you to specify which gestures are displayed in the UI, and which colors to use when drawing them. There is one checkbox for each gesture type and an edit box which allows you to enter a color.
Note: Direct Manipulation and Pan/Scroll are mutually exclusive. So, if DIRECT MANIPULATION is checked, PAN and SCROLL will automatically clear. And, if either PAN or SCROLL are checked, DIRECT MANIPULATION will automatically clear.
Here are the supported gestures (and the relevant registry keys):
* Direct Manipulation (ShowDM=0/1; DMColor)
* Pan (ShowPAN=0/1; PANColor)
* Scroll (ShowSCROLL=0/1; SCROLLColor)
* Select (ShowSELECT=0/1; SELECTColor)
* Double-Select (ShowDSELECT=0/1; DSELECTColor)
* Hold (ShowHOLD=0/1; HOLDColor)
Warnings
This pane allows you to specify which warning messages to show. There checkboxes for each of the three warning types:
* Initial: If CETouchFilter is not installed when CETouchView starts up, display a warning message. (ShowInitialWarning=0/1)
* dwID: The dwID sent from the driver needs to be consistent within a touch session (Down through Up). When this is checked, will warn if an inconsistency is detected. If CETouchFilter is not installed, this is disabled. (ShowIDWarning=0/1)
* Contact Range: Checks that the contact information sent from the driver is within the range specified in the Contact Range edit controls. If filter is not installed, this is disabled. (ShowContactsWarning=0/1)
There are two edit controls for Contact Range
* Min: (Value is in fourths of a pixel.) If cxContact or cyContact is less than this value when Contact Range warnings are enabled, CETouchView will display a warning message. If Contact Range Warnings are not checked or filter is not installed, this is disabled. 0 <= MIN <= MAX <= larger of screen width or screen height. Default: 12 (ContactsMin)
* Max: (Value is in fourths of a pixel.) If cxContact or cyContact is greater than this value when Contact Range Warnings are enabled, CETouchView will display a warning message. If Contact Range Warnings are not checked or filter is not installed, this is disabled. 0 <= MIN <= MAX <= larger of screen width or screen height. Default: 80 (ContactsMax)
Record/Playback
This pane controls the recording and playback of touch sessions.
Note: This pane does not appear if filter is not installed.
This dialog contains an edit control for file name (FileName) and two buttons for starting and stopping the playback or recording.
* Begin Playback/Begin Puppet: Pressing this button saves the current settings to registry, closes the Options Dialog, and begins playback of the file named in the edit control. If the edit control is not blank, the button text is "Begin Playback." If the edit control names a file that does not exist when this button is pressed, displays a message box "Invalid Filename"/"Unable to open the file specified. Nothing to play back." If edit control is blank, the button text becomes "Begin Puppet" and it plays back a sequence of prerecorded stretch/pinch gestures (see description in Command Line Options). (MacroMode = 0)
* Start Recording: Pressing this button saves the current settings to registry, closes the Options Dialog, and begins recording to the file named in the edit control. If the edit control is blank this button is disabled. If unable to create the file when this button is pressed, displays a message box "Invalid Filename"/" Unable to create the file specified." (MacroMode = 1)
Command Line Options: -t
The "-t" command line option causes CETouchView to "trigger" the "puppet mode" of CETouchFilter, playing a prerecorded sequence of touch events. This feature can be used to verify whether an application responds to multi-touch gestures, without having a real multi-touch device. This "puppet mode" sequence consists of a 20-step stretch, followed by a 20-step pinch, which are repeated once.
You may specify an additional argument after "-t" which should be the name of a recorded touch session file. This will "trigger" CETouchFilter to play it if it exists. If the file does not exist, CETouchView displays an error message and exits.
If CETouchFilter is not installed, the "-t" command line option will not work and CETouchView will display an error message and exit.
Verifying the Test
Troubleshooting the Test
While using the CETouchView tool, you may observe either of the following issues:
* Spurious touch events: These are symptoms of issues with the underlying touch driver
* Ghost touch points: These are touch artifacts of symmetric touch screens that are caused by the way symmetric touch screens are implemented.
Spurious Touch Events
During a multi-touch session, the touch driver may send a spurious "Up" event, even when neither finger lifts. This puts the gesture recognizer of GWES into an invalid touch state and the system won't be able to generate any correct gesture messages until all fingers lift and a new gesture session is started.
To make it obvious when this occurs, the text or bar will turn red when an Up event is received from driver. If the text or bar turns red but the user didn’t left all fingers from the device, this indicates that there is likely an issue with the touch driver.
Ghost Touch Points
Symmetrical multi-touch screens report two touch points as a pair of X-coordinates and a pair of Y-coordinates, but don’t specify which X-coordinate goes with which Y-coordinate. As a result, the touch driver will sometimes pair the coordinates incorrectly, producing ghost touch points.
Touch Session File Format
As described above CETouchView can record and play touch sessions. These sessions are saved as a data file where each line contains all of the data for a single touch event. If there is only one contact used for this touch event, all values for the second contact should be -1. The time value applies to both contact points. All numbers are expressed in Base 10
Lines that are completely blank, and lines that begin with a semicolon ( ; ) are ignored.
A valid line should be formatted as follows:
time, x1, y1, flags1, mask1, width1, height1, x2, y2, flags2, mask2, width2, height2
Here is further information about each value:
* time= (DWORD value in ms) elapsed time in milliseconds since the previous touch event
* x= ( DWORD value in fourths of a pixel) x coordinate of touch point
* y= (DWORD value in fourths of a pixel) y coordinate of touch point
* flags= (DWORD value) the touch input flags
* mask=(DWORD value) the touch input mask
* width= (DWORD value in fourths of a pixel) width of the touch point
* height= (DWORD value in fourths of a pixel) height of the touch point