The Joystick module has been extended in RISC OS 3.6 to provide support for PC-style analogue joysticks, as well as the Atari-style digital joysticks supported by earlier versions of RISC OS.
Support has also been added for calls used with analogue input devices on older Acorn machines.
Joystick_Read has been extended to support reason codes. In RISC OS 3.6 these are used to specify the format in which to return the read values: 8 bit, or 16 bit (available for analogue only). For full details, see Joystick_Read.
Different analogue joysticks will output different voltages when in the same position. Two new SWIs have been added to calibrate the voltages, so that all analogue joysticks return consistent values when their position is read. These are:
You should also see OS_Byte calls for details of OS_Byte calls added.
Previously, analogue input devices could be connected to a RISC OS computer using the Acorn I/O Podule's ADC port.
The old I/O Podule and the new joystick interface use the same type of connector. However, the pinout used by a PC-style joystick - and hence by the new joystick interface - differs from that used by the I/O Podule's ADC port. You will therefore need an adaptor cable to connect devices intended for the old I/O Podule to the new joystick interface.
The I/O Podule provides various OS_Byte calls and the BASIC ADVAL command to support its ADC port. If there is no I/O Podule present then the Joystick module provides the same calls, which instead access the joystick interface (provided it has been configured for analogue input).
The OS_Byte calls provided are:
Differences between the I/O Podule's hardware and the joystick interface's hardware mean that not all the OS_Byte calls provide identical functionality in both implementations. However, the vast majority of I/O Podule software should still run using the joystick interface, without change.
ADVAL is a BASIC function that takes a single parameter. The Joystick module adds support for parameters 0 - 4:
All other ADVAL parameters continue to work in the same way as always; they are documented in the BBC BASIC Reference Manual.
| R0 | = | 16 (reason code) |
| R1 | = | number of channels to be sampled (0 - 4) |
| R0 | preserved | |
This call stores the number of channels to be sampled. If the value passed is greater than 4, it is stored as 4. This stored value can be read using OS_Byte 189.
(On the I/O Podule this call also set the number of channels to be sampled; but this is not possible on the joystick interface's hardware.)
| R0 | = | 17 (reason code) |
| R1 | = | channel number on which to force ADC conversion (0 - 4) - not implemented |
| R0 | preserved | |
This call returns to the caller, doing nothing.
(On the I/O Podule this call forced an ADC conversion on the given channel; but this is not possible on the joystick interface's hardware.)
| R0 | = | 128 (reason code) | ||||||
| R1 | = | sub-reason code:
|
| R0 | preserved | |
| R1 | = | state of switch 0 on joysticks 0 (in bit 0) and 1 (in bit 1) - if R1 = 1 on entry; or low byte of 16 bit uncalibrated position for channel given in R1 on entry |
| R2 | = | number of last channel converted - if R1 = 1 on entry; or high byte of 16 bit uncalibrated position for channel given in R1 on entry |
This call returns the switch state and last channel converted, or a channel's uncalibrated position, depending on the value passed in R4:
(On the I/O Podule this call does the same.)
For details of other OS_Byte 128 sub-reason codes, see OS_Byte 128.
| R0 | = | 188 (reason code) |
| R0 | preserved | |
| R1 | = | current channel (1 - 4) |
This call reads the current channel.
(On the I/O Podule this call does the same.)
| R0 | = | 189 (reason code) |
| R0 | preserved | |
| R1 | = | number of channels to be sampled (0 - 4) |
This call reads the number of channels to be sampled, as stored using OS_Byte 16.
(On the I/O Podule this call does the same.)
| R0 | = | 190 (reason code) |
| R0 | preserved | |
| R1 | = | 0 (default conversion, which is 16 bit) |
This call reads the resolution of conversion. This is always returned as 0, meaning the default for the hardware, which is 16 bit.
(On the I/O Podule this call can return 0 for the default (which for its hardware is 12 bit), or 8 for 8 bit conversion, or 12 for 12 bit conversion; however, hardware limitations mean that conversion can only be guaranteed to 8 bits.)
| R0 | = | joystick number and reason code:
| |||||||||||
| R0-2 | = | Registers depend on reason code |
This SWI is used to obtain the state of the requested joystick. The format in which the state is returned is set by the reason code in bits 8 - 15 of R0:
| Reason | Meaning |
|---|---|
| 0 | Returns the 8 bit state of a digital or analogue joystick |
| 1 | Returns the 16 bit state of an analogue joystick |
| R0 | = | joystick number and reason code:
| |||||||||||
| R0 | = | 8 bit joystick state:
| ||||||||||||||
This reason code returns the 8 bit state of a digital or analogue joystick.
For an analogue joystick, this call reads the last conversion made; it does not force a conversion itself. Furthermore, conversions are not started until you first call this SWI. That first call always returns X = 0, Y = 0, and no switches closed, since there is no completed conversion to read.
Applications which are only interested in state (up, down, left, right) should not simply test the bytes for positive, negative or zero. We recommend that the 'at rest' state should span a middle range, say from -32 to 32, since you cannot always rely upon analogue joysticks to produce a particular value when at rest.
This reason code is available from RISC OS 3 onwards. (In earlier versions of the RISC OS 3 Programmer's Reference Manual it was referred to simply as Joystick_Read, since reason codes were not in use.)
| R0 | = | joystick number and reason code:
| |||||||||||
| R0 | = | 16 bit joystick position:
| ||||||||
| R1 | = | joystick switch state:
| ||||||||
This reason code returns the 16 bit state of an analogue joystick.
For an analogue joystick, this call reads the last conversion made; it does not force a conversion itself. Furthermore, conversions are not started until you first call this SWI. That first call always returns X = 0, Y = 0, and no switches closed, since there is no completed conversion to read.
Applications which are only interested in state (up, down, left, right) should not simply test the bytes for minimum, middle, and maximum values. We recommend that the 'at rest' state should span a middle range, say from 24576 (&6000) to 40960 (&A000), since you cannot always rely upon analogue joysticks to produce a particular value when at rest.
This reason code is available from RISC OS 3.6 onwards.
This call calibrates analogue joysticks to return the full range of values. You should make this call with all joysticks held in the top right position.
To calibrate, you must call both this SWI and Joystick_CalibrateBottomLeft. Once you have called one of this pair of SWIs, Joystick_Read and the ADVAL command return an error, until you have completed the process of calibration by calling the other one of the pair. The read calls will then return their full range of values.
This call calibrates analogue joysticks to return the full range of values. You should make this call with all joysticks held in the bottom left position.
To calibrate, you must call both this SWI and Joystick_CalibrateTopRight. Once you have called one of this pair of SWIs, Joystick_Read and the ADVAL command return an error, until you have completed the process of calibration by calling the other one of the pair. The read calls will then return their full range of values.
| Maintainer(s): | RISCOS Ltd <developer@riscos.com> | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| History: |
| ||||||||||||||||
| Disclaimer: |
Copyright © Pace Micro Technolgy plc, 2002. |