Wayland Relative Pointer API Progress

Bill Spitzak spitzak at gmail.com
Fri Apr 17 12:19:14 PDT 2015

On 04/16/2015 07:51 PM, x414e54 wrote:
> Hi,
> I am wondering if there has been any recent progress on the stability of
> the Wayland relative pointer API?
> I had a few ideas on the original December implementation:
> Whilst we definitely need the relative event support, I feel that the
> client should never be allowed to warp or confine the global pointer
> even if it is just a hint. There may be cases such as IR or laser
> pointer devices (e.g. wii mote) which can never guarantee a warp or
> pointer confinement but can still transmit accelerometer data as
> relative pointer motion. Looking at most toolkits and applications they
> cannot be trusted even with "hints".
> I think the API needs to be split into two use cases:

I agree and about 90% of what I am interested in falls in the first case:

> 1. GUI sliders etc. - They should be allowed to freeze the pointer and
> receive relative events based on an implicit button down grab similar to
> the drag and drop protocol. They should not be allowed to warp or
> confine and upon button up the grab is lost. Gnome already looks like it
> uses heuristics todo this if the cursor is hidden on button down.

They MUST be able to move the cursor image. Blanking it and replacing it 
with another surface will BLINK, which is a direct violation of basic 
Wayland principle that every frame is perfect. In addition for many 
input devices the compositor will need to know where the user thinks the 
cursor is so it can put the real cursor there when the grab finishes. In 
addition it means you can't reuse any specialization the compositor did 
with the cursor image (such as putting it in a special hardware plane).

I don't think this is very hard:

- the client can lock the pointer in response to an event such as a 

- This makes the cursor image STOP (it does not disappear, does not 
change appearance, and does not move from where it happens to be). 
NOTHING visible happens!!!!!

- The client can change the cursor image and move it to any location 
they want (compositor may restrict this to the client input area). 
Ideally this should be in sync with buffer updates.

- Client gets events as the user moves the input pointer. One thing it 
gets is IDENTICAL to the location they would have gotten if the lock had 
not happened, but instead a grab had happened and also (if the device 
supports it) the screen had unlimited area. It also appears some clients 
will want unaccelerated motion as another event.

- When the mouse is released the lock is lost. This event is also 
delivered to the client, with the same xy position it would have had if 
the lock had never happened.

- On an absolute device the cursor most likely then jumps to the actual 
location of the absolute pointer, producing enter/exit events as needed. 
On a relative device (ie a mouse) the cursor should probably remain 
where it is.

I have certainly moved GUI sliders that slow the cursor with an absolute 
device (a Wacom tablet) and there is no problem. The cursor jumping when 
I release the slider is perfectly natural. I believe the same thing 
applies to touch screens. So there is no reason to say this should only 
work with "real mice".

> 1. Games - They do not really need relative "pointer" events they just
> want the current seat mapped to a 6DOF or joystick style input. They
> should be allowed to request some kind of wl_joystick or wl_6dof
> interface. Then the compositor can decide what it actually presents to
> the application for using that input. Maybe a user has a joystick they
> always select to use instead of their mouse or they have an
> accelerometer device etc. It is then up to the compositor what it does
> with the actual on screen cursor if it confines it or hides it etc,
> there could be a notification of entering "game mode" etc. If the
> compositor is not using the same input device for wl_pointer and a
> wl_joystick or wl_6dof then it does nothing. This would also allow a
> user to hot-swap the device between mouse and keyboard and a gamepad
> just by using the WM settings. It could also allow for using 6DOF or 3D
> mice in an application which is also mapped as the default x, y pointer.
> The application will then still receive absolute pointer events which it
> can use for in game GUI clicks.

A big problem with just saying "the game must use the joystick api" is 
that the game won't work on a machine without a joystick unless the 
joystick api is emulated for the mouse. This seems to me to be exactly 
the same problem and requiring exactly the same solutions, except you 
have moved the code from the client to the compositor, which is usually 
a bad idea. Also you have made it a pain in the ass to create simple 
toolkits since they now have to provide the joystick api.

I believe this can be done exactly as above except releasing the mouse 
button does not cancel the lock. There is no need for a restriction 
rectangle, since the game can just position the cursor wherever it wants 
and thus "restrict" it (it can also blank it or use it's own image for 
the cursor). And the game can make up it's own method for translating 
relative motion into camera motion or whatever.

I do not know what the rules should be so that a client can request such 
a grab (can it require the user to click on the game? Or does just 
entering the window have to do it?). Also how you get out of it if the 
client refuses to give it up? Does the client require special privileges 
(may be a bad idea for a *game*...).

More information about the wayland-devel mailing list