Axis.Identifier

[endolf]

Right, I know this has come up before, lots, and never been resolved, but this time I intend to do something about it

as it stands, Axis.Identifier is abused left right and centre. The API docs are fairly clear that it should be used as a type identifier, but that doesn't say what the types are. e.g. there are types for different axis, like a rudder or a throttle, but there are not types for different buttons, 'A', 'Z', 'ctrl' etc. I have a couple of suggestions.

1) Restrict that Axis.Identifier statics to genuine type, so Button, or Axis. I hate this one, but it's an option.

2) Use the current standard defined types, and just fix the usage of them in the plugins.

3) Update the types and add ButtonX and ButtonY type identifiers.

4) make Axis.Identifier.Button.X type structures where Axis.Identifier.Button extends Axis.Identifier and Axis.Identifier.Button.X extends Axis.Identifier.Button, this way you can have as narrow or wide a type search as you like. This would mean moving the existing types around so that there is an Axis.Identifier.Axis.X etc.

5) Just have one huge long list of them, extending the current list to include all the button names etc.

6) Modify Axis.Identifier, so that it includes a Type field, the type is one of Axis, Button or a few others we think of, and the Axis.Identifier is one of a huge list containing all the new types for buttons etc.

I just want to see what the consensus is amongs both jinput devs and API users.

Cheers

Endolf

[swpalmer]

I don't like #1 or #6.   The subclassing scheme seems to make more sense from an OO programming perspective.

[kmconroy]

I don't like #1 or #6.   The subclassing scheme seems to make more sense from an OO programming perspective.

I agree.

Games published by our own members! Check 'em out!

[TheBohemian]

4) sounds good. the only thing that annoys me is the Axis is used way to often. Isn't there a better word for it? the whole thing would look ridiculous in code:

1   2   3   4   5   6   7   8   9   10   11   12   13

package foo; public class Axis{  public class Identifier{     public class Axis {    public static final Axis X = new foo.Axis.Identifier.Axis("X");   }  } }

that looks error prone. yeah right, compiler will catch it easily but it makes programming the stuff not very friendly.
please find a new name for (net.java....)Axis which does not interfere with the name of a device feature. it is awful to distinguish between axis and Axis in documentation all the time

btw:

Axis.Identifier.Button.X extends Axis.Identifier.Button

err .. um thats a mistake, isn't it? X is an instance of Axis.Identifier.Button not a subclass? the example above think its an instance.

another question: can plugin developers create their own Axis.Identifier and Axis.Identifier.SOME_CLASS instances or is everything given as constants?

[swpalmer]

the whole thing would look ridiculous in code:

1   2   3   4   5   6   7   8   9   10   11   12   13

package foo; public class Axis{  public class Identifier{     public class Axis {    public static final Axis X = new foo.Axis.Identifier.Axis("X");   }  } }

that looks error prone. yeah right, compiler will catch it easily but it makes programming the stuff not very friendly.

Remember that code would only look like that in a few places WITHIN JInput.   Where the plugin programmers need to deal with defining the Axis Identifiers.   For USERS of JInput and most places within the plugins it will just look like a fully qualified class name.

[endolf]

When using it you'll also have Axis.Identifier.Axis.X, which isn't nice, and yes, it was a mistake, X is an instance of Axis.Identifier.Axis in this case. Would also need to remember that anyone not using AbstractController would need to make sure they update the way Controller.getAxis(Axis.Identifier) works, and we would need a new method Controller.getAxis(Class identifierType)

