sdlAddGamepadMapping function

int sdlAddGamepadMapping(
  1. String? mapping
)

Add support for gamepads that SDL is unaware of or change the binding of an existing gamepad.

The mapping string has the format "GUID,name,mapping", where GUID is the string value from SDL_GUIDToString(), name is the human readable string for the device and mappings are gamepad mappings to joystick ones. Under Windows there is a reserved GUID of "xinput" that covers all XInput devices. The mapping format for joystick is:

  • bX: a joystick button, index X
  • hX.Y: hat X with value Y
  • aX: axis X of the joystick

Buttons can be used as a gamepad axes and vice versa.

If a device with this GUID is already plugged in, SDL will generate an SDL_EVENT_GAMEPAD_ADDED event.

This string shows an example of a valid mapping for a gamepad:

"341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"

\param mapping the mapping string. \returns 1 if a new mapping is added, 0 if an existing mapping is updated, -1 on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

\since This function is available since SDL 3.1.3.

\sa SDL_AddGamepadMappingsFromFile \sa SDL_AddGamepadMappingsFromIO \sa SDL_GetGamepadMapping \sa SDL_GetGamepadMappingForGUID \sa SDL_HINT_GAMECONTROLLERCONFIG \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE \sa SDL_EVENT_GAMEPAD_ADDED

extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping)

Implementation

int sdlAddGamepadMapping(String? mapping) {
  final sdlAddGamepadMappingLookupFunction = libSdl3.lookupFunction<
      Int32 Function(Pointer<Utf8> mapping),
      int Function(Pointer<Utf8> mapping)>('SDL_AddGamepadMapping');
  final mappingPointer = mapping != null ? mapping.toNativeUtf8() : nullptr;
  final result = sdlAddGamepadMappingLookupFunction(mappingPointer);
  calloc.free(mappingPointer);
  return result;
}