From 49a6882b67264ede3ef62276ae1a31b80b4c9874 Mon Sep 17 00:00:00 2001 From: Simon Zeni Date: Fri, 18 Aug 2023 21:57:19 -0400 Subject: [PATCH] gamepad-v1: new protocol This protocol defines the behaviour of game controllers in the Wayland environment. Signed-off-by: Simon Zeni --- meson.build | 1 + staging/gamepad/README | 4 + staging/gamepad/gamepad-v1.xml | 283 +++++++++++++++++++++++++++++++++ 3 files changed, 288 insertions(+) create mode 100644 staging/gamepad/README create mode 100644 staging/gamepad/gamepad-v1.xml diff --git a/meson.build b/meson.build index c096772..ec70c36 100644 --- a/meson.build +++ b/meson.build @@ -48,6 +48,7 @@ staging_protocols = { 'ext-session-lock': ['v1'], 'ext-transient-seat': ['v1'], 'fractional-scale': ['v1'], + 'gamepad': ['v1'], 'linux-drm-syncobj': ['v1'], 'security-context': ['v1'], 'single-pixel-buffer': ['v1'], diff --git a/staging/gamepad/README b/staging/gamepad/README new file mode 100644 index 0000000..b4a42bf --- /dev/null +++ b/staging/gamepad/README @@ -0,0 +1,4 @@ +game controller protocol + +Maintainers: +Simon Zeni diff --git a/staging/gamepad/gamepad-v1.xml b/staging/gamepad/gamepad-v1.xml new file mode 100644 index 0000000..445ba7c --- /dev/null +++ b/staging/gamepad/gamepad-v1.xml @@ -0,0 +1,283 @@ + + + + Copyright © 2023-2024 Collabora, Ltd. + Copyright © 2024 Colin Marc + + 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. + + + + This descriptions provides a high-level overview of the interplay between + the interfaces defined in this protocol. For details, see the protocol + specification. + + To start receiving gamepad input events, a client must first bind the + global interface wp_gamepad_manager, which will be used to request a + seat-specific object, using get_gamepad_seat. + + A wp_gamepad_seat object is used by the compositor to notify the client of + connected controllers, via the gamepad_available event. The wp_gamepad + object contained in that event is then used to send actual input events. + + Which surface currently holds the focus of the gamepad, and therefore + receives input events from that controller, is maintained by the + compositor and communicated to the client with the enter and leave events. + + Clients should watch for the wp_gamepad.removed event, which indicates a + device was unplugged. If the same device is then replugged, it results in + a new wp_gamepad_seat.gamepad_available event and a new wp_gamepad object. + Gamepads can be identified across hotplug events by their unique ID, sent + in the wp_gamepad.device_info event. + + 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. + + + + + An object that provides access to connected gamepads. + + + + + Destroy the wp_gamepad_manager object. + + The objects created from this object are unaffected and should be + destroyed separately. + + + + + + Get the wp_gamepad_seat object for a given seat. This object provides + access to all gamepads in this seat. + + + + + + + + + An object providing access to the gamepads available on this seat. After + binding to this interface, the compositor sends available gamepad through + gamepad_available event. + + + + + Destroy the wp_gamepad_seat object. + + The objects created from this object are unaffected and should be + destroyed separately. + + + + + + This event is sent whenever a gamepad becomes available on this + seat. + + + + + + + + This interface represents a physical gamepad currently connected to the + system. + + Upon binding to the interface, the compositor will advertise the + properties of the gamepad through the device_info event. + + Input events are grouped by the wp_gamepad_v1.frame events. All events + received before the frame event should be considered part of the same + hardware state change. + + + + + Destroy the wp_gamepad object. + + + + + + Each vendor uses a different set of glyph on its controller's buttons. + + + + + + + + + + + + Information about the gamepad. The name and uniq values are UTF-8 + strings, the uniq value should not be NULL. + + + + + + + + + + + Notification that the gamepad is focused on a given surface. + + + + + + + + Notification that the gamepad is no longer focused on the given surface. + + + + + + + + Describes the source of a button event. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Describes the physical state of a button on the gamepad. + + + + + + + + Describes the gamepad button source press and release notification. + + The time arguments is a timestamp in microseconds granularity with an + unknown base of the moment of the state changes + + + + + + + + + + Describes gamepad button source pressure notification, expressed + with a value varying between 0.0 and 1.0, with 0.0 being the neutral + state. + + The time arguments is a timestamp in microseconds granularity with an + unknown base of the moment of the state changes + + + + + + + + + + Describes the source of an axis event. + + + + + + + + + + + + Describes gamepad axis position notification. + + Thumbstick axis value varies from -1.0 to 1.0 and trigger axis value + varies from 0.0 to 1.0, with 0.0 being the neutral state. + + The time arguments is a timestamp in microseconds of the moment of the + state 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 + + All wp_gamepad_v1 events before a wp_gamepad_v1.frame event belong + together. + + + + + + This event indicates that the controller is not available and no more + events will follow. Upon receipt of this event, the client should + immediately destroy the wp_gamepad object. + + + +