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.hutte...@who-t.net> wrote: > > Signed-off-by: Peter Hutterer <peter.hutte...@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 > > > _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
