[mutter/wip/tablet-protocol-v2: 1/14] protocol: Add wayland-tablet.xml
- From: Carlos Garnacho <carlosg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [mutter/wip/tablet-protocol-v2: 1/14] protocol: Add wayland-tablet.xml
- Date: Wed, 28 Oct 2015 18:35:03 +0000 (UTC)
commit 727b6c022a0c8760f2895a4ddf23cb6fe8ba18bb
Author: Carlos Garnacho <carlosg gnome org>
Date: Fri Jan 9 17:17:22 2015 +0100
protocol: Add wayland-tablet.xml
This contains the Wayland tablet protocol
src/Makefile.am | 3 +
src/wayland/protocol/wayland-tablet.xml | 516 +++++++++++++++++++++++++++++++
2 files changed, 519 insertions(+), 0 deletions(-)
---
diff --git a/src/Makefile.am b/src/Makefile.am
index bee8741..2f67d63 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -51,6 +51,8 @@ mutter_built_sources += \
gtk-shell-server-protocol.h \
xdg-shell-protocol.c \
xdg-shell-server-protocol.h \
+ wayland-tablet-protocol.c \
+ wayland-tablet-server-protocol.h \
$(NULL)
endif
@@ -58,6 +60,7 @@ wayland_protocols = \
wayland/protocol/pointer-gestures.xml \
wayland/protocol/gtk-shell.xml \
wayland/protocol/xdg-shell.xml \
+ wayland/protocol/wayland-tablet.xml \
$(NULL)
libmutter_la_SOURCES = \
diff --git a/src/wayland/protocol/wayland-tablet.xml b/src/wayland/protocol/wayland-tablet.xml
new file mode 100644
index 0000000..fe19451
--- /dev/null
+++ b/src/wayland/protocol/wayland-tablet.xml
@@ -0,0 +1,516 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="wayland_tablet">
+
+ <copyright>
+ Copyright 2014 © Stephen "Lyude" Chandler Paul
+ Copyright 2015 © Red Hat, Inc.
+
+ Permission to use, copy, modify, distribute, and sell this
+ software and its documentation for any purpose is hereby granted
+ without fee, provided that the above copyright notice appear in
+ all copies and that both that copyright notice and this permission
+ notice appear in supporting documentation, and that the name of
+ the copyright holders not be used in advertising or publicity
+ pertaining to distribution of the software without specific,
+ written prior permission. The copyright holders make no
+ representations about the suitability of this software for any
+ purpose. It is provided "as is" without express or implied
+ warranty.
+
+ THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
+ SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+ SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+ AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+ THIS SOFTWARE.
+ </copyright>
+
+ <interface name="wl_tablet_manager" 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 wl_tablet_manager.get_tablet_seat.
+ </description>
+
+ <request name="get_tablet_seat">
+ <description summary="get the tablet seat">
+ Get the wl_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="wl_tablet_seat"/>
+ <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="wl_tablet_seat" 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
+ wl_tablet_seat.tablet_added and wl_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 wl_tablet interface.
+ </description>
+ <arg name="id" type="new_id" interface="wl_tablet" 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 wl_tablet_tool interface.
+ </description>
+ <arg name="id" type="new_id" interface="wl_tablet_tool" summary="the newly added tablet tool"/>
+ </event>
+ </interface>
+
+ <interface name="wl_tablet_tool" 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 wl_tablet_tool
+ object stays valid until the client destroys it; the compositor
+ reuses the wl_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 wl_tablet_tool.destroy until it receives a
+ wl_tablet_tool.release event.
+
+ A wl_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 wl_tablet_seat.tool_added event before any actual
+ events from this tool. This initial event sequence is terminated by a
+ wl_tablet_tool.done event.
+
+ Tablet tool events are grouped by wl_tablet_tool.frame events.
+ Any events received before a wl_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 wl_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"/>
+ <arg name="tablet" type="object" interface="wl_tablet" summary="the tablet the tool must be in
proximity of" />
+ </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
+ wl_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
+ wl_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 wl_tablet_tool objects will be created, one per
+ tablet.
+
+ This event is sent in the initial burst of events before the
+ wl_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
+ wl_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
+ wl_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
+ wl_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 wl_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 wl_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="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ <arg name="tablet" type="object" interface="wl_tablet" 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 wl_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>
+ <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ </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
+ wl_tablet::up event, followed by a wl_tablet::proximity_out event and a
+ wl_tablet::frame event.
+ </description>
+ <arg name="serial" type="uint"/>
+ <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ </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>
+ <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ </event>
+
+ <event name="motion">
+ <description summary="motion event">
+ Sent whenever a tablet tool moves.
+ </description>
+ <arg name="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ <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="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ <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="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ <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="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ <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="time" type="uint" summary="The time of the event with millisecond granularity"/>
+ <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>
+ </event>
+
+ <enum name="error">
+ <entry name="role" value="0" summary="given wl_surface has another role"/>
+ </enum>
+ </interface>
+
+ <interface name="wl_tablet" version="1">
+ <description summary="graphics tablet device">
+ The wl_tablet interface represents one graphics tablet device. The
+ tablet interface itself does not generate events, all events are
+ generated by wl_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
+ wl_tablet_seat.tablet_added event. This initial event sequence is
+ terminated by a wl_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
+ wl_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
+ wl_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
+ wl_tablet.done event.
+ </description>
+ <arg name="vid" type="uint" summary="vendor id"/>
+ <arg name="pid" type="uint" summary="product id"/>
+ </event>
+
+ <enum name="tablet_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
+ wl_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 wl_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
+ wl_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
+ wl_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 wl_tablet.destroy
+ the object.
+ </description>
+ </event>
+ </interface>
+</protocol>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
