[PATCH 3/4] protocol: Introduce pointer_lock interface

[Pekka Paalanen]

On Mon, 25 Feb 2013 21:24:47 -0500
Kristian Høgsberg <krh at bitplanet.net> wrote:

> The pointer_lock interface is modelled after the HTML5 pointer lock
> extension:
> 
>   https://dvcs.w3.org/hg/pointerlock/raw-file/default/index.html
> 
> The extension allows a wayland client to lock the pointer while a surface
> is active.  While the pointer is locked, the client receives relative
> motion events and the pointer position isn't updated.
> ---
>  protocol/wayland.xml | 37 +++++++++++++++++++++++++++++++++++--
>  1 file changed, 35 insertions(+), 2 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index b43799d..5e30cd1 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -951,7 +951,7 @@
>      </request>
>     </interface>
>  
> -  <interface name="wl_seat" version="1">
> +  <interface name="wl_seat" version="2">
>      <description summary="seat">
>        A group of keyboards, pointer (mice, for example) and touch
>        devices . This object is published as a global during start up,
> @@ -967,9 +967,9 @@
>        <entry name="pointer" value="1" summary="wl_pointer"/>
>        <entry name="keyboard" value="2" summary="wl_keyboard"/>
>        <entry name="touch" value="4" summary="wl_touch"/>
> +      <entry name="pointer_lock" value="8" summary="lock pointer"/>
>      </enum>
>  
> -
>      <event name="capabilities">
>        <description summary="seat capabilities changed">
>          This is emitted whenever a seat gains or loses the pointer,
> @@ -1002,6 +1002,39 @@
>        </description>
>        <arg name="id" type="new_id" interface="wl_touch"/>
>      </request>
> +
> +    <request name="lock_pointer" since="2">
> +      <description summary="return pointer object">
> +	The lock_pointer request lets the client disable pointer
> +	motion and request relative motion events.
> +
> +	This request initializes the pointer lock and activates it in
> +	case the surface is active.  If the surface isn't active when
> +	the server receives the request, the compositor will activate
> +	the pointer_lock when the surface is eventually activated.
> +
> +	The lock_pointer request will create a new wl_pointer object.
> +	When the pointer_lock is activated, the regular wl_seat
> +	pointer send out a leave event and the pointer_lock wl_pointer
> +	object will receive an enter event.  The enter event will
> +	indicate the position of the pointer at the time of
> +	activation.  While the pointer lock is active, the wl_pointer
> +	object will send out motion events, but the coordinates
> +	correspond to relative pointer motion.
> +
> +	The compositor can break the pointer_lock at any time, for
> +	example when switching to a different application (eg,
> +	alt-tab), if a notification pops up or when the screensaver
> +	starts.  When this happens the pointer lock wl_pointer will
> +	send a leave event.  When or if the server activates the
> +	surface again, the client will receive an enter event again.
> +
> +	The client can break the pointer lock at any time by releasing
> +	the pointer lock wl_pointer using the wl_pointer.release request.
> +      </description>
> +      <arg name="id" type="new_id" interface="wl_pointer"/>
> +      <arg name="surface" type="object" interface="wl_surface"/>
> +    </request>
>    </interface>
>  
>    <interface name="wl_pointer" version="1">

Hi,

should we add a bit of text to say that the relative events are in no
way "raw" events? That they correspond to normal pointer motion, except
they are just relative instead of absolute in surface coordinates.

This definition is a bit problematic, though. For a non-linear surface
transformations (this includes projective), the transform of a
displacement vector depends also on the absolute position. I guess we
just have to say that the displacement vector is transformed in the
neighborhood of the last absolute pointer position sent to the
client... but that doesn't make much sense. Maybe use the center of the
surface?

This also means, that using only relative motion event, a client simply
cannot replicate the cursor motion and feel of absolute events. Maybe
that's not important, either.

You can study these problems by imagining, that a surface is being
transformed into a trapezoid (projective transformation), whose top edge
is very short, and bottom edge is long. for simplicity, let's also
assume the top and bottom edges are parallel to the global x-axis. Now,
a small pointer motion in x-direction in the top of the surface is shown
to the client as a huge motion, but on the bottom of the surface as
tiny motion.


Thanks,
pq