USBJoystick - desirable features / next steps
===============================================

A high-level list of things still worth doing. The reference docs
(doc.APIs, doc.Architecture, doc.Config, doc.MouseKeyboard) describe how
the module behaves *now*; this is the one place that looks forward, so the
reference docs do not have to carry half-finished promises. Delete an item
here once it is done.


Mouse pointer feel
--------------------
  Pointer movement works and coexists with the real mouse, but it is a
  crude fixed step applied once per USB packet, so pointer speed is tied
  to the USB report rate. It should instead be driven from a steady ticker
  that converts a sustained axis deflection into a proportional velocity,
  with a dead zone and a per-axis sensitivity (the sensitivity field
  already exists in the data but is not yet used), optionally through a
  response curve for fine control near centre. See doc.MouseKeyboard.


Joy_ReadPipe
--------------
  The Teque/Krisalis "Joy" module's &CFFC3 SWI is currently a stub that
  returns without error and does nothing - the original behaviour it
  should replicate is not known. Needs the original documentation or a
  reference binary before it can be implemented properly.


ADC pointer-position reads
----------------------------
  The ADC/ADVAL emulation does not answer the pointer-position calls
  (ADVAL(-1)/(-2)); they pass straight through to the real OS. Decide
  whether the emulation should service these itself.


Per-binding ADC range
-----------------------
  An adc:<n> binding currently maps the whole axis min..max onto the ADC
  channel (Invert reverses it). The joy_binding record reserves a 'param'
  field for a start/end sub-range so a binding could map only part of an
  axis onto a channel. The motivating case: a cheap single-axis pedal set
  where one physical axis runs accelerate <-> brake through centre - map
  centre..max onto one ADC channel (accelerate) and centre..min, reversed,
  onto another (brake). Needs a grammar for the range in *USBJoystick_Map /
  the config bind= line, and use of param in binding_compile's ADC path.


Device capability detection
-----------------------------
  Joystick_DeviceInfo returns a capabilities bitfield (rumble, LED,
  battery, touchpad, sensors) whose bits are all reserved and read 0.
  Nothing yet detects or populates them.


Per-game profiles
-------------------
  The config file already reserves a profile= key per device (written but
  ignored on read) for a future "same device, different mapping per game"
  feature. The file shape is in place; the runtime support is not.


Fuller internationalisation
-----------------------------
  Error messages are looked up via MessageTrans (c.errors, Resources.UK.
  Messages), and every `*USBJoystick_*` command's declared Syntax/Help text
  now goes through the same mechanism too - `international:` set on every
  command-keyword-table entry in cmhg.USBJoystickHdr, tokens in
  Resources.UK.CmdHelp (see doc.Architecture). What's NOT yet
  internationalised: the actual runtime OUTPUT a command prints when it
  runs (e.g. *USBJoystick_List/*USBJoystick_Mappings/*USBJoystick_Debug's
  listings, *USBJoystick_Emulate's "<method> is on/off" report) - these are
  plain printf() calls with no MessageTrans lookup. Moving those over would
  need parameterised message-token substitution, not just static text.


Free the USB scan buffer at init
----------------------------------
  module_initialise's usb_scan_devices() enumeration allocates a device
  list that is never freed. Harmless (once, at startup) but untidy; free
  it after the scan completes.


Local copies of USB definitions
---------------------------------
  Most USB constants and descriptor types come from the exported USBDriver
  headers (dev.usb.h.usb and USB.h.USBDevFS), but h.usb still defines a
  few things locally because USBDriver doesn't export them: the HID class
  definitions (usbhid - usage pages and usages, the HID descriptor and
  request codes) and the SuperSpeed endpoint-companion and BOS descriptor
  types. Drop each from h.usb if a future USBDriver exports it.

  The exported usb.h declares its 16-bit fields as uWord byte pairs, so
  they must be read with UGETW(). The compiler rejects most misuse, but
  a bare field passed to debug_printf() compiles and prints garbage.
