Chapter 9. Joystick

Table of Contents
SDL_NumJoysticks -- Count available joysticks.
SDL_JoystickName -- Get joystick name.
SDL_JoystickOpen -- Opens a joystick for use.
SDL_JoystickOpened -- Determine if a joystick has been opened
SDL_JoystickIndex -- Get the index of an SDL_Joystick.
SDL_JoystickNumAxes -- Get the number of joystick axes
SDL_JoystickNumBalls -- Get the number of joystick trackballs
SDL_JoystickNumHats -- Get the number of joystick hats
SDL_JoystickNumButtons -- Get the number of joysitck buttons
SDL_JoystickUpdate -- Updates the state of all joysticks
SDL_JoystickGetAxis -- Get the current state of an axis
SDL_JoystickGetHat -- Get the current state of a joystick hat
SDL_JoystickGetButton -- Get the current state of a given button on a given joystick
SDL_JoystickGetBall -- Get relative trackball motion
SDL_JoystickClose -- Closes a previously opened joystick

Joysticks, and other similar input devices, have a very strong role in game playing and SDL provides comprehensive support for them. Axes, Buttons, POV Hats and trackballs are all supported.

Joystick support is initialized by passed the SDL_INIT_JOYSTICK flag to SDL_Init. Once initilized joysticks must be opened using SDL_JoystickOpen.

While using the functions describe in this secton may seem like the best way to access and read from joysticks, in most cases they aren't. Ideally joysticks should be read using the event system. To enable this, you must set the joystick event processing state with SDL_JoystickEventState. Joysticks must be opened before they can be used of course.

Note: If you are not handling the joystick via the event queue then you must explicitly request a joystick update by calling SDL_JoystickUpdate.

Note: Force Feedback is not yet supported. Sam (slouken@libsdl.org) is soliciting suggestions from people with force-feedback experience on the best way to design the API.