Libretro Input API¶
Overview¶
Libretro's input system is based on abstracted input device types:
- RetroPad
- Digital 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.
In terms of button layout and functionality, the RetroPad is based on a PlayStation/Super Nintendo joypad.
Specification¶
The minimum implementation required for the RetroPad abstraction:
- At least two shoulder buttons
- At least four face buttons
- At least one D-pad
- At least one analogue stick
- A
Start
button and aSelect
/Back
button.
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. 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. 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.
Pointer Input¶
The pointer abstraction represents pen, stylus, touch and other input devices that use absolute coordinates with respect to the screen.
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.
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.
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
.
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.