301 lines
11 KiB
Python
301 lines
11 KiB
Python
"""Reading an Xbox pad on Windows through XInput, with no dependencies.
|
|
|
|
## Why XInput
|
|
|
|
XInput is a plain C function in a DLL every Windows since 8 ships
|
|
(`xinput1_4.dll`), so `ctypes` reaches it and nothing has to be installed -- the
|
|
same trade `device.py` makes with evdev. The price is that it reads **only XInput
|
|
devices**: Xbox pads and the ones that present themselves as one. A PlayStation or
|
|
Switch pad is not one until Steam Input or DS4Windows sits in between.
|
|
|
|
## It speaks evdev, not a dialect of its own
|
|
|
|
Each reading is turned into the `{(type, code): value}` table the Linux `xpad`
|
|
driver produces for the same pad over USB, with the ranges `xpad` declares, and
|
|
then handed to `xbox.normalise` -- the function that reads a Linux pad. The sign
|
|
conventions, the dead-zone rescaling and the button names are therefore one piece
|
|
of code on both platforms rather than two that have to be kept agreeing, and
|
|
`python -m controller` is the same bench check on either.
|
|
|
|
## The Y axes are flipped here, and nowhere else
|
|
|
|
XInput reports a stick pushed **up** as positive; evdev, and everything above this
|
|
package, reads **down** as positive (`xbox.py` says why that is kept). The flip is
|
|
`~y`, which is what `xpad` itself does to the same 16-bit value: it maps
|
|
-32768..32767 onto itself exactly, where negation would leave the range at -32768.
|
|
Leaving it out would not raise -- it would walk the robot backwards when the stick
|
|
says forwards.
|
|
|
|
## The dead zone is Microsoft's
|
|
|
|
evdev hands over the driver's `flat`; XInput reports none. Microsoft documents one
|
|
instead, `XINPUT_GAMEPAD_LEFT_THUMB_DEADZONE` and its siblings, because a stick does
|
|
not return to exactly centre, and that is what goes into `flat` here -- the
|
|
platform's own figure, which is the role the driver's `flat` plays on Linux. It is
|
|
wider than what a Linux pad reports (xpad's 128 of 32768 over USB; 4095 of 65535
|
|
from `hid-generic` over Bluetooth), so the stick travels further before it bites,
|
|
and is rescaled like every dead zone here so full deflection still reads 1.
|
|
|
|
## Buttons are matched by name
|
|
|
|
XInput's bits name physical buttons, so each is mapped onto the code `xbox.BUTTONS`
|
|
gives **that name**, not onto the code `xpad` would send. The physical X button is
|
|
`X` here whatever is eventually decided about evdev's 307 and 308, which
|
|
`controller/vocabulary.json` records as unresolved.
|
|
|
|
## The Xbox button needs the undocumented entry point
|
|
|
|
`XInputGetState` never reports it. Ordinal 100 of the same DLL, `XInputGetStateEx`,
|
|
does -- it is what SDL reads -- and it writes four bytes more than the documented
|
|
struct holds, so the struct below carries them. It is used when the DLL exports it
|
|
and `home` simply never goes down when it does not (`xinput9_1_0.dll`). Windows
|
|
also opens the Game Bar on that button unless the Game Bar is told not to.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import ctypes
|
|
import functools
|
|
import sys
|
|
from collections.abc import Callable
|
|
from dataclasses import dataclass, field
|
|
from typing import NamedTuple
|
|
|
|
from .device import PadInfo
|
|
from .xbox import (
|
|
ABS_HAT0X,
|
|
ABS_HAT0Y,
|
|
ABS_RX,
|
|
ABS_RY,
|
|
ABS_RZ,
|
|
ABS_X,
|
|
ABS_Y,
|
|
ABS_Z,
|
|
BUTTONS,
|
|
EV_ABS,
|
|
EV_KEY,
|
|
GamepadState,
|
|
normalise,
|
|
)
|
|
|
|
__all__ = ["RANGES", "XInputGamepad", "XInputPad", "describe", "find_pads", "read", "translate"]
|
|
|
|
#: `XUSER_MAX_COUNT`: XInput has four player slots and no more.
|
|
SLOTS = 4
|
|
ERROR_SUCCESS = 0
|
|
|
|
# ── The documented constants, from XInput.h ─────────────────────────────
|
|
DPAD_UP = 0x0001
|
|
DPAD_DOWN = 0x0002
|
|
DPAD_LEFT = 0x0004
|
|
DPAD_RIGHT = 0x0008
|
|
LEFT_THUMB_DEADZONE = 7849
|
|
RIGHT_THUMB_DEADZONE = 8689
|
|
TRIGGER_THRESHOLD = 30
|
|
|
|
#: XInput button bit -> the dictionary's name for that physical button. 0x0400 is
|
|
#: the Xbox button, which only `XInputGetStateEx` sets.
|
|
_BUTTON_NAMES = {
|
|
0x1000: "A", 0x2000: "B", 0x4000: "X", 0x8000: "Y",
|
|
0x0100: "LB", 0x0200: "RB", 0x0020: "view", 0x0010: "menu",
|
|
0x0400: "home", 0x0040: "L3", 0x0080: "R3",
|
|
}
|
|
_CODE_OF = {name: code for code, name in BUTTONS.items()}
|
|
#: XInput button bit -> evdev key code, by way of the name. A name `xbox.BUTTONS`
|
|
#: does not know raises here, at import, rather than reading as never pressed.
|
|
BUTTON_CODES = {bit: _CODE_OF[name] for bit, name in _BUTTON_NAMES.items()}
|
|
|
|
#: What `xpad` declares for these axes over USB, with Microsoft's dead zones as the
|
|
#: `flat`. Having `ABS_RX`/`ABS_RY` is also what makes `xbox.layout_of` choose the
|
|
#: USB layout, so the triggers are read from `ABS_Z`/`ABS_RZ` and not the sticks.
|
|
RANGES: dict[int, tuple[int, int, int]] = {
|
|
ABS_X: (-32768, 32767, LEFT_THUMB_DEADZONE),
|
|
ABS_Y: (-32768, 32767, LEFT_THUMB_DEADZONE),
|
|
ABS_RX: (-32768, 32767, RIGHT_THUMB_DEADZONE),
|
|
ABS_RY: (-32768, 32767, RIGHT_THUMB_DEADZONE),
|
|
ABS_Z: (0, 255, TRIGGER_THRESHOLD),
|
|
ABS_RZ: (0, 255, TRIGGER_THRESHOLD),
|
|
ABS_HAT0X: (-1, 1, 0),
|
|
ABS_HAT0Y: (-1, 1, 0),
|
|
}
|
|
|
|
|
|
class XInputGamepad(ctypes.Structure):
|
|
"""`XINPUT_GAMEPAD`, plus the trailing DWORD `XInputGetStateEx` writes.
|
|
|
|
Fixed-width types rather than `ctypes.wintypes`, so the struct -- and
|
|
`translate` with it -- exists on every platform and is tested on Linux.
|
|
"""
|
|
|
|
_fields_ = [
|
|
("wButtons", ctypes.c_uint16),
|
|
("bLeftTrigger", ctypes.c_uint8),
|
|
("bRightTrigger", ctypes.c_uint8),
|
|
("sThumbLX", ctypes.c_int16),
|
|
("sThumbLY", ctypes.c_int16),
|
|
("sThumbRX", ctypes.c_int16),
|
|
("sThumbRY", ctypes.c_int16),
|
|
("dwPaddingReserved", ctypes.c_uint32),
|
|
]
|
|
|
|
|
|
class XInputState(ctypes.Structure):
|
|
"""`XINPUT_STATE` as `XInputGetStateEx` fills it."""
|
|
|
|
_fields_ = [("dwPacketNumber", ctypes.c_uint32), ("Gamepad", XInputGamepad)]
|
|
|
|
|
|
# Asserted rather than assumed: a buffer four bytes short of what the Ex call
|
|
# writes does not raise, it overwrites whatever ctypes allocated next to it.
|
|
assert ctypes.sizeof(XInputGamepad) == 16 and ctypes.sizeof(XInputState) == 20, (
|
|
f"XINPUT_STATE_EX is {ctypes.sizeof(XInputState)} bytes here, not 20"
|
|
)
|
|
|
|
|
|
def translate(pad: XInputGamepad) -> dict[tuple[int, int], int]:
|
|
"""One XInput reading -> the raw evdev table `xpad` would have produced."""
|
|
buttons = pad.wButtons
|
|
raw = {(EV_KEY, code): int(bool(buttons & bit)) for bit, code in BUTTON_CODES.items()}
|
|
raw[(EV_ABS, ABS_X)] = pad.sThumbLX
|
|
raw[(EV_ABS, ABS_Y)] = ~pad.sThumbLY # up is positive in XInput, down in evdev
|
|
raw[(EV_ABS, ABS_RX)] = pad.sThumbRX
|
|
raw[(EV_ABS, ABS_RY)] = ~pad.sThumbRY
|
|
raw[(EV_ABS, ABS_Z)] = pad.bLeftTrigger
|
|
raw[(EV_ABS, ABS_RZ)] = pad.bRightTrigger
|
|
raw[(EV_ABS, ABS_HAT0X)] = bool(buttons & DPAD_RIGHT) - bool(buttons & DPAD_LEFT)
|
|
raw[(EV_ABS, ABS_HAT0Y)] = bool(buttons & DPAD_DOWN) - bool(buttons & DPAD_UP)
|
|
return raw
|
|
|
|
|
|
class _Api(NamedTuple):
|
|
dll: str
|
|
get_state: Callable[[int, object], int]
|
|
#: Whether `get_state` is `XInputGetStateEx`, i.e. whether `home` can be read.
|
|
guide: bool
|
|
|
|
|
|
#: Newest first. 1_4 ships with Windows 8 and later; 1_3 comes with the DirectX
|
|
#: runtime; 9_1_0 is Windows 7's and has no ordinal 100.
|
|
_DLLS = ("xinput1_4", "xinput1_3", "xinput9_1_0")
|
|
|
|
|
|
@functools.lru_cache(maxsize=1)
|
|
def _api() -> _Api | None:
|
|
if sys.platform != "win32":
|
|
return None
|
|
for name in _DLLS:
|
|
try:
|
|
dll = ctypes.WinDLL(name)
|
|
except OSError:
|
|
continue
|
|
try:
|
|
fn, guide = dll[100], True
|
|
except AttributeError:
|
|
fn, guide = dll.XInputGetState, False
|
|
fn.argtypes = (ctypes.c_uint32, ctypes.POINTER(XInputState))
|
|
fn.restype = ctypes.c_uint32
|
|
return _Api(name, fn, guide)
|
|
return None
|
|
|
|
|
|
def read(slot: int) -> XInputGamepad | None:
|
|
"""The pad in `slot` now, or None if there is none (or no XInput at all)."""
|
|
api = _api()
|
|
if api is None:
|
|
return None
|
|
state = XInputState()
|
|
if api.get_state(slot, ctypes.byref(state)) != ERROR_SUCCESS:
|
|
return None
|
|
return state.Gamepad
|
|
|
|
|
|
def find_pads(readable_only: bool = False) -> list[PadInfo]:
|
|
"""Every slot with a pad in it. XInput has no permissions to be refused, so a
|
|
pad that answers is one this process can read, and `readable_only` changes
|
|
nothing."""
|
|
del readable_only
|
|
return [
|
|
PadInfo(f"xinput:{slot}", f"XInput pad, player {slot + 1}", True)
|
|
for slot in range(SLOTS)
|
|
if read(slot) is not None
|
|
]
|
|
|
|
|
|
def describe() -> str:
|
|
"""What was found, or why nothing was."""
|
|
api = _api()
|
|
if api is None:
|
|
return (
|
|
"XInput is not available: none of "
|
|
+ ", ".join(f"{name}.dll" for name in _DLLS)
|
|
+ " could be loaded."
|
|
)
|
|
pads = find_pads()
|
|
if not pads:
|
|
return (
|
|
"no XInput controller is connected. Windows pads are read through XInput, "
|
|
"which sees Xbox pads and pads that present themselves as one; a "
|
|
"PlayStation or Switch pad needs Steam Input or DS4Windows in between."
|
|
)
|
|
lines = [f" {p.path} {p.name} -- usable, through {api.dll}" for p in pads]
|
|
if not api.guide:
|
|
lines.append(f" {api.dll} has no XInputGetStateEx, so `home` never reads as pressed")
|
|
return "\n".join(lines)
|
|
|
|
|
|
@dataclass
|
|
class XInputPad:
|
|
"""An XInput slot, presenting the same surface as `device.Gamepad`.
|
|
|
|
Read on the caller's thread, once per `state()`: XInput is a poll API with
|
|
nothing to wait on, so a reader thread would only add latency -- up to the
|
|
15.6 ms system timer tick on Python 3.10, whose sleeps on Windows round up to
|
|
it. When the pad goes away the last reading is kept and `connected` goes False,
|
|
as `Gamepad` does, and the empty slot is not polled again: an empty slot is the
|
|
slow case of `XInputGetState`, which Microsoft's documentation of it says not to
|
|
poll every frame.
|
|
"""
|
|
|
|
info: PadInfo
|
|
_raw: dict[tuple[int, int], int] = field(default_factory=dict)
|
|
_ranges: dict[int, tuple[int, int, int]] = field(default_factory=lambda: dict(RANGES))
|
|
_alive: bool = False
|
|
|
|
@property
|
|
def name(self) -> str:
|
|
return self.info.name
|
|
|
|
@property
|
|
def _slot(self) -> int:
|
|
return int(self.info.path.rpartition(":")[2])
|
|
|
|
def start(self) -> None:
|
|
self._alive = True
|
|
self._poll()
|
|
|
|
def close(self) -> None:
|
|
self._alive = False
|
|
|
|
@property
|
|
def connected(self) -> bool:
|
|
return self._alive
|
|
|
|
def _poll(self) -> None:
|
|
if not self._alive:
|
|
return
|
|
pad = read(self._slot)
|
|
if pad is None:
|
|
self._alive = False
|
|
return
|
|
self._raw = translate(pad)
|
|
|
|
def state(self) -> GamepadState:
|
|
"""A normalised snapshot. Never raises."""
|
|
self._poll()
|
|
return normalise(dict(self._raw), self._ranges)
|
|
|
|
def raw(self) -> dict[tuple[int, int], int]:
|
|
"""The reading as evdev codes, for `python -m controller --raw`."""
|
|
self._poll()
|
|
return dict(self._raw)
|