joy(3)

📦 version 4.4.3.1, in fedora 43, fedora 44

✨ NAME ✨

joy — okay so this is the global array of joystick state information, bestie. It's part of the Allegro game programming library, and the manual page is joy(3). It's giving "all your joystick tea in one place." 💖

🌸 SYNOPSIS 🌸

#include <allegro.h>

extern JOYSTICK_INFO joy[n];

🎀 DESCRIPTION 🎀

Okay so joy is a global array of joystick state information. The poll_joystick() function updates it. Only the first num_joysticks elements will contain meaningful information — the rest are just sitting there, not serving facts. 💅

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;

If you're putting together an input config screen, you might wanna show those button names so the user can pick which game function each button does. But in simpler situations, you can safely assume the first two elements in the button array are always the main trigger controls. Slay. 🎮

Every joystick is gonna give you one or more stick inputs, and they come in different types. Some are digital controls that 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). Others are full analogue inputs with a smooth range of motion. Sticks can also have different numbers of axes — like a normal directional control has two, but the Flightstick Pro throttle is only a single axis. And it's possible 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;

One joystick can have several different stick inputs, but you can safely assume the first element in the stick array is always the main directional controller. Main character energy, fr. 🌟

Each stick axis's info lives in this 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;

So you get analogue input in the pos field (ranging from -128 to 128 or from 0 to 255, depending on the type of the control), plus digital values in the d1 and d2 fields. Like, when you're describing the X-axis position, pos holds the horizontal position of the joystick, d1 gets set if it's moved left, and d2 gets set if it's moved right. Allegro fills in all these values whether it's using a digital or analogue joystick. For digital inputs, it emulates pos by snapping to the min, middle, and maximum positions. For an analogue stick, it emulates d1 and d2 by comparing the current position with the centre point. It's giving "we got you either way." 🔥

The joystick flags field can hold any combo of these bit flags:

  • JOYFLAG_DIGITAL — right now, this control is giving digital input.
  • JOYFLAG_ANALOGUE — right now, this control is giving analogue input.
  • JOYFLAG_CALIB_DIGITAL — this control will be able to give digital input once it's calibrated, but it's not doing that right now.
  • JOYFLAG_CALIB_ANALOGUE — this control will be able to give analogue input once it's calibrated, but it's not doing that right now.
  • JOYFLAG_CALIBRATE — this control needs to be calibrated. Lots of devices need multiple calibration steps, so you should call calibrate_joystick() in a loop until this flag is cleared.
  • JOYFLAG_SIGNED — the analogue axis position is in signed format, ranging from -128 to 128. This is true for all 2d directional controls.
  • JOYFLAG_UNSIGNED — the analogue axis position is in unsigned format, ranging from 0 to 255. This is true for all 1d throttle controls.

Note for people who spell funny: if you don't like typing "analogue", there are some #define aliases in allegro/joystick.h that let you write "analog" instead. You're welcome. 💅

🦋 SEE ALSO 🦋

Allegro version 4.4.3, joy(3) — that's the footer tea, bestie. No date on this one, just vibes. 💖✨

📦 where this page comes from