[RFC wayland-protocols] unstable: Add input-timestamps protocol
Alexandros Frantzis
alexandros.frantzis at collabora.com
Thu Nov 30 10:52:55 UTC 2017
On Thu, Nov 30, 2017 at 04:08:06PM +1000, Peter Hutterer wrote:
> On Wed, Nov 29, 2017 at 12:42:57PM +0200, Alexandros Frantzis wrote:
> > wl_pointer, wl_keyboard and wl_touch events currently use a 32-bit
> > timestamp with millisecond resolution. In some cases, notably latency
> > measurements, this resolution is too coarse to be useful.
> >
> > This protocol provides additional timestamps events, which are emitted
> > just before the corresponding input event. Each timestamp event contains
> > a high-resolution, and ideally higher-accuracy, version of the 'time'
> > argument of the event that follows.
> >
> > Clients that care about high-resolution timestamps just need to keep
> > track of the last timestamp event they receive and associate it with the
> > next input event that arrives.
> >
> > Some notes and possible points for discussion:
> >
> > 1. Supported pointer/keyboard/touch events
> >
> > At the moment the protocol is phrased to be forward-compatible with
> > new pointer/keyboard/touch events. For example, for touch:
> >
> > "represents a subscription to high-resolution timestamp events for
> > for all wl_touch events that carry a timestamp."
> >
> > This guards against making input-timestamps protocol updates for new
> > input events (unless we add a new input category), and is easy to
> > implement in practice.
> >
> > 2. Guaranteed timestamp accuracy?
> >
> > Currently: "The timestamp provided by this event is at least as
> > accurate as the timestamp provided by the input event that follows".
> >
> > In a previous discussion it was suggested that an option would be for
> > the server to advertise support for this protocol only if it can
> > provide better (than millisecond) accuracy. My concern with such an
> > approach is that there may be cases where only some input objects can
> > provide high-accuracy timestamps, so the guarantee may not be
> > globally applicable.
> >
> > 3. Clocks domains
> >
> > The high-resolution timestamps are guaranteed to be in the same clock
> > domain as the input event timestamps (for which the clock domain is
> > currently unspecified).
> >
> > A proof of concept implementation for weston can be found at:
> >
> > https://gitlab.collabora.com/alf/weston/commits/zwp-input-timestamps
> >
> > Currently only touch timestamps are implemented, but supporting pointer
> > and keyboard event timestamps will be similar.
> >
> > Signed-off-by: Alexandros Frantzis <alexandros.frantzis at collabora.com>
> > ---
> > Makefile.am | 1 +
> > unstable/input-timestamps/README | 4 +
> > .../input-timestamps-unstable-v1.xml | 132 +++++++++++++++++++++
> > 3 files changed, 137 insertions(+)
> > create mode 100644 unstable/input-timestamps/README
> > create mode 100644 unstable/input-timestamps/input-timestamps-unstable-v1.xml
> >
> > diff --git a/Makefile.am b/Makefile.am
> > index 0296d5d..a4fd82e 100644
> > --- a/Makefile.am
> > +++ b/Makefile.am
> > @@ -16,6 +16,7 @@ unstable_protocols = \
> > unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-unstable-v1.xml \
> > unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml \
> > unstable/xdg-output/xdg-output-unstable-v1.xml \
> > + unstable/input-timestamps/input-timestamps-unstable-v1.xml \
> > $(NULL)
> >
> > stable_protocols = \
> > diff --git a/unstable/input-timestamps/README b/unstable/input-timestamps/README
> > new file mode 100644
> > index 0000000..3e82890
> > --- /dev/null
> > +++ b/unstable/input-timestamps/README
> > @@ -0,0 +1,4 @@
> > +High-resolution timestamps for input events.
> > +
> > +Maintainers:
> > +Alexandros Frantzis <alexandros.frantzis at collabora.com>
> > diff --git a/unstable/input-timestamps/input-timestamps-unstable-v1.xml b/unstable/input-timestamps/input-timestamps-unstable-v1.xml
> > new file mode 100644
> > index 0000000..73500d0
> > --- /dev/null
> > +++ b/unstable/input-timestamps/input-timestamps-unstable-v1.xml
> > @@ -0,0 +1,132 @@
> > +<?xml version="1.0" encoding="UTF-8"?>
> > +<protocol name="input_timestamps_unstable_v1">
> > +
> > + <copyright>
> > + Copyright © 2017 Collabora Ltd.
> > +
> > + Permission is hereby granted, free of charge, to any person obtaining a
> > + copy of this software and associated documentation files (the "Software"),
> > + to deal in the Software without restriction, including without limitation
> > + the rights to use, copy, modify, merge, publish, distribute, sublicense,
> > + and/or sell copies of the Software, and to permit persons to whom the
> > + Software is furnished to do so, subject to the following conditions:
> > +
> > + The above copyright notice and this permission notice (including the next
> > + paragraph) shall be included in all copies or substantial portions of the
> > + Software.
> > +
> > + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> > + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> > + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
> > + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> > + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> > + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> > + DEALINGS IN THE SOFTWARE.
> > + </copyright>
> > +
> > + <description summary="High-resolution timestamps for input events">
> > + This protocol specifies a way for a client to request and receive
> > + high-resolution timestamps for input events.
> > +
> > + Warning! The protocol described in this file is experimental and
> > + backward incompatible changes may be made. Backward compatible changes
> > + may be added together with the corresponding interface version bump.
> > + Backward incompatible changes are done by bumping the version number in
> > + the protocol and interface names and resetting the interface version.
> > + Once the protocol is to be declared stable, the 'z' prefix and the
> > + version number in the protocol and interface names are removed and the
> > + interface version number is reset.
> > + </description>
> > +
> > + <interface name="zwp_input_timestamps_manager_v1" version="1">
> > + <description summary="context object for high-resolution input timestamps">
> > + A global interface used for requesting high-resolution timestamps
> > + for input events.
> > + </description>
> > +
> > + <request name="destroy" type="destructor">
> > + <description summary="destroy the input timestamps manager object">
> > + Informs the server that the client will no longer be using this
> > + protocol object. Existing objects created by this object are not
> > + affected.
> > + </description>
> > + </request>
> > +
> > + <request name="get_pointer_timestamps">
> > + <description summary="subscribe to high-resolution pointer timestamp events">
> > + Creates a new input timestamps object that represents a subscription
> > + to high-resolution timestamp events for all wl_pointer events that
> > + carry a timestamp.
> > +
> > + If the associated wl_pointer resource is invalidated, either through
> > + client action (e.g., release) or server-side changes, the input
>
> remove ','
I see that the convention in wayland(-protocols) is not to use a comma
after 'e.g.'. I will remove the comma.
> > + timestamps object becomes inert.
>
>
> "and the client should call wp_input_timestamps.destroy()", I assume?
Yes, I will clarify this.
> > + </description>
> > + <arg name="id" type="new_id" interface="zwp_input_timestamps_v1"/>
> > + <arg name="pointer" type="object" interface="wl_pointer"
> > + summary="the wl_pointer for which to get timestamp events"/>
> > + </request>
> > +
> > + <request name="get_keyboard_timestamps">
> > + <description summary="subscribe to high-resolution keyboard timestamp events">
> > + Creates a new input timestamps object that represents a subscription
> > + to high-resolution timestamp events for all wl_keyboard events that
> > + carry a timestamp.
> > +
> > + If the associated wl_keyboard resource is invalidated, either through
> > + client action (e.g., release) or server-side changes, the input
> > + timestamps object becomes inert.
> > + </description>
> > + <arg name="id" type="new_id" interface="zwp_input_timestamps_v1"/>
> > + <arg name="keyboard" type="object" interface="wl_keyboard"
> > + summary="the wl_keyboard for which to get timestamp events"/>
> > + </request>
> > +
> > + <request name="get_touch_timestamps">
> > + <description summary="subscribe to high-resolution touch timestamp events">
> > + Creates a new input timestamps object that represents a subscription
> > + to high-resolution timestamp events for all wl_touch events that
> > + carry a timestamp.
> > +
> > + If the associated wl_touch resource becomes invalid, either through
> > + client action (e.g., release) or server-side changes, the input
> > + timestamps object becomes inert.
> > + </description>
> > + <arg name="id" type="new_id" interface="zwp_input_timestamps_v1"/>
> > + <arg name="touch" type="object" interface="wl_touch"
> > + summary="the wl_touch for which to get timestamp events"/>
> > + </request>
> > + </interface>
> > +
> > + <interface name="zwp_input_timestamps_v1" version="1">
> > + <description summary="context object for input timestamps">
> > + Provides high-resolution timestamp events for input events.
> > + </description>
> > +
> > + <request name="destroy" type="destructor">
> > + <description summary="destroy the input timestamps object">
> > + Informs the server that the client will no longer be using this
> > + protocol object. After the server processes the request, no more
> > + timestamp events will be emitted.
> > + </description>
> > + </request>
> > +
> > + <event name="timestamp">
> > + <description summary="high-resolution timestamp event">
> > + The timestamp event is sent just before the corresponding input event
> > + and provides a high-resolution version of the timestamp argument of the
> > + event that follows.
>
> probably better to write this as "first subsequent input event" to avoid
> locking yourself into a protocol where [timestamp, input event] is the only
> permissible sequence. We already stack some input events with extra events
> so avoiding a fixed sequence is preferable. This way you can have a [axis
> source, timestamp, axis] sequence but also a [timestamp, axis source, axis]
> sequence.
This makes sense, I will update the wording.
> For pointer and touch events we have frames now to group identical events
> together. It may be worth it to bind the timestamp to the frames to reduce
> the events. Mind you, the only real reduction you'd see is during diagonal
> scrolling. But doing so makes the protocol more precise, I'm not a big fan
> of just saying "corresponding input event".
>
> We also have the wp_tablet protocol with wp_tablet_tool.frame events.
Timestamps in the core protocols are associated with each input event
rather than the frame. If we change this association in the
input-timestamps protocol we will be inconsistent with the core
protocols. On the other hand, in wp_tablet the time is attached to frame
events for interfaces that provide one.
All things considered, I think that in terms of consistency and
simplicity it would be better to avoid introducing new timestamp
semantics for input interfaces into this protocol. That is, the
input-timestamps protocol should provide improved timestamps for input
events only if the events already carry a timestamp (which is what this
RFC currently describes).
Thanks,
Alexandros
More information about the wayland-devel
mailing list