![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction and overview
The Pyromaniac Joystick module provides an experimental controller interface for registering polling joystick drivers. It extends the existing Joystick SWI chunk while retaining the legacy read operations for the first registered device. It is a prototype interface and is not an allocated public RISC OS interface.
The extended registration SWIs are available at &43F50 and &43F51. They require allocation review before use in a released RISC OS component.
Technical details
A driver registers a 32-byte joystick descriptor. The name and all descriptor data are copied during registration, except the synchronous callback address and private word which remain owned by the driver.
| Offset | Size | Name | Contents |
|---|---|---|---|
| 0 | 4 | name | Pointer to a NUL-terminated joystick name. |
| 4 | 4 | driver | Driver callback entry point. |
| 8 | 4 | private-word | Value supplied in R12 on callback. |
| 12 | 4 | flags | Must be zero. |
| 16 | 4 | inputs | Number of input descriptors, from 1 to 254. |
| 20 | 4 | input-list | Pointer to input descriptors. |
| 24 | 4 | button-map | Pointer to a byte list of button input identifiers, terminated by 255. |
| 28 | 4 | axis-map | Pointer to three bytes mapping X, Y and Z respectively; 255 means unavailable. |
Each input descriptor is 32 bytes. Types 0, 1 and 2 are centred X, Y and Z axes; types 4, 5 and 6 are X, Y and Z axes whose rest position is low. Types 256 to 511 are buttons. A linear range must have a non-zero width.
| Offset | Size | Name | Contents |
|---|---|---|---|
| 0 | 4 | type | Input type. |
| 4 | 4 | name | Pointer to a NUL-terminated input name. |
| 8 | 4 | usage | Usage: type in bits 0-11, sequence in bits 12-15, related input in bits 16-23; bits 24-31 must be zero. |
| 12 | 4 | location | Physical location; reserved bits must be zero. |
| 16 | 4 | minimum | Signed minimum raw value for a linear input. |
| 20 | 4 | maximum | Signed maximum raw value for a linear input. |
| 24 | 4 | rest | Signed rest value, or -1 for an unsprung input. |
| 28-31 | Reserved, must be zero |
The v1 callback is synchronous, non-blocking and read-only. R12 is the registered private word, R0 is 0 for ReadLinear or 1 for ReadButton, and R1 is the input identifier. It returns a signed raw linear value or a button value of 0 or 1 in R0. Callback errors become Joystick errors.
Experimental service notifications are disabled. Initialisation, shutdown, registration and deregistration stub paths are retained, but no service block is emitted until a formally allocated block is available.
SWI calls
| R0 | = | Pointer to the joystick descriptor. |
| R0 | = | Allocated joystick number, from 0 to 254. |
Registers a validated descriptor and copies its descriptive data.
| R0 | = | Joystick number; all other bits must be zero. |
Removes the driver and releases copied descriptor data.
| R0 | = | Joystick number in bits 0-7, reason in bits 8-15, and a reason-specific input identifier in bits 16-23.
|
Reserved bits must be zero. Scaled values are clamped to the registered range and returned as 0 to 65535.
Legacy compatibility
Reasons 0 and 1 adapt joystick 0's default X/Y/Z and button mappings. Missing X or Y axes read as the centred normalised value; unmapped buttons read clear. Reason 0 returns signed 8-bit X and Y values and the first eight mapped button states. Reason 1 returns normalised 16-bit X and Y values and the first eight button states in R1.
SWI Joystick_CalibrateTopRight and SWI Joystick_CalibrateBottomLeft return the error Joystick calibration is not implemented in this prototype. Calibration requires a later design for driver requests, persistent data and the legacy calibration state machine.
Error messages
Registration rejects invalid descriptors, unsupported input types, invalid ranges, malformed mappings and reserved bits. Reads reject bad joystick or input identifiers, invalid usages, non-linear inputs where a linear input is required, and non-button inputs where a button is required.