wayland-protocols: Add gaming-input-unstable-v1 protocol

third_party/wayland-protocols/unstable/gaming-input/gaming-input-unstable-v1.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="gaming_input_unstable_v1">
+
+  <copyright>
+    Copyright 2016 The Chromium Authors.
+
+    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_gaming_input_v1" version="1">
+    <description summary="extends wl_seat with gaming input devices">
+      A global uinterface to provide gaming input devices for a given seat.
+
+      Currently only gamepad devices are supported.
+
+      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 uinterface version bump.
+      Backward incompatible changes are done by bumping the version number in
+      the protocol and uinterface 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>
+
+    <request name="get_gamepad">
+      <description summary="get gamepad device assigned to seat">
+        Create gamepad object. See zwp_gamepad_v1 interface for details.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_gamepad_v1"/>
+      <arg name="seat" type="object" interface="wl_seat"/>
+    </request>
+  </interface>
+
+  <interface name="zwp_gamepad_v1" version="1">

[reveman, 2016/06/29 22:37:50]

do we need enter/leave events to notify the client when this seat's gamepad
focus is on a certain surface and the state of all buttons?

[denniskempin, 2016/07/12 20:15:23]

as discussed, not with this version of the protocol. Potentially for later
versions. 

+    <description summary="gamepad input device">
+      The zwp_gamepad_v1 interface represents one or more gamepad input devices,
+      which are reported as a normalized 'Standard Gamepad' as it is specified
+      by the W3C Gamepad API at: https://w3c.github.io/gamepad/#remapping
+    </description>
+
+    <enum name="gamepad_state">
+      <description summary="connection state"/>
+      <entry name="off" value="0" summary="no gamepads are connected or on."/>
+      <entry name="on" value="1" summary="at least one gamepad is connected."/>
+    </enum>
+
+    <event name="state_change">
+      <description summary="state change event">
+        Notification that this seat's connection state has changed.
+      </description>
+      <arg name="state" type="uint" enum="gamepad_state" summary="new state"/>
+    </event>
+
+    <event name="axis">
+      <description summary="axis change event">
+        Notification of axis change.
+
+        The axis id specifies which axis has changed as defined by the W3C
+        'Standard Gamepad'.
+
+        The value is calibrated and normalized to the -1 to 1 range.
+      </description>
+      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+      <arg name="axis" type="uint" summary="axis that produced this event"/>
+      <arg name="value" type="fixed" summary="new value of axis"/>
+    </event>
+
+    <enum name="button_state">
+      <description summary="physical button state">
+        Describes the physical state of a button that produced the button
+        event.
+      </description>
+      <entry name="released" value="0" summary="the button is not pressed"/>
+      <entry name="pressed" value="1" summary="the button is pressed"/>
+    </enum>
+
+    <event name="button">
+      <description summary="Gamepad button changed">
+        Notification of button change.
+
+        The button id specifies which button has changed as defined by the W3C
+        'Standard Gamepad'.
+
+        A button can have a digital and an analog value. The analog value is
+        normalized to a 0 to 1 range.
+        If a button does not provide an analog value, it will be derived from
+        the digital state.
+      </description>
+      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>

[reveman, 2016/06/29 22:37:50]

should we have a serial here in case we ever want these events to be able to be
used for window manager interaction?

<arg name="serial" type="uint" summary="serial number of the button event"/>

[denniskempin, 2016/07/12 20:15:23]

Also not exactly feasible with the current protocol since buttons can be analog.
Might be possible by splitting button events into logical 0->1 button changes
and analog changes. 

+      <arg name="button" type="uint" summary="id of button"/>
+      <arg name="state" type="uint" enum="button_state" summary="digital state of the button"/>
+      <arg name="analog" type="fixed" summary="analog value of the button"/>
+    </event>
+
+    <event name="frame">
+      <description summary="Notifies end of a series of gamepad changes.">
+        Indicates the end of a set of events that logically belong together.
+        A client is expected to accumulate the data in all events within the
+        frame before proceeding.
+      </description>
+      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+    </event>
+
+    <request name="destroy" type="destructor">

[reveman, 2016/06/29 22:37:50]

nit: move destructor to top for consistency with other interfaces

[denniskempin, 2016/07/12 20:15:23]

Done.

+      <description summary="destroy gamepad object"/>
+    </request>
+  </interface>
+</protocol>