|
|
!HID User Manual - Joysticks
|
|
|
Joysticks - Technical backgrounds
|
 |
 |
 |
From version 0.22 onwards, !HID is supplied with a Joystick module that
allows the state of any of the USB joysticks to be read and used by your
software. The entire functionality of the Joystick module is implemented
so any existing software that uses the Joystick interface, should theoretically
work straight away. There are three ways for your software to read the
state of the joysticks:
|
- Using the Joystick SWIs
- Using a set of OS_Byte calls
- Using the BASIC function ADVAL
|
In addition to this, the range of SWI calls has been extended and new
reason codes have been added to the existing SWI Joystick_Read.
Furthermore, some useful *-commands have been added to allow flexible
configuration of the software.
|
Joystick module version number
|
 |
 |
 |
The Joystick module is numbered from 3.00 upwards as to avoid
confusion with existing modules and software.
The initial Joystick module supplied by Acorn on some RISC OS 3
computers, always has a version number of 1.xx.
Third party Joystick modules should have a version of 2.xx so
that the Acorn module can be replaced automatically.
As we've extended the API (Application Programmers Interface),
we will use version numbers 3.xx from now on.
If your software want's to access any of the new features,
please check the module's version number prior to calling them.
|
Standard Joystick SWI calls
|
 |
 |
 |
The Joystick module supports the standard SWI calls as specified
by Acorn in PRM-5a on page 629.
Please refer to the PRM for further information.
As the documentation contains quite
a number of typos, the SWIs are listed again here.
|
- Joystick_Read 0 (SWI &43F40)
This is the principle method to read the joystick X and Y position
in 8-bit format. The call is present from RISC OS 3.00 onwards.
The joysticks are numbered from 0 onwards.
Entry:
r0 : Joystick number (bits 0-7) and reason code (bits 8-15).
Exit:
r0 : 8-bit joystick state (see below}.
Joystick state: (returned in r0 on exit)
bits 0-7: signed Y value in the range -127 (down) to 127 (up).
bits 8-15: signed X value in the range -127 (left) to 127 (right).
bits 16-23: switches (e.g. fire buttons) starting in bit 16.
bits 24-31: reserved. (Extended: now contains 8 extra buttons)
- Joystick_Read 1 (SWI &43F40)
This call is available from RISC OS 3.60 onwards and allows the
joystick X and Y position to be read in 16-bit format.
The values for X and Y are in the range 0-65535 (i.e. 16 bits)
and are combined into a single 32-bit word which is returned in
r0 on exit. The state of the switches is returned in r1 and any
unimplemented switch is returned as 0.
Entry:
r0 : Joystick number (bits 0-7) and reason code 1 (bits 8-15).
Exit:
r0 : Joystick Y positon (bits 0-15) and X position (bits 16-31).
r1 : Switches (bits 0-7) starting in bit 0 (e.g. fire button). )Extended: now contains all buttons)
- Joystick_CalibrateTopRight (SWI &43F41)
As analogue joysticks might be inacurate, it is necessary to calibrate
them in order to make them return the full range of values.
This SWI should be called with all joysticks (and additional controls)
held in the top right position.
This SWI call is one of a pair of SWIs (see below) that need to be
called both before the joystick interface can be used properly.
Once you have called only one of this pair of SWIs, Joystick_Read and
the BASIC ADVAL command will return an error, until the process of
calibration has been completed by calling the other one of the pair.
- Joystick_CalibrateBottomLeft (SWI &43F42)
As analogue joysticks might be inacurate, it is necessary to calibrate
them in order to make them return the full range of values.
This SWI should be called with all joysticks (and additional controls)
held in the bottom left position.
This SWI call is one of a pair of SWIs (see below) that need to be
called both before the joystick interface can be used properly.
Once you have called only one of this pair of SWIs, Joystick_Read and
the BASIC ADVAL command will return an error, until the process of
calibration has been completed by calling the other one of the pair.
|
The Joystick module adds some new OS_Byte calls and extends the range
of reason codes of some others. This is done to ensure that the module
is backwards compatible with existing software. The same OS_Byte calls
are used by the Acorn Joystick module in RISC OS 3.6 and the BBC I/O
Podule.
The OS_Byte calls are detailed below,
but you are advised to use the SWI calls when writing new software.
|
- OS_Byte 16 (SWI &06)
Stores the number of channels to be sampled.
Entry:
r0 : 16 (reason code)
r1 : number of channels to be sampled (0-4)
Exit:
r0 : preserved
- OS_Byte 17 (SWI &06)
Returns to the caller, doing nothing.
Entry:
r0 : 17 (reason code)
r1 : channel number on which to force ADC conversion (0-4)
Exit:
r0 : preserved
- OS_Byte 128, 0-4 (SWI &06)
Returns the switch state and last channel converted or a channel's
uncalibrated position. This is an extension to the existing OS_Byte
128 call.
Entry:
r0 : 128 (reason code)
r1 : sub-reason code
0 : return the switch state and number of last channel converted.
1-4 : channel number for which to return position.
Exit:
r0 : preserved
r1 : state of switch 0 on joysticks 0 (bit 0) and 1 (bit 1), if r0 was 0 on entry.
Low byte of 16 bit joystick position, if r0 was 0-4 on entry.
r2 : Number of last channel converted, if r0 was 0 on entry.
High of 16 bit joystick position, if r0 was 0-4 on entry.
- OS_Byte 188 (SWI &06)
Reads the current channel.
Entry:
r0 : 188 (reason code)
Exit:
r0 : preserved
r1 : current channel (1-4)
- OS_Byte 189 (SWI &06)
Reads the current channel.
Entry:
r0 : 189 (reason code)
Exit:
r0 : preserved
r1 : number of channels to be sampled (1-4)
- OS_Byte 190 (SWI &06)
Reads the resolution of conversion.
Entry:
r0 : 190 (reason code)
Exit:
r0 : preserved
r1 : 0 (i.e. the default conversion, which is 16-bit)
|
Whenever the joystick module is present, the ADVAL function
in BASIC is extended automatically. The syntax is ADVAL(argument)
and the argument is in the range 0-5. THe functionality is identical
to OS_Byte 128, 0-4 (see above).
Argument:
0 : Read the state of the switch (fire button) on both joysticks (bits 0 and 1).
1-4 : Channel number for which to return position.
Position:
The returned position is a 16 bit value (0-65635) with 32768 being the
centre position. Reading the ADVAL function with no joystick(s) connected,
always return the centre position to avoid joystick simulation software
being confused.
|
Limitations of the current calls
|
 |
 |
 |
