/lib/pods/SDL/Joystick.pod

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