Signed-off-by: Peter Hutterer <peter.hutte...@who-t.net> --- This is the revamped version of the tablet protocol for graphics tablets (e.g. Wacom tablets). Too many changes from the last version (a year ago or so), so I won't detail them, best to look at it with fresh eyes.
Makefile.am | 1 + unstable/tablet/README | 4 + unstable/tablet/tablet-unstable-v1.xml | 588 +++++++++++++++++++++++++++++++++ 3 files changed, 593 insertions(+) create mode 100644 unstable/tablet/README create mode 100644 unstable/tablet/tablet-unstable-v1.xml diff --git a/Makefile.am b/Makefile.am index 4bcab32..588cb2c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -6,6 +6,7 @@ protocols = \ unstable/text-input/text-input-unstable-v1.xml \ unstable/input-method/input-method-unstable-v1.xml \ unstable/xdg-shell/xdg-shell-unstable-v5.xml \ + unstable/tablet/tablet-unstable-v1.xml \ $(NULL) nobase_dist_pkgdata_DATA = $(protocols) diff --git a/unstable/tablet/README b/unstable/tablet/README new file mode 100644 index 0000000..7ba8e77 --- /dev/null +++ b/unstable/tablet/README @@ -0,0 +1,4 @@ +Tablet protocol + +Maintainers: +Peter Hutterer <peter.hutte...@who-t.net> diff --git a/unstable/tablet/tablet-unstable-v1.xml b/unstable/tablet/tablet-unstable-v1.xml new file mode 100644 index 0000000..b07eccb --- /dev/null +++ b/unstable/tablet/tablet-unstable-v1.xml @@ -0,0 +1,588 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="wayland_tablet_unstable_v1"> + <description summary="Wayland protocol for graphics tablets"> + This description provides a high-level overview of the interplay between + the interfaces defined this protocol. For details, see the protocol + specification. + + More than one tablet may exist, and device-specifics matter. Tablets are + not represented by a single virtual device like wl_pointer. A client + binds to the tablet manager object which is just a proxy object. From + that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat) + and that returns the actual interface that has all the tablets. With + this indirection, we can avoid merging wp_tablet into the actual wayland + protocol, a long-term benefit. + + The wp_tablet_seat sends a "tablet added" for each tablet connected. + That event is followed by descriptive events about the hardware; + currently that includes events for name, vid/pid and + internal/external/display type, and a wp_tablet.path event that + describes a local path. This path can be used to uniquely identify a + tablet, or get more information through libwacom. Emulated or nested + tablets can skip any of those, e.g. a virtual tablet may not have a + vid/pid. The sequence of descriptive events is terminated by a + wp_tablet.done event to signal that a client may now finalize any + initialization for that tablet. + + Events from tablets require a tool in proximity. Tools are also managed + by the tablet seat, a "tool added" is sent whenever a tool is new to + the compositor. That event is followed by a number of descriptive events + about the hardware; currently that includes capabilities, serial id, + hardware serial and tool type. Similar to the tablet interface, a + wp_tablet_tool.done event is sent to terminate that initial sequence. + + Any event from a tool happens on the wp_tablet_tool interface. When the + tool gets into proximity of the tablet, a proximity_in event is sent on + the wp_tablet_tool interface, listing the tablet and the surface. That + event is followed by a motion event with the coordinates. After that, + it's the usual motion, axis, button, etc. events. + The protocol's serialisation means events are grouped by by + wp_tablet_tool.frame events. + + Two special events (that don't exist in X) are down and up. They signal + "tip touching the surface". For tablets without real proximity + detection, the sequence is: proximity_in, motion, down, frame. + + When the tool leaves proximity, a proximity_out event is sent, followed + by button release events for any button still down. This signals to + the client that the buttons were held when the tool left proximity. + Those events are all sent within the same frame. + + If the tool moves out of the surface but stays in proximity (i.e. + between windows), compositor-specific grab policies apply. This usually + means that the proximity-out is delayed until all buttons are released. + + Moving a tool physically from one tablet to the other has no real effect + on the protocol, since we already have the tool object from the "tool + added" event. All the information is already there and the proximity_in + is all a client needs to reconstruct what happened. + + 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. The current axes are pressure, tilt (both x/y required) and + distance, the most common set. + + Since tablets work independently of the pointer controlled by the mouse, + the focus handling is independent too and controlled by proximity. + The wp_tablet_tool.set_cursor request sets a tool-specific cursor. + This cursor surface may be the same as the mouse cursor, and it may be + the same across tools but it is possible to be more fine-grained. For + example, a client may set different cursors for the pen and eraser. + + Tools are generally independent of tablets and it is + compositor-specific policy when a tool can removed. Common approaches + will likely include some form of removing a tool when all tablets the + tool was used on is removed. + + 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> + <copyright> + Copyright 2014 © Stephen "Lyude" Chandler Paul + Copyright 2015 © Red Hat, Inc. + + 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> + <interface name="zwp_tablet_manager1" version="1"> + <description summary="controller object for graphic tablet devices"> + An object that provides access to the graphics tablets available on this + system. Any tablet is associated with a seat, to get access to the + actual tablets, use wp_tablet_manager.get_tablet_seat. + </description> + + <request name="get_tablet_seat"> + <description summary="get the tablet seat"> + Get the wp_tablet_seat object for the given seat. This object + provides access to all graphics tablets in this seat. + </description> + <arg name="tablet_seat" type="new_id" interface="zwp_tablet_seat1"/> + <arg name="seat" type="object" interface="wl_seat" summary="The wl_seat object to retrieve the tablets for" /> + </request> + + <request name="destroy" type="destructor"> + <description summary="release the memory for the tablet manager object"> + This destroys the resources associated with the tablet manager. + </description> + </request> + </interface> + + <interface name="zwp_tablet_seat1" version="1"> + <description summary="controller object for graphic tablet devices of a seat"> + An object that provides access to the graphics tablets available on this + seat. After binding to this interface, the compositor sends a set of + wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events. + </description> + + <request name="destroy" type="destructor"> + <description summary="release the memory for the tablet seat object"> + This destroys the resources associated with the tablet seat. + </description> + </request> + + <event name="tablet_added"> + <description summary="new device notification"> + This event is sent whenever a new tablet becomes available on this + seat. This event only provides the object id of the tablet, any + static information about the tablet (device name, vid/pid, etc.) is + sent through the wp_tablet interface. + </description> + <arg name="id" type="new_id" interface="zwp_tablet1" summary="the newly added graphics tablet"/> + </event> + + <event name="tool_added"> + <description summary="a new tool has been used with a tablet"> + This event is sent whenever a tool that has not previously been used + with a tablet comes into use. This event only provides the object id + of the tool, any static information about the tool (capabilities, + type, et.c) is sent through the wp_tablet_tool interface. + </description> + <arg name="id" type="new_id" interface="zwp_tablet_tool1" summary="the newly added tablet tool"/> + </event> + </interface> + + <interface name="zwp_tablet_tool1" version="1"> + <description summary="a physical tablet tool"> + An unique object that represents a physical tool that has been, or is + currently in use with a tablet in this seat. Each wp_tablet_tool + object stays valid until the client destroys it; the compositor + reuses the wp_tablet_tool object to indicate that the object's + respective physical tool has come into proximity of a tablet again. + A client must not call wp_tablet_tool.destroy until it receives a + wp_tablet_tool.release event. + + A wp_tablet_tool object's uniqueness depends on the tablet's ability + to report serial numbers. If the tablet doesn't support this + capability, then the tool cannot be guaranteed to be unique. + + A tablet tool has a number of static characteristics, e.g. tool type, + serial_id and capabilities. These capabilities are sent in an event + sequence after the wp_tablet_seat.tool_added event before any actual + events from this tool. This initial event sequence is terminated by a + wp_tablet_tool.done event. + + Tablet tool events are grouped by wp_tablet_tool.frame events. + Any events received before a wp_tablet_tool.frame event should be + considered part of the same hardware state change. + </description> + + <request name="set_cursor"> + <description summary="set the tablet tool's surface"> + Sets the surface of the cursor used for this tool on the given + tablet. The surface is only shown when this tool is in proximity of + this tablet. If the surface is NULL, the pointer image is hidden + completely. + + The parameters hotspot_x and hotspot_y define the position of the + pointer surface relative to the pointer location. Its top-left corner + is always at (x, y) - (hotspot_x, hotspot_y), where (x, y) are the + coordinates of the pointer location, in surface local coordinates. + + On surface.attach requests to the pointer surface, hotspot_x and + hotspot_y are decremented by the x and y parameters passed to the + request. Attach must be confirmed by wl_surface.commit as usual. + + The hotspot can also be updated by passing the currently set pointer + surface to this request with new values for hotspot_x and hotspot_y. + + The current and pending input regions of the wl_surface are cleared, + and wl_surface.set_input_region is ignored until the wl_surface is no + longer used as the cursor. When the use as a cursor ends, the current + and pending input regions become undefined, and the wl_surface is + unmapped. + + This request gives the surface the role of a cursor. The role + assigned by this request is the same as assigned by + wl_pointer.set_cursor meaning the same surface can be + used both as a wl_pointer cursor and a wp_tablet cursor. If the + surface already has another role, it raises a protocol error + The surface may be used on multiple tablets and across multiple + seats. + </description> + <arg name="serial" type="uint" summary="serial of the enter event"/> + <arg name="surface" type="object" interface="wl_surface" allow-null="true"/> + <arg name="hotspot_x" type="int" summary="x coordinate in surface-relative coordinates"/> + <arg name="hotspot_y" type="int" summary="y coordinate in surface-relative coordinates"/> + </request> + + <request name="destroy" type="destructor"> + <description summary="destroy the tool object"> + This destroys the client's resource for this tool object. + + A client must not issue this request until it receives a + wp_tablet_tool.remove event. + </description> + </request> + + <enum name="type"> + <description summary="a physical tool type"> + Describes the physical type of a tool. The physical type of a tool + generally defines its base usage. + + The mouse tool represents a mouse-shaped tool that is not a relative + device but bound to the tablet's surface, providing absolute + coordinates. + + The lens tool is a mouse-shaped tool with an attached lens to + provide precision focus. + </description> + <entry name="pen" value="0x140" summary="Pen"/> + <entry name="eraser" value="0x141" summary="Eraser"/> + <entry name="brush" value="0x142" summary="Brush"/> + <entry name="pencil" value="0x143" summary="Pencil"/> + <entry name="airbrush" value="0x144" summary="Airbrush"/> + <entry name="finger" value="0x145" summary="Finger"/> + <entry name="mouse" value="0x146" summary="Mouse"/> + <entry name="lens" value="0x147" summary="Lens"/> + </enum> + + <event name="type"> + <description summary="tool type"> + The tool type is the high-level type of the tool and usually decides + the interaction expected from this tool. + + This event is sent in the initial burst of events before the + wp_tablet_tool.done event. + </description> + <arg name="tool_type" type="uint" summary="the physical tool type"/> + </event> + + <event name="serial_id"> + <description summary="unique serial number of the tool"> + If the tool can be identified by a unique 64-bit serial number, this + event notifies the client of the 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="serial_id_msb" type="uint" summary="the unique serial number of the tool, most significant bits"/> + <arg name="serial_id_lsb" type="uint" summary="the unique serial number of the tool, least significant bits"/> + </event> + + <enum name="hardware_id_format"> + <description summary="the hardware id format"> + Specifies the format of the hardware id in the + wp_tablet_tool.hardware_id event. + + A wacom_stylus_id format indicates a hardware id as the id used by + graphics tablet made by Wacom Inc. For example, on Wacom tablets the + hardware id of a Grip Pen (a stylus) is 0x802. + </description> + <entry name="wacom_stylus_id" value="0" /> + </enum> + + <event name="hardware_id"> + <description summary="hardware id notification"> + 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 device-specific. + + This event is sent in the initial burst of events before the + wp_tablet_tool.done event. + </description> + <arg name="format" type="uint" summary="the type of the id" /> + <arg name="hardware_id_msb" type="uint" summary="the hardware id, most significant bits"/> + <arg name="hardware_id_lsb" type="uint" summary="the hardware id, least significant bits"/> + </event> + + + <enum name="capability"> + <description summary="capability flags for a tool"> + Describes extra capabilities on a tablet. + + Any tool must provide x and y values, extra axes are + device-specific. + </description> + <entry name="tilt" value="1" summary="Tilt axes"/> + <entry name="pressure" value="2" summary="Pressure axis"/> + <entry name="distance" value="3" summary="Distance axis"/> + </enum> + + <event name="capability"> + <description summary="tool capability notification"> + This event notifies the client of any capabilities of this tool, + beyond the main set of x/y axes and tip up/down detection. + + One event is sent for each extra capability available on this tool. + + This event is sent in the initial burst of events before the + wp_tablet_tool.done event. + </description> + <arg name="capability" type="uint" summary="the capability"/> + </event> + + <event name="done"> + <description summary="tool description events sequence complete"> + This event signals the end of the initial burst of descriptive + events. A client may consider the static description of the tool to + be complete and finalize initialization of the tool. + </description> + </event> + + <event name="removed"> + <description summary="tool removed"> + This event is sent when the tool is removed from the system. The client + should not expect the resource it currently has associated with the + tool to be used again if the tool comes back into proximity later. + + It is compositor-dependent when a tool is removed. Some tools are + associated with a single tablet only and may get removed when the + respective tablet is removed. Other tools may be used on multiple + tablets and removing a tablet may not remove this tool. + + When this event is received, the client must wp_tablet_tool.destroy + the object. + </description> + </event> + + <event name="proximity_in"> + <description summary="proximity in event"> + Notification that this tool is focused on a certain surface. + + This event can be received when the tool has moved from one surface to + another, or when the tool has come back into proximity above the + surface. + + Any button events sent within the same wp_tablet.frame as a + proximity_in event indicate the button state of the tool at the time + of proximity in. + </description> + <arg name="serial" type="uint"/> + <arg name="tablet" type="object" interface="zwp_tablet1" summary="The tablet the tool is in proximity of"/> + <arg name="surface" type="object" interface="wl_surface" summary="The current surface the tablet tool is over"/> + </event> + + <event name="proximity_out"> + <description summary="proximity out event"> + Notification that this tool has either left proximity, or is no + longer focused on a certain surface. + + When the tablet tool leaves proximity of the tablet, button release + events are sent for each button that was held down at the time of + leaving proximity. These events are sent in the same wp_tablet.frame + of the proximity_out event. + + If the tool stays within proximity of the tablet, but the focus + changes from one surface to another, a button release event may not + be sent until the button is actually released or the tool leaves the + proximity of the tablet. + </description> + </event> + + <event name="down"> + <description summary="tablet tool is making contact"> + Sent whenever the tablet tool comes in contact with the surface of the + tablet. If the tablet tool moves out of a region while in contact with + the surface of the tablet, the client owning said region will receive a + wp_tablet::up event, followed by a wp_tablet::proximity_out event and a + wp_tablet::frame event. + </description> + <arg name="serial" type="uint"/> + </event> + + <event name="up"> + <description summary="tablet tool is no longer making contact"> + Sent whenever the tablet tool stops making contact with the surface of + the tablet, or when the tablet tool moves off of a surface while it was + making contact with the tablet's surface. + </description> + </event> + + <event name="motion"> + <description summary="motion event"> + Sent whenever a tablet tool moves. + </description> + <arg name="x" type="fixed" summary="surface-relative x coordinate"/> + <arg name="y" type="fixed" summary="surface-relative y coordinate"/> + </event> + + <event name="pressure"> + <description summary="pressure change event"> + Sent whenever the pressure axis on a tool changes. The value of this + event is normalized to a value between 0 and 65535. + </description> + <arg name="pressure" type="uint" summary="The current pressure value"/> + </event> + + <event name="distance"> + <description summary="distance change event"> + Sent whenever the distance axis on a tool changes. The value of this + event is normalized to a value between 0 and 65535. + </description> + <arg name="distance" type="uint" summary="The current distance value"/> + </event> + + <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> + + <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 stylus 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" 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_tablet1" 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 vid/pid"> + This event is sent in the initial burst of events before the + wp_tablet.done event. + </description> + <arg name="vid" type="uint" summary="vendor id"/> + <arg name="pid" type="uint" summary="product id"/> + </event> + + <enum name="type"> + <description summary="tablet type"> + Describes the type of tablet + </description> + + <entry name="external" value="0" summary="The tablet is an external tablet, such as an Intuos"/> + <entry name="internal" value="1" summary="The tablet is a built-in tablet, usually in a laptop"/> + <entry name="display" value="2" summary="The tablet is a display tablet, such as a Cintiq"/> + </enum> + + <event name="type"> + <description summary="the tablet type"> + This event is sent in the initial burst of events before the + wp_tablet.done event. + </description> + <arg name="type" type="uint" summary="the tablet type (internal, external, ...)"/> + </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.4.3 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel