Skip to content

Commit ccac5a8

Browse files
fpscanfpscan
authored
Merge pull request #1012 from zoltanvb/input_driver_update
Update input and controller drivers
2 parents 27f8905 + bf1d2c8 commit ccac5a8

File tree

1 file changed

+67
-275
lines changed

1 file changed

+67
-275
lines changed

‎docs/guides/input-controller-drivers.md

Lines changed: 67 additions & 275 deletions
Original file line numberDiff line numberDiff line change
@@ -2,49 +2,65 @@
22

33
RetroArch makes use of two input systems in order to support the full range of input devices available across RetroArch's supported platforms.
44

5-
- **Input Drivers** provide access to keyboards, mice, and mouse-like devices such as lightguns, spinners, steering wheels, etc.
6-
- **Controller Drivers** provide access to gamepads and joysticks.
5+
- **Input Drivers** provide access to keyboards, mice, and mouse-like devices such as lightguns or touch screens. Input drivers are typically set up automatically, and are either not changeable or there is only a limited selection.
6+
- **Controller Drivers** provide access to gamepads and joysticks. On desktop platforms, controller drivers can be usually changed. The autoconfiguration profile database is different per controller driver.
77

88
!!! Note
99
Controller drivers were previously referred to as joypad drivers. Some documentation may still use the older "joypad" terminology.
1010

