libretro/docs
1
0
Fork 0
mirror of https://github.com/libretro/docs.git synced 2024-11-23 16:59:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

update input API doc - move RA material

Browse Source
This commit is contained in:
markwkidd 2019-03-22 02:47:03 -04:00 committed by Mark W. Kidd
parent 19c998f40e
commit ccaf7960fa
4 changed files with 57 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
docs/development/input-api.md
View File

@ -1,13 +1,25 @@
# Libretro Input API
## RetroPad Abstraction
## Overview
Libretro's input system is based on abstracted input device types:
* RetroPad
- Digitial Joypad
- Analog and Digital Joypad
* Mouse
* Pointer
* Keyboard
* Lightgun
## RetroPad
The **RetroPad** is a joypad abstraction interface defined by the Libretro API. It is the primary input device for a libretro frontend. Unless a core absolutely requires the use of a keyboard with no possible fallback for gamepad-type controls, a [[Libretro core]] should always be implemented as such that it is directly controllable by the RetroPad.
![RetroPad Conceptual Diagram](../image/guides/retropad-conceptual-diagram.png)
In terms of button layout and functionality, the RetroPad is based on a PlayStation/Super Nintendo joypad.
#### Definition/Criteria
### Specification
The minimum implementation required for the RetroPad abstraction:
* At least two shoulder buttons
@ -21,48 +33,24 @@ The minimum implementation required for the RetroPad abstraction:
Above: An example of the RetroPad joypad abstraction mapped to the Megadrive 6-Button gamepad.
### Digital RetroPad
A RetroPad abstraction with all digital controls can be used.
A RetroPad abstraction with all digital controls can be used. The conceptual arrangement for the buttons for the RetroPad is inspired by the Super Nintendo controller and the Sony Playstation DualShock.
### Analog RetroPad
A RetroPad abstraction with one or more analog inputs can be used.
A RetroPad abstraction with one or more analog inputs can be used. Conceptually inspired by the Sony DualShock2, this adds two analog sticks to the digital RetroPad and allows all buttons to return analog values in the range of `[-0x7fff, 0x7fff]`, although some devices may return `-0x8000`. Positive X axis is right. Positive Y axis is down. Buttons are returned in the range `[0, 0x7fff]`.
## Mouse Input
X and Y coordinates are reported relatively to last poll (poll callback) and it is up to the core to keep track of where the pointer coordinates with respect to the display.
#### Parallel port joypads in Linux
RetroArch supports parallel port joypads on Linux via the "parport" joypad driver. It uses an extended version of the Linux Multisystem 2-button joystick protocol.
## Pointer Input
The pointer abstraction represents pen, stylus, touch and other input devices that use absolute coordinates with respect to the screen.
| Function | Pin | Register | Bit | Active |
|----------|-----|----------|-----|--------|
| Up | 2 | Data | 0 | Low |
| Down | 3 | Data | 1 | Low |
| Left| 4 | Data | 2 | Low |
| Right| 5 | Data | 3 | Low |
| A | 6 | Data | 4 | Low |
| B | 7 | Data | 5 | Low |
| Start | 8 | Data | 6 | Low |
| Select | 9 | Data | 7 | Low |
| Menu toggle | 10 | Status | 6 | Low |
| X | 11 | Status | 7 | Low* |
| Y | 12 | Status | 5 | Low |
| L1 | 13 | Status | 4 | Low |
| R1 | 15 | Status | 3 | Low |
Coordinates in X and Y are reported as `[-0x7fff, 0x7fff]`: `-0x7fff` corresponds to the far left/top of the screen, `0x7fff` to the far right/bottom of the screen. The "screen" is defined as area that is passed to the frontend and later displayed on the monitor. The frontend is free to scale/resize this screen as it sees fit but `(X, Y) = (-0x7fff, -0x7fff)` will always correspond to the top-left pixel of the display.
(*) Pin is hardware inverted, but RetroArch inverts it back again so the same pullup scheme may be used for all pins. Pin 1 is set high so it can be used for pullups.
## Keyboard Input
The libretro API allows a core to poll the frontend for the raw current pressed state of keys. There is also a callback available which is called by the frontend in response to keyboard events. `down` is set if the key is being pressed and `false` if it is being released.
RetroArch does not perform debouncing, and so long as the button settling time is less than the frame time no bouncing will be observed. This replicates the latching behavior common in old games consoles. For optimum latency and jitter a high performance debouncing routine should be implemented in the controller hardware.
Even though the frontend should try to synchronize keypresses with keycode events, cores should assume that multiple characters can be generated from a single keypress. In other words, keycode events should be treated separately from character events. Similarily if only a keycode event is generated with no corresponding character, the character should be `0`.
Parallel port hardware does not provide a way to detect non-connected pins. To avoid rendering the menu usable with spurious button presses, RetroArch checks each pin on startup and assumes any active pin is not connected. Avoid holding joypad buttons while starting RetroArch or those buttons will be disabled.
## Mouse input
To be written.
## Keyboard input
To be written.
## Lightgun input
To be written.
## Lightgun Input
The libretro lightgun abstraction reports X/Y coordinates in screen space (similar to the pointer) in the range `[-0x8000, 0x7fff]` in both axes, with zero being center and `-0x8000` being out of bounds. The core an query the on/off screen state of the lightgun. It features a trigger, start/select buttons, auxiliary action buttons and a directional pad. A forced off-screen shot can be requested for
auto-reloading function in some games.

