Awesome
SDL_JoystickButtonNames
Description
A small library to get joystick button names and colors, to be used with SDL2
SDL2's game controller API works by assuming an "ideal gamepad" - the Xbox 360 controller - and all button names will be translated to the same layout as that gamepad. That is, the bottom face button will always be called "A", and the right face button "B", even if you're not using the Xbox 360 controller.
What if you want to display button names that match the real controller's? What about the button colors too?
This library intends to provide this missing functionality, by providing a database of controller button names and colors, given an SDL_Joystick
and an SDL_GameControllerButton
.
The library looks up the controller's buttons using a combination of its GUID and its joystick name.
Shoutout
Author "cxong": https://github.com/cxong/SDL_JoystickButtonNames
How it works
Given the following code:
SDL_Joystick *joy;
char name[256];
Uint8 r, g, b;
SDLJBN_GetButtonNameAndColor(joy, SDL_CONTROLLER_BUTTON_A, name, &r, &g, &b);
printf("Button A is %s with color rgb(%d,%d,%d)\n", name, r, g, b);
If you have an Xbox 360 controller connected, this will print:
Button A is A with color rgb(96,160,0)
But if you have a Logitech Dual Action
Then the code will print:
Button A is 2 with color rgb(244,244,244)
Running the examples
-
Clone this repo
-
Use CMake to configure and compile the examples:
cd SDL_JoystickButtonNames/examples cmake . make
-
Make sure you have joysticks plugged in, and run the example
./find_all_joy_buttons
-
You should now have a file called
out.html
, which when you open up you'll see diagrams. You should see some output too. For example for my gamepad:
Platform: Linux
Read 1 new mappings
Button: 2 [R: 244, G: 244, B 244], Button: 3 [R: 244, G: 244, B 244], Button: 1 [R: 244, G: 244, B 244], Button: 4 [R: 244, G: 244, B 244], Button: 9 [R: 64, G: 64, B 64], Button: Guide [R: 128, G: 176, B 0], Button: 10 [R: 64, G: 64, B 64], Button: Left Stick [R: 64, G: 64, B 64], Button: Right Stick [R: 64, G: 64, B 64], Button: 5 [R: 64, G: 64, B 64], Button: 6 [R: 64, G: 64, B 64], Button: D-pad Up [R: 64, G: 64, B 64], Button: D-pad Down [R: 64, G: 64, B 64], Button: D-pad Left [R: 64, G: 64, B 64], Button: D-pad Right [R: 64, G: 64, B 64], Axis: Left Stick X [R: 64, G: 64, B 64], Axis: Left Stick Y [R: 64, G: 64, B 64], Axis: Right Stick X [R: 64, G: 64, B 64], Axis: Right Stick Y [R: 64, G: 64, B 64], Axis: 7 [R: 64, G: 64, B 64], Axis: 8 [R: 64, G: 64, B 64],
In second example, when you run:
./minimal
You should see something like this:
Logitech Logitech Dual Action
BUTTONS
On joystick 1, button X is "X" with color rgb(0,96,208)
On joystick 1, button A is "A" with color rgb(96,160,0)
On joystick 1, button B is "B" with color rgb(240,0,0)
On joystick 1, button Y is "Y" with color rgb(255,160,0)
On joystick 1, button Back is "Back" with color rgb(224,224,224)
On joystick 1, button Start is "Start" with color rgb(224,224,224)
On joystick 1, left shoulder is "LB" with color rgb(224,224,224)
On joystick 1, left shoulder is "RB" with color rgb(224,224,224)
On joystick 1, left stick is "Left Stick" with color rgb(96,128,128)
On joystick 1, right stick is "Right Stick" with color rgb(96,128,128)
On joystick 1, button Up is "D-pad Up" with color rgb(96,128,128)
On joystick 1, button Down is "D-pad Down" with color rgb(96,128,128)
On joystick 1, button Left is "D-pad Left" with color rgb(96,128,128)
On joystick 1, button Right is "D-pad Right" with color rgb(96,128,128)
AXES
On joystick 1, left trigger is "LT" with color rgb(224,224,224)
On joystick 1, right trigger is "RT" with color rgb(224,224,224)
On joystick 1, axis X of left trigger is "Left Stick X" with color rgb(96,128,128)
On joystick 1, axis Y of left trigger is "Left Stick Y" with color rgb(96,128,128)
On joystick 1, axis X of right trigger is "Right Stick X" with color rgb(96,128,128)
On joystick 1, axis Y of right trigger is "Right Stick Y" with color rgb(96,128,128)
You can execute another file with no information about RGB too:
./minimalWithoutRGB
result:
Logitech Logitech Dual Action
BUTTONS
On joystick 1, button X is "X"On joystick 1, button A is "A"
On joystick 1, button B is "B"
On joystick 1, button Y is "Y"
On joystick 1, button Back is "Back"
On joystick 1, button Start is "Start"
On joystick 1, left shoulder is "LB"
On joystick 1, left shoulder is "RB"
On joystick 1, left stick is "Left Stick"
On joystick 1, right stick is "Right Stick"
On joystick 1, button Up is "D-pad Up"
On joystick 1, button Down is "D-pad Down"
On joystick 1, button Left is "D-pad Left"
On joystick 1, button Right is "D-pad Right"
AXES
On joystick 1, left trigger is "LT"
On joystick 1, right trigger is "RT"
On joystick 1, axis X of left trigger is "Left Stick X"
On joystick 1, axis Y of left trigger is "Left Stick Y"
On joystick 1, axis X of right trigger is "Right Stick X"
On joystick 1, axis Y of right trigger is "Right Stick Y"
However it would be better to execute this, whenever you just want to know Vendor ID, Product ID, Product Version or GUID:
./checkInfo
in my case the result would be:
Platform: Linux
Name: Logitech Logitech Dual Action
GUID: 030000006d04000016c2000011010000
Vendor: 1133 (0x046d)
Product: 49686 (0xc216)
Product Version: 273 (0x0111)
Getting started
- Include the library in your SDL2 + CMake project, or if you are using a different build system, include
SDL_joystickbuttonnames.c
andSDL_joystickbuttonnames.h
in your project- This includes
db.h
, which is generated fromdb.h.cmake
- This includes
- In your code:
- Call
SDLJBN_Init()
during startup - (Recommended) take a copy of
gamecontrollerbuttondb.txt
and include it in your game's data directory, and load it during runtime usingSDLJBN_AddMappingsFromFile()
. Remember to find line about your gamepad ingamecontrollerdb.txt
and overwrite line under a name of your system ingamecontrollerbuttondb.txt
. (This method will be changed to automatic method) - Once you have detected and opened
SDL_Joystick
devices, get button names and colors usingSDLJBN_GetButtonNameAndColor()
- You can also get axis names and colors using
SDLJBN_GetAxisNameAndColor()
- Call
- Check out
examples/minimal.c
for a minimal code example
Database
If you have a joystick that is not included in this project's database (gamecontrollerbuttondb.txt
), please let me know. Include your OS, the joystick's SDL2 GUID, and a picture of the joystick, so it can be added to the database.