On Fri, Jan 08, 2016 at 02:43:10PM +1000, Peter Hutterer wrote: > ping - can we merge this now?
Just pushed the protocol patch: 2b236af..c5356e9 master -> master If no one objects, I intend to push the weston implementation patches as well within a couple of days. FWIW, the weston APIs are not stable, and if they need to change, nothing stops us from doing that later. Jonas > > On Tue, Dec 08, 2015 at 11:11:07AM +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. > > 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. The axis_discrete event carries the axis > > information and the discrete value and can occur at any time in the frame > > provided it is ordered before the matching axis event. Specifically, this > > sequence is valid: > > > > wl_pointer.axis_source > > wl_pointer.axis_discrete (vert) > > wl_pointer.axis_discrete (horiz) > > wl_pointer.axis (horiz) > > wl_pointer.axis (vert) > > wl_pointer.frame > > > > Enter and leave event also trigger wl_pointer.frame events, where possible > > the > > compositor should group leave and subsequent enter into the same frame. This > > indicates to the client that the pointer has moved between surfaces and may > > allow a client to shortcut code otherwise triggerd by the leave or enter > > events. > > > > Signed-off-by: Peter Hutterer <peter.hutte...@who-t.net> > > Reviewed-by: Carlos Garnacho <carl...@gnome.org> > > Reviewed-by: Jonas Ådahl <jad...@gmail.com> > > Reviewed-by: Daniel Stone <dani...@collabora.com> > > Reviewed-by: Bryce Harrington <br...@osg.samsung.com> > > --- > > Changes to v7: > > - remove notion of latching, now that we have the axis value the discrete > > event can occur any time before the coupled axis event, not just > > immediately before. > > - add documentation for enter/leave event frame grouping. > > > > Note: I left the previous rev-by in here, pls let me know where it doesn't > > apply anymore. > > > > protocol/wayland.xml | 150 > > +++++++++++++++++++++++++++++++++++++++++++++++++-- > > 1 file changed, 147 insertions(+), 3 deletions(-) > > > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml > > index df8ed19..8a62190 100644 > > --- a/protocol/wayland.xml > > +++ b/protocol/wayland.xml > > @@ -1482,7 +1482,7 @@ > > > > </interface> > > > > - <interface name="wl_pointer" version="3"> > > + <interface name="wl_pointer" version="5"> > > <description summary="pointer input device"> > > The wl_pointer interface represents one or more input devices, > > such as mice, which control the pointer location and pointer_focus > > @@ -1649,9 +1649,153 @@ > > </description> > > </request> > > > > + <!-- Version 5 additions --> > > + > > + <event name="frame" since="5"> > > + <description summary="end of a pointer event sequence"> > > + Indicates the end of a set of events that logically belong together. > > + A client is expected to accumulate the data in all events within the > > + frame before proceeding. > > + > > + All wl_pointer events before a wl_pointer.frame event belong > > + logically together. For example, in a diagonal scroll motion the > > + compositor will send an optional wl_pointer.axis_source event, two > > + wl_pointer.axis events (horizontal and vertical) and finally a > > + wl_pointer.frame event. The client may use this information to > > + calculate a diagonal vector for scrolling. > > + > > + When multiple wl_pointer.axis events occur within the same frame, > > + the motion vector is the combined motion of all events. > > + When a wl_pointer.axis and a wl_pointer.axis_stop event occur within > > + the same frame, this indicates that axis movement in one axis has > > + stopped but continues in the other axis. > > + When multiple wl_pointer.axis_stop events occur within in the same > > + frame, this indicates that these axes stopped in the same instance. > > + > > + A wl_pointer.frame event is sent for every logical event group, > > + even if the group only contains a single wl_pointer event. > > + Specifically, a client may get a sequence: motion, frame, button, > > + frame, axis, frame, axis_stop, frame. > > + > > + The wl_pointer.enter and wl_pointer.leave events are logical events > > + generated by the compositor and not the hardware. These events are > > + also grouped by a wl_pointer.frame. When a pointer moves from one > > + surface to the another, a compositor should group the > > + wl_pointer.leave event within the same wl_pointer.frame. > > + However, a client must not rely on wl_pointer.leave and > > + wl_pointer.enter being in the same wl_pointer.frame. > > + Compositor-specific policies may require the wl_pointer.leave and > > + wl_pointer.enter event being split across multiple wl_pointer.frame > > + groups. > > + </description> > > + </event> > > + > > + <enum name="axis_source"> > > + <description summary="axis source types"> > > + Describes the source types for axis events. This indicates to the > > + client how an axis event was physically generated; a client may > > + adjust the user interface accordingly. For example, scroll events > > + from a "finger" source may be in a smooth coordinate space with > > + kinetic scrolling whereas a "wheel" source may be in discrete steps > > + of a number of lines. > > + > > + The "continuous" axis source is a device generating events in a > > + continuous coordinate space, but using something other than a > > + finger. One example for this source is button-based scrolling where > > + the vertical motion of a device is converted to scroll events while > > + a button is held down. > > + </description> > > + <entry name="wheel" value="0" summary="A physical wheel" /> > > + <entry name="finger" value="1" summary="Finger on a touch surface" /> > > + <entry name="continuous" value="2" summary="Continuous coordinate > > space"/> > > + </enum> > > + > > + <event name="axis_source" since="5"> > > + <description summary="axis source event"> > > + Source information for scroll and other axes. > > + > > + This event does not occur on its own. It is sent before a > > + wl_pointer.frame event and carries the source information for > > + all events within that frame. > > + > > + 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 > > + 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. > > + > > + This event is optional. If the source is unknown for a particular > > + axis event sequence, no event is sent. > > + Only one wl_pointer.axis_source event is permitted per frame. > > + > > + The order of wl_pointer.axis_discrete and wl_pointer.axis_source is > > + not guaranteed. > > + </description> > > + <arg name="axis_source" type="uint" enum="axis_source"/> > > + </event> > > + > > + <event name="axis_stop" since="5"> > > + <description summary="axis stop event"> > > + Stop notification for scroll and other axes. > > + > > + For some wl_pointer.axis_source types, a wl_pointer.axis_stop event > > + is sent to notify a client that the axis sequence has terminated. > > + This enables the client to implement kinetic scrolling. > > + See the wl_pointer.axis_source documentation for information on when > > + this event may be generated. > > + > > + Any wl_pointer.axis events with the same axis_source after this > > + event should be considered as the start of a new axis motion. > > + > > + The timestamp is to be interpreted identical to the timestamp in the > > + wl_pointer.axis event. The timestamp value may be the same as a > > + preceeding wl_pointer.axis event. > > + </description> > > + <arg name="time" type="uint" summary="timestamp with millisecond > > granularity"/> > > + <arg name="axis" type="uint" enum="axis" summary="the axis stopped > > with this event"/> > > + </event> > > + > > + <event name="axis_discrete" since="5"> > > + <description summary="axis click event"> > > + Discrete step information for scroll and other axes. > > + > > + 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 with the same > > + axis number within the same wl_pointer.frame. Note that the protocol > > + allows for other events to occur between the axis_discrete and > > + its coupled axis event, including other axis_discrete or axis > > + events. > > + > > + This event is optional; continuous scrolling devices > > + like two-finger scrolling on touchpads do not have discrete > > + steps and do not generate this event. > > + > > + The discrete value carries the directional information. e.g. a value > > + of -2 is two steps towards the negative direction of this axis. > > + > > + The axis number is identical to the axis number in the associate > > + axis event. > > + > > + The order of wl_pointer.axis_discrete and wl_pointer.axis_source is > > + not guaranteed. > > + </description> > > + <arg name="axis" type="uint" enum="axis" /> > > + <arg name="discrete" type="int"/> > > + </event> > > </interface> > > > > - <interface name="wl_keyboard" version="4"> > > + <interface name="wl_keyboard" version="5"> > > <description summary="keyboard input device"> > > The wl_keyboard interface represents one or more keyboards > > associated with a seat. > > @@ -1765,7 +1909,7 @@ > > </event> > > </interface> > > > > - <interface name="wl_touch" version="3"> > > + <interface name="wl_touch" version="5"> > > <description summary="touchscreen input device"> > > The wl_touch interface represents a touchscreen > > associated with a seat. > > -- > > 2.5.0 > > > > _______________________________________________ > > wayland-devel mailing list > > wayland-devel@lists.freedesktop.org > > http://lists.freedesktop.org/mailman/listinfo/wayland-devel > > _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