0
docs/development/retroarch/overlay.md → docs/development/retroarch/input/overlay.md
View File

27
docs/development/retroarch/input/parallel-port-joypads.md Normal file
View File

@ -0,0 +1,27 @@
# Parallel port joypads
## Linux parport joypad driver
RetroArch supports parallel port joypads on Linux via the "parport" joypad driver. It uses an extended version of the Linux Multisystem 2-button joystick protocol.
| Function | Pin | Register | Bit | Active |
|----------|-----|----------|-----|--------|
| Up | 2 | Data | 0 | Low |
| Down | 3 | Data | 1 | Low |
| Left| 4 | Data | 2 | Low |
| Right| 5 | Data | 3 | Low |
| A | 6 | Data | 4 | Low |
| B | 7 | Data | 5 | Low |
| Start | 8 | Data | 6 | Low |
| Select | 9 | Data | 7 | Low |
| Menu toggle | 10 | Status | 6 | Low |
| X | 11 | Status | 7 | Low* |
| Y | 12 | Status | 5 | Low |
| L1 | 13 | Status | 4 | Low |
| R1 | 15 | Status | 3 | Low |
(*) Pin is hardware inverted, but RetroArch inverts it back again so the same pullup scheme may be used for all pins. Pin 1 is set high so it can be used for pullups.
RetroArch does not perform debouncing, and so long as the button settling time is less than the frame time no bouncing will be observed. This replicates the latching behavior common in old games consoles. For optimum latency and jitter a high performance debouncing routine should be implemented in the controller hardware.
Parallel port hardware does not provide a way to detect non-connected pins. To avoid rendering the menu usable with spurious button presses, RetroArch checks each pin on startup and assumes any active pin is not connected. Avoid holding joypad buttons while starting RetroArch or those buttons will be disabled.

4
mkdocs.yml
View File

@ -239,7 +239,9 @@ nav:
- 'RetroArch Development':
- 'Debugging': 'development/retroarch/debugging.md'
- 'Adding Menu Entries': 'development/retroarch/new-menu-options.md'
- 'Input Overlays': 'development/retroarch/overlay.md'
- 'Input':
- 'Input Overlays': 'development/retroarch/input/overlay.md'
- 'Parallel Port Joypads': 'development/retroarch/input/parallel-port-joypads.md'
- 'Adding Translations': 'development/retroarch/new-translations.md'
- 'Network Protocols':
- 'Netplay': 'development/retroarch/netplay.md'