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.