The above calls were implemented at a time when analogue joysticks were
just becoming available. As a result most calls can only cope with up to
two joysticks and the values are limited to X and Y movement only.
As most modern joysticks have a variety of controls, including sliders,
Z-axis movement, rotation, multiple buttons, etc., it was neccesary to
add some new SWI calls. When writing new software, you should use the
new calls whenever posssible, unless your software needs to be backward
compatible with older versions of the OS.
The new calls provide higher accuracy and more
detailed information than the existing calls.
|
The new SWI calls are in the same range as the existing ones
and they are available from version 3.00 of the module onwards.
|
- Joystick_Read 2 (SWI &43F40)
This is an extension to the existing SWI Joystick_Read.
The call returns a pointer to a structure containing all data of the
joystick.
Entry:
r0 : Joystick number (bits 0-7) and reason code 2 (bits 8-15).
Exit:
r0 -> Structure containing a number of 32-bit results.
+0 : Number of parameters following
+4 : Buttons (up to 32 buttons starting in bit 0)
+8 : X position (0-65535)
+12 : Y position (0-65535)
+16 : Z position (0-65535)
+20 : X rotation (0-65535)
+24 : Y rotation (0-65535)
+28 : Z rotation (0-65535)
+32 : Slider (0-65535)
+36 : HatSwitch (-1 if off, otherwise angle in degrees (0-315)
Use:
The first word of the structure gives the number of parameters
following, so that it can be extended in the future. Your code should
check the first word before trying to read past the end of the list.
The Joystick module maintains this structure for each channel, so there
is no need to make your own local copy of it.
- Joystick_Info 0 (SWI &43F43)
Read global information from the Joystick module.
Entry:
r0 : 0 (reason code)
Exit:
r0 : Number of active joysticks (bits 0-7) and flags (bits 8-31).
r1-r4: May be corrupted (may contain information in future versions of the call).
Flags:
bit 8 : Calibrated (both SWIs have been called).
bit 9 : Fake calibration.
- Joystick_Info 1 (SWI &43F43)
Read global information about a joystick port.
Entry:
r0 : 1 (reason code)
r1 : Joystick port number
Exit:
r0 : Channel number (bits 0-7) and flags (bits 8-31).
r1 : DeviceID (USB Vendor and Product code).
Flags:
bit 8 : Calibrated (both SWIs have been called).
bit 9 : Fake calibration.
- Joystick_Info 2 (SWI &43F43)
Read controls calibration.
THIS CALL IS FOR INTERNAL USE ONLY.
- Joystick_Calibrate (SWI &43F44)
Provides flexible calibration for each joystick individually.
Entry:
r0 : Joystick port number
r1 : Calibration type
0 : Reset calibration
1 : Calibrate Bottom Left
2 : Calibrate Top Right
3 : Set fake calibration flag
4 : Reset calibrated flag
r2 : Parameter to calibrate
0 : All parameters (should be 0 for now).
Exit:
All registers preserved.
|
|
|
© Copyright Paul Reuvers
X-Ample Technology bv
usb@xat.nl
Last changed: Last changed: Saturday, 22 April 2006 - 15:20 CET.
|
|