Joystick routines

These functions are declared in the main Allegro header file:

     #include <allegro5/allegro.h>

On Windows there are two joystick drivers, a DirectInput one and an Xinput one. If support for XInput was compiled in, then it can be enabled by calling al_set_config_value(al_get_system_config(), “joystick”, “driver”, “xinput”) before calling al_install_joystick, or by setting the same option in the allegro5.cfg configuration file. The Xinput and DirectInput drivers are mutually exclusive. The haptics subsystem will use the same driver as the joystick system does.

# ALLEGRO_JOYSTICK

    typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK;

Source Code

This is an abstract data type representing a physical joystick.

See also: al_get_joystick

Examples:

- ex_haptic.c
- ex_joystick_hotplugging.c
- ex_joystick_events.c

# ALLEGRO_JOYSTICK_STATE

    typedef struct ALLEGRO_JOYSTICK_STATE ALLEGRO_JOYSTICK_STATE;

Source Code

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

See also: al_get_joystick_state

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# ALLEGRO_JOYFLAGS

    enum ALLEGRO_JOYFLAGS

Source Code

- 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)

See also: al_get_joystick_stick_flags

# al_install_joystick

    bool al_install_joystick(void)

Source Code

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

See also: al_uninstall_joystick

Examples:

- ex_haptic.c
- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_uninstall_joystick

    void al_uninstall_joystick(void)

Source Code

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.

See also: al_install_joystick

# al_is_joystick_installed

    bool al_is_joystick_installed(void)

Source Code

Returns true if al_install_joystick was called successfully.

# al_reconfigure_joysticks

    bool al_reconfigure_joysticks(void)

Source Code

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.

See also: al_get_joystick_event_source, ALLEGRO_EVENT

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c
- ex_haptic2.cpp

# al_get_num_joysticks

    int al_get_num_joysticks(void)

Source Code

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.

See also: al_get_joystick, al_get_joystick_active

Examples:

- ex_haptic.c
- ex_joystick_hotplugging.c
- ex_haptic2.cpp

# al_get_joystick

    ALLEGRO_JOYSTICK * al_get_joystick(int num)

Source Code

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. After al_reconfigure_joysticks is called, al_get_joystick may return handles in a different order, and handles which represent disconnected devices will not be returned.

See also: al_get_num_joysticks, al_reconfigure_joysticks, al_get_joystick_active

Examples:

- ex_haptic.c
- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_release_joystick

    void al_release_joystick(ALLEGRO_JOYSTICK *joy)

Source Code

This function currently does nothing.

See also: al_get_joystick

Examples:

- ex_haptic.c

# al_get_joystick_active

    bool al_get_joystick_active(ALLEGRO_JOYSTICK *joy)

Source Code

Return if the joystick handle is “active”, i.e. in the current configuration, the handle represents some physical device plugged into the system. al_get_joystick returns active handles. After reconfiguration, active handles may become inactive, and vice versa.

See also: al_reconfigure_joysticks

Examples:

- ex_joystick_hotplugging.c

# al_get_joystick_name

    const char *al_get_joystick_name(ALLEGRO_JOYSTICK *joy)

Source Code

Return the name of the given joystick.

See also: al_get_joystick_stick_name, al_get_joystick_axis_name, al_get_joystick_button_name

Examples:

- ex_haptic.c
- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_stick_name

    const char *al_get_joystick_stick_name(ALLEGRO_JOYSTICK *joy, int stick)

Source Code

Return the name of the given “stick”. If the stick doesn’t exist, NULL is returned.

See also: al_get_joystick_axis_name, al_get_joystick_num_sticks

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_axis_name

    const char *al_get_joystick_axis_name(ALLEGRO_JOYSTICK *joy, int stick, int axis)

Source Code

Return the name of the given axis. If the axis doesn’t exist, NULL is returned. Indices begin from 0.

See also: al_get_joystick_stick_name, al_get_joystick_num_axes

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_button_name

    const char *al_get_joystick_button_name(ALLEGRO_JOYSTICK *joy, int button)

Source Code

Return the name of the given button. If the button doesn’t exist, NULL is returned. Indices begin from 0.

See also: al_get_joystick_stick_name, al_get_joystick_axis_name, al_get_joystick_num_buttons

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_stick_flags

    int al_get_joystick_stick_flags(ALLEGRO_JOYSTICK *joy, int stick)

Source Code

Return the flags of the given “stick”. If the stick doesn’t exist, NULL is returned. Indices begin from 0.

See also: ALLEGRO_JOYFLAGS

# al_get_joystick_num_sticks

    int al_get_joystick_num_sticks(ALLEGRO_JOYSTICK *joy)

Source Code

Return the number of “sticks” on the given joystick. A stick has one or more axes.

See also: al_get_joystick_num_axes, al_get_joystick_num_buttons

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_num_axes

    int al_get_joystick_num_axes(ALLEGRO_JOYSTICK *joy, int stick)

Source Code

Return the number of axes on the given “stick”. If the stick doesn’t exist, 0 is returned.

See also: al_get_joystick_num_sticks

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_num_buttons

    int al_get_joystick_num_buttons(ALLEGRO_JOYSTICK *joy)

Source Code

Return the number of buttons on the joystick.

See also: al_get_joystick_num_sticks

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_state

    void al_get_joystick_state(ALLEGRO_JOYSTICK *joy, ALLEGRO_JOYSTICK_STATE *ret_state)

Source Code

Get the current joystick state.

See also: ALLEGRO_JOYSTICK_STATE, al_get_joystick_num_buttons, al_get_joystick_num_axes

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c

# al_get_joystick_event_source

    ALLEGRO_EVENT_SOURCE *al_get_joystick_event_source(void)

Source Code

Returns the global joystick event source. All joystick events are generated by this event source.

Examples:

- ex_joystick_hotplugging.c
- ex_joystick_events.c
- ex_haptic2.cpp

Allegro version 5.2.8 - Last updated: 2022-06-06 01:10:00 UTC