unless anyone can think of a new name for Axis.Identifier.Axis etc, then I'll go ahead and start implementing it. I also want to get the ControllerEnvironment.isSupported() method in that was discussed some time ago, that just returns true or false based on wether the plugin is supported in this environment or not, for example, the linux plugin won't work unless the OS property is linux, and the AWT plugin (that doesn't exist yet) will only work if an awt class can be loaded.

Endolf

[TheBohemian]

my suggestions for replacement of net.java.games.input.Axis:
Feature
Control - taken from HID naming: http://www.osr.com/ddk/intinput/hidclass_4omf.htm

Controller.getAxis(Class identifierType)

looks strange to me. maybe using inheritance for that isnt the best idea...

what about:

1   2   3   4   5   6   7   8   9   10   11   12   13   14   15   16   17   18   19   20   21   22   23   24   25   26   27   28   29   30   31   32   33

public class Axis {  // not an interface to force single-inheritance model public static class Identifier {    public abstract Type getType();  }  // non-overrideable/non-user instanceable (type-safe enum) public final static class Type{    public static final BUTTON = new ...    public static final ABSOLUTE_AXIS = new ...    public static final RELATIVE_AXIS = new ...    } } // non-user or plugin-designer overrideable class public final class ButtonIdentifier extends Axis.Identifier {   // non-user instanceable  private ButtonIdentifier() { }   // hardcoded Axis.Type for all instances of this class  public Axis.Type getType() { return Axis.Type.BUTTON; }   // hardcoded constants for use by plugin developers/users  public static final ButtonIdentifier START = new ButtonIdentifier("Start");   // more constants ... } // more direct Axis.Identifier subclasses defining public final fields for // (rel/abs) axes, keys

(that would be a compromise to my former intention to separate Axis.Type and Axis.Identifier - here they play an intermixed role because of Axis.Identifier subclass instances referencing Axis.Type objects)

Controller now needs getAxis(Axis.Identifier ai) and getAxis(Axis.Type). This is more expressive than getAxis(Class clazz) where clazz could be anything from Hashtable.class, over Boolean.class to StrictMath.class. For the way I suggest a documentation only needs to say that all public fields of Axis.Type are valid arguments.

btw: replace all 'Axis' with 'Control' or 'Feature'. Control fits better to the standard (HID) but may cause confusion because of the already chosen Controller-class. What about:
Controller => InputDevice
Axis => Control
I know it may cause discomfort because of all that renaming but I think we agree on the fact that jinput's classnames were not chosen very advisedly.

I also want to get the ControllerEnvironment.isSupported()

let us discuss this here (where it was first mentioned):
http://www.java-gaming.org/cgi-bin/JGNetForums/YaBB.cgi?board=jinput;action=display;num=1077169583

[endolf]

Thats number 6 (or what I was thinking of anyway) on the list, so is that a vote for 4 and a vote for 6?

Endolf

[TheBohemian]

its kind of a combination of both. but unlike 6 there is not one huge list of constants: they are separated into several Axis.Identifier subclasses (ButtonIdentifier, ...).
the reason for the subclass solution is that it allows some kind of grouping which would not be possible when putting all constants into Axis.Identifier.

my main complaint with 4 is Controller.getAxis(Class clazz) ...
I am not sure whether it was a good idea to introduce Axis.Identifier.getType() .. hmmm.

what about the renaming thing?

[swpalmer]

Well, I'm still  against the Axis.Type thing.   The language does that for you... use the class heirarchy...  it's more flexible that way.

So controllers and Axis have types based on the class heirarchy.   if (controller instanceof Mouse) is simple and easy to read.  It tells you that you can use Mouse methods on that controller etc.  Maybe just interfaces are enough.

I'm thinking that I would be coding something like this:

1   2   3   4

if( controller instanceof Mouse ) {    Axis horizontal = ((Mouse)controller).getXAxis(); }

which works fine because we know that a Mouse has an X Axis and a Y Axis, even if the controller is actually an instance of TrackBall, so long as Mouse is a super class it all works out..

Of course I should probably shut up until I actually use the API seriously

1   2   3   4   5   6   7   8   9   10   11   12

if( horizontal instanceof AnalogAxis ) {   // analog stick? } if( horizontal instance of DigitalAxis ) {   // direction pad? } if( horizontal instanceof RelativeAxis ) {   // trackball/ mouse ball }

Games published by our own members! Check 'em out!

[rreyelts]

my main complaint with 4 is Controller.getAxis(Class clazz) ..

With JDK 1.5, you can specify a bounds on the Class type, so you can write this as,

1	<T extends Axis.Identifier> Axis Controller.getAxis( Class<T> identifierClass )

or whatever makes sense.

God bless,
-Toby Reyelts

[endolf]

Another suggetion on this. Hows about the Axis.Identifier.Button and Axis.Identifier.Button.X style id's as before, with a method called something like 'ofType' that takes an ID, and Axis.Identifier.Button is an implementation of Axis.Identifier too, when ofType is called on a specific button it checks if the passed Axis.Identifier is itself or if it's Axis.Identifier.Button. this solves the nasty method that takes a class

Comments?

Endolf

(I plan on looking at this soon, as I've fixed the linux plugin without re-writting chunks of it )

[TheBohemian]

This took some time until I understood what you are telling .. especially  because of the term:

or if it's Axis.Identifier.Button

You probably meant "or if its an instance of Axis.Identifier.Button". This would give us to the following implementation of "ofType":

1   2   3

public boolean ofType(Axis.Identifier id){ return id == this || id instanceof Axis.Identifier.Button; }

The problem I see here is that the user has to provide an instance of Axis.Identifier which as you said can be Axis.Identifier.Button.X or such. IMHO when the method is called it would look like this:

someAxisId.ofType(Axis.Identifier.Button.X)
which would be equivalent to:
someAxisId.ofType(Axis.Identifier.Button.ANY_OTHER).

the 'ofType' approach seems a little bit odd but the "Axis.Identifier.Button extends Axis.Identifier thing" looks good: It is similar to what swpalmer brought up already and would allow things like:

someAxisId instanceof Axis.Identifier.Button.

This would not be that ambigous although I am not a big fan of the idea that the nested-nested class inherits from its surrounding class ...
I know its possible but it reminds me of a C function returning an array of function pointers on functions returning arrays of integers and taking some amazing arguments ...

maybe we could have a separate ButtonIdentifier class which inherits Axis.Identifier but is not nested inside it.

[endolf]

Nope, no idea what I was talking about there , but hows about a Axis.Identifier.Button.ANY and Axis.Identifier.Axis.ANY etc, that can be passed in and checked for in the ofType method (of which the naming sux, but I couldn't think of anything else)

Endolf

[swpalmer]

I'm completely lost now...  I'm going to wait for someone to document how JInput plugins are supposed to work and how the  API is supposed to be used and then come back and RTFM.
As it is I don't see how JInput works in a reasonable cross-platform way.

[endolf]

As I see it, the Axis.Identifier is mainly going to be used to pass into Axis[] Controller.getAxis(Axis.Identifier) method, so the axis id's need  to be consistent across all plugins. The end user will say, hey, I want an X button from this controller that I know is a gamepad, or hey, I want the A key from this keyboard. And they will use those to check for changes to control the game play. Thats why we need to standardise it as I see it. The second part of the problem, is that a user might want to so 'I don't care which button I get, I need them all, so give me all the buttons on this controller', which is where Axis.Identifier.Button.Any comes in, as a special axis id that can be passed in to the getAxis method on a controller, to aid plugin development the new method on axis 'ofType' would be introduced so that the plugin developer can just loop through all the controller axis going if axis.ofType(id), add it to the list to return.

Hope that makes some sence

Cheers

Endolf

[TheBohemian]

maybe I can add my 2¤ cents experience of what the user might want because our game (freefodder.dev.java.net) can run with JInput as its input API (in CVS only atm ):

1)
It would be nice if I were able to access certain things directly: Like endolf said one might want a specific key on the keyboard. This is a good thing whenever fixed control bindings are needed. Eg. our ingame menu should always be controllable with cursor keys and the ESC key is important too because it acts as the key which aborts the auto-detection when auto-detecting controls.

As endolf said cross-plattform constants like Axis.Identifier would help here.

2)
IMHO for user-defined control bindings one needs something which can be saved to disk (or java.util.prefs) and restored at a later time. In FFMKI our 'solution' is to store a path of objects. Such a path describes where to find a certain Axis instance when beginning to search in the initial Controller array.

eg. I have an Axis instance and know it is accessible when calling

1   2   3   4   5   6

controllers[4].getControllers()[1].getAxis(16) (where controllers is the array of Controller instances returned from DefaultEnvironmentPlugin) the path which is saved to disk is: new ControllerNode(4, new ControllerNode(1, new AxisLeaf(16)));

(Now you know why I beg for 'flat' Controller instances which do not have subcontrollers itself.)

With unique identifiers one could store something that describes the input device (index?) and something that corresponds to the identifier (?).

endolf proposed:

Axis[] Controller.getAxis(Axis.Identifier)

I wonder why this method should return an array of Axis objects. I thought there would be only one instance per identifier or is this just a hack for the ANY identifier to return more than one?

Well, I give up insisting on Axis.Type (or something like that) in favor of getting the Axis.Identifier thing as easy as possible (and implemented ASAP).

Starting from endolf's initial choices I think option 2) is the way to go. (but adding different classes for each group of identifiers and not a long list like in 5).

[swpalmer]

As I see it, the Axis.Identifier is mainly going to be used to pass into Axis[] Controller.getAxis(Axis.Identifier) method...

Ok. sounds good. But I would return a single Axis not an array.

...which is where Axis.Identifier.Button.Any comes in, as a special axis id that can be passed in to the getAxis method on a controller, to aid plugin development the new method on axis 'ofType' would be introduced so that the plugin developer can just loop through all the controller axis going if axis.ofType(id), add it to the list to return.

I don't like the idea of Axis.Identifier.Button.Any the way it is described here.  Why not just enumerate the existing axis with an iterator or just have a getAllAxis() method that doesn't take an Identifier.

[endolf]

Hi
 Ok, if people don't want the Axis.Identifier.Button.Any style id's then it's simple, and in this case the getAxis(Axis.Identifier) will just return a single Axis.

So, the only thing then is do we do

Axis.Identifier.Button.X,
Axis.Identifier.Key.A and
Axis.Identifier.Axis.X

or

Axis.Identifier.Button_X,
Axis.Identifier.Key_A and
Axis.Identifier.Axis_X

I much prefer the first, even with the Axis.Identifier.Axis nasty name.

If we can sort this asap I'll start reworking the coreAPI and plugins.

Cheers

Endolf

[TheBohemian]

IMHO the first suggestion is the way to go but please rename net.java.games.input.Axis to something making more sense.

[endolf]

Any suggestions?

Endolf

[endolf]

Hows about component?

of course the problem here is that a sub controller is also a component, so it's still ambiguous , and I still think sub controllers are required, so they aint comming out . We could introduce a method getAllComponents(Component.Identifier) that returns all the axis, on this device and it's subdevices, that returns much like the getComponent(Component.Identifier) method, but searches it's sub controllers too if that would be an appropriate compromise?

Component.Identifier.Button.X
Component.Identifier.Axis.Z

Hmm

Endolf

[swpalmer]

I don't see any need to rename Axis and would definitely vote against it.  

As for the double "Axis" in the use of identifiers.. maybe try "Axis.Identifier.Generic.X" instead of "Axis.Identifier.Axis.X"

[TheBohemian]

my reason for renaming:

please find a new name for (net.java....)Axis which does not interfere with the name of a device feature. it is awful to distinguish between axis and Axis in documentation all the time.

my name suggestion:

my suggestions for replacement of net.java.games.input.Axis:
Feature
or
Control - taken from HID naming: http://www.osr.com/ddk/intinput/hidclass_4omf.htm

[swpalmer]

A Controller with Controls which can be either Buttons or Values.. makes sense if you want to follow HID conventions.

Though I find the HID terminology a bit wacky in some places - e.g. "value"

But I fail to see how this solves any problem.  Documentation will be no more clear with Controller and Control, control, etc.  Isn't the whole point to name it Axis exactly because that is the device feature???

[endolf]

Hi
 Right, for now the name stays as Axis, I was willing to go either way with it, based on what the community wanted, and we got one vote to change it and one to leave it, so for now, out of laziness, it stays . I'll do all the other Axis.Identifier changes. I have no way to test or even build the mac changes, although it should be just java changes, so can an osx user build and test it. I imagine it will be later on in the week before I get to start this as I'm in the process of moving flats.

Endolf

[TheBohemian]

agreed, although not happy - maybe we can address this again at a later time when there is a bigger user base for jinput.

@endolf:
could you please change the filenames of

• the native libraries
  
• the resulting jar files
  

because:
The current names (dxinput.dll, libjinput.so, linux.jar, HIDWrapper.jar, etc) are not consistent nor are they self-explanatory or expressive. I suggest something that makes it clear ...

• that it is a plugin for JInput (or its native library)
  
• which OS/hw hardware architecture it can run on
  
• what OS feature it uses or what input device it supports
  

[endolf]

Ok
 The coreAPI changes have been made (not in CVS yet), and I've updated DX8 and linux plugin. (again, not in CVS yet). I'm going to need some testers before I commit it, it's a significat (but not large) change, and it will break everything if it's not right . I've done my own testing on windows, but I'm in the process of moving house, so I don't have access to my linux dev box.

You can get the changes to test here, you will need the coreAPI and one of the plugins. Please let me know if it builds, if it runs, any errors, or if it all fails horribly, all reports are welcomed.

Cheers

Endolf

[TheBohemian]

Ok, I am going to test this.

[TheBohemian]

for the linux plugin I can say that it works although there are 4 abs axes which do not do anything - thats why in my plugin i just ignored them. please have a look at the minimum and maximum data the kernel provides. the problem with these axes is that they marked as being pressed constantly (-1) which is very bad for input autodetection.

another bad thing is that my pc speaker is still a non-usable but visible input device.

another small problem: Controller.getAxes() still exists but returns the Component array. apidoc is outdated too.