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

[Peter Hutterer]

On Wed, Oct 28, 2015 at 09:36:02AM -0700, Bill Spitzak wrote:
> On Tue, Oct 27, 2015 at 10:34 PM, Peter Hutterer <peter.hutterer at who-t.net>
> 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.
> > Frame events group all wl_pointer events. An example sequence of motion
> > events
> > followed by a diagonal scroll followed by a button event is:
> > wl_pointer.motion
> > wl_pointer.frame
> > wl_pointer.motion
> > wl_pointer.frame
> > wl_pointer.axis
> > wl_pointer.axis
> > wl_pointer.frame
> > wl_pointer.button
> > wl_pointer.frame
> >
> > In the future, other extensions may insert additional information about an
> > event into the frame. For example, an extension may add information about
> > the
> > physical device that generated an event into the frame. For this reason,
> > enter/leave events are grouped by a frame event too.
> >
> > The axis_source event determines how an axis event was generated. That
> > enables
> > clients to judge when to use kinetic scrolling. Only one axis_source event
> > is
> > allowed per frame and applies to all events in this frame.
> >
> > The axis_stop event notifies a client about the termination of a scroll
> > sequence, likewise needed to calculate kinetic scrolling parameters.
> > Multiple axis_stop events within the same frame indicate that scrolling has
> > stopped in all these axis at the same time.
> >
> > The axis_discrete event provides the wheel click count. Previously the axis
> > value was some hardcoded number (10), with the discrete steps this enables
> > a
> > client to differ between line-based scrolling on a mouse wheel and smooth
> > scrolling with a touchpad.
> >
> > We can't extend the existing wl_pointer.axis events so we introduce a new
> > concept: latching events. These events (currently only axis_discrete)
> > are prefixed before a wl_pointer.axis event. A client must build the full
> > state of the event until the respective top-level event arrives.
> > i.e. a single event frame for a diagonal scroll with discrete information
> > may
> > be:
> >
> > wl_pointer.axis_source
> > wl_pointer.axis_discrete
> > wl_pointer.axis
> > wl_pointer.axis_discrete
> > wl_pointer.axis
> > wl_pointer.frame
> >
> 
> This description is a little confusing. Actually it looks like a client can
> ignore the axis events entirely, the information it needs is in the
> discrete events. This description makes it sound like the movement must be
> determined by examining the axis event.
> 
> Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> > Changes to v4:
> > - axis argument added to axis_discrete. While technically redundant since
> >   the axis event carries this information, the lack of this argument leads
> >   to awkward client-side implementation. A single uint32_t value with no
> >   other information attached had to be stacked in a temporary variable,
> > only
> >   the next event can then tell us whether the event was x or y scroll.
> >   Providing the axis in the discrete event means we can immediately stack
> >   this into the right variable.
> >
> 
> Yea it does sound like you are altering the discrete event into a
> stand-alone event, I think this is correct.

not quite, axis_discrete is not fully standalone, it's lacking the
timestamp. so you still need to look at both events to get the full
information.

> > - the big change is the rename from axis_frame to wl_pointer.frame.
> >   the axis_frame concept was solid but working on other things Carlos and I
> >   discovered that we may need to add additional information to some events.
> >   A generic wl_pointer.frame event gives us the same benefit of the
> >   axis_frame but allows to insert events (even from other extensions)
> >   into a specific frame and augment that event.
> >
> 
>  I think you might want to expand this even further, making the "frame"
> event per-seat, or per client connection. It could then be used to group
> other events into units, similar to how the commit request works in the
> other direction.

we talked about adding it to wl_keyboard.frame as well and couldn't think of
a use-case. The same is true for per-seat.

Cheers,
   Peter

Cheers,
   Peter