Sponsoring The Perl Toolchain Summit 2025: Help make this important event another success Learn more

 / 
SDL-2.548
River stage two • 23 direct dependents • 25 total dependents
/ SDL::Joystick

NAME

SDL::Joystick -- SDL Bindings for the Joystick device

CATEGORY

Core, Joystick

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);

METHODS

num_joysticks


            

              
              
int SDL::Joystick::num_joysticks( void );

Counts and returns available joysticks.

name


            

              
              
string SDL::Joystick::name( index );

Get the implementation dependent name of joystick. The 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));
}

new


            

              
              
object SDL::Joystick->new( index );

Opens a joystick for use within SDL. The 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);
}

opened


            

              
              
int SDL::Joystick::opened( index );

Determines whether a joystick has already been opened within the application. index refers to the N'th joystick on the system.

Returns 1 if the joystick has been opened, or 0 if it has not.

index


            

              
              
int SDL::Joystick::index( object );

Returns the index of a given SDL_Joystick structure. See SDL::Joystick::new

num_axes


            

              
              
int SDL::Joystick::num_axes( object );

Return the number of axes available from a previously opened joystick. See SDL::Joystick::new

num_balls


            

              
              
int SDL::Joystick::num_balls( object );

Return the number of trackballs available from a previously opened joystick. See SDL::Joystick::new

num_hats


            

              
              
int SDL::Joystick::num_hats( object );

Gets the number of joystick hats from a previously opened joystick. See SDL::Joystick::new

num_buttons


            

              
              
int SDL::Joystick::num_buttons( object );

Gets the number of joystick buttons from a previously opened joystick. See SDL::Joystick::new

update


            

              
              
void SDL::Joystick::update();

Updates the state(position, buttons, etc.) of all open joysticks. If joystick events have been enabled with SDL::Joystick::event_state then this is called automatically in the event loop.

get_axis

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 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.

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);

get_hat


            

              
              
int SDL::Joystick::get_hat( object, int );

get_hat returns the current state of the given hat on the given joystick.

The current state is returned which is an OR'd combination of one or more of the following:

  • SDL_HAT_CENTERED

  • SDL_HAT_UP

  • SDL_HAT_RIGHT

  • SDL_HAT_DOWN

  • SDL_HAT_LEFT

  • SDL_HAT_RIGHTUP

  • SDL_HAT_RIGHTDOWN

  • SDL_HAT_LEFTUP

  • SDL_HAT_LEFTDOWN


            

              
              
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;

get_button


            

              
              
int SDL::Joystick::get_button( object, int );

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);

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 dx and 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);

close


            

              
              
void SDL::Joystick::close( object );

Closes a previously opened joystick. See SDL::Joystick::new


            

              
              
SDL::Joystick::close($joystick) if SDL::Joystick::opened(0);

AUTHORS

See "AUTHORS" in SDL.