Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-gamepad Reference Manual, version 3.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 03:41:53 2022 GMT+0.
Next: Systems, Previous: The cl-gamepad Reference Manual, Up: The cl-gamepad Reference Manual [Contents][Index]
## About cl-gamepad
This is a library to provide cross-platform access to gamepads, joysticks, and other such HID devices.
## How To
For this tutorial we assume the nickname ``gamepad`` exists for ``org.shirakumo.fraf.gamepad``. Before you can start, you must initialise the library.
::common lisp
(gamepad:init)
::
If successful, it will return a list of currently connected gamepads. You can query the device properties with ``name``, ``vendor``, ``product``, ``version``, and ``driver``. Once you are ready to process device input, you can do so with ``poll-events``.
::common lisp
(gamepad:poll-events device
(lambda (event)
(format T "~& ~a ~a~%"
(etypecase event
(gamepad:button-down "Pressed")
(gamepad:button-up "Released")
(gamepad:axis-move "Moved"))
(or (gamepad:event-label event) (gamepad:event-code event)))))
::
You can access the event properties with ``event-device``, ``event-time``, ``event-code``, ``event-label``, and for axis events ``event-value``. Do note that the event instance is only valid within the dynamic extent of your supplied function. You cannot store the event elsewhere or process it out of band.
If the device gets disconnected or some other problem occurs during event polling, an error of type ``gamepad-error`` will be signalled. You should handle this error and unhook the device from your own system, then either invoke the restart ``drop-device``, or call ``poll-devices`` to automatically refresh the current device list.
If the label in the event is ``NIL``, the feature may not be properly mapped to a standardised label. Please see the "following section"(#Standardised Button Maps).
Whenever you want to listen for new device connections or ensure current devices still exist, you should run ``poll-devices``. Both ``poll-events`` and ``poll-devices`` accept a timeout argument to allow you to efficiently poll if you need a dedicated thread. The default behaviour is to return immediately if there are no pending changes, allowing you to use the calls synchronously.
Most gamepads also support haptic or force feedback. You can activate the rumble feature and modulate it over time using the ``rumble`` function. Do note that sadly the capability of the devices, and especially the capability of the underlying drivers varies wildly and the feature may thus sometimes just not be available.
You can query the last known state of a gamepad feature through ``button`` and ``axis``. Only standardised labels can be given for these functions however, so unmapped features cannot be queried.
Finally you can configure common axis features such as the ``dead-zone`` and the ``ramp`` per device. Do note however that these settings are not persistent, so you must apply them whenever the device is connected anew. The axis values are rezoned after the dead-zone clamp has applied, meaning that if the value exceeds the dead-zone, it will be remapped to fit into the [0,1] range again. Also note that if you apply the dead-zone to the two axes of a single joystick separately, the zone you set will be square, rather than the expected circular dead zone. You can set a circular dead zone by setting the dead zone on the virtual labels ``:L`` for the ``:L-H`` and ``:L-V`` axes, or ``:R`` for the ``:R-H`` and ``:R-V`` axes. The ``ramp`` function is applied after the dead zone. By default no dead zone or ramp is applied.
## Standardised Button Maps
In order to make portable interaction with gamepads possible, their features (buttons and axes) must be mapped to standardised purposes (see ``+labels+``). Cl-gamepad will try to determine such a mapping automatically if possible. On Evdev and XInput this is typically the case. On DirectInput and IOKit not so much. In any case, when the automated mapping fails, manual mappings from the device's internal feature IDs to the standardised labels must be provided.
To this end cl-gamepad includes a database of mappings in ``default-device-mappings.lisp``. These mappings are automatically loaded for any matching controller and should thus apply immediately, making the listed controllers compatible. If your controller is not listed and auto-detection fails, please use ``configure-device`` from a terminal. It will guide you through the process of mapping the device features to the proper labels, and will then save the mapping to the aforementioned file to make it persistent.
If you do configure a new device, please "submit the updated mapping file"(https://github.com/Shirakumo/cl-gamepad/compare) to the upstream repository so that it can be included in the main distribution.
## Supported Platforms
Currently the following platforms are supported:
- Linux evdev (via libevdev)
- macOS/iOS IOKit
- Windows DirectInput
- Windows XInput
On Windows DirectInput and XInput are used at the same time.
Next: Files, Previous: Introduction, Up: The cl-gamepad Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Portability library for gamepad and joystick access.
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(GIT https://github.com/Shirakumo/cl-gamepad.git)
zlib
3.0.0
trivial-features (system).
Next: Packages, Previous: Systems, Up: The cl-gamepad Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: cl-gamepad/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
cl-gamepad (system).
Next: cl-gamepad/protocol.lisp, Previous: cl-gamepad/cl-gamepad.asd, Up: Lisp [Contents][Index]
cl-gamepad (system).
Next: cl-gamepad/mapping.lisp, Previous: cl-gamepad/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
cl-gamepad (system).
Next: cl-gamepad/configurator.lisp, Previous: cl-gamepad/protocol.lisp, Up: Lisp [Contents][Index]
protocol.lisp (file).
cl-gamepad (system).
Next: cl-gamepad/common.lisp, Previous: cl-gamepad/mapping.lisp, Up: Lisp [Contents][Index]
mapping.lisp (file).
cl-gamepad (system).
Next: cl-gamepad/evdev-cffi.lisp, Previous: cl-gamepad/configurator.lisp, Up: Lisp [Contents][Index]
configurator.lisp (file).
cl-gamepad (system).
Next: cl-gamepad/linux.lisp, Previous: cl-gamepad/common.lisp, Up: Lisp [Contents][Index]
:linux
common.lisp (file).
cl-gamepad (system).
Next: cl-gamepad/win32-cffi.lisp, Previous: cl-gamepad/evdev-cffi.lisp, Up: Lisp [Contents][Index]
:linux
cl-gamepad (system).
Next: cl-gamepad/xinput-cffi.lisp, Previous: cl-gamepad/linux.lisp, Up: Lisp [Contents][Index]
:windows
cl-gamepad (system).
Next: cl-gamepad/dinput-cffi.lisp, Previous: cl-gamepad/win32-cffi.lisp, Up: Lisp [Contents][Index]
:windows
cl-gamepad (system).
Next: cl-gamepad/windows.lisp, Previous: cl-gamepad/xinput-cffi.lisp, Up: Lisp [Contents][Index]
:windows
cl-gamepad (system).
Next: cl-gamepad/corefoundation-cffi.lisp, Previous: cl-gamepad/dinput-cffi.lisp, Up: Lisp [Contents][Index]
:windows
cl-gamepad (system).
Next: cl-gamepad/iokit-cffi.lisp, Previous: cl-gamepad/windows.lisp, Up: Lisp [Contents][Index]
:darwin
cl-gamepad (system).
Next: cl-gamepad/darwin.lisp, Previous: cl-gamepad/corefoundation-cffi.lisp, Up: Lisp [Contents][Index]
:darwin
cl-gamepad (system).
Next: cl-gamepad/default-device-mappings.lisp, Previous: cl-gamepad/iokit-cffi.lisp, Up: Lisp [Contents][Index]
:darwin
cl-gamepad (system).
Next: cl-gamepad/documentation.lisp, Previous: cl-gamepad/darwin.lisp, Up: Lisp [Contents][Index]
cl-gamepad (system).
Previous: cl-gamepad/default-device-mappings.lisp, Up: Lisp [Contents][Index]
default-device-mappings.lisp (file).
cl-gamepad (system).
Next: Definitions, Previous: Files, Up: The cl-gamepad Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: org.shirakumo.fraf.gamepad, Previous: Packages, Up: Packages [Contents][Index]
common-lisp.
Previous: org.shirakumo.fraf.gamepad.impl, Up: Packages [Contents][Index]
common-lisp.
Next: Indexes, Previous: Packages, Up: The cl-gamepad Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
Next: Compiler macros, Previous: Special variables, Up: Public Interface [Contents][Index]
Defines a new device mapping for the named device type.
This is a shorthand around (SETF DEVICE-MAPPING). The BODY should be a
plist with :NAME :BUTTONS and :AXES keys. For buttons and axes, the
value should be a plist from device IDs to labels.
See DEVICE-MAPPING
Next: Ordinary functions, Previous: Macros, Up: Public Interface [Contents][Index]
Next: Generic functions, Previous: Compiler macros, Up: Public Interface [Contents][Index]
Returns the last known value of the axis.
Returns a single-float representing the axis state.
This state is automatically updated when POLL-EVENTS is called.
The axis name must be a known and mapped keyword from +LABELS+.
See AXIS-MOVE
See POLL-EVENTS
See DEVICE
See +LABELS+
Returns the last known value of the button.
Returns T if the button is pressed, NIL if it is released. This state is automatically updated when POLL-EVENTS is called. The button name must be a known and mapped keyword from +LABELS+.
See BUTTON-DOWN
See BUTTON-UP
See POLL-EVENTS
See DEVICE
See +LABELS+
Run an interactive configuration wizard to determine the proper button mappings.
This will interactively ask you to press the correct buttons and axes
corresponding to the prompted labels.
You can use this to configure a device’s button and axis mappings if
the default mapping is not correct.
You can pass the desired axis and button labels.
If the device reports faulty axes that interfere with the axis mapping
mechanism, you can ignore them by passing their IDs with the IGNORED-AXES
argument.
See +COMMON-BUTTONS+
See +COMMON-AXES+
See SAVE-DEVICE-MAPPINGS
Accessor for the dead zone of the axis on the device.
The dead zone can be defined on a combination of horizontal and vertical axes, or a single axis. When applied to a combination, the axis name must be :L, or :R, in which case the dead zone is circular.
See +LABELS+
See DEVICE
A place accessing the device mapping associated with the given ID.
An ID can either be a DEVICE instance, or a list with the following
members:
DRIVER — The name of the underlying driver for the device.
One of :DINPUT :XINPUT :EVDEV :IOKIT
VENDOR — The vendor ID of the device.
PRODUCT — The product ID of the device.
Returns NIL if no mapping is known, or a plist with the following
members:
:NAME — A string identifying the device in a hopefully
human-readable way.
:BUTTONS — A hash table mapping backend-specific button IDs to the
standardised button labels from +LABELS+
:AXES — A hash table mapping backend-specific axis IDs to the
standardised axis labels from +LABELS+
Setting a device mapping will automatically update all known
devices that match the mapping.
See REMOVE-DEVICE-MAPPING
See CONFIGURE-DEVICE
Returns the underlying code of the feature on the device that caused the event.
The code is a positive integer that has a device and driver specific
meaning.
This field is always set.
See EVENT
code.
Returns the device the event came from.
This field is always set.
See EVENT
See DEVICE
Returns the standardised label associated with the axis or button that caused the event.
If the feature is unknown or not properly mapped, NIL is
returned. Otherwise the returned symbol must be one contained in
+LABELS+.
See EVENT
See +LABELS+
Returns the previous axis value as a single-float in [-1,+1]
See EVENT-VALUE
See AXIS-MOVE
Returns some form of time identifier for the event.
The actual time resolution is dependent on the driver. This is mostly
useful to gauge whether events happened simultaneously or not.
This field is always set.
See EVENT
time.
Returns the axis value as a single-float in [-1,+1].
For a horizontal axis, -1 means left, +1 means right.
For a vertical axis, -1 means down, +1 means up.
This field is only accessible for AXIS-MOVEs.
See AXIS-MOVE
Initialises the library for use.
This will cause system shared objects to be loaded and will cause certain support structures to be allocated and initialised. Only call this function on a target system where the gamepads should be queried.
You MUST call this function before calling any other device functions.
It is safe to call this function multiple times.
Returns the list of currently known devices.
See SHUTDOWN
Returns a fresh list of all known gamepad devices.
This will not query for device updates, and only represents the
currently known state of the system.
On an uninitialised system this will return NIL.
See POLL-DEVICES
Queries for device changes.
TIMEOUT can be a one of the following:
T — Continuously poll for device changes indefinitely.
NIL — Immediately return if no changes are pending.
REAL — Wait up to the given number of seconds until a change is
noticed. Returns as soon as a change happened, or some
time until the timeout runs out.
You should call this function whenever you want to allow changing the connected devices, or whenever an existing device is disconnected.
You must have called INIT prior to calling this function.
See INIT
See LIST-DEVICES
Queries the device for events.
The FUNCTION is called with any new device events that arrive during
querying. The events are not guaranteed to be fresh and you MUST NOT
store them anywhere. You should instead translate the event into a
format more suitable for your use case or consume it on the spot.
TIMEOUT can be of one of the following:
T — Continuously poll for device events indefinitely.
NIL — Immediately return if no events are pending.
REAL — Wait up to the given number of seconds until an event is
noticed. Returns as soon as an event happened, or some
time until the timeout runs out.
You should call this function whenever you wish to query the gamepad
for new changes in its buttons or axes.
This function may signal an error of type GAMEPAD-ERROR. When this
happens the device has become unavailable for some reason. You should
remove the device from your own references and invoke the restart
DROP-DEVICE which will remove the device from the internal library and
abort the query.
You must have called INIT prior to calling this function.
See INIT
See DEVICE
See EVENT
Accessor for the ramp of the axis on the device.
The ramp descriptor must be a function of a single argument that takes
a basic, linear axis value, and returns the mapped axis value.
See +LABELS+
See DEVICE
Removes the device mapping associated with the given ID.
See DEVICE-MAPPING
Causes haptic feedback on the controller.
STRENGTH should be a number in [0,1] denoting the strength of the
haptic feedback.
PAN should be a number in [-1,+1] denoting where (from left to right)
to rumble.
Note that haptic feedback is wildly inconsistent across devices and
drivers, and may be completely unsupported, or not behave exactly as
described here.
If the haptic feedback is unsupported, this function returns
:UNSUPPORTED.
The rumbling will last at least 0.1 seconds, and may go on
indefinitely. You must modulate the rumbling manually, or stop it
completely by setting the strength to zero.
You must have called INIT prior to calling this function.
See INIT
See DEVICE
Saves all known device mappings to a lisp source file.
The source file can simply be LOADed in to restore the mappings.
See *DEFAULT-MAPPINGS-FILE*
Uninitialises the library and closes all used resources.
This will not unload system shared objects, but it will close all used
devices and other services and deallocate them. You should call this
function when shutting down on a target system.
After calling this function you MUST NOT call any other device
functions without first calling INIT again.
It is safe to call this function multiple times.
See INIT
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Returns a symbol identifying the driver underlying the device.
May be one of:
:EVDEV — (Linux evdev)
:DINPUT — (Windows DirectInput)
:XINPUT — (Windows XInput)
:IOKIT — (Apple IOKit)
See DEVICE
Returns a symbol identifying what icons to use for the buttons.
May be one of:
:GENERIC-NINTENDO
:GENERIC-XBOX
:GENERIC-PLAYSTATION
:NINTENDO-SWITCH
:DUALSHOCK-4
or another kind of label. You should be prepared to default to
:GENERIC-XBOX on encountering an unknown icon type.
See DEVICE
Returns a human-readable name for the device.
No guarantees can be made about the quality or descriptiveness of the
name.
See DEVICE
Returns an integer ID identifying the device product.
See DEVICE
Returns an integer ID identifying the vendor of the device.
See DEVICE
Returns an integer denoting the version of the device.
See DEVICE
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
Next: Structures, Previous: Standalone methods, Up: Public Interface [Contents][Index]
Error signalled when an underlying operating system, driver, or device problem occurs.
Depending on the driver used the actual type of error signalled may be
a subtype of this condition with more information available about the
error specifics.
error.
Next: Classes, Previous: Conditions, Up: Public Interface [Contents][Index]
Event issued when an axis moves.
This event may be signalled many times with very similar values.
It will NOT be issued if the combined axis (horizontal and vertical)
has a dead zone set and the axis falls within the dead zone.
If a ramp is defined on the axis, the value is already ramp-adjusted.
See EVENT-VALUE
see EVENT-OLD-VALUE
See EVENT
Event issued when a button is pressed down.
This event is only signalled once on the rising edge.
See EVENT
Event issued when a button is released.
This event is only signalled once on the falling edge.
See EVENT
Base type for device events.
An event denotes a change in the device’s buttons or axes.
See POLL-EVENTS
See BUTTON-DOWN
See BUTTON-UP
See AXIS-MOVE
See EVENT-DEVICE
See EVENT-TIME
See EVENT-CODE
See EVENT-LABEL
See EVENT-VALUE
See EVENT-OLD-VALUE
structure-object.
common-lisp.
(unsigned-byte 64)
0
(unsigned-byte 32)
0
symbol
Previous: Structures, Up: Public Interface [Contents][Index]
Representation of a physical gamepad device.
The actual type of instances may be a subtype of this with internal
features relevant to the driver.
See NAME
See VENDOR
See PRODUCT
See VERSION
See DRIVER
See ICON-TYPE
:generic-xbox
:icon-type
(make-hash-table :test (quote eql))
:button-map
(make-hash-table :test (quote eql))
:axis-map
(make-hash-table :test (quote eql))
:orientation-map
(make-array (length org.shirakumo.fraf.gamepad:+labels+) :element-type (quote bit) :initial-element 0)
(make-array (length org.shirakumo.fraf.gamepad:+labels+) :element-type (quote single-float) :initial-element 0.0)
(make-array (length org.shirakumo.fraf.gamepad:+labels+) :element-type (quote single-float) :initial-element 0.0)
(make-array (length org.shirakumo.fraf.gamepad:+labels+) :initial-element (function identity))
(make-array (+ 2 (length org.shirakumo.fraf.gamepad:+labels+)) :element-type (quote single-float) :initial-element 0.0)
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Symbol macros, Previous: Internals, Up: Internals [Contents][Index]
Next: Macros, Previous: Special variables, Up: Internals [Contents][Index]
Next: Compiler macros, Previous: Symbol macros, Up: Internals [Contents][Index]
Next: Ordinary functions, Previous: Macros, Up: Internals [Contents][Index]
Next: Generic functions, Previous: Compiler macros, Up: Internals [Contents][Index]
Next: Conditions, Previous: Ordinary functions, Up: Internals [Contents][Index]
automatically generated reader method
automatically generated writer method
automatically generated reader method
automatically generated writer method
code.
Next: Classes, Previous: Generic functions, Up: Internals [Contents][Index]
(quote nil)
:function-name
This slot is read-only.
Previous: Conditions, Up: Internals [Contents][Index]
Previous: Definitions, Up: The cl-gamepad Reference Manual [Contents][Index]
| Jump to: | %
(
A B C D E F G H I L M N O P Q R S T U V W |
|---|
| Jump to: | %
(
A B C D E F G H I L M N O P Q R S T U V W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
A B C D E F I L M N O P S T V |
|---|
| Jump to: | *
A B C D E F I L M N O P S T V |
|---|
| Jump to: | A B C D E F G I L M O P S W X |
|---|
| Jump to: | A B C D E F G I L M O P S W X |
|---|