Posting tablet tilt and pressure events to Xwindows

[Vincent Stemen]

Hi.

I am working on an xinput driver for my older serial tablet under FreeBSD.  My
main question is, how do you post tilt and pressure events to Xwindows and is
there any complete up to date API documentation anywhere for it?

I originally wrote the driver a number of years ago and have finally gotten it
updated to compile and work with Xorg-7.7.  I have cursor motion and buttons
working by calling xf86PostMotionEvent() and xf86PostButtonEvent() so that it
can be used as a core pointer, but I can find no API documentation on posting
tilt and pressure events.

The only documentation I have found with examples is
https://www.x.org/wiki/Development/Documentation/XorgInputHOWTO/
which apparently was mostly written around 10 years ago and is very out of
date.  It says right at the top of the page,

    "Warning: This tutorial is outdated and refers to APIs that have since
    been changed."

No links or mention of any docs for the updated APIs.

I have been pulling my hair out for days dealing with changes that seem to be
completely undocumented.
For example:  I had this call from the example in my driver.

    xf86InitValuatorAxisStruct(device, i, *pIdev->labels, -1, -1, 1, 1, 1);

which produced this compilation error:

    error: too few arguments to function call, expected 9, have 8
        xf86InitValuatorAxisStruct(device, i, *pIdev->labels, -1, -1, 1, 1, 1);

Not only can I find no API docs mentioning this but nowhere in the ChangeLog
for xorg-server-1.18.4 does it even mention adding a 9th argument or what it
is.  They are making significant compatibility changes and staying completely
quiet about it.

I found a prototype for it in the Xorg source tree that showed that it now had
a mode parameter but, like most of the rest of the sources, it was completely
uncommented.  So what the hell is mode?

After much digging, I finally found an uncommented call to it in the mouse.c
file from the xf86-input-mouse-1.7.2 sources where I discovered an extra
argument of Relative being added under 

    #if GET_ABI_MAJOR(ABI_XINPUT_VERSION) >= 12

So, after digging through all the headers, I came to the conclusion that it
now accepts either Absolute or Relative value as the parameter. 

This is just one example of many issues that I had.

The Xorg developers are making all kinds of changes without putting out updated
API reference documentation or howtos, commenting their code, or in cases like
above, even mentioning it in the change logs.

I have searched with google and various other major search engines for days
and have found no up to date or complete xinput API documentation.  It has
been frustrating.  Am I overlooking something obvious or have the Xwindows
developers lost the ability to communicate in recent years?

I have always griped and complained about hardware vendors, such as Wacom,
ignoring open source platforms like Linux and FreeBSD and only putting out
drivers for Microshaft.  Now I may be beginning to understand one of the
reasons why.  It's hard to write drivers or debug code for a poorly documented
platform, where most of the documentation either does not exist or is wrong or
incomplete or hasn't been updated in 10 years.

BTW, before anybody points out that there are existing Xwindows drivers for
Wacom and other tablets, I do realize that.  1, I have never had much luck
getting them to work on FreeBSD.  This is getting too long to go into those
issues.  And 2, I am taking a very different approach than the existing
drivers to provide features and capabilities, that we wanted for in-house use,
that the existing drivers do not have. I will document it if I get it working
well enough to release to the public.