---
name: "SDL::Joystick"
section: "3pm"
platform: "linux"
package: "libsdl-perl"
version: "2.548-5+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/SDL::Joystick"
---

# SDL::Joystick(3pm)

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