ping - can we merge this now?
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
