[PATCH v5 wayland] protocol: add wl_pointer.frame, axis_source, axis_stop, and axis_discrete

[Bryce Harrington]

On Sun, Nov 01, 2015 at 11:41:22AM +1000, Peter Hutterer wrote:
> On 31/10/2015 09:17 , Bryce Harrington wrote:
> >On Wed, Oct 28, 2015 at 03:34:31PM +1000, Peter Hutterer wrote:
> >>The frame event groups separate pointer events together. The primary use-case
> >>for this at the moment is diagonal scrolling - a vertical/horizontal scroll
> >>event can be grouped together to calculate the correct motion vector.
> >
> >If I understand correctly, this is an optimization for non-orthogonal
> >cursor movement?  Or is there some specialized hardware or usage pattern
> >that needs this functionality specifically?
> 
> any touchpad, more or less :)
> if you scroll diagonally, the wayland protocol has no indication
> that a vertical scroll event is followed by a horizontal one (or
> vice versa) so you don't necessarily know when to update the UI.
> Think about it this way: there's a reason we send x/y in the same
> pointer event :)
> 
> The immediate impact is relatively low.

Ok cool, that's what I was gathering.

> >>We can't extend the existing wl_pointer.axis events so we introduce a new
> >>concept: latching events.
> >
> >Could you briefly explain why that can't be extended?
> 
> The GNOME guys have a need for knowing a bit more about the device
> that generates a specific event, specifically: was this a touchpad,
> a mouse, a trackball, etc. Based on that the UI may react
> differently.
> This isn't something that should be in the core wayland protocol,
> but a specific extension could add this information as additional
> events inside a frame.

Okay, gotcha that makes sense.  This is wrappering lower level events.

> >Is this a new concept unique to Wayland, or has this design been
> >employed before in X11 or other window systems?  (Sorry, my depth in
> >input tech is pretty shallow.)  If there is prior art, it might be worth
> >a h/t.
> 
> we have wl_touch.frame for pretty much the same reason - multiple
> touch point updates in the same HW event that should be considered
> as simultaneous.
> in the proposed tablet protocol, the wl_tablet.frame event does the
> same - we may get 5 axes updated simultaneously and need to signal
> that.
> The kernel's evdev protocol is another example of serial event
> stacking - you get EV_SYN SYN_REPORT as a signal that the previous
> events all belong together.
> 
> X doesn't do this, we pack all the information into a single event,
> but this makes it a lot harder to extend with extra information,
> especially optional information. libinput doesn't do it, but mostly
> because that is a C API where we can add information later and get
> the same effect. wayland is effectively a serialised API, so we need
> some frame event to get to that point.

Makes sense.  Now that you mention it, I remember you discussing this in
relation to figure data for gesture interpretation.

> >>+	The source specifies how this event was generated. If the source is
> >>+	wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be
> >>+	sent when the user lifts the finger off the device.
> >>+
> >>+	If the source is wl_pointer.axis_source.wheel or
> >>+	wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
> >>+	be sent but is not guaranteed to be sent.
> >
> >This sentence seems a bit weird.  Better grammar might be "...may or may
> >not be sent..."  However, perhaps it should explain under what
> >conditions the stop event might be expected or not expected?  Or a
> >suggestion on how the client should be handling the documented
> >ambiguity?
> 
> I'm mostly worried that "may or may not" isn't strong enough here.
> The original sentence is supposed to convey that wheel events will
> likely never send stop events (at least not until hw changes) and
> continuous is pretty much random, it depends how it is generated.
> But there's always the chance that you get an event, maybe not today
> but maybe in 3 years time. How about:
> 
> If the source is wl_pointer axis_source.wheel or
> wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
> or may not be sent. Whether a compositor sends a axis_stop event for
> these sources is hardware-specific and implementation-dependent,
> clients must not rely on receiving an axis_stop event for these
> scroll sources and should treat scroll sequences from these scroll
> sources as unterminated by default.

Sounds great, much improved.

That last comma should be a semi-colon.

> >>+
> >>+    <event name="axis_discrete" since="5">
> >>+      <description summary="axis click event">
> >>+	Discrete step information for scroll and other axes.
> >>+
> >>+	This event does not occur on its own. It is sent before a
> >
> >Is what you're saying here basically that axis_discrete events will
> >always be followed by one or more wl_pointer.axis events?
> 
> correct. an axis_discrete event is always followed by exactly one
> axis event, (which effectively serves as a mini-frame boundary).
> I'll write it as such into the protocol, how about:
> 
> "This event carries the axis value of the wl_pointer.axis event in
> discrete steps (e.g. mouse wheel clicks).
> 
> This event does not occur on its own, it is coupled with a
> wl_pointer.axis event that represents this axis value on a
> continuous scale. The protocol guarantees that each axis_discrete
> event is always followed by exactly one axis event within the same
> wl_pointer.frame.
> The coupled axis event is always the first axis event to follow the
> axis_discrete event. Note that the protocol otherwise allows for
> other events to occur between axis_discrete and the coupled axis
> event."

Yep, that's definitely clearer.

> The event ordering addition is so we can slot in additional events
> for axis events in the future without breaking the protocol. Think
> wl_pointer.axis_discrete
> someextension.axis-related-event
> wl_pointer.axis
> wl_pointer.frame
> 
> Thanks for the typo fixes, etc, I'll fold these in.

Cool, I'll keep my eye out for the next revision.

Bryce