11-
**Absolute mouse devices** in the tables below refers to input drivers which support mouse-like devices such as light guns, air mice, and Wiimotes that use 'absolute' coordinate systems. Certain input drivers only support mouse devices with 'relative' coordinate systems.
11+
- **Multi-mouse** indicates if it is possible to select a separate mouse-type device (such as a lightgun) for each player. If multi-mouse is not supported, typically all pointing devices are controlling the same default cursor.
12+
- **Pointer device** indicates if it is possible for the core to query the absolute coordinates of the pointer, as opposed to the default (relative) mouse. Certain cores may only support one or the other.
13+
- **Lightgun device** indicates if it is possible for the core to query a specific lightgun device, which has a different button set compared to a RetroPad. A few platforms support physical lightguns natively, or lightguns may appear as pointer devices.
14+
- **Rumble support** indicates if the driver can pass on haptic feedback (vibration) signals.
15+
- **Autoconfig support** indicates if the driver can read the controller vendor/product identifiers and apply an automatic mapping for [RetroPad](../../guides/input-and-controls/#what-is-a-retropad).
1216

17+
The listing below is not complete, but on the rest of the platforms, there is usually only 1 valid driver.
18+
19+
---
1320
## Apple OSes
1421

22+
**Apple Input Drivers**
23+
24+
| Input driver | Conditions | Multi-mouse support | Pointer device | Lightgun device |
25+
|--------------|------------|---------------------|----------------|-----------------|
26+
| `cocoa` | - | No | Yes | No |
27+
1528
**Apple Controller Drivers[^1]**
16-
- mfi
1729

30+
| Controller driver | Conditions | Rumble support | Autoconfig support |
31+
|-------------------|------------|----------------|--------------------|
32+
| `mfi` | - | Yes | Yes |
33+
| `sdl2` | - | Yes | Yes |
34+
35+
---
1836
## Linux
19-
`udev` is the most full-featured Input Driver and Controller Driver for Linux.
2037

2138
**Linux Input Drivers**
2239

23-
- linuxraw
24-
- sdl2
25-
- udev
26-
- wayland
40+
| Input driver | Conditions | Multi-mouse support | Pointer device | Lightgun device |
41+
|--------------|------------|---------------------|----------------|-----------------|
42+
| `x` | Desktop environment is X11, video driver is OpenGL (any version) or Vulkan | No | Yes | Yes |
43+
| `wayland` | Desktop environment is Wayland, video driver is OpenGL (any version) or Vulkan | No | Yes | Yes, button map is fixed |
44+
| `sdl` | Video driver is sdl or sdl2 | No | Yes | Yes, button map is fixed |
45+
| `udev` | No desktop environment (KMS) or X11 | Yes | Yes | Yes |
46+
| `linuxraw` | No desktop environment (KMS) | No mouse support at all | No | No |
2747

2848
**Linux Controller Drivers**
2949

30-
- linuxraw
31-
- sdl2
32-
- udev
33-
- [parport](https://docs.libretro.com/development/retroarch/input/parallel-port-controllers/)
50+
| Controller driver | Conditions | Rumble support | Autoconfig support |
51+
|-------------------|------------|----------------|--------------------|
52+
| `udev` | Access to the udev interface (see below) | Yes | Yes |
53+
| `sdl2` | - | Yes | Yes |
54+
| `linuxraw` | - | No | Yes |
55+
| `parport` | [Special adapter](../../development/retroarch/input/parallel-port-controllers/) on physical parallel port | No | No |
56+
| `hid` | Only if enabled during compilation | Yes | Yes |
3457

35-
### udev input driver
58+
### udev drivers
3659
udev is the newest input driver and uses the evdev joypad interface at `/dev/input`. It supports hotplugging and force feedback (if supported by device). udev reads evdev events directly and supports keyboard callback, mice, and touchpads. `libudev` is used to discover devices and support hotplugging.
3760

38-
#### Features
39-
40-
| Multi-mouse | Absolute mice |
41-
|-------------|---------------|
42-
| Yes | Yes |
61+
The `libudev` and `libxkbdcommon` packages are required. udev does not require X11, but udev does depend on X11 keyboard layout files being installed.
4362

44-
#### Required packages
45-
TThe `libudev` and `libxkbdcommon` packages are required. udev does not require X, but udev does depend on X11 keyboard layout files being installed.
46-
47-
#### Setting up udev permissions
63+
### Setting up udev permissions
4864
Most Linux distributions prevent users from capturing keyboard/mouse information by default. Only root and users in the group "input" are able to access raw input. This is a security feature in case the system is used by multiple users.
4965

5066
The easiest way to gain access to this input is to:
@@ -58,275 +74,51 @@ If adding your user to the input group does not succeed, you may also set up a u
5874
* **Step 2:** Reload the rules with `sudo udevadm control --reload-rules`.
5975
* **Step 3:** Reboot
6076

61-
### linuxraw input driver
62-
The older linuxraw driver is available which uses the legacy joystick API at `/dev/input/js*`. The linuxraw driver requires an active TTY in order to read keyboard events.
63-
64-
#### Features
65-
66-
| Multi-mouse | Absolute mice |
67-
|-------------|---------------|
68-
| No | Yes |
69-
70-
### wayland input driver
71-
72-
#### Features
73-
74-
| Multi-mouse | Absolute mice |
75-
|-------------|---------------|
76-
| - | - |
77-
78-
### sdl2 input driver
79-
80-
#### Features
81-
82-
| Multi-mouse | Absolute mice* |
83-
|-------------|----------------|
84-
| No | No |
85-
86-
87-
### hid controller driver
88-
89-
#### Features
90-
91-
| Rumble |
92-
|--------|
93-
| - |
94-
95-
### linuxraw controller driver
96-
97-
#### Features
98-
99-
| Rumble |
100-
|--------|
101-
| - |
102-
103-
104-
### sdl2 controller driver
105-
106-
#### Features
77+
### linuxraw drivers
78+
The linuxraw controller driver uses the legacy joystick API at `/dev/input/js*`. The linuxraw input driver requires an active TTY in order to read keyboard events.
10779

108-
| Rumble |
109-
|--------|
110-
| Yes |
111-
112-
### udev controller driver
113-
114-
#### Features
115-
116-
| Rumble |
117-
|--------|
118-
| Yes |
119-
120-
### xinput controller driver
121-
122-
#### Features
123-
124-
| Rumble |
125-
|--------|
126-
| Yes |
80+
### hid driver
81+
The hid driver on Linux platform detects Human Interface Devices via libusb. By default it is not enabled during compilation.
12782

12883
---
129-
13084
## Windows
13185

13286
**Windows Input Drivers**
13387

134-
- dinput
135-
- raw
136-
- sdl2
88+
| Input driver | Conditions | Multi-mouse support | Pointer device | Lightgun device |
89+
|--------------|------------|---------------------|----------------|-----------------|
90+
| `dinput` | Video driver is not sdl(2) | No | Yes | Yes |
91+
| `raw` | Video driver is not sdl(2) | Yes | Yes | Yes |
92+
| `sdl` | Video driver is sdl or sdl2 | No | Yes | Yes, button map is fixed |
13793

13894
**Windows Controller Drivers**
13995

140-
- dinput
141-
- hid
142-
- sdl2
143-
- xinput
144-
145-
### raw input driver
146-
147-
#### Features
148-
149-
| Multi-mouse | Absolute mice |
150-
|-------------|---------------|
151-
| Yes | Yes |
152-
153-
154-
### dinput input driver
155-
156-
#### Features
157-
158-
| Multi-mouse | Absolute mice |
159-
|-------------|---------------|
160-
| No | No |
161-
162-
### sdl2 input driver
163-
-To be written-
164-
165-
#### Features
166-
167-
| Multi-mouse | Absolute mice |
168-
|-------------|---------------|
169-
| - | - |
170-
171-
### dinput controller driver
172-
173-
#### Features
174-
175-
| Rumble |
176-
|--------|
177-
| No |
178-
179-
### hid controller driver
180-
181-
#### Features
182-
183-
| Rumble |
184-
|--------|
185-
| - |
186-
187-
### sdl2 controller driver
188-
189-
#### Features
96+
| Controller driver | Conditions | Rumble support | Autoconfig support |
97+
|-------------------|------------|----------------|--------------------|
98+
| `dinput` | Controller is connected as a DirectInput device | Yes | Yes |
99+
| `xinput` | Controller is connected as an XInput device | Yes | Yes |
100+
| `sdl2` | - | Yes | Yes |
101+
| `hid` | Only if enabled during compilation | Yes | Yes |
190102

191-
| Rumble |
192-
|--------|
193-
| Yes |
194-
195-
### xinput controller driver
196-
197-
#### Features
198-
199-
| Rumble |
200-
|--------|
201-
| Yes |
103+
### hid driver
104+
The hid driver on Windows platform detects Human Interface Devices via libusb. By default it is not enabled during compilation.
202105

203106
---
107+
## Auxiliary sensor support
204108

205-
## Android
206-
207-
**Android Input Drivers**
208-
209-
- android
210-
- linuxraw
211-
- udev
212-
213-
**Android Controller Drivers**
214-
215-
- android
216-
- hid
217-
- udev
218-
219-
### android input driver
220-
221-
#### Features
222-
223-
| Multi-mouse | Absolute mice |
224-
|-------------|---------------|
225-
| - | - |
226-
227-
### linuxraw input driver
228-
229-
#### Features
230-
231-
| Multi-mouse | Absolute mice |
232-
|-------------|---------------|
233-
| No | Yes |
234-
235-
### udev input driver
236-
237-
#### Features
238-
239-
| Multi-mouse | Absolute mice |
240-
|-------------|---------------|
241-
| Yes | No |
242-
243-
244-
### android controller driver
245-
246-
#### Features
247-
248-
| Rumble |
249-
|--------|
250-
| - |
251-
252-
### hid controller driver
253-
254-
#### Features
255-
256-
| Rumble |
257-
|--------|
258-
| - |
259-
260-
### udev controller driver
261-
262-
#### Features
109+
The libretro API provides a possibility to pass extra sensor inputs to cores: 3 axes of accelerometer/tilt sensor, 3 axes of gyroscope, and an illumination sensor. The following input drivers support extra sensors:
263110

264-
| Rumble |
265-
|--------|
266-
| Yes |
267-
268-
## OS X
269-
270-
**OS X Input Drivers**
271-
272-
- cocoa
273-
274-
**OS X Controller Drivers**
275-
276-
- hid
277-
278-
### cocoa input driver
279-
-To be written-
280-
281-
#### Features
282-
283-
| Multi-mouse | Absolute mice |
284-
|-------------|---------------|
285-
| - | - |
286-
287-
### hid controller driver
288-
289-
#### Features
290-
291-
| Rumble |
292-
|--------|
293-
| - |
294-
295-
### sdl2 controller driver
296-
297-
#### Features
298-
299-
| Rumble |
300-
|--------|
301-
| Yes |
111+
- `linuxraw`: illumination
112+
- `sdl`: illumination (only on Linux)
113+
- `android`: accelerometer and gyroscope
114+
- `cocoa`: accelerometer and gyroscope
115+
- `vita`: accelerometer and gyroscope
116+
- `switch`: accelerometer, gyroscope and illumination
117+
- `udev`: illumination
118+
- `x`: illumination
302119

303120
---
304-
305-
## DOS
306-
307-
308-
### DOS input driver
309-
310-
#### Features
311-
312-
| Multi-mouse | Absolute mice |
313-
|-------------|---------------|
314-
| - | - |
315-
316-
### DOS controller driver
317-
318-
#### Features
319-
320-
| Rumble |
321-
|--------|
322-
| - |
323-
324-
## QNX
325-
326-
### QNX controller driver
327-
- QNX
328-
329-
# Fotnotes
121+
## Footnotes
330122
[^1]: MFi controllers are primarily supported on Apple devices, which means that the operating systems supporting this configuration would include:
331123
- iOS: Used on iPhones and iPads.
332124
- macOS: Used on Mac computers.

0 commit comments

Comments
 (0)