What is SDL_Joystick and what is SDL_GameController? What are the relationships between the two?

What is the relationship between SDL_Joystick and SDL_GameController? These are the only things I know of right now:

• SDL_GameController and related functions are all part of a new API introduced in SDL2.
• SDL_GameController and related functions are built on top of the existing SDL_Joystick API.
• (Working Draft) You can obtain an instance of SDL_Joystick by calling on the function SDL_GameControllerGetJoystick() and passing in an instance of SDL_GameController.
• (Working Draft) You can obtain an instance of SDL_GameController first by calling on SDL_JoystickInstanceID() and passing in an instance of SDL_Joystick, then pass in the SDL_JoystickID to SDL_GameControllerFromInstanceID.

Even though SDL_Joystick and SDL_GameController are both interchangeable, it seems like SDL_GameController is here to replace and slowly succeed the SDL_Joystick.

Reason is, when polling for SDL_Event, the SDL_Event instance contains both the SDL_Event::jbutton and SDL_Event::cbutton structs, representing the SDL_Joystick buttons and SDL_GameController buttons, respectively. I guess I can use either one, or both, button events for the player controls.

I could be wrong here.

I would like to ask:

• What are the differences between SDL_Joystick and SDL_GameController?

• Is SDL_Joystick now referring to this controller?

  

  And the same for SDL_GameController?

  

• What are the advantages/disadvantages of using SDL_Joystick over SDL_GameController (and vice versa)?

First of all, SDL game controllers are the extension of SDL joysticks (for the scope of this answer when I say "controller" or "joystick" I mean SDL's implementation, not hardware device category in general). As wiki says:

This category contains functions for handling game controllers and for mapping joysticks to game controller semantics. This is built on top of the existing joystick API.

If you are running your game from Steam, the game controller mapping is automatically provided for your game.

Internally SDL uses joystick events and processes them to produce game controller events according to controller mapping. Hence one may say that joystick is lower level thing while game controller is a generalisation upon joysticks to produce more predictable/compatible (but more constrained) for games that wants gamepad-like input devices.

With game controller, you can program input for just one xbox-like controller thing, and SDL will make user's controller compatible with that (sometimes with the user's help - there are way too many different controllers, we can't possibly expect SDL to have configurations for all of them). Of course if controller is very different (or not controller at all - e.g. flight simulation sticks, wheels, etc.), that would be problematic.

Basically game controller provides xbox-like buttons and axes for user side, freeing application developer from the need to support controller remapping - as remapping is done in SDL itself. For some popular controllers SDL already have builtin mappings, and for others user-defined mapping can be loaded via environment variable.

There is also a configuration tool that simplifies remapping for end user, including exporting resulting configuration to said environment variable. Steam also have builtin configuration tool, which configuration it (supposedly - I've never used that) exports to SDL - essentially making users themselves responsible for configuring their controllers.