|
www.riscos.com Technical Support: |
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
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.)
Returns to the caller, doing nothing
R0 = 17 (reason code)
R1 = channel number on which to force ADC conversion (0 - 4) - not implemented
R0 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.)
None
None
Returns the switch state and last channel converted, or a channel's uncalibrated position
R0 = 128 (reason code)
R1 = sub-reason code:
| 0 | return switch state and number of last channel converted |
| 1 - 4 | channel number for which to return position |
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
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.
None
None
Reads the current channel
R0 = 188 (reason code)
R0 preserved
R1 = current channel (1 - 4)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call reads the current channel.
(On the I/O Podule this call does the same.)
None
Reads the number of channels to be sampled
R0 = 189 (reason code)
R0 preserved
R1 = number of channels to be sampled (0 - 4)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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)
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.)
None
R0 = joystick number and reason code:
| bits 0 - 7 | joystick number (0  FIRST JOYSTICK_ 1 second, etc)
|
| bits 8 - 15 | reason code |
| bits 16 - 31 | reserved (must be zero) |
Registers depend on reason code
Interrupt status is unaltered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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 | See |
|---|---|---|
| 0 | Returns the 8 bit state of a digital or analogue joystick | Joystick_Read 0 |
| 1 | Returns the 16 bit state of an analogue joystick | Joystick_Read 1 |
None
None
Returns the 8 bit state of a digital or analogue joystick
R0 = joystick number and reason code:
| bits 0 - 7 | joystick number (0 FIRST JOYSTICK_ 1 second, etc)
|
| bits 8 - 15 | 0 (reason code) |
| bits 16 - 31 | reserved (must be zero) |
R0 = 8 bit joystick state:
| bits 0 - 7 | signed Y value in the range -127 (down) to 127 (up); for a single switch joystick, -64 DOWN_ 0 REST_ AND 64 up
|
| bits 8 - 15 | signed X value in the range -127 (left) to 127 (right); for a single switch joystick, -64 LEFT_ 0 REST_ AND 64 right
|
| bits 16 - 23 | switches (eg fire buttons) starting in bit 16; unimplemented switches return 0 |
| bits 24 - 31 | reserved |
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.)
Returns the 16 bit state of an analogue joystick
R0 = joystick number and reason code:
| bits 0 - 7 | joystick number (0 FIRST JOYSTICK_ 1 second, etc)
|
| bits 8 - 15 | 1 (reason code) |
| bits 16 - 31 | reserved (must be zero) |
R0 = 16 bit joystick position:
| bits 0 - 7 | signed Y value in the range 0 (down) to 65535 (up) |
| bits 8 - 15 | signed X value in the range 0 (left) to 65535 (right) |
| bits 0 - 7 | switches (eg fire buttons) starting in bit 0; unimplemented switches return 0 |
| bits 8 - 31 | reserved |
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.
Calibrates analogue joysticks to return the full range of values
--
--
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.
Calibrates analogue joysticks to return the full range of values
--
--
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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.