[PATCH v3 wayland-protocols] Add the tablet protocol
Peter Hutterer
peter.hutterer at who-t.net
Tue Feb 2 23:58:31 UTC 2016
On Fri, Jan 29, 2016 at 11:40:44AM -0800, Jason Gerecke wrote:
> On Thu, Jan 28, 2016 at 8:32 PM, Peter Hutterer
> <peter.hutterer at who-t.net> wrote:
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> > Changes to v2:
> > - renamed hwserial to hardware_serial
> > - renamed to hwid event to a hardware_id_wacom. no-one else uses this ID
> > type, so having a generic event with a wacom-specific type + enum is
> > optimistic. The next company may use a string instead, so it'll be
> > non-generic anyway. Might as well rename it to something specific now.
> > - added slider, rotation and wheel axes
> > - couple of documentation fixes
> >
> > Makefile.am | 1 +
> > unstable/tablet/README | 4 +
> > unstable/tablet/tablet-unstable-v1.xml | 622 +++++++++++++++++++++++++++++++++
> > 3 files changed, 627 insertions(+)
> > create mode 100644 unstable/tablet/README
> > create mode 100644 unstable/tablet/tablet-unstable-v1.xml
[...]
> > +
> > + <event name="hardware_serial">
> > + <description summary="unique hardware serial number of the tool">
> > + If the physical tool can be identified by a unique 64-bit serial
> > + number, this event notifies the client of this serial number.
> > +
> > + If multiple tablets are available in the same seat and the tool is
> > + uniquely identifiable by the serial number, that tool may move
> > + between tablets.
> > +
> > + Otherwise, if the tool has no serial number and this event is
> > + missing, the tool is tied to the tablet it first comes into
> > + proximity with. Even if the physical tool is used on multiple
> > + tablets, separate wp_tablet_tool objects will be created, one per
> > + tablet.
> > +
> > + This event is sent in the initial burst of events before the
> > + wp_tablet_tool.done event.
> > + </description>
> > + <arg name="hardware_serial_hi" type="uint" summary="the unique serial number of the tool, most significant bits"/>
> > + <arg name="hardware_serial_lo" type="uint" summary="the unique serial number of the tool, least significant bits"/>
>
> Any idea how resistant the core Wayland protocol developers would be
> to adding native 64-bit datatypes? Its a bit of a hassle to split and
> recombine the data on both sides of the wire, though its admittedly
> not often that you need to deal with such large types...
did some digging, found:
http://lists.freedesktop.org/archives/wayland-devel/2014-April/014305.html
probably still accurate, so I guess the answer remains at "no can do" :)
>
> > + </event>
> > +
> > + <event name="hardware_id_wacom">
> > + <description summary="hardware id notification in Wacom's format">
> > + This event notifies the client of a hardware id available on this tool.
> > +
> > + The hardware id is a device-specific 64-bit id that provides extra
> > + information about the tool in use, beyond the wl_tool.type
> > + enumeration. The format of the id is specific to tablets made by
> > + Wacom Inc. For example, the hardware id of a Wacom Grip
> > + Pen (a stylus) is 0x802.
> > +
> > + This event is sent in the initial burst of events before the
> > + wp_tablet_tool.done event.
> > + </description>
> > + <arg name="hardware_id_hi" type="uint" summary="the hardware id, most significant bits"/>
> > + <arg name="hardware_id_lo" type="uint" summary="the hardware id, least significant bits"/>
> > + </event>
>
> If this event is specific to Wacom hardware, it would probably be okay
> to limit it to a single uint since that's all that is reported by
> current tools. Though since it'd be painful to expand retroactively
> I'm also fine leaving it at 64 bits if you want.
I think having 64 bits now will just save us the trouble later and it's
fairly minimal code on the client side.
Cheers,
Peter
> > +
> > + <event name="tilt">
> > + <description summary="tilt change event">
> > + Sent whenever one or both of the tilt axes on a tool change. Each tilt
> > + value is normalized between -65535 and 65535.
> > + </description>
> > + <arg name="tilt_x" type="int" summary="The current value of the X tilt axis"/>
> > + <arg name="tilt_y" type="int" summary="The current value of the Y tilt axis"/>
> > + </event>
> > +
> > + <event name="rotation">
> > + <description summary="z-rotation change event">
> > + Sent whenever the z-rotation axis on the tool changes. The
> > + rotation value is in 0.01 of a degree clockwise from the tool's
> > + logical neutral position.
> > + </description>
>
> From the protocol description: "Any extra axis is normalized, i.e. the
> client knows the range as specified in the protocol (e.g. [0, 65535]),
> the granularity however is unknown." This was chosen because we don't
> always have the necessary information to translate a kernel value for
> a given device's axis into a physical measurement, but we can always
> report a normalized value that that gives clients a sense of its
> relative magnitude.
>
> We do need to provide a way for clients to translate the normalized
> values into physical measurements if possible though. I would suggest
> adding the following event to the tool definition. Several could be
> sent as part of the initial pre-"done" burst.
>
> <event name="physical_range">
> <description summary="tool physical range notification">
> This event provides information about the physical range of one
> of the axes of the tool. This information can be used to translate
> the normalized values (0 to 65535, or -65535 to +65535) axis values
> sent by events into physical quantities.
>
> Minimum and maximum values have units of gram-force for pressure,
> millimeters for distance, and degrees of arc for tilt and rotation.
> This event will not be sent for axes whose physical minimum and
> maximum is not known.
> </description>
> <arg name="capability" type="uint" enum="capability" summary="the
> capability"/>
> <arg name="minimum" type="fixed" summary="physical value of axis minimum"/>
> <arg name="maximum" type="fixed" summary="physical value of axis maximum"/>
> </event>
>
>
> > + <arg name="degrees" type="int" summary="The current rotation of the Z axis"/>
> > + </event>
> > +
> > + <event name="slider">
> > + <description summary="Slider position change event">
> > + Sent whenever the slider position on the tool changes. The
> > + value is normalized between -65535 and 65535, with 0 as the logical
> > + neutral position of the slider.
> > +
> > + The slider is available on e.g. the Wacom Airbrush tool.
> > + </description>
> > + <arg name="position" type="int" summary="The current position of slider"/>
> > + </event>
> > +
> > + <event name="wheel">
> > + <description summary="Wheel delta event">
> > + Sent whenever the wheel on the tool emits an event. This event
> > + contains two values for the same axis change. The degrees value is
> > + in 0.01 of a degree in the same orientation as the
> > + wl_pointer.vertical_scroll axis. The clicks value is in discrete
> > + logical clicks of the mouse wheel. This value may be zero if the
> > + movement of the wheel was less than one logical click.
>
> Same comments as for "rotation"
>
> Jason
> ---
> Now instead of four in the eights place /
> you’ve got three, ‘Cause you added one /
> (That is to say, eight) to the two, /
> But you can’t take seven from three, /
> So you look at the sixty-fours....
>
>
> > +
> > + Clients should choose either value and avoid mixing degrees and
> > + clicks. The compositor may accumulate values smaller than a logical
> > + click and emulate click events when a certain threshold is met.
> > + Thus, wl_tablet_tool.wheel events with non-zero clicks values may
> > + have different degrees values.
> > + </description>
> > + <arg name="degrees" type="int" summary="The wheel delta in 0.01 of a degree"/>
> > + <arg name="clicks" type="int" summary="The wheel delta in discrete clicks"/>
> > + </event>
> > +
> > + <enum name="button_state">
> > + <description summary="physical button state">
> > + Describes the physical state of a button which provoked the button event
> > + </description>
> > + <entry name="released" value="0" summary="button is not pressed"/>
> > + <entry name="pressed" value="1" summary="button is pressed"/>
> > + </enum>
> > +
> > + <event name="button">
> > + <description summary="button event">
> > + Sent whenever a button on the tool is pressed or released.
> > + </description>
> > +
> > + <arg name="serial" type="uint"/>
> > + <arg name="button" type="uint" summary="The button whose state has changed"/>
> > + <arg name="state" type="uint" enum="button_state" summary="Whether the button was pressed or released"/>
> > + </event>
> > +
> > + <event name="frame">
> > + <description summary="frame event">
> > + Marks the end of a series of axis and/or button updates from the
> > + tablet. The wayland protocol requires axis updates to be sent
> > + sequentially, however all events within a frame should be considered
> > + one hardware event.
> > + </description>
> > + <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
> > + </event>
> > +
> > + <enum name="error">
> > + <entry name="role" value="0" summary="given wl_surface has another role"/>
> > + </enum>
> > + </interface>
> > +
> > + <interface name="zwp_tablet_v1" version="1">
> > + <description summary="graphics tablet device">
> > + The wp_tablet interface represents one graphics tablet device. The
> > + tablet interface itself does not generate events, all events are
> > + generated by wp_tablet_tool objects when in proximity above a tablet.
> > +
> > + A tablet has a number of static characteristics, e.g. device name and
> > + pid/vid. These capabilities are sent in an event sequence after the
> > + wp_tablet_seat.tablet_added event. This initial event sequence is
> > + terminated by a wp_tablet.done event.
> > + </description>
> > +
> > + <request name="destroy" type="destructor">
> > + <description summary="destroy the tablet object">
> > + This destroys the client's resource for this tablet object.
> > +
> > + A client must not issue this request until it receives a
> > + wp_tablet.remove event.
> > + </description>
> > + </request>
> > +
> > + <event name="name">
> > + <description summary="tablet device name">
> > + This event is sent in the initial burst of events before the
> > + wp_tablet.done event.
> > + </description>
> > + <arg name="name" type="string" summary="the device name"/>
> > + </event>
> > +
> > + <event name="id">
> > + <description summary="tablet device USB vendor/product id">
> > + This event is sent in the initial burst of events before the
> > + wp_tablet.done event.
> > + </description>
> > + <arg name="vid" type="uint" summary="USB vendor id"/>
> > + <arg name="pid" type="uint" summary="USB product id"/>
> > + </event>
> > +
> > + <event name="path">
> > + <description summary="path to the device">
> > + A system-specific device path that indicates which device is behind
> > + this wp_tablet. This information may be used to gather additional
> > + information about the device, e.g. through libwacom.
> > +
> > + A device may have more than one device path, if so, multiple
> > + wp_tablet.path events are sent. A device may be emulated and not
> > + have a device path, in that case this event will not be sent.
> > +
> > + The format of the path is unspecified, it may be a device node, a
> > + sysfs path, or some other identifier. It is up to the client to
> > + identify the string provided.
> > +
> > + This event is sent in the initial burst of events before the
> > + wp_tablet.done event.
> > + </description>
> > + <arg name="path" type="string" summary="path to local device"/>
> > + </event>
> > +
> > + <event name="done">
> > + <description summary="tablet description events sequence complete">
> > + This event is sent immediately to signal the end of the initial
> > + burst of descriptive events. A client may consider the static
> > + description of the tablet to be complete and finalize initialization
> > + of the tablet.
> > + </description>
> > + </event>
> > +
> > + <event name="removed">
> > + <description summary="tablet removed event">
> > + Sent when the tablet has been removed from the system. When a tablet
> > + is removed, some tools may be removed.
> > +
> > + When this event is received, the client must wp_tablet.destroy
> > + the object.
> > + </description>
> > + </event>
> > + </interface>
> > +</protocol>
> > --
> > 2.5.0
> >
>
More information about the wayland-devel
mailing list