Re: [AD] demo of new joystick API

[Peter Wang <tjaden@xxxxxxxxxx>]

Peter Wang wrote:

> I'll post about the new API later.


Now, in fact.  For those of you who know what I'm talking about, the API 
is the same as what I proposed on alleg-bigfive, with a few changes:

1. There is now an explicit driver initialisation function.  This was 
the idea from Matthew and Chris in the "about driver lists" thread.

2. The concept of "sticks", i.e. collections of related axes, from 
Allegro 4 is back in.  I had discarded them to make the API a bit easier 
to use, but now I think the loss in information was too much.

3. Button states were changed from bits (i.e. pressed or released) into 
integer values.  This is to support analogue buttons.  Neither the Linux 
nor DirectX drivers support analogue buttons yet, though.

--------------------------------------------

- Function: bool al_install_joystick_driver(void)

  Initialise the joystick driver.  Returns true if successful.

- Function: void al_uninstall_joystick_driver(void)

  Shuts down the joystick driver.  If no joystick driver is active, does nothing.

  This function automatically calls al_release_joystick() on any outstanding
  joystick handles (see below).  Also, it is automatically called when Allegro
  is shut down (so if you are lazy you don't need to call it).

- Function: int al_num_joysticks(void)

  Return the number of joystick devices that are available on the
  system.

  The system driver must be installed before this function is called.


- Function: AL_JOYSTICK *al_request_joystick(int joyn)

  Make a request for joystick number NUM on the system.  If
  successful a pointer to a joystick object is returned.  Otherwise
  NULL is returned.

  If the joystick was previously requested (and not yet released)
  then the returned object will be the same as in previous calls.

  The joystick driver must be installed before this function can be
  called.


- Function: void al_release_joystick(AL_JOYSTICK *joystick)

  Release a previously requested joystick object.  This will automatically
  unregister the joystick with any event queues.

  JOYSTICK may not be NULL.


- Function: int al_joystick_num_sticks(AL_JOYSTICK *joystick)

  Returns the number of "sticks" on a joystick.  A "stick" is one or
  more axes collected together.  e.g. the X and Y axes on a standard
  joystick would form a "stick".


- Function: int al_joystick_stick_flags(AL_JOYSTICK *joystick, int stick)

  Returns a bitfield containing information about a joystick "stick".
  The following flags are currently defined:

     AL_JOYFLAG_ANALOGUE -- the stick inherently outputs analogue
       data, e.g. the directional controls on a joystick.

     AL_JOYFLAG_DIGITAL -- the stick inherently outputs digital data,
       e.g. the POV hats on a joystick, or the directional controls
       on a gamepad.

  Note that usually both flags are set, so the information isn't
  particularly useful.

  AXIS must be non-negative.  If the axis specified doesn't actually
  exist on the device, this function returns 0.


- Function: const char *al_joystick_stick_name(AL_JOYSTICK *joystick, int stick)

   blah blah


- Function: int al_joystick_num_axes(AL_JOYSTICK *joystick, int stick)

   Returns the number of axes on a "stick", or 0 if that stick doesn't
   actually exist.


- Function: const char *al_joystick_axis_name(AL_JOYSTICK *joystick, int stick, int axis)

  Returns the name of a joystick axis as a string.  This string is
  not to be freed or modified.

  AXIS must be non-negative.  If the axis specified doesn't actually
  exist on the device, this function returns NULL.


- Function: int al_joystick_num_buttons(AL_JOYSTICK *joystick)

  Return the number of buttons on a joystick device.


- Function: const char *al_joystick_button_name(AL_JOYSTICK *joystick, int button)

  Returns the name of a joystick button as a string.  This string is
  not to be freed or modified.

  BUTTON must be non-negative.  If the button specified doesn't
  actually exist on the device, this function returns NULL.


- Type: AL_JOYSTATE

  This is a structure that is used to hold a "snapshot" of a
  joystick's axes and buttons at a particular instant.  It contains
  the following publically readable fields:

typedef struct AL_JOYSTATE
{
  struct
  {
     struct
     {
        int pos;                               /* -32767 to +32767 */
        int d;                                 /* -1, 0, +1 */
     } axis[_AL_MAX_JOYSTICK_AXES];
  } stick[_AL_MAX_JOYSTICK_STICKS];
  int button[_AL_MAX_JOYSTICK_BUTTONS];        /* 0 to 32767 */
} AL_JOYSTATE;

  The `stick[s].axis[a].pos' values are always in the range -32767 to 32767.

  The `stick[s].axis[a].d' values are always -1, 0 or +1.
  (This is supposed to be used as "digital" input.)

  `button[b]' values are always in the range 0 to 32767.  0 means the button
  is not pressed, whereas 32767 means the button is fully pressed (for analogue
  buttons).  For digital buttons, the values will always be 0 or 32767.


- Function: void al_get_joystick_state(AL_JOYSTICK *joystick,
       AL_JOYSTATE *ret_state)

  Save the state of the joystick specified at the time the function
  is called into the joystate pointed to by RET_STATE.  The previous
  state stored in RET_STATE is clobbered.

  RET_STATE may not be NULL.



The events that joysticks can emit are:
	AL_EVENT_JOYSTICK_AXIS
	AL_EVENT_JOYSTICK_BUTTON_DOWN
	AL_EVENT_JOYSTICK_BUTTON_UP

and the event structure looks like:


	typedef struct AL_JOYSTICK_EVENT
	{
		unsigned int type;
		AL_JOYSTICK *source;
		unsigned long timestamp;
		[...some internal stuff...]
		int stick;
  		int axis;
	   	int pos, d;
  		int button;
	} AL_JOYSTICK_EVENT;


--------------------------

Some issues:

1. "request" & "release".  I'm not sure what to call them.  
"acquire/release" was suggested but it sounds too much like 
acquire_bitmap/release_bitmap.

2. The name "stick" is so crappy.  I'd call them "axis groups" but 
that's too long.

3. The joystate structure is getting to be rather large now (I just 
checked: 320 bytes!).  Some of the int's could become short's to make 
copying joystates more efficient.  The button[] array could also be 
changed to an array of bytes.  Making both changes, the size is down to 
92 bytes.  All figures based on max sticks=5, max axes=3, max buttons=32.

4. As a simple optimisation, I'm thinking of adding a "timestamp" or 
"watermark" field to the joystate structure.  When you call 
al_get_joystick_state() the function would check that field in the 
joystate you give it to see if the joystate has already got the latest 
state of the joystick.  If so, it can avoid doing the copying.

Peter