The Linux Wacom Project
|Main | News | FAQ | Downloads | Help | Development | TOC | All||Jun 20, 2013|
Linux Wacom Project HOWTO
6.0 - Viewing XInput Events (xidump)
The xidump program is similar to wacdump, but it parses and displays event data from the XFree86 XInput extension rather than from the tablet itself. This is useful for seeing what programs like gimp and gsumi are receiving from X.
Presently, xidump will display proximity and motion events for the stylus, cursor, eraser, and pad input devices. xidump supports different display modes with "curses" and "raw" modes already implemented and a GTK-based graphical mode in the works. The curses mode is probably the most useful in terms of verifying that the tablet is functioning correctly in the XFree environment; however, the raw mode has the additional benefit of being able to verify the order, timing, and history of events.
Since xidump uses the same XInput interface that gimp and gsumi use to get tablet data, the values displayed in xidump should be identical to what they are receiving. If you are having trouble with pressure in gimp, chances are that xidump will demonstrate the same problem. xidump does not require root access to use.
xidump takes one argument, the input device specified in your XF86Config/xorg.conf file. It is the Identifier entry in the InputDevice section. Normally they are either stylus, cursor, eraser, touch, or pad. You can get a complete list by running xidump with the list option '-l'. xidump has the additional feature of dumping all the device capabilities by specifying the verbose option '-v'. Both are demonstrated below.
Note: The device identifiers (input_device) are case sensitive.
[jej@ayukawa src]$ ./xidump -l eraser extension stylus extension cursor extension Mouse0 disabled keyboard keyboard [jej@ayukawa src]$ ./xidump -l -v eraser eraser extension key: min=8, max=39, num=32 btn: num=1 val: axes=6 mode=abs buf=0 axis: res=2540, min=0, max=30480 axis: res=2540, min=0, max=30480 axis: res=1, min=0, max=1023 axis: res=1, min=-64, max=63 axis: res=1, min=-64, max=63 axis: res=1, min=0, max=1023
In the first dump, we see the eraser, stylus, and cursor with the additional Mouse0 pointer and keyboard. Only the first three are "extension" devices. Using xidump on the keyboard or mouse pointer will generate an error since neither are XInput devices.
The second dump shows the capabilities of the eraser device including the number of keys (32), buttons (1), and axes (6). It also shows the mode to be absolute. In order, the axes are: x, y, pressure, tilt-x, tilt-y, and wheel. When the cursor is used, axis 3 becomes z-rotation instead of tilt-x.
You should be aware that xidump and gimp must take ownership of the device in order to get real-time data. This creates a conflict if you are running both of them simultaneously. gimp is the more clever of the two programs in that it only "grabs" the input device if you are hovering over the gimp drawing window. xidump is less friendly. In order to display the absolute position across the entire screen, it creates a small "listening window," grabs the device immediately, and does not release it until you quit the program. Neither program should fail, but you will not be able to draw in gimp and run xidump at the same time if they are both using the same input device.
We will run xidump in raw mode for the first time to see the stylus events directly. A small window will appear on the desktop while xidump runs; you can safely ignore it. Closing it will kill the application.
[jej@ayukawa src]$ ./xidump -u raw stylus 14.56291895: Proximity In 14.56305595: Motion: x= +5978 y=+28728 p= 0 tx= +64 ty= +64 w= +0 ID: 2323 Serial: -60 ... 16.87158095: Motion: x= +4941 y=+27842 p= 225 tx= +41 ty= +67 w= +0 ID: 2323 Serial: -60 16.87164395: Button: 1 DOWN 16.87169595: Motion: x= +4964 y=+27844 p= 398 tx= +42 ty= +66 w= +0 ID: 2323 Serial: -60 ... 17.27328395: Motion: x= +5261 y=+27543 p= 3 tx= +48 ty= +64 w= +0 ID: 2323 Serial: -60 17.27334395: Button: 1 UP 17.27515995: Motion: x= +5348 y=+27451 p= 4 tx= +48 ty= +63 w= +0 ID: 2323 Serial: -60 ... 17.35933795: Motion: x= +7089 y=+27061 p= 4 tx= +48 ty= +63 w= +0 ID: 2323 Serial: -60 17.37444395: Proximity Out <Ctrl-C>
The timestamp on the left is seconds elapsed; the next field is the event type. Mostly, you will encounter motion events although I've trimmed many of them out of this listing. As you can see from the above, the first line is a "proximity in" event which indicates the stylus came in range of the tablet. The last event was a "proximity out." At 16.87 seconds, I tapped the stylus to the tablet surface as recorded by the "Button: 1 DOWN" and subsequent "UP" message. Raw mode is useful for verifying the order and timing of messages, but is not particularly clean. The ncurses mode works much better.
[jej@ayukawa src]$ ./xidump stylus InputDevice: stylus Valuators: Absolute ID: 2323 Serial Number: -60 x-axis y-axis pressure x-tilt y-tilt wheel data: +10826 +09919 +00084 +00058 +00065 +00000 min: +00000 +00000 +00000 -00064 -00064 +00000 max: +30480 +30480 +01023 +00063 +00063 +01023 res: +00000 +00000 +00039 +00001 +00001 +00001 ******** Proximity: IN Focus: Buttons: 1-DOWN Keys:
All of the ranges are displayed above, include their resolutions which as far as I know are not normally used. Only the proximity, focus, valuator, and button events are currently implemented.
For completeness sake, here are the command line options:
Usage: xidump [options] input_device -h, --help - usage -v, --verbose - verbose -V, --version - version -l, --list - list available input devices -u, --ui ui_type - use specified ui, see below Use --list option for input_device choices UI types: curses, raw
There are not many options, but the --list option is helpful for
identifying devices, and the --ui option allows you to switch between
curses and raw modes. Adding the --verbose option increases the amount of output, and
when used in conjunction with --list, displays the device capabilities.