1joy(3) Allegro manual joy(3)
2
6 joy - Global array of joystick state information. Allegro game program‐
7 ming library.
8
10 #include <allegro.h>
11 extern JOYSTICK_INFO joy[n];
14
16 Global array of joystick state information, which is updated by the
17 poll_joystick() function. Only the first num_joysticks elements will
18 contain meaningful information. The JOYSTICK_INFO structure is defined
19 as:
20 typedef struct JOYSTICK_INFO
22 {
23 int flags; - status flags for this
24 joystick
25 int num_sticks; - how many stick inputs?
26 int num_buttons; - how many buttons?
27 JOYSTICK_STICK_INFO stick[n]; - stick state information
28 JOYSTICK_BUTTON_INFO button[n]; - button state information
29 } JOYSTICK_INFO;
30 The button status is stored in the structure:
32 typedef struct JOYSTICK_BUTTON_INFO
34 {
35 int b; - boolean on/off flag
36 char *name; - description of this
37 button
38 } JOYSTICK_BUTTON_INFO;
39 You may wish to display the button names as part of an input configura‐
41 tion screen to let the user choose what game function will be performed
42 by each button, but in simpler situations you can safely assume that
43 the first two elements in the button array will always be the main
44 trigger controls.
45 Each joystick will provide one or more stick inputs, of varying types.
47 These can be digital controls which snap to specific positions (eg. a
48 gamepad controller, the coolie hat on a Flightstick Pro or Wingman
49 Extreme, or a normal joystick which hasn't yet been calibrated), or
50 they can be full analogue inputs with a smooth range of motion. Sticks
51 may also have different numbers of axes, for example a normal direc‐
52 tional control has two, but the Flightstick Pro throttle is only a sin‐
53 gle axis, and it is possible that the system could be extended in the
54 future to support full 3d controllers. A stick input is described by
55 the structure:
56 typedef struct JOYSTICK_STICK_INFO
58 {
59 int flags; - status flags for this
60 input
61 int num_axis; - how many axes do we
62 have? (note the misspelling)
63 JOYSTICK_AXIS_INFO axis[n]; - axis state information
64 char *name; - description of this
65 input
66 } JOYSTICK_STICK_INFO;
67 A single joystick may provide several different stick inputs, but you
69 can safely assume that the first element in the stick array will always
70 be the main directional controller.
71 Information about each of the stick axis is stored in the substructure:
73 typedef struct JOYSTICK_AXIS_INFO
75 {
76 int pos; - analogue axis position
77 int d1, d2; - digital axis position
78 char *name; - description of this axis
79 } JOYSTICK_AXIS_INFO;
80 This provides both analogue input in the pos field (ranging from -128
82 to 128 or from 0 to 255, depending on the type of the control), and
83 digital values in the d1 and d2 fields. For example, when describing
84 the X-axis position, the pos field will hold the horizontal position of
85 the joystick, d1 will be set if it is moved left, and d2 will be set if
86 it is moved right. Allegro will fill in all these values regardless of
87 whether it is using a digital or analogue joystick, emulating the pos
88 field for digital inputs by snapping it to the min, middle, and maximum
89 positions, and emulating the d1 and d2 values for an analogue stick by
90 comparing the current position with the centre point.
91 The joystick flags field may contain any combination of the bit flags:
93 JOYFLAG_DIGITAL This control is currently providing digital input.
95 JOYFLAG_ANALOGUE This control is currently providing analogue input.
97 JOYFLAG_CALIB_DIGITAL This control will be capable of providing digital
99 input once it has been calibrated, but is not doing this at the moment.
100 JOYFLAG_CALIB_ANALOGUE This control will be capable of providing ana‐
102 logue input once it has been calibrated, but is not doing this at the
103 moment.
104 JOYFLAG_CALIBRATE Indicates that this control needs to be calibrated.
106 Many devices require multiple calibration steps, so you should call the
107 calibrate_joystick() function from a loop until this flag is cleared.
108 JOYFLAG_SIGNED Indicates that the analogue axis position is in signed
110 format, ranging from -128 to 128. This is the case for all 2d direc‐
111 tional controls.
112 JOYFLAG_UNSIGNED Indicates that the analogue axis position is in
114 unsigned format, ranging from 0 to 255. This is the case for all 1d
115 throttle controls.
116 Note for people who spell funny: in case you don't like having to type
118 "analogue", there are some #define aliases in allegro/joystick.h that
119 will allow you to write "analog" instead.
120
123 install_joystick(3), poll_joystick(3), num_joysticks(3), calibrate_joy‐
124 stick(3), calibrate_joystick_name(3), exjoy(3)
125Allegro version 4.2.3 joy(3)