SDL Joystick mapping

From wiki.gp2x.org

Contents

Events

In SDL and PyGame, every action produces button events (SDL_JOYBUTTONUP, SDL_JOYBUTTONDOWN), including the joystick - not joystick events. Each action is counted as a button press. Press and release of each control triggers SDL_JOYBUTTONDOWN and SDL_JOYBUTTONUP respectively.

You need to track the events yourself; SDL gives events on button presses/releases instead of continuous events when a button or the joystick is not in it's normal state. That is, there is no event meaning "the button is still down". This can be taken care of by acting upon an event until another action is in the queue.

=== Joystick ===
Visual Mapping

The joystick has eight directions. If you hold it along a minor diagonal and another direction (e.g. between left and left-up), you can get two separate button events for left and left-up. See Suggested Joystick Configurations for mapping between joystick directions.

Joystick Direction Event Value
Up 0
Down 4
Left 2
Right 6
Up-Left 1
Up-Right 7
Down-Left 3
Down-Right 5
Stick "Click" 18

Other Buttons

It is highly recommended that when mapping actions to your game, application or emulator, you should refer to the Common User Interface Recommendations.

Button Event Value
A 12
B 13
Y 14
X 15
R 10
L 11
Start 8
Select 9
Vol - 17
Vol + 16

Note: These mappings are assuming you are using Guyfawkes' library. X/Y and L/R may be the other way around. See the talk page.

Implementation

  • When you call SDL_Init, make sure you include SDL_INIT_JOYSTICK.
  • You must call SDL_JoystickOpen(0)
  • In your event loop, you should check for SDL_JOYBUTTONDOWN and SDL_JOYBUTTONUP events
  • You should compare event.jbutton.button to the constants below
  • You may sometimes get an inital SDL_JOYBUTTONDOWN event for the button used to launch the application (usually the B button). This can be intermittent depending on the execution time before running SDL_Init() and how long the button is pressed for

Examples

C

/* initialize */
SDL_Init(SDL_INIT_JOYSTICK|SDL_INIT_VIDEO);
SDL_JoystickOpen(0);

SDL_Event event;

/* event loop */
while(SDL_PollEvent(&event))
{
    switch(event.type)
    {
        case SDL_JOYBUTTONDOWN:
            switch(event.jbutton.button)
            {
                case GP2X_BUTTON_X: /* X pressed */
                    printf("X was pressed\n");
                    break;
                case GP2X_BUTTON_L: /* L pressed */
                    printf("L was pressed\n");
                    break;
            }
            
            break;
        case SDL_JOYBUTTONUP:
            switch(event.jbutton.button)
            {
                case GP2X_BUTTON_X: /* X released */
                    printf("X was released\n");
                    break;
                case GP2X_BUTTON_L: /* L released */
                    printf("L was released\n");
                    break;
            }
            
            break;
    }
}

Python

import gp2x

# initialize
num_joysticks = pygame.joystick.get_count()
if num_joysticks > 0:
    stick = pygame.joystick.Joystick(0)
    stick.init() # now we will receive events for the joystick

# event loop
while 1:
    event = pygame.event.poll()
    print "got event"
    print repr(event)
    if event.type == pygame.NOEVENT:
        print "No more events for now"
        break
    if event.type == pygame.QUIT:
        print "got quit event"
        running = 0
    elif event.type == pygame.JOYBUTTONDOWN:
        if event.button == gp2x.BUTTON_X:
            print "X pressed"
        elif event.button == gp2x.BUTTON_Y:
            print "Y pressed"
        else:
            print "unknown button pushed"
    elif event.type == pygame.JOYBUTTONUP:
        if event.button == gp2x.BUTTON_X:
            print "X released"
        elif event.button == gp2x.BUTTON_Y:
            print "Y released"
        else:
            print "unknown button released"

Headers

C

#define GP2X_BUTTON_UP              (0)
#define GP2X_BUTTON_DOWN            (4)
#define GP2X_BUTTON_LEFT            (2)
#define GP2X_BUTTON_RIGHT           (6)
#define GP2X_BUTTON_UPLEFT          (1)
#define GP2X_BUTTON_UPRIGHT         (7)
#define GP2X_BUTTON_DOWNLEFT        (3)
#define GP2X_BUTTON_DOWNRIGHT       (5)
#define GP2X_BUTTON_CLICK           (18)
#define GP2X_BUTTON_A               (12)
#define GP2X_BUTTON_B               (13)
#define GP2X_BUTTON_Y               (14)
#define GP2X_BUTTON_X               (15)
#define GP2X_BUTTON_L               (10)
#define GP2X_BUTTON_R               (11)
#define GP2X_BUTTON_START           (8)
#define GP2X_BUTTON_SELECT          (9)
#define GP2X_BUTTON_VOLUP           (16)
#define GP2X_BUTTON_VOLDOWN         (17)

NOTE: for dynamically linked Open2x applications and recent versions of SDL, the following mapping should be used instead.

#define GP2X_BUTTON_UP              (0)
#define GP2X_BUTTON_DOWN            (4)
#define GP2X_BUTTON_LEFT            (2)
#define GP2X_BUTTON_RIGHT           (6)
#define GP2X_BUTTON_UPLEFT          (1)
#define GP2X_BUTTON_UPRIGHT         (7)
#define GP2X_BUTTON_DOWNLEFT        (3)
#define GP2X_BUTTON_DOWNRIGHT       (5)
#define GP2X_BUTTON_CLICK           (18)
#define GP2X_BUTTON_A               (12)
#define GP2X_BUTTON_B               (13)
#define GP2X_BUTTON_X               (14)
#define GP2X_BUTTON_Y               (15)
#define GP2X_BUTTON_L               (10)
#define GP2X_BUTTON_R               (11)
#define GP2X_BUTTON_START           (8)
#define GP2X_BUTTON_SELECT          (9)
#define GP2X_BUTTON_VOLUP           (16)
#define GP2X_BUTTON_VOLDOWN         (17)

Python

# GP2X joystick button mappings
BUTTON_UP            = 0
BUTTON_DOWN          = 4
BUTTON_LEFT          = 2
BUTTON_RIGHT         = 6
BUTTON_UPLEFT        = 1
BUTTON_UPRIGHT       = 7
BUTTON_DOWNLEFT      = 3
BUTTON_DOWNRIGHT     = 5
BUTTON_CLICK         = 18
BUTTON_A             = 12
BUTTON_B             = 13
BUTTON_X             = 14
BUTTON_Y             = 15
BUTTON_L             = 10
BUTTON_R             = 11
BUTTON_START         = 8 
BUTTON_SELECT        = 9
BUTTON_VOLUP         = 16
BUTTON_VOLDOWN       = 17
Personal tools