Would there be any objections to changing the spec of Joystick_Read 1 to support 32 buttons. eg from:

to:

changing the spec of Joystick_Read 1 to support 32 buttons

I’ll briefly come out of hiding to say – please do this.

Even a basic SNES style joystick has ten buttons, which can’t be fully used with an eight bit value.
I’ll keep an eye out for this, and will update Mamie accordingly.

Now to crawl back under my rock…

No objections from me.

For SDL, it would also be useful to have SWIs to list how many joysticks exist, and what features they have – SDL 1.2 on RISC OS currently hardcodes 1 joystick with 2 axes and 8 buttons since there isn’t a reliable way of looking this up. For SDL2, it would also be good to have a way of getting the named elements for all buttons including A, B, X and Y so that the game controller API will work without requiring the user to manually provide a mapping string.

Sounds good to me.

For SDL, it would also be useful to have SWIs to list how many joysticks exist, and what features they have

Borrowing a few ideas from this old thread, and the SDL 2 API perhaps a sensible course of action would be:

• Define a JoystickV vector to allow the Joystick module to act as a frontend to multiple backend driver modules
• Define a fixed list of buttons & axes which we want to support, like the SDL_GameControllerButton & SDL_GameControllerAxis enums, based around the common case of Playstation/Xbox style controllers. Over time we can extend the list as necessary.
• Add a new Joystick_Read API which uses those button & axis identifiers, like SDL
• Add a Joystick_Features API (or whatever we decide to call it) to read the name of the joystick, which buttons & axes are supported, etc., similar to the SDL API
• Support for the old API could be handled by adding a SWI and/or *Command to allow the user to control which joystick is mapped to the old API (“make my X360 controller joystick 0 and my PS3 controller joystick 1”), while the backend driver does the work of mapping all the different buttons down to the limited set supported by the old API.

That should give us a reasonably feature-rich API without requiring too much effort to design & implement it.

I’ve revised the documentation for Joystick_Read 1 to support 32 buttons and noted that it previously supported only 8.

I’ll hold off doing anything about a better API until there’s been more feedback. I would particularly like to see feedback from game authors and Richard Walker.

My suggestion in the OP is primarily centred around XB/PS controllers and needs expanding/changing to cover HOTAS, steering wheels and other forms of HID that games are likely to need. Jeffrey’s suggestion of using a naming standard that already exists is worth investigating. I’m inclined to lean towards an existing Microsoft, Sony or Linux standard, as I expect every game API has it’s own naming convention.

I wouldn’t bother extending the definition of the Joystick_Read 1 SWI.

As a user of the proposed interface, you don’t know what the buttons are, and no existing client using the interface before any such change would know that they were there. Therefore only new clients who explicitly want to use the new buttons would know to look for them. And they wouldn’t know what they meant – how to present them or what they could do with them. As such, any client wanting to use them only gains the ability to look for buttons but cannot present any interface to help the user any better than before.

Essentially I think that just defining new buttons on that API is too narrow and if you’re going to make changes it should be in a more significant manner – otherwise you’re immediately going to throw away what you’ve got because the existing interface is too limited.

The suggestion of an extra SWI is redundant, as the mechanism for extending the Joystick reading interface is through Joystick_Read – just create new reason codes, don’t start creating new SWIs when they aren’t needed. If you were doing something other than a ‘Read’ operation then it’d be reasonable, but… you’re not.

If it were me doing it, I’d create a registration interface where hardware drivers can register with the Joystick module to provide their functions. However, using Jeffrey Lee’s suggestion to vector the interface so that multiple clients can be connected at once would work equally.

Start by working out what features a Joystick has – because the current implementation is limited (and the proposal identifies a few but only for specific instances).

• There may be multiple joysticks connected.
• Any given joystick may have a number of linear controllers, not just a pair of X and Y controllers, as well as a number of buttons.
• Those linear controllers and buttons may have known identifiers. Buttons may be generic or may have given known allocations. This allows the buttons to be presented to the user through an interface. Linear controllers may have a type or a location.
• A button might be of a different type – it might be an instantaneous control, or it might be a toggle.
• A joystick might be identifiable itself (it might give its name, or it might be identifiable by a serial number of connection mechanism). This mechanism allows the device to be identified to the user.
• A joystick may have a feedback mechanism. This may take multiple forms – a force feedback of a given strength and position, for example, or a LED. Feedbacks may be related to buttons or linear controllers.
• Linear controllers will have relative positions – they may go from 0-10. They may go from -256 to 256. They may have a relaxed position of 0, or return to position. They may report an absolute position, or they may only ever report relative changes (consider a rotational control).
• Linear controllers may have relationships to other controllers – eg a given linear controller may control an x-axis and be related to a y-axis, essentially providing a controller group.
• Linear controllers may provide more than two related controls – an x, a y and a z would not be unreasonable for a yoke.

