9da305afe8c75518fbcab1776097caff800b783b
[sdlgit/SDL-Site.git] / pages / SDL-Joystick.html-inc
1 <div class="pod">
2 <!-- INDEX START -->
3 <h3 id="TOP">Index</h3>
4
5 <ul><li><a href="#NAME">NAME</a></li>
6 <li><a href="#CATEGORY">CATEGORY</a></li>
7 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
8 <li><a href="#METHODS">METHODS</a>
9 <ul><li><a href="#num_joysticks">num_joysticks</a></li>
10 <li><a href="#name">name</a></li>
11 <li><a href="#open">open</a></li>
12 <li><a href="#opened">opened</a></li>
13 <li><a href="#index">index</a></li>
14 <li><a href="#num_axes">num_axes</a></li>
15 <li><a href="#num_balls">num_balls</a></li>
16 <li><a href="#num_hats">num_hats</a></li>
17 <li><a href="#num_buttons">num_buttons</a></li>
18 <li><a href="#update">update</a></li>
19 <li><a href="#get_axis">get_axis</a></li>
20 <li><a href="#get_hat">get_hat</a></li>
21 <li><a href="#get_button">get_button</a></li>
22 <li><a href="#get_ball">get_ball</a></li>
23 <li><a href="#close">close</a>
24 </li>
25 </ul>
26 </li>
27 </ul><hr />
28 <!-- INDEX END -->
29
30 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
31 <div id="NAME_CONTENT">
32 <p>SDL::Joystick -- SDL Bindings for the Joystick device</p>
33
34 </div>
35 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
36 <div id="CATEGORY_CONTENT">
37 <p>Core, Joystick</p>
38
39 </div>
40 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
41 <div id="SYNOPSIS_CONTENT">
42 <pre> use SDL;
43  use SDL::Joystick;
44
45  SDL::init_sub_system(SDL_INIT_JOYSTICK);
46
47  die('no joystick found') unless(SDL::Joystick::num_joysticks());
48
49  my $joystick = SDL::Joystick-&gt;new(0);
50
51 </pre>
52
53 </div>
54 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
55 <div id="METHODS_CONTENT">
56
57 </div>
58 <h2 id="num_joysticks">num_joysticks</h2>
59 <div id="num_joysticks_CONTENT">
60 <pre> int SDL::Joystick::num_joysticks( void );
61
62 </pre>
63 <p>Counts and returns available joysticks.</p>
64
65 </div>
66 <h2 id="name">name</h2>
67 <div id="name_CONTENT">
68 <pre> string SDL::Joystick::name( index );
69
70 </pre>
71 <p>Get the implementation dependent name of joystick. The <code>index</code> parameter refers to the N'th joystick on the system. </p>
72 <pre> my $num_joysticks = SDL::Joystick::num_joysticks();
73
74  printf(&quot;%d joysticks found\n&quot;, $num_joysticks);
75
76  for($i = 0; i &lt; $num_joysticks; $i++)
77  {
78      printf(&quot;%s\n&quot;, SDL::Joystick::name($i));
79  }
80
81 </pre>
82
83 </div>
84 <h2 id="open">open</h2>
85 <div id="open_CONTENT">
86 <pre> object SDL::Joystick::open( index );
87
88 </pre>
89 <p>Opens a joystick for use within SDL. The <code>index</code> refers to the N'th joystick in the system. 
90 A joystick must be opened before it can be used.</p>
91 <pre> # Initialize the joystick subsystem
92  SDL::init_sub_system(SDL_INIT_JOYSTICK);
93
94  # Check for joystick
95  if(SDL::Joystick::num_joysticks() &gt; 0)
96  {
97      # Open joystick
98      my $joystick = SDL::Joystick::open(0);
99
100      if($joystick)
101      {
102          printf(&quot;Opened Joystick 0\n&quot;);
103          printf(&quot;Name: %s\n&quot;,              SDL::Joystick::name(0));
104          printf(&quot;Number of Axes: %d\n&quot;,    SDL::Joystick::num_axes($joystick));
105          printf(&quot;Number of Buttons: %d\n&quot;, SDL::Joystick::num_buttons($joystick));
106          printf(&quot;Number of Balls: %d\n&quot;,   SDL::Joystick::num_balls($joystick));
107      }
108      else
109      {
110          printf(&quot;Couldn't open Joystick 0\n&quot;);
111      }
112
113      # Close if opened
114      SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
115  }
116
117 </pre>
118
119 </div>
120 <h2 id="opened">opened</h2>
121 <div id="opened_CONTENT">
122 <pre> int SDL::Joystick::opened( index );
123
124 </pre>
125 <p>Determines whether a joystick has already been opened within the application. <code>index</code> refers to the N'th joystick on the system.</p>
126 <p>Returns 1 if the joystick has been opened, or 0 if it has not.</p>
127
128 </div>
129 <h2 id="index">index</h2>
130 <div id="index_CONTENT">
131 <pre> int SDL::Joystick::index( object );
132
133 </pre>
134 <p>Returns the <code>index</code> of a given <code>SDL_Joystick</code> structure. See <a href="#open">SDL::Joystick::open</a></p>
135
136 </div>
137 <h2 id="num_axes">num_axes</h2>
138 <div id="num_axes_CONTENT">
139 <pre> int SDL::Joystick::num_axes( object );
140
141 </pre>
142 <p>Return the number of axes available from a previously opened joystick. See <a href="#open">SDL::Joystick::open</a></p>
143
144 </div>
145 <h2 id="num_balls">num_balls</h2>
146 <div id="num_balls_CONTENT">
147 <pre> int SDL::Joystick::num_balls( object );
148
149 </pre>
150 <p>Return the number of trackballs available from a previously opened joystick. See <a href="#open">SDL::Joystick::open</a></p>
151
152 </div>
153 <h2 id="num_hats">num_hats</h2>
154 <div id="num_hats_CONTENT">
155 <pre> int SDL::Joystick::num_hats( object );
156
157 </pre>
158 <p>Gets the number of joystick hats from a previously opened joystick. See <a href="#open">SDL::Joystick::open</a></p>
159
160 </div>
161 <h2 id="num_buttons">num_buttons</h2>
162 <div id="num_buttons_CONTENT">
163 <pre> int SDL::Joystick::num_buttons( object );
164
165 </pre>
166 <p>Gets the number of joystick buttons from a previously opened joystick. See <a href="/SDL-Joystick::open.html">SDL::Joystick::open</a></p>
167
168 </div>
169 <h2 id="update">update</h2>
170 <div id="update_CONTENT">
171 <pre> void SDL::Joystick::update();
172
173 </pre>
174 <p>Updates the state(position, buttons, etc.) of all open joysticks. If joystick events have been enabled 
175 with <code>SDL::Joystick::event_state</code> then this is called automatically in the event loop. </p>
176
177 </div>
178 <h2 id="get_axis">get_axis</h2>
179 <div id="get_axis_CONTENT">
180 <p><code>get_axis</code> returns the current state of the given axis on the given joystick.</p>
181 <p>On most modern joysticks the X axis is usually represented by axis 0 and the Y axis by axis 1. 
182 The value returned by <code>get_axis</code> is a signed integer (-32768 to 32767) representing the current position of the axis, 
183 it may be necessary to impose certain tolerances on these values to account for jitter.</p>
184 <p><strong>Note</strong>: Some joysticks use axes 2 and 3 for extra buttons. </p>
185 <p>Returns a 16-bit signed integer representing the current position of the axis.</p>
186 <pre> my $joystick = SDL::Joystick::open(0);
187
188  my $x_move   = SDL::Joystick::get_axis($joystick, 0);
189  my $y_move   = SDL::Joystick::get_axis($joystick, 1);
190
191 </pre>
192
193 </div>
194 <h2 id="get_hat">get_hat</h2>
195 <div id="get_hat_CONTENT">
196 <pre> int SDL::Joystick::get_hat( object, int );
197
198 </pre>
199 <p><code>get_hat</code> returns the current state of the given <code>hat</code> on the given <code>joystick</code>. </p>
200 <p>The current state is returned which is an OR'd combination of one or more of the following:</p>
201 <ul>
202                 <li><code>SDL_HAT_CENTERED</code>       </li>
203                 <li><code>SDL_HAT_UP</code>     </li>
204                 <li><code>SDL_HAT_RIGHT</code>  </li>
205                 <li><code>SDL_HAT_DOWN</code>   </li>
206                 <li><code>SDL_HAT_LEFT</code>   </li>
207                 <li><code>SDL_HAT_RIGHTUP</code>        </li>
208                 <li><code>SDL_HAT_RIGHTDOWN</code>      </li>
209                 <li><code>SDL_HAT_LEFTUP</code> </li>
210                 <li><code>SDL_HAT_LEFTDOWN</code></li>
211 </ul>
212
213 <pre> my $joystick = SDL::Joystick::open(0);
214
215  my $position = SDL::Joystick::get_hat($joystick, 0);
216
217  print(&quot;hat is in position UP\n&quot;) if $position &amp; SDL_HAT_UP;
218
219 </pre>
220
221 </div>
222 <h2 id="get_button">get_button</h2>
223 <div id="get_button_CONTENT">
224 <pre> int SDL::Joystick::get_button( object, int );
225
226 </pre>
227 <p><code>get_button</code> returns the current state of the given button on the given joystick.</p>
228 <p>Returns 1 if the button is pressed. Otherwise, 0. </p>
229 <pre> my $joystick    = SDL::Joystick::open(0);
230
231  my $num_buttons = SDL::Joystick::num_buttons($joystick);
232
233  for(my $i = 0; $i &lt; $num_buttons; $i++)
234  {
235      printf(&quot;button %d is %s\n&quot;, $i, SDL::Joystick::get_button($joystick, $i) ? 'pressed' : 'not pressed');
236  }
237
238  SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
239
240 </pre>
241
242 </div>
243 <h2 id="get_ball">get_ball</h2>
244 <div id="get_ball_CONTENT">
245 <pre> int SDL::Joystick::get_ball(SDL_Joystick $joystick, int $ball, int $dx, int $dy);
246
247 </pre>
248 <p>Get the ball axis change.</p>
249 <p>Trackballs can only return relative motion since the last call to SDL::Joystick::get_ball, these motion deltas are placed into <code>dx</code> and <code>dy</code>.</p>
250 <p>Returns 0 on success or -1 on failure</p>
251 <pre> my $delta_x  = 0;
252  my $delta_y  = 0;
253  my $joystick = SDL::Joystick::open(0);
254
255  SDL::Joystick::update();
256
257  printf(&quot;TrackBall Read Error!\n&quot;) if(SDL::JoystickGetBall($joystick, 0, $delta_x, $delta_y) == -1);
258  printf(&quot;Trackball Delta- X:%d, Y:%d\n&quot;, delta_x, delta_y);
259
260 </pre>
261
262 </div>
263 <h2 id="close">close</h2>
264 <div id="close_CONTENT">
265 <pre> void SDL::Joystick::close( object );
266
267 </pre>
268 <p>Closes a previously opened joystick. See <a href="#open">SDL::Joystick::open</a></p>
269 <pre> SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
270
271 </pre>
272
273 </div>
274 </div>