These functions are declared in the main Allegro header file:

#include <allegro5/allegro.h>

ALLEGRO_JOYSTICK

typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK;

This is an abstract data type representing a physical joystick.

ALLEGRO_JOYSTICK_STATE

typedef struct ALLEGRO_JOYSTICK_STATE ALLEGRO_JOYSTICK_STATE;

This is a structure that is used to hold a "snapshot" of a joystick's axes and buttons at a particular instant. All fields public and read-only.

struct {
      float axis[num_axes];             // -1.0 to 1.0 
} stick[num_sticks];
int button[num_buttons];                // 0 to 32767

ALLEGRO_JOYFLAGS

enum ALLEGRO_JOYFLAGS

ALLEGRO_JOYFLAG_DIGITAL - the stick provides digital input
ALLEGRO_JOYFLAG_ANALOGUE - the stick provides analogue input

(this enum is a holdover from the old API and may be removed)

al_install_joystick

bool al_install_joystick(void)

Install a joystick driver, returning true if successful. If a joystick driver was already installed, returns true immediately.

al_uninstall_joystick

void al_uninstall_joystick(void)

Uninstalls the active joystick driver. All outstanding ALLEGRO_JOYSTICK structures are invalidated. If no joystick driver was active, this function does nothing.

This function is automatically called when Allegro is shut down.

al_is_joystick_installed

bool al_is_joystick_installed(void)

Returns true if al_install_joystick was called successfully.

al_reconfigure_joysticks

bool al_reconfigure_joysticks(void)

Allegro is able to cope with users connecting and disconnected joystick devices on-the-fly. On existing platforms, the joystick event source will generate an event of type ALLEGRO_EVENT_JOYSTICK_CONFIGURATION when a device is plugged in or unplugged. In response, you should call al_reconfigure_joysticks.

Afterwards, the number returned by al_get_num_joysticks may be different, and the handles returned by al_get_joystick may be different or be ordered differently.

All ALLEGRO_JOYSTICK handles remain valid, but handles for disconnected devices become inactive: their states will no longer update, and al_get_joystick will not return the handle. Handles for devices which remain connected will continue to represent the same devices. Previously inactive handles may become active again, being reused to represent newly connected devices.

Returns true if the joystick configuration changed, otherwise returns false.

It is possible that on some systems, Allegro won't be able to generate ALLEGRO_EVENT_JOYSTICK_CONFIGURATION events. If your game has an input configuration screen or similar, you may wish to call al_reconfigure_joysticks when entering that screen.

al_get_num_joysticks

int al_get_num_joysticks(void)

Return the number of joysticks currently on the system (or potentially on the system). This number can change after al_reconfigure_joysticks is called, in order to support hotplugging.

Returns 0 if there is no joystick driver installed.

al_get_joystick

ALLEGRO_JOYSTICK * al_get_joystick(int num)

Get a handle for a joystick on the system. The number may be from 0 to al_get_num_joysticks-1. If successful a pointer to a joystick object is returned, which represents a physical device. Otherwise NULL is returned.

The handle and the index are only incidentally linked.

Joystick routines