NAME

       joy - Global array of joystick state information. Allegro game programming library.

SYNOPSIS

       #include <allegro.h>

       extern JOYSTICK_INFO joy[n];

DESCRIPTION

       Global  array  of  joystick  state  information,  which  is updated by the poll_joystick()
       function. Only the first num_joysticks elements will contain meaningful  information.  The
       JOYSTICK_INFO structure is defined as:

          typedef struct JOYSTICK_INFO
          {
             int flags;                       - status flags for this
                                                joystick
             int num_sticks;                  - how many stick inputs?
             int num_buttons;                 - how many buttons?
             JOYSTICK_STICK_INFO stick[n];    - stick state information
             JOYSTICK_BUTTON_INFO button[n];  - button state information
          } JOYSTICK_INFO;

       The button status is stored in the structure:

          typedef struct JOYSTICK_BUTTON_INFO
          {
             int b;                           - boolean on/off flag
             char *name;                      - description of this
                                                button
          } JOYSTICK_BUTTON_INFO;

       You  may  wish to display the button names as part of an input configuration screen to let
       the user choose what game function will be  performed  by  each  button,  but  in  simpler
       situations  you  can  safely  assume  that the first two elements in the button array will
       always be the main trigger controls.

       Each joystick will provide one or more stick inputs,  of  varying  types.   These  can  be
       digital  controls  which  snap to specific positions (eg. a gamepad controller, the coolie
       hat on a Flightstick Pro or Wingman Extreme, or a normal joystick which  hasn't  yet  been
       calibrated), or they can be full analogue inputs with a smooth range of motion. Sticks may
       also have different numbers of axes, for example a normal directional control has two, but
       the  Flightstick  Pro  throttle  is only a single axis, and it is possible that the system
       could be extended in the future to support full 3d controllers. A stick input is described
       by the structure:

          typedef struct JOYSTICK_STICK_INFO
          {
             int flags;                       - status flags for this
                                                input
             int num_axis;                    - how many axes do we
                                                have? (note the misspelling)
             JOYSTICK_AXIS_INFO axis[n];      - axis state information
             char *name;                      - description of this
                                                input
          } JOYSTICK_STICK_INFO;

       A  single  joystick  may provide several different stick inputs, but you can safely assume
       that the first element in the stick array will always be the main directional controller.

       Information about each of the stick axis is stored in the substructure:

          typedef struct JOYSTICK_AXIS_INFO
          {
             int pos;                         - analogue axis position
             int d1, d2;                      - digital axis position
             char *name;                      - description of this axis
          } JOYSTICK_AXIS_INFO;

       This provides both analogue input in the pos field (ranging from -128 to 128 or from 0  to
       255,  depending  on  the type of the control), and digital values in the d1 and d2 fields.
       For example, when describing the X-axis position, the pos field will hold  the  horizontal
       position  of the joystick, d1 will be set if it is moved left, and d2 will be set if it is
       moved right. Allegro will fill in all these values regardless of whether  it  is  using  a
       digital or analogue joystick, emulating the pos field for digital inputs by snapping it to
       the min, middle, and maximum positions, and emulating the d1 and d2 values for an analogue
       stick by comparing the current position with the centre point.

       The joystick flags field may contain any combination of the bit flags:

       JOYFLAG_DIGITAL This control is currently providing digital input.

       JOYFLAG_ANALOGUE This control is currently providing analogue input.

       JOYFLAG_CALIB_DIGITAL  This control will be capable of providing digital input once it has
       been calibrated, but is not doing this at the moment.

       JOYFLAG_CALIB_ANALOGUE This control will be capable of providing analogue  input  once  it
       has been calibrated, but is not doing this at the moment.

       JOYFLAG_CALIBRATE Indicates that this control needs to be calibrated. Many devices require
       multiple calibration steps, so you should call the calibrate_joystick()  function  from  a
       loop until this flag is cleared.

       JOYFLAG_SIGNED Indicates that the analogue axis position is in signed format, ranging from
       -128 to 128. This is the case for all 2d directional controls.

       JOYFLAG_UNSIGNED Indicates that the analogue axis position is in unsigned format,  ranging
       from 0 to 255. This is the case for all 1d throttle controls.

       Note  for  people who spell funny: in case you don't like having to type "analogue", there
       are some #define aliases in allegro/joystick.h that  will  allow  you  to  write  "analog"
       instead.

SEE ALSO

       install_joystick(3alleg4),         poll_joystick(3alleg4),         num_joysticks(3alleg4),
       calibrate_joystick(3alleg4), calibrate_joystick_name(3alleg4), exjoy(3alleg4)