e14743d1 |
1 | /* |
2 | SDL - Simple DirectMedia Layer |
3 | Copyright (C) 1997-2009 Sam Lantinga |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Lesser General Public |
7 | License as published by the Free Software Foundation; either |
8 | version 2.1 of the License, or (at your option) any later version. |
9 | |
10 | This library is distributed in the hope that it will be useful, |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | Lesser General Public License for more details. |
14 | |
15 | You should have received a copy of the GNU Lesser General Public |
16 | License along with this library; if not, write to the Free Software |
17 | Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
18 | |
19 | Sam Lantinga |
20 | slouken@libsdl.org |
21 | */ |
22 | |
23 | /** @file SDL_joystick.h |
24 | * Include file for SDL joystick event handling |
25 | */ |
26 | |
27 | #ifndef _SDL_joystick_h |
28 | #define _SDL_joystick_h |
29 | |
30 | #include "SDL_stdinc.h" |
31 | #include "SDL_error.h" |
32 | |
33 | #include "begin_code.h" |
34 | /* Set up for C function definitions, even when using C++ */ |
35 | #ifdef __cplusplus |
36 | extern "C" { |
37 | #endif |
38 | |
39 | /** @file SDL_joystick.h |
40 | * @note In order to use these functions, SDL_Init() must have been called |
41 | * with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system |
42 | * for joysticks, and load appropriate drivers. |
43 | */ |
44 | |
45 | /** The joystick structure used to identify an SDL joystick */ |
46 | struct _SDL_Joystick; |
47 | typedef struct _SDL_Joystick SDL_Joystick; |
48 | |
49 | /* Function prototypes */ |
50 | /** |
51 | * Count the number of joysticks attached to the system |
52 | */ |
53 | extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); |
54 | |
55 | /** |
56 | * Get the implementation dependent name of a joystick. |
57 | * |
58 | * This can be called before any joysticks are opened. |
59 | * If no name can be found, this function returns NULL. |
60 | */ |
61 | extern DECLSPEC const char * SDLCALL SDL_JoystickName(int device_index); |
62 | |
63 | /** |
64 | * Open a joystick for use. |
65 | * |
66 | * @param[in] device_index |
67 | * The index passed as an argument refers to |
68 | * the N'th joystick on the system. This index is the value which will |
69 | * identify this joystick in future joystick events. |
70 | * |
71 | * @return This function returns a joystick identifier, or NULL if an error occurred. |
72 | */ |
73 | extern DECLSPEC SDL_Joystick * SDLCALL SDL_JoystickOpen(int device_index); |
74 | |
75 | /** |
76 | * Returns 1 if the joystick has been opened, or 0 if it has not. |
77 | */ |
78 | extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index); |
79 | |
80 | /** |
81 | * Get the device index of an opened joystick. |
82 | */ |
83 | extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick *joystick); |
84 | |
85 | /** |
86 | * Get the number of general axis controls on a joystick |
87 | */ |
88 | extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(SDL_Joystick *joystick); |
89 | |
90 | /** |
91 | * Get the number of trackballs on a joystick |
92 | * |
93 | * Joystick trackballs have only relative motion events associated |
94 | * with them and their state cannot be polled. |
95 | */ |
96 | extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(SDL_Joystick *joystick); |
97 | |
98 | /** |
99 | * Get the number of POV hats on a joystick |
100 | */ |
101 | extern DECLSPEC int SDLCALL SDL_JoystickNumHats(SDL_Joystick *joystick); |
102 | |
103 | /** |
104 | * Get the number of buttons on a joystick |
105 | */ |
106 | extern DECLSPEC int SDLCALL SDL_JoystickNumButtons(SDL_Joystick *joystick); |
107 | |
108 | /** |
109 | * Update the current state of the open joysticks. |
110 | * |
111 | * This is called automatically by the event loop if any joystick |
112 | * events are enabled. |
113 | */ |
114 | extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); |
115 | |
116 | /** |
117 | * Enable/disable joystick event polling. |
118 | * |
119 | * If joystick events are disabled, you must call SDL_JoystickUpdate() |
120 | * yourself and check the state of the joystick when you want joystick |
121 | * information. |
122 | * |
123 | * @param[in] state The state can be one of SDL_QUERY, SDL_ENABLE or SDL_IGNORE. |
124 | */ |
125 | extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); |
126 | |
127 | /** |
128 | * Get the current state of an axis control on a joystick |
129 | * |
130 | * @param[in] axis The axis indices start at index 0. |
131 | * |
132 | * @return The state is a value ranging from -32768 to 32767. |
133 | */ |
134 | extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, int axis); |
135 | |
136 | /** |
137 | * @name Hat Positions |
138 | * The return value of SDL_JoystickGetHat() is one of the following positions: |
139 | */ |
140 | /*@{*/ |
141 | #define SDL_HAT_CENTERED 0x00 |
142 | #define SDL_HAT_UP 0x01 |
143 | #define SDL_HAT_RIGHT 0x02 |
144 | #define SDL_HAT_DOWN 0x04 |
145 | #define SDL_HAT_LEFT 0x08 |
146 | #define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) |
147 | #define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) |
148 | #define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) |
149 | #define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) |
150 | /*@}*/ |
151 | |
152 | /** |
153 | * Get the current state of a POV hat on a joystick |
154 | * |
155 | * @param[in] hat The hat indices start at index 0. |
156 | */ |
157 | extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, int hat); |
158 | |
159 | /** |
160 | * Get the ball axis change since the last poll |
161 | * |
162 | * @param[in] ball The ball indices start at index 0. |
163 | * |
164 | * @return This returns 0, or -1 if you passed it invalid parameters. |
165 | */ |
166 | extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); |
167 | |
168 | /** |
169 | * Get the current state of a button on a joystick |
170 | * |
171 | * @param[in] button The button indices start at index 0. |
172 | */ |
173 | extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, int button); |
174 | |
175 | /** |
176 | * Close a joystick previously opened with SDL_JoystickOpen() |
177 | */ |
178 | extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick); |
179 | |
180 | |
181 | /* Ends C function definitions when using C++ */ |
182 | #ifdef __cplusplus |
183 | } |
184 | #endif |
185 | #include "close_code.h" |
186 | |
187 | #endif /* _SDL_joystick_h */ |