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

Jonas Ådahl jadahl at gmail.com
Thu Jan 14 00:29:32 PST 2016


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.hutterer at who-t.net>
> > Reviewed-by: Carlos Garnacho <carlosg at gnome.org>
> > Reviewed-by: Jonas Ådahl <jadahl at gmail.com>
> > Reviewed-by: Daniel Stone <daniels at collabora.com>
> > Reviewed-by: Bryce Harrington <bryce at 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 at lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/wayland-devel
> > 


More information about the wayland-devel mailing list