Knowing what sorts of input devices exist, an interface should be designed which gives the ability to represent the bulk of the forms, even if they are not used right now. Simplified interfaces will be required for those who don’t need the full set, and just want to know ‘are they pressing a button’, or ‘where is the joystick relative to its rest position’ (eg like we currently have)?

It might be useful to decide whether the input to the system is intended to be instantaneous, or buffered. At present input readings are essentially instantaneous – you make a request for the current state and you get it. Just ignore the fact that you might have missed some clicks or whatever. Is that reasonable? Can a mechanism be given which allows this?

That’s some quick thoughts… I’ll throw down some more thoughts that I’ve had this evening later, but it’s late and I’m pretty sure my eyes are glazing over…

A few hours after I’d seen this and I’ve written up some ideas on how I would go about providing an extensible interface to allow multiple joystick drivers, a reasonable numbers of buttons, a variety of linear controllers, enumeration and informational interfaces, and how the interfaces could be made to work with older clients. Initally introductory section just outlines some of my thoughts for how it would work. Service calls expected to be used are listed. Errors which would be returned are listed with each SWI. Outstanding issues that I can think of are listed at the bottom. Inter-driver interface is not defined here; it would essentially fall out of the external interface and how the Joystick controller module would operate.

I suspect some of this won’t format well… Oh for a sensible documentation format…

Joystick interface

Ideas for a proposed Joystick interface, replacing the dedicated hardware vendor supplied driver with a generic
controller module. The controller allows registration by other hardware driver modules, which communicate with it
through the Joystick SWIs. The Joystick module communcates with the drivers through a registered interface.

This does not allow for an upgrade path for existing Joystick driver modules.

There may be up to 255 joysticks using the current selection mechanism (joystick 255 reserved).
The current Joystick_Read interface is used to provide all read operations for the calls.

Joysticks are registered through a Joystick_Register, and deregistered with a Joystick_Deregister SWI.

On registration the joystick supplies a descriptor block that describes the joystick’s name (if any),
and the number of input controls that it provides.
Within the descriptor block a mapping of the control identifiers to the original buttons is defined,
together with the default linear control

Inputs:

• Joysticks may support up to 255 input controls (control 255 reserved)
• An input control may be a linear control, or a button (at present, other types may be defined in the future).
• Input controls are identified thought an input identifier, a value from 0 – a maximum value for a Joystick with no
  invalid values between.
• Each control can be defined by a known set of types, or be anonymous.
• A mapping is provided by the driver for the buttons to the original buttons interface.
• A mapping is provided by the driver for the linear controls to the original x/y interface.
• The Joystick driver may provide a mechanism for remapping those buttons and linear controls.

Outputs:

• Force feedback, LEDs indicators, and RGB effects not considered here.

Joystick_Read calls are split into sections:

• 0-15 – old, or simplified, interfaces
• 16-31 – information about joysticks
• 32-47 – state of linear inputs for a specific joystick
• 48-63 – state of button inputs for a specific joystick

Joystick_Register

=> R0 = pointer to joystick descriptor (will be copied):
             +0 pointer to name of the joystick device (or some identifing mark), will be copied
             +4 pointer to entry point for joystick requests
             +8 private word to pass on calls to entry point in R12
            +12 joystick support flags (must be 0, to define future interfaces)
                    (might include flags indicating support for force feedback or LED returns)
            +16 number of inputs supported
            +20 pointer to input definition blocks (one for each input):
                     +0 input type (see below)
                     +4 input usage (see below)
                     +8 input location (see below)
                    +12 minimum value (only for linear controls)
                    +16 maximum value (only for linear controls)
                    +20 rest position (only for linear controls)
            +24 pointer to default mapping of buttons to input identifiers (terminated by -1)
            +28 input identifier for the default linear control
<= R0 = joystick number

Errors possible: CannotRegister

Joystick_Deregister

=> R0 = joystick number

