USBJoystick - fitting in with SDL
===================================

How USBJoystick relates to SDL (libsdl.org, SDL3), and what the module could
offer to help a RISC OS SDL joystick backend.



Division of labour
--------------------
USBJoystick: simple RISC OS interfaces (Joystick_Read, Enumerate, Rumble) and
built-in support for popular devices, so they work with no further software.

SDL: the large body of per-device knowledge (gamepad mapping database, per-
controller drivers), for applications wanting more than that. This is not
duplicated here.

SDL's RISC OS port (src/video/riscos and others) has no joystick backend yet.



What SDL's backend interface wants
------------------------------------
SDL_JoystickDriver (src/joystick/SDL_sysjoystick.h) has two shapes of
implementation:

  Device-descriptive (Linux evdev)
      The OS reports identity (bus, vendor, product, version, name), the
      axes, buttons and hats, and their state. SDL maps them to gamepad roles
      from its database, keyed on the GUID and on the OS's own ordering.

  Raw report (HIDAPI)
      SDL reads and writes the device's reports itself, and its per-device
      drivers (Xbox 360, PlayStation 3/4/5, Switch, ...) decode them, set
      LEDs and rumble. Needs only the hidapi calls: enumerate, open, read,
      write, feature reports, descriptor.



What exists now
-----------------
Joystick_Enumerate, DeviceInfo, AxisInfo and AxisValues (doc.APIs section 5.1)
are device-descriptive: identity, GUID, capabilities, per-axis usage and
range, native values and a button mask. Enough for a basic SDL joystick.

Gaps against that shape:
  - No per-attach unique ID. Enumerate's generation counter says the device
    list changed, not which slot. A slot detached and re-attached between two
    polls looks unchanged.
  - Device version (bcdDevice) is only inside the GUID bytes.
  - Hats appear as two synthetic digital axes, not as hats. Only the first
    hat is read, and each one costs two axis slots.
  - Rumble and raw output are commands only. No SWI.
  - No raw report access.


Gamepad roles (what each axis and button means) are not provided; SDL's
database and drivers supply them.



Interactions
--------------
Reading is passive, so SDL and the classic APIs can use a device at once.
The mouse and keyboard gates (Joystick_Control) are off by default.
