/lib/pods/SDL/Joystick.pod
http://github.com/PerlGameDev/SDL · Unknown · 245 lines · 139 code · 106 blank · 0 comment · 0 complexity · 8dcea05e7247a503d824f53dbac10257 MD5 · raw file
- =pod
- =head1 NAME
- SDL::Joystick -- SDL Bindings for the Joystick device
- =head1 CATEGORY
- Core, Joystick
- =head1 SYNOPSIS
- use SDL;
- use SDL::Joystick;
-
- SDL::init_sub_system(SDL_INIT_JOYSTICK);
-
- die('no joystick found') unless(SDL::Joystick::num_joysticks());
-
- my $joystick = SDL::Joystick->new(0);
-
- =head1 METHODS
- =head2 num_joysticks
- int SDL::Joystick::num_joysticks( void );
- Counts and returns available joysticks.
- =head2 name
- string SDL::Joystick::name( index );
- Get the implementation dependent name of joystick. The C<index> parameter refers to the N'th joystick on the system.
- my $num_joysticks = SDL::Joystick::num_joysticks();
- printf("%d joysticks found\n", $num_joysticks);
- for($i = 0; $i < $num_joysticks; $i++)
- {
- printf("%s\n", SDL::Joystick::name($i));
- }
- =head2 new
- object SDL::Joystick->new( index );
- Opens a joystick for use within SDL. The C<index> refers to the N'th joystick in the system.
- A joystick must be opened before it can be used.
- # Initialize the joystick subsystem
- SDL::init_sub_system(SDL_INIT_JOYSTICK);
-
- # Check for joystick
- if(SDL::Joystick::num_joysticks() > 0)
- {
- # Open joystick
- my $joystick = SDL::Joystick->new(0);
-
- if($joystick)
- {
- printf("Opened Joystick 0\n");
- printf("Name: %s\n", SDL::Joystick::name(0));
- printf("Number of Axes: %d\n", SDL::Joystick::num_axes($joystick));
- printf("Number of Buttons: %d\n", SDL::Joystick::num_buttons($joystick));
- printf("Number of Balls: %d\n", SDL::Joystick::num_balls($joystick));
- }
- else
- {
- printf("Couldn't open Joystick 0\n");
- }
-
- # Close if opened
- SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
- }
- =head2 opened
- int SDL::Joystick::opened( index );
- Determines whether a joystick has already been opened within the application. C<index> refers to the N'th joystick on the system.
- Returns 1 if the joystick has been opened, or 0 if it has not.
- =head2 index
- int SDL::Joystick::index( object );
- Returns the C<index> of a given C<SDL_Joystick> structure. See L<SDL::Joystick::new|/new>
- =head2 num_axes
- int SDL::Joystick::num_axes( object );
- Return the number of axes available from a previously opened joystick. See L<SDL::Joystick::new|/new>
- =head2 num_balls
- int SDL::Joystick::num_balls( object );
- Return the number of trackballs available from a previously opened joystick. See L<SDL::Joystick::new|/new>
- =head2 num_hats
- int SDL::Joystick::num_hats( object );
- Gets the number of joystick hats from a previously opened joystick. See L<SDL::Joystick::new|/new>
- =head2 num_buttons
- int SDL::Joystick::num_buttons( object );
- Gets the number of joystick buttons from a previously opened joystick. See L<SDL::Joystick::new|/new>
- =head2 update
- void SDL::Joystick::update();
- Updates the state(position, buttons, etc.) of all open joysticks. If joystick events have been enabled
- with C<SDL::Joystick::event_state> then this is called automatically in the event loop.
- =head2 get_axis
- C<get_axis> returns the current state of the given axis on the given joystick.
- On most modern joysticks the X axis is usually represented by axis 0 and the Y axis by axis 1.
- The value returned by C<get_axis> is a signed integer (-32768 to 32767) representing the current position of the axis,
- it may be necessary to impose certain tolerances on these values to account for jitter.
- B<Note>: Some joysticks use axes 2 and 3 for extra buttons.
- Returns a 16-bit signed integer representing the current position of the axis.
- my $joystick = SDL::Joystick->new(0);
- my $x_move = SDL::Joystick::get_axis($joystick, 0);
- my $y_move = SDL::Joystick::get_axis($joystick, 1);
- =head2 get_hat
- int SDL::Joystick::get_hat( object, int );
- C<get_hat> returns the current state of the given C<hat> on the given C<joystick>.
- The current state is returned which is an OR'd combination of one or more of the following:
- =over 4
- =item *
- C<SDL_HAT_CENTERED>
- =item *
- C<SDL_HAT_UP>
- =item *
- C<SDL_HAT_RIGHT>
- =item *
- C<SDL_HAT_DOWN>
- =item *
- C<SDL_HAT_LEFT>
- =item *
- C<SDL_HAT_RIGHTUP>
- =item *
- C<SDL_HAT_RIGHTDOWN>
- =item *
- C<SDL_HAT_LEFTUP>
- =item *
- C<SDL_HAT_LEFTDOWN>
- =back
- my $joystick = SDL::Joystick->new(0);
-
- my $position = SDL::Joystick::get_hat($joystick, 0);
-
- print("hat is in position UP\n") if $position & SDL_HAT_UP;
- =head2 get_button
- int SDL::Joystick::get_button( object, int );
- C<get_button> returns the current state of the given button on the given joystick.
- Returns 1 if the button is pressed. Otherwise, 0.
- my $joystick = SDL::Joystick->new(0);
-
- my $num_buttons = SDL::Joystick::num_buttons($joystick);
-
- for(my $i = 0; $i < $num_buttons; $i++)
- {
- printf("button %d is %s\n", $i, SDL::Joystick::get_button($joystick, $i) ? 'pressed' : 'not pressed');
- }
-
- SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
- =head2 get_ball
- int SDL::Joystick::get_ball(SDL_Joystick $joystick, int $ball, int $dx, int $dy);
- Get the ball axis change.
- Trackballs 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>.
- Returns 0 on success or -1 on failure
- my $delta_x = 0;
- my $delta_y = 0;
- my $joystick = SDL::Joystick->new(0);
-
- SDL::Joystick::update();
-
- printf("TrackBall Read Error!\n") if(SDL::JoystickGetBall($joystick, 0, $delta_x, $delta_y) == -1);
- printf("Trackball Delta- X:%d, Y:%d\n", delta_x, delta_y);
- =head2 close
- void SDL::Joystick::close( object );
- Closes a previously opened joystick. See L<SDL::Joystick::new|/new>
- SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);
- =head1 AUTHORS
- See L<SDL/AUTHORS>.
- =cut