Errors possible: NotRegistered

Service_Joystick 0 – Joystick module initialised

Issued on a callback by Joystick when the Joystick module starts to allow drivers to register themselves.

Service_Joystick 1 – Joystick module finalised

Issued on Joystick module finalisation, for Joystick drivers to become quiescent.

Service_Joystick 2 – Joystick registered
h2. Service_Joystick 3 – Joystick deregistered

=> R0 = joystick number

Issued by Joystick when new drivers appear or are removed.
Explicitly issued on module finalisation, prior to Service_Joystick 1.

Joystick_Read 16 – read joystick information

=> R0 = bit field:
            b0-7: Joystick number, or 255 to begin enumeration
            b8-15: 16 (reason code)
            b16-31: reserved, must be 0
   R1 = pointer to buffer for the joystick name, or 0 to not read
   R2 = size of the joystick name buffer, or -ve to read length
<= R0 = this joystick number
   R1-> input name in buffer (if requested)
   R2 = size of buffer required, or size written (if requested)
   R3 = number of input identifiers supported (maximum identifier number + 1)
   R4 = joystick support flags (from the registered descriptor)
   R5 = next joystick number after this one, or -1 if there are no more joysticks

Reads information about a specific joystick. The interface allows for the enumeration of joysticks
by passing the value 255 to the interface initially. This allows joysticks to come and go, and for
the enumeration of the joysticks to begin at a non-0 value.

Errors possible: ReservedFlagsSet, BadJoystick

Joystick_Read 17 – read joystick input information

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 17 (reason code)
            b16-23: input identifier
   R1 = pointer to buffer for the input name, or 0 to not read
   R2 = size of the input name buffer, or -ve to read length
<= R0 = input type:
        0-255 - linear controls:
            0 x-y-z controlling device, resting at centre positions
            1 x-y controlling device, resting at centre positions
            2 x controlling device, resting at centre position
            3 reserved
            4 x-y-z controlling device, resting at low positions
            5 x-y controlling device, resting at low positions
            6 x controlling device, resting at low position
            7 reserved
        256-512 - buttons:
            256 instantaneous state
            257 edge triggered
            258 toggle
   R1-> input name in buffer (if requested)
   R2 = size of buffer required, or size written (if requested)
   R3 = input usage:
        b0-11: usage type
            0-255 - linear controls:
                0 generic linear device
                1 joystick
                2 yoke
                3 throttle
                4 thumbstick
                ...
            256-512 - buttons:
                256 generic button
                257 dpad-up
                258 dpad-down
                259 dpad-left
                260 dpad-right
                270 A
                271 B
                272 X
                273 Y
                274 Start
                275 Back
                276 Left Bottom
                277 Left Top
                278 Right Bottom
                279 Right Top
                280 Trigger
            4095 use not defined
        b12-15: sequence number, or 0 for undefined
        b16-23: input identifier this input relates to, or 255 for the controller as a whole
        b24-31: reserved, must be 0
   R4 = relative physical location
        b0-1: lateral position:
                    0: undefined
                    1: left
                    2: centre
                    3: right
        b2-3: longitudinal position
                    0: undefined
                    1: front (towards user)
                    2: middle
                    3: rear (away from user)
        b4-5: vertical position
                    0: undefined
                    1: lower
                    2: middle
                    3: upper
        b6-15: reserved, must be 0
        b16-23: input identifier this location relates to, or 255 for the controller as a whole
   R5 = linear control value (linear controls only)
   R6 = minimum linear value (linear controls only)
   R7 = maximum linear value (linear controls only)
   R8 = rest value, or -1 if control is not sprung

Reads information about a given input control.

Errors possible: BadJoystick, BadJoystickInput.

Usage types allow the game to provide a specific known label for a given device, if the type is known.
These usage types might be remapped within the Joystick module at the user’s request for a given device type.
For example, a particular joystick controller might return every button as a generic button -
the user may configure the Joystick module to map the first to X, the second to Y, the third to A, etc.

The physical location allows a generic interface to supply a simple diagram of the control’s buttons if the
locations are given, or just a list if not. Related buttons means that a given button can be described more
readily (eg a Trigger could be associated with a given linear controller, and described as being on the
front relative to that controller). These descriptors are not relevant to the data read by the controller
but give a better configuration and descriptive interface for clients that wish to use it.

Joystick_Read 18 – read button mapping

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 18 (reason code)
            b16-23: original interface button number
            b24-32: reserved, must be 0
<= R1 = input identifier

Reads the input identifier which is mapped to the original interface’s buttons.

Errors possible: ReservedFlagsSet, BadJoystick

Joystick_Read 32 – read linear control group (scaled)

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 32 (reason code)
            b16-23: control identifier
            b24-31: reserved, must be 0
<= R0 = input type (as defined above)
   R1 = x position (0-65536), or -1 if no x position available for control group
   R2 = y position (0-65536), or -1 if no y position available for control group
   R3 = z position (0-65536), or -1 if no z position available for control group

Reads a value of a linear control scaled to the standardised range.

Errors possible: ReservedFlagsSet, BadJoystick, BadJoystickInput, NotALinearControl.

Postions are defined as:

• x – lateral position, low to left, high to right
• y – longitudinal, low being to the front (towards the user), high being to the rear (away from the user)
• z – vertical, low being down, high being up

Rotational controls should attempt to provide conventions which are similar.

Joystick_Read 33 – read linear control group (raw)

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 33 (reason code)
            b16-23: input identifier
            b24-31: reserved, must be 0
<= R1 = linear control value
   R2 = minimum linear value
   R3 = maximum linear value
   R4 = rest value, or -1 if control is not sprung

Reads the unscaled values directly from the device.

Errors possible: ReservedFlagsSet, BadJoystick, BadJoystickInput, NotALinearControl.

Joystick_Read 48 – read button state (single)

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 48 (reason code)
            b16-23: input identifier
            b24-31: reserved, must be 0
<= R0 = button state (1 = pressed, 0 = not pressed)

Reads a single button’s state, given its identifier.

Errors possible: ReservedFlagsSet, BadJoystick, BadJoystickInput, NotAButton.

Joystick_Read 49 – read button state (single, by usage)

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 49 (reason code)
            b16-23: sequence number
            b24-31: reserved, must be 0
   R1 = button usage to read
            b0-15: usage type
            b12-15: sequence number, or 0 for undefined
            b16-23: input identifier this input relates to, or 255 for the controller as a whole
            b24-31: reserved, must be 0
<= R0 = button state (1 = pressed, 0 = not pressed)

Reads a single button’s state, given its usage. If multiple usages are present the sequence number and
input identifier will differentiate them. Where the sequence number is given as 0, the first suitable
usage type will be returned, ignoring the input identifier or sequence number for that input.

Errors possible: ReservedFlagsSet, BadJoystick, BadJoystickInput, NotAButton.

Joystick_Read 50 – read button state (range)

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 50 (reason code)
            b16-23: base input identifier
            b24-31: reserved, must be 0
   R1 = number of buttons to read
<= R0 = b0-31 describe the state of each ascending button

Read the button state for each button from a given base (ie from base input identifier to base input identifier + R1 -1).
This allows a bulk read of many buttons. As in most cases there will be less than 32 buttons, this will be sufficient
to read the state of most buttons in a single call.
Linear controls will always return unpressed.

Errors possible: ReservedFlagsSet, BadJoystick, BadJoystickInput, NotAButton.

Joystick_Read 51 – read button state (supplied buttons)

=> R0 = bit field:
            b0-7: Joystick number
            b8-15: 51 (reason code)
            b16-31: reserved, must be 0
   R1 = pointer to list of bytes describing the input identifiers to read, terminated by 255 for buttons to read
   R2 = pointer to list of bytes to populate with the button state, one bit each.
<= R0 = number of buttons pressed

Read the button state for each button in a list. This allows a bulk read of explicit buttons. The returned count
of the number of pressed buttons ensures that the client can return quickly without checking the entire state.
Linear controls will always return unpressed.

Errors possible: ReservedFlagsSet, BadJoystick, BadJoystickInput, NotAButton.

Outstanding issues:

• Joystick→Driver interface not defined here.
• Calibration interface cannot be extended as there are no input parameters.
  A new interface is required, however it can be implemented through the above-defined read linear group (raw) calls
  to update the calibration – which can take place entirely within the Joystick module. This implies that there should
  be a set of calls to read the calibration settings and to write them. Consider Joystick_Calibration where
  defines a ‘calibrate position’, ‘read calibration’, ‘write calibrration’ for joystick + input combination.
  The existing calibration calls could be used for calibrating the lowest numbered joystick’s default linear control,
  but it’s not clear that any one ever used this interface anyhow.
• Relative linear controls are not considered (eg a wheel with full rotational motion is not a considered case here -
  this might be a new linear control input type for ‘x controlling device – unbounded range, no rest position’, to
  allow clients to recognise these and map transitions over the wrapping boundary?
• Joystick 0 might not exist. Consider making Joystick 0 implicitly the lowest numbered (oldest?) joystick, so that
  it’s always there if a joystick is connected, for older clients. This might make the enumeration interface easier,
  as you could always start the enumeration at Joystick 0.
• Interface currently precludes the use of joystick buttons to trigger events as they must be polled. Consider making
  the drivers call the Joystick to notify it of button pressed? (and the Joystick module then issuing Event_Joystick for
  those buttons)
• Outputs such as force feedback and LEDs could be defined in a similar manner to buttons, with a write call to update
  them. Defining them in terms of the locations on the control, or in relation to a given input would help with LEDs
  in particular (right LED, for example, or a LED associated with a specific input identifier). Additionally,
  feedback on linear controls would necessitate multiple axes of response.
• Upgrade path for existing Joystick modules to be considered. Consider supplying a !Patch file which turns the
  original joystick module into a driver module which registers itself with the new system. Because existing clients
  will call the known Joystick interface, it is not possible to replace and subsume the old drivers at the same time.
  Consider calling the new module JoystickDriver, and reinitialising itself if it sees a Joystick module start, then
  locating the module named Joystick and providing an implicit registration for its SWIs. Reinitialisation would be
  necessary to ensure that the old style Joystick module didn’t capture the SWIs of the new module, although
  doing a reinitialisation would cause the Joystick numbers to change. This form of indirection would be similar to
  the use case provided by NetI for Econet. It’s possible that this manner of operation would be too complex for
  general use but would allow existing drivers to function with the new interface, which is important if you don’t want
  to frustrate users who cannot obtain new driver modules.

Right now I’d settle for expanding the buttons to return all of the bits.

Remapping a joystick should be something a user does if they want to change the default assignments, or they have a notably different joystick, not a necessity because ten bits are arbitrarily stuffed into eight, with two bits thrown away.

The suggestion of an extra SWI is redundant, as the mechanism for extending the Joystick reading interface is through Joystick_Read

Point taken.

I’d create a registration interface where hardware drivers can register with the Joystick module to provide their functions

That is covered by the other Joystick thread which is focused on the hardware layer interface

Start by working out what features a Joystick has

Features are already defined by the USB HID standard, I don’t think we need reinvent the wheel.

Knowing what sorts of input devices exist, an interface should be designed which gives the ability to represent the bulk of the forms, even if they are not used right now

Agreed

Simplified interfaces will be required for those who don’t need the full set

As we’re defining a new standard, I don’t think we need to provide multiple application interfaces. The existing Joystick_Read has the simplest form of use coverage for most games.

decide whether the input to the system is intended to be instantaneous, or buffered.

Buffering has not been an issue to date as generally a user can’t mash the buttons quick enough, but I understand your point. Provided a game checks inputs during any framesync delays, non-buffered should be sufficient.

Joystick_Register / Joystick_Unregister / Service_Joystick

I believe we’ve already reached a consensus that we will use JoystickV for the hardware interface in the other Joystick thread

With regard to the remainder of your 2nd post, although very thorough, I would say its overly complicated for a game developer to implement and some of what you’ve detailed needs to shift over to JoystickV as its hardware layer.

Upgrade path for existing Joystick modules to be considered

We’re defining a new interface so do not need to consider backward compatibility. Other than USBJoystick and a few I maintain, I’m not sure there are any existing Joystick Modules that run on RISC OS 5. Provided Joystick_Read 0/1 continue to provide basic input from the primary Joystick, we’re not going to break any existing usage.

I’d really like to see feedback from developers that are potentially going to be implementing this in games. The OP was based on my experience of getting existing games to support Joysticks under RISC OS 5 over the past year and just an idea to kick off the application layer discussion among application developers.

Right now I’d settle for expanding the buttons to return all of the bits

I agree, I never really understood why Joystick_Read 0/1 were limited to 8 although to be fair, at the time Joysticks only had one fire button. Hopefully, once Richard gets involved in the discussion we can get the extra buttons implemented in the next USBJoystick update.

Remapping a joystick should be something a user does if they want to change the default assignments

Also agree, as the alternative leaves the decision to the game developers, many of whom won’t implement reassignment.

I’d really like to see feedback from developers

As someone who has just done this – all I ask for is that all of the buttons be available to be read.
I have supported “SNES style” joysticks as they are cheap and cheerful and available from box shifters like Amazon, however I’m aware that there are PlayStation style controllers (fully analogue and even more buttons), and indeed more styles of “joystick” than I could imagine.

I don’t plan on implementing redefinable buttons. There’s no point when there’s a remap command that will do it. A remap command that could also be useful for adjusting the controls of different styles of joystick.

In fact, the only thing I think is missing from that (it’s only a small thing, and might be possible – I’ve not tried) is to assign multiple buttons to the same bit in the SWI – so if there are two shoulder buttons instead of one, you can map it so both do the same action.

get the extra buttons implemented in the next USBJoystick update.

Brilliant! ;)

PlayStation style controllers (fully analogue and even more buttons)

Not just more buttons, but programmable buttons. For example, the two ‘triggers’ (“L2” and “R2”) on the PS5 controller can have their resistance set by a game, adjusting how hard you need to pull them before they activate. There’s also a trackpad :)

Sorry for the lack of response. I’ve had the ‘delight’ of trying to move over the last few months, and it’s still ongoing!

I think it seems entirely sensible to go for any quick wins, such as allowing more button statuses to be included in Joystick_Read. I think we can safely say that stuff Acorn might have marked as ‘reserved’ is, well, no longer reserved – they had their chance, and chose to exit the market instead. :)

I do like the fully-blown ideas from Charles & Jeffrey regarding a ‘base’ and then having drivers to register/deregister different types of hardware. This is something that has been nagging away in my head ever since I developed USBJoystick: half of it is really ‘joystick’, and the other half is ‘USB’. If someone wanted to knock-up, say, a GPIO interface for a joystick, then it would make sense to split it all out and be able to load multiple modules: Joystick, USBJoystickDriver and BlahGPIOJoystickDriver.

However, at this moment, I was only implementing an existing API (for classic games) so all of this is mere implementation detail, and we can change it at any point in the future. Secondly, you can get a USB joystick very cheaply – are people really going to be rigging up other hardware interfaces? USBJoystick has probably been used by less than a dozen people, so I cannot imagine much of a userbase for that!

When it comes to extending the API for game writers, I didn’t feel I knew enough about it. I’ve written zero joystick games for RISC OS, and have zero experience of what joystick APIs look like on other platforms (e.g. SDL2 – so thanks Cameron for your comments). Regardless of what gets implemented, never mind when, getting the API right is important, as obviously we can’t go making sweeping changes once it gets a few games using it.

I was thinking of something where we could provide: 1) a list of connected controllers 2) a ‘full read’ which would list out each button/axes and the min/max/live values. Further down the line, something which could list and control capabilities like ‘force feedback’. For (2) I was thinking of going closely with the USB HID spec with regard to button and axis names – but maybe that’s not a good idea?

I agree with Jon that it would be good to look at what sort of things game authors want (e.g. Rick with ‘more buttons’) and what would make porting games/libraries easier.

Start by working out what features a Joystick has
bq. Features are already defined by the USB HID standard, I don’t think we need reinvent the wheel.

That is one source of information. I wasn’t stating what source were to be used, just that that should be the way that you approach things. Not by randomly shoving extra bits onto an already bad interface.

The HID spec is hideously (no intended) complex for handling the different button types, so in my design I proposed I suggested I selected only the two types of inputs which are required right now, and which offer the greatest benefit, and allowing the design to expend to other types with clients being able to identify and expand beyond them without redesigning the API again.

That is covered by the other Joystick thread which is focused on the hardware layer interface

I’ve skimmed that thread. I don’t see much of value in there [I meant until I came across your JoystickV proposal] One thing I see is:

One thing that’s probably worth considering is changing the Joystick module so that it’s just a middleman which sends all its SWIs over a vector (“JoystickV”).

That’s a bad idea. In the first case, vectors are in short supply and adding another would potentially preclude the use on older systems without extended vector numbers. Secondly they’re useful for extension of interfaces, and there’s pretty much no useful way you can provide an extensible interface using a joystick interface which doesn’t involve calling all claimants for them to filter the call – calling everyone and asking them if they’re interested in servicing a call, is a bad interface from a design and performance perspective, particularly for a collection of devices which can appear and disappear dynamically. Similarly the ‘pass SWIs over a vector’ is used by a few modules and really doesn’t help provide a consistent interface. Passing intent over a vector is better, but as stated introduces overhead that you wish to avoid. Providing a registration interface is far more in line with other users.

I see a design from yourself in https://www.riscosopen.org/forum/forums/5/topics/2504?page=2#posts-31843 but I strongly disagree with the use of a vector for such things. Also… the API talks about Wimp features… WTF?! nothing in the low level interfaces for joysticks should have anything whatsoever to do with the Wimp.

[The actual content has a lot of reasonable things, and is similar to what I proposed in some respects]

That was in 2014. I assume that you’re referring to some other discussions or prototypes that someone has put together?

Seriously… this sort of work should take just a couple of weeks to put together, not 7 years.

We’re defining a new interface so do not need to consider backward compatibility.

You always consider with backwards compatibility. That consideration can be that we don’t need to worry, but you always consider it. I offered a possible suggested way to make that work, but if you have people who do have such interfaces you need to consider how they will be affected, and whether there is a way forward. Otherwise you have a CDFS 3.

vectors are in short supply

Jeffrey would not have suggested using a vector if it was a potential issue. It seems like the perfect solution to me as it avoids issuing Services or SWI’s which can cause issues when threaded.

An SWI to Register/Unregister as you’ve suggested works equally well – RTSupport uses that method, but generally where driver support has been added, vectors have been the method. eg GraphicsV

preclude the use on older systems without extended vector numbers

What older systems do we need to take into account? We are defining a new standard for a future build of RISC OS 5. Out of scope are all previous versions of RISC OS and all machines that can’t run the latest build of RISC OS 5.

API talks about Wimp features… WTF?! nothing in the low level interfaces for joysticks should have anything whatsoever to do with the Wimp.

The Configuration app needs to show the Joystick and its buttons for any Configuration extension added, this is to allowing users to reconfigure button/axis mappings, set deadzones, calibrate etc.

Seriously… this sort of work should take just a couple of weeks to put together, not 7 years.

In a corporate environment perhaps. Joystick support isn’t exactly a priority as I’m possibly the only developer that has any need for an API at the moment. Up until quite recently nobody was developing games for RISC OS, so there was no need to even support Joysticks under RISC OS 5.

You always consider with backwards compatibility…Otherwise you have a CDFS

Having intimate knowledge of CDFS, the issue there wasn’t so much backwards compatibility but a lack of open documentation, but I understand your point.

I’m not aware of any modern machines that support legacy Joysticks. I suppose you could connect RTFM via Econet on a RiscPC, but that’s not a supported scenario for any existing games.

I feel we should stick to USB Joysticks and put everything else out of scope, including precluding a backport of the API to any other OS versions.

Just a few comments.

I am not interested in older hardware or OS versions. I don’t see the point in worrying about decades-old systems. They can be left alone.

On the timescales, yeah, it is mad that things take years. But that is how things are here. RISC OS is a hobby. Before that, I have got a family and a full-time job. I take my hat off to those who can program professionally all day then carry on through the evening – I can’t. I have recently moved house,and the Pi is in a box… Somewhere!

The great thing is that anyone is welcome to contribute (to anything). There are people here who do, but there are many more who just talk about it. There are even some who hint at making/having all sorts of treats, but don’t deliver. That is all fine. It is a hobby for everyone, as I say.

One thing on my to do list for USBJoystick is to put the source in github/gitlab. I was waiting for a RISC OS git client.

Over Christmas, I’ll flesh out the Joystick SWI’s and hardware driver API, taking on board feedback from this post and the other thread.

Having spent a week pondering, I think I’ll take Charles’ suggestion and use a Register/Unregister SWI for the drivers to register with Joystick as it removes any OS dependency. For the interaction between Joystick and hardware driver Modules, it will be direct code calls (like GraphicsV) to avoid threading issues.

Games will remain using Joystick_Read, but with additional reasons to allow querying multiple axis/buttons at once (like OS_ReadVduVariables) and reasons for force feedback etc.

The driver Modules will be light touch with no deadzone code or scaling, they’ll simply provide updates of device inputs to Joystick. Joystick will handle scaling, deadzones, normalization, button/axis mappings etc. with a Configuration app to allow the user to remap buttons/axis, device order, set deadzones etc.

I might also add a reason for Games to register with Joystick, this is primarily to allow per-game configuration preferences in the Configuration app. For example, if you have an XB360 controller and a Logitech Steering Wheel attached, you’d want Zarch using the XB360 as primary and Saloon Cars the Logitech.

Sounds good. A few additional comments:

• Am I correct in thinking that the current proposal will support hot-plugging joysticks?
• It would be good to still have the driver report which button from the existing SWIs maps to which button on a standard Xbox 360 controller, since that would be what would map most cleanly to how joystick drivers in SDL2 are implemented. I’d also recommend accounting for the system mapping when returning this to applications, since being able to remap this would likely cause trouble in newer games that have in-game remapping or button prompts.
• I don’t know how many games make use of this, but the Joystick module in !HID makes several extensions to the existing SWIs, as well as adding two new ones, so I’d suggest watching out for that when adding further SWIs or Joystick_Read reason codes.

Ahh… Maybe the HID extensions are worth looking at. Are they documented publicly?

There’s a section in the manual included in the download that describes both the existing Joystick API and the extensions made to it.

!HID extends Joystick_Read 1 R1 to 32 buttons as proposed in the OP and is now in the documentation. It also adds:

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

Exit

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

Exit

Flags

Joystick_Info 1 (SWI &43F43)

Read global information about a joystick port.

Entry

Exit

Flags

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

Exit

All registers preserved.

My comments relating to !HID and calibration.

The Joystick Module will need to jump to v4.00 as HID is v3.x

Joystick_Read 2 as implemented by !HID is very specific to a particular Joystick type and isn’t something I’d look to include in any future spec. I’d prefer to let the caller decide what data they want returned.

Joystick_Info has never been documented and I’m not even certain it was part of the original Acorn spec.

Joystick_Info 0 will need to be implemented (no. of Joysticks connected), although I’m not sure why it needs its own SWI and can’t be a reason code off Joystick_Read.

Joystick_Info 1 – I’m unclear as to what this reason code is meant to be doing.

Joystick_Calibrate / Joystick_CalibrateTopRight / Joystick_CalibrateBottomLeft – I am not convinced these need to be externally accessible from the Joystick Module. Calibration is something you’d only need to do once and it would be better placed in the Configuration control panel, where each axis can be calibrated individually and the settings linked with an individual Joystick either by name or GUID.

For USB Joysticks, calibration is mostly redundant as the HID spec includes the min/max values as part of the spec. and the Joystick Module will scale values appropriately. Where it might be applicable is with legacy Joysticks, but I’m not proposing we include legacy devices, only future-proof and cover deadzones that require calibration scaling.

There are some issues around calibration, in particular CalibrateTopRight and CalibrateBottomLeft. Many modern Joysticks do not have a top right/bottom left unless normalized. XB/PS thumbsticks are (almost) circular and normalizing an XB360 thumbstick feels quite unnatural in games such as Zarch . Where normalization might be applicable is when mapping a circular stick to the mouse pointer. Normalization would need to be on a per-app basis and decided by the app itself. For example, BloodLust might want the right stick normalized as it’s controlling the Mouse pointer and the left stick un-normalized for movement.

Just for the sake of clearing up one minor sideline of the discussion…

Having intimate knowledge of CDFS, the issue there wasn’t so much backwards compatibility but a lack of open documentation, but I understand your point.

I think you missed the point, because CDFS 3 was the topic, and I am fairly sure that you have intimate knowledge of CDFS 2, not 3. Because nobody still around has intimate or even a working knowledge of CDFS 3.

Amusingly, I had more docs on CDFS 3 than CDFS 2, but never saw it working anywhere. Maybe ROOL have the source?

Read controls calibration.
THIS CALL IS FOR INTERNAL USE ONLY.

Can we please stop with this nonsense. What’s the point of being able to set (or reset) calibration, without being able to read it?

This isn’t to say that games should concern themselves with this, it’s more the principle of hiding information behind an “internal use only” tag.

Also, Joystick_Info 0 and 1. Shouldn’t the “calibrated” flag be per joystick?

It would be easy to get rid of call zero entirely. Simply have call 1 return an error for joysticks that don’t exist, so the caller can just count up from zero to X to enumerate the available joysticks.

Any update on this? Is there anything I can do to help move things forward?