From 0b387b43402cb1268dcdd58ec806270eeb1d32b6 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 29 Feb 2024 10:23:27 +1000 Subject: [PATCH 1/4] tablet: Bump the tablet protocol version Unfortunately all the objects depend on each other so any change in any requires bumping all versions. --- unstable/tablet/tablet-unstable-v2.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml index ccbb541..e8018e8 100644 --- a/unstable/tablet/tablet-unstable-v2.xml +++ b/unstable/tablet/tablet-unstable-v2.xml @@ -3,7 +3,7 @@ Copyright 2014 © Stephen "Lyude" Chandler Paul - Copyright 2015-2016 © Red Hat, Inc. + Copyright 2015-2024 © Red Hat, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files @@ -115,7 +115,7 @@ interface version number is reset. - + An object that provides access to the graphics tablets available on this system. All tablets are associated with a seat, to get access to the @@ -139,7 +139,7 @@ - + An object that provides access to the graphics tablets available on this seat. After binding to this interface, the compositor sends a set of @@ -190,7 +190,7 @@ - + An object that represents a physical tool that has been, or is currently in use with a tablet in this seat. Each wp_tablet_tool @@ -576,7 +576,7 @@ - + The wp_tablet interface represents one graphics tablet device. The tablet interface itself does not generate events; all events are @@ -651,7 +651,7 @@ - + A circular interaction area, such as the touch ring on the Wacom Intuos Pro series tablets. @@ -765,7 +765,7 @@ - + A linear interaction area, such as the strips found in Wacom Cintiq models. @@ -881,7 +881,7 @@ - + A pad group describes a distinct (sub)set of buttons, rings and strips present in the tablet. The criteria of this grouping is usually positional, @@ -1016,7 +1016,7 @@ - + A pad device is a set of buttons, rings and strips usually physically present on the tablet device itself. Some From b5bafcc56d305f2b186702acca8ad6d49adcacb4 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 29 Feb 2024 10:43:37 +1000 Subject: [PATCH 2/4] tablet: Add scroll events to the tablet interface A common-enough interaction with the tablet is to use the tablet for scrolling - either "pan-scrolling" (one specific pen button down, moving the pen scroll) or ring-scrolling/strip-scrolling. Neither are supported in the protocol right now and we completely rely on the client to implement this interaction - arguably this should be supported more generically in the compositor to have the same interactions work the same way. --- unstable/tablet/tablet-unstable-v2.xml | 213 +++++++++++++++++++++++++ 1 file changed, 213 insertions(+) diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml index e8018e8..5d47c8e 100644 --- a/unstable/tablet/tablet-unstable-v2.xml +++ b/unstable/tablet/tablet-unstable-v2.xml @@ -574,6 +574,107 @@ + + + + + Scroll event notification. + + This event indicates a logical scroll motion along the x and/or y axis. + The x and y values are relative deltas of the scroll motion in a coordinate + space identical to those of motion events. When applicable, a client can + transform its content relative to the scroll distance. + + A compositor must not send a scroll event with both x and y on zero. + + A scroll event may occur outside a scroll_start/scroll_stop sequence to + indicate it is a standalone event. This may happen if the compositor is + unable to detect boundary conditions (e.g. finger down or button down) and + can thus only provide the scroll events. It is up to the client on how to + process these events (e.g. whether to provide kinetic scrolling). + + If a scroll_start event is sent by the compositor, all scroll events until + a subsequent scroll_stop are part of the same scroll gesture. + + The timestamp of this event is that of the corresponding frame event. + + The scroll and scroll_v120 events are mutually exclusive and must + not occur in the same frame. + + + + + + + + Discrete high-resolution scroll information. + + The values of this event is interpreted identical to the + wl_pointer.axis_value120 event as of wl_pointer version 8. + + A compositor must not send a scroll_v120 event with both x and y on zero. + + This event carries high-resolution wheel scroll information, + with each multiple of 120 representing one logical scroll step + (a wheel detent). For example, an scroll_v120 value of 30 is one + quarter of a logical scroll step in the positive direction, a value of + -240 are two logical scroll steps in the negative direction within the + same hardware event. + Clients that rely on discrete scrolling should accumulate the + values to multiples of 120 before processing the event. + + The timestamp of this event is that of the corresponding frame event. + + The scroll and scroll_v120 events are mutually exclusive and must + not occur in the same frame. + + scroll_v120 events may be part of a scroll_start/scroll_stop sequence and follow + the same semantics as the scroll event. See the scroll event documentation for + details. + + + + + + + + Notification about the start of a logical scroll sequence. + + This event signals that a user has initiated a scroll sequence (e.g. by + touching a scrollable hardware surface or pressing a button). + Such a sequence must comprise of exactly one scroll_start event + followed by zero or more scroll or scroll_v120 events and then exactly one + scroll_stop event. + + The timestamp of this event is that of the corresponding frame event. + + A scroll_start event may occur in the same frame as a scroll and scroll_v120 event. + A scroll_start event may occur in the same frame as a scroll_stop event. + + + + + + + Notification about the end of a logical scroll sequence. + + This event signals that a user has stopped interacting with a scroll sequence + (e.g. by lifting a finger or releasing a button). + Such a sequence must comprise of exactly one scroll_start event + followed by zero or more scroll or scroll_v120 events and then exactly one + scroll_stop event. + + If cancelled is nonzero, the scroll sequence was cancelled and a client should + attempt to undo any state changes made by this seqeuence. + + The timestamp of this event is that of the corresponding frame event. + + A scroll_stop event may occur in the same frame as a scroll and scroll_v120 event. + A scroll_stop event may occur in the same frame as a scroll_start event. + + + + @@ -1174,5 +1275,117 @@ the pad itself. + + + + + Marks the end of a series of axis and/or button updates from the + pad. The Wayland protocol requires axis updates to be sent + sequentially, however all events within a frame should be considered + one hardware event. + + + + + + + Scroll event notification. + + This event indicates a logical scroll motion along the x and/or y axis. + The x and y values are relative deltas of the scroll motion in a coordinate + space identical to those of motion events. When applicable, a client can + transform its content relative to the scroll distance. + + A compositor must not send a scroll event with both x and y on zero. + + A scroll event may occur outside a scroll_start/scroll_stop sequence to + indicate it is a standalone event. This may happen if the compositor is + unable to detect boundary conditions (e.g. finger down or button down) and + can thus only provide the scroll events. It is up to the client on how to + process these events (e.g. whether to provide kinetic scrolling). + + If a scroll_start event is sent by the compositor, all scroll events until + a subsequent scroll_stop are part of the same scroll gesture. + + The timestamp of this event is that of the corresponding frame event. + + The scroll and scroll_v120 events are mutually exclusive and must + not occur in the same frame. + + + + + + + + Discrete high-resolution scroll information. + + The values of this event is interpreted identical to the + wl_pointer.axis_value120 event as of wl_pointer version 8. + + A compositor must not send a scroll_v120 event with both x and y on zero. + + This event carries high-resolution wheel scroll information, + with each multiple of 120 representing one logical scroll step + (a wheel detent). For example, an scroll_v120 value of 30 is one + quarter of a logical scroll step in the positive direction, a value of + -240 are two logical scroll steps in the negative direction within the + same hardware event. + Clients that rely on discrete scrolling should accumulate the + values to multiples of 120 before processing the event. + + The timestamp of this event is that of the corresponding frame event. + + The scroll and scroll_v120 events are mutually exclusive and must + not occur in the same frame. + + scroll_v120 events may be part of a scroll_start/scroll_stop sequence and follow + the same semantics as the scroll event. See the scroll event documentation for + details. + + + + + + + + Notification about the start of a logical scroll sequence. + + This event signals that a user has initiated a scroll sequence (e.g. by + touching a scrollable hardware surface or pressing a button). + Such a sequence must comprise of exactly one scroll_start event + followed by zero or more scroll or scroll_v120 events and then exactly one + scroll_stop event. + + The timestamp of this event is that of the corresponding frame event. + + A scroll_start event may occur in the same frame as a scroll and scroll_v120 event. + A scroll_start event may occur in the same frame as a scroll_stop event. + + + + + + + Notification about the end of a logical scroll sequence. + + This event signals that a user has stopped interacting with a scroll sequence + (e.g. by lifting a finger or releasing a button). + Such a sequence must comprise of exactly one scroll_start event + followed by zero or more scroll or scroll_v120 events and then exactly one + scroll_stop event. + + If cancelled is nonzero, the scroll sequence was cancelled and a client should + attempt to undo any state changes made by this seqeuence. + + The timestamp of this event is that of the corresponding frame event. + + A scroll_stop event may occur in the same frame as a scroll and scroll_v120 event. + A scroll_stop event may occur in the same frame as a scroll_start event. + + + + + From 541d2aa2cb8d253a22d83d9b2d4daa6e45d04adb Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 29 Feb 2024 10:32:00 +1000 Subject: [PATCH 3/4] tablet: Add support for relative dials Some tablets provide one or more rotary controls (see e.g. the Huion Inspiroy Dial 2) that provide delta information effectively equivalent to a mouse wheel. Expose those in the same way as the strip or ring controls, with the event matching the wl_pointer.axis_v120 approach. Like a typical mouse wheel we do not expect there to be a source information, so this is left out of the interface. --- unstable/tablet/tablet-unstable-v2.xml | 93 +++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 3 deletions(-) diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml index 5d47c8e..d85d475 100644 --- a/unstable/tablet/tablet-unstable-v2.xml +++ b/unstable/tablet/tablet-unstable-v2.xml @@ -1115,11 +1115,24 @@ + + + + + + Sent on wp_tablet_pad initialization to announce available dials. + One event is sent for each dial available on this pad group. + + This event is sent in the initial burst of events before the + wp_tablet_pad_group.done event. + + + - - A pad device is a set of buttons, rings and strips + + A pad device is a set of buttons, rings, strips and dials usually physically present on the tablet device itself. Some exceptions exist where the pad device is physically detached, e.g. the Wacom ExpressKey Remote. @@ -1133,7 +1146,7 @@ This initial event sequence is terminated by a wp_tablet_pad.done event. - All pad features (buttons, rings and strips) are logically divided into + All pad features (buttons, rings, strips and dials) are logically divided into groups and all pads have at least one group. The available groups are notified through the wp_tablet_pad.group event; the compositor will emit one event per group before emitting wp_tablet_pad.done. @@ -1388,4 +1401,78 @@ + + + + A rotatary control, such as a dial or a wheel. + + Events on a dial are logically grouped by the wl_tablet_pad_dial.frame + event. + + + + + Requests the compositor to use the provided feedback string + associated with this dial. This request should be issued immediately + after a wp_tablet_pad_group.mode_switch event from the corresponding + group is received, or whenever the dial is mapped to a different + action. See wp_tablet_pad_group.mode_switch for more details. + + Clients are encouraged to provide context-aware descriptions for + the actions associated with the dial, and compositors may use this + information to offer visual feedback about the button layout + (eg. on-screen displays). + + The provided string 'description' is a UTF-8 encoded string to be + associated with this ring, and is considered user-visible; general + internationalization rules apply. + + The serial argument will be that of the last + wp_tablet_pad_group.mode_switch event received for the group of this + dial. Requests providing other serials than the most recent one will be + ignored. + + + + + + + + This destroys the client's resource for this dial object. + + + + + + Sent whenever the position on a dial changes. + + This event carries the wheel delta as multiples or fractions + of 120 with each multiple of 120 representing one logical wheel detent. + For example, an axis_value120 of 30 is one quarter of + a logical wheel step in the positive direction, a value120 of + -240 are two logical wheel steps in the negative direction within the + same hardware event. See the wl_pointer.axis_value120 for more details. + + The value120 must not be zero. + + + + + + + Indicates the end of a set of events that represent one logical + hardware dial event. A client is expected to accumulate the data + in all events within the frame before proceeding. + + All wp_tablet_pad_dial events before a wp_tablet_pad_dial.frame event belong + logically together. + + A wp_tablet_pad_dial.frame event is sent for every logical event + group, even if the group only contains a single wp_tablet_pad_dial + event. Specifically, a client may get a sequence: delta, frame, + delta, frame, etc. + + + + From c1f12085b7e42192a057b9b067c0dbbba04f6626 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 29 Feb 2024 10:23:27 +1000 Subject: [PATCH 4/4] tablet: Add a bustype event to the initial burst of tablet events Just VID/PID is not enough, we need the bustype too --- unstable/tablet/tablet-unstable-v2.xml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/unstable/tablet/tablet-unstable-v2.xml b/unstable/tablet/tablet-unstable-v2.xml index d85d475..126b088 100644 --- a/unstable/tablet/tablet-unstable-v2.xml +++ b/unstable/tablet/tablet-unstable-v2.xml @@ -750,6 +750,18 @@ the object. + + + + + The bustype argument is one of the BUS_ defines in the Linux kernel's + linux/input.h + + This event is sent in the initial burst of events before the + wp_tablet.done event. + + +