Add "gamepad" support.

A gamepad has a stereotyped arrangement of buttons and sticks/axes that
remains consistent across platforms. Hardware differences are handled by
parsing SDL's community-sourced database.

See #1533

addons/acodec/dumb.c

@@ -6,6 +6,7 @@
 #define _FILE_OFFSET_BITS 64
 #include <ctype.h>
 
+#define ALLEGRO_INTERNAL_UNSTABLE
 #include "allegro5/allegro.h"
 #include "allegro5/allegro_acodec.h"
 #include "allegro5/allegro_audio.h"

addons/acodec/flac.c

@@ -10,8 +10,6 @@
 #include "allegro5/allegro_audio.h"
 #include "allegro5/internal/aintern.h"
 #include "allegro5/internal/aintern_audio.h"
-#include "allegro5/internal/aintern_exitfunc.h"
-#include "allegro5/internal/aintern_system.h"
 #include "acodec.h"
 #include "helper.h"
 

addons/acodec/helper.c

@@ -2,7 +2,6 @@
 #include "allegro5/allegro_audio.h"
 #include "allegro5/internal/aintern.h"
 #include "allegro5/internal/aintern_audio.h"
-#include "allegro5/internal/aintern_system.h"
 #include "helper.h"
 
 void _al_acodec_start_feed_thread(ALLEGRO_AUDIO_STREAM *stream)

addons/acodec/mp3.c

@@ -10,8 +10,6 @@
 #include "allegro5/allegro_audio.h"
 #include "allegro5/internal/aintern.h"
 #include "allegro5/internal/aintern_audio.h"
-#include "allegro5/internal/aintern_exitfunc.h"
-#include "allegro5/internal/aintern_system.h"
 #include "acodec.h"
 #include "helper.h"
 

addons/acodec/ogg.c

@@ -10,8 +10,6 @@
 #include "allegro5/allegro_audio.h"
 #include "allegro5/internal/aintern.h"
 #include "allegro5/internal/aintern_audio.h"
-#include "allegro5/internal/aintern_exitfunc.h"
-#include "allegro5/internal/aintern_system.h"
 #include "acodec.h"
 #include "helper.h"
 

addons/acodec/openmpt.c

@@ -3,6 +3,7 @@
  * author: Pavel Sountsov
  */
 
+#define ALLEGRO_INTERNAL_UNSTABLE
 #define _FILE_OFFSET_BITS 64
 #include <ctype.h>
 

addons/acodec/opus.c

@@ -9,8 +9,6 @@
 #include "allegro5/allegro_audio.h"
 #include "allegro5/internal/aintern.h"
 #include "allegro5/internal/aintern_audio.h"
-#include "allegro5/internal/aintern_exitfunc.h"
-#include "allegro5/internal/aintern_system.h"
 #include "acodec.h"
 #include "helper.h"
 

addons/audio/dsound.cpp

@@ -32,6 +32,8 @@ const IID GUID_NULL = { 0, 0, 0, { 0, 0, 0, 0, 0, 0, 0, 0 } };
 
 static const IID _al_IID_IDirectSoundBuffer8 =        { 0x6825a449, 0x7524, 0x4d82, { 0x92, 0x0f, 0x50, 0xe3, 0x6a, 0xb3, 0xab, 0x1e } };
 static const IID _al_IID_IDirectSoundCaptureBuffer8 = { 0x00990df4, 0x0dbb, 0x4872, { 0x83, 0x3e, 0x6d, 0x30, 0x3e, 0x80, 0xae, 0xb6 } };
+
+#define ALLEGRO_INTERNAL_UNSTABLE
 #include "allegro5/allegro.h"
 
 extern "C" {

addons/font/fontbmp.c

@@ -16,6 +16,8 @@
  */
 
 
+#define ALLEGRO_INTERNAL_UNSTABLE
+
 #include <string.h>
 
 #include "allegro5/allegro.h"

addons/font/text.c

@@ -20,6 +20,8 @@
  */
 
 
+#define ALLEGRO_INTERNAL_UNSTABLE
+
 #include <math.h>
 #include <ctype.h>
 #include "allegro5/allegro.h"

addons/image/android.c

@@ -1,3 +1,4 @@
+#define ALLEGRO_INTERNAL_UNSTABLE
 #include "allegro5/allegro.h"
 #include "allegro5/allegro_image.h"
 #include "allegro5/internal/aintern_android.h"

addons/native_dialog/android_dialog.c

@@ -13,6 +13,7 @@
  *      By Alexandre Martins.
  */
 
+#define ALLEGRO_INTERNAL_UNSTABLE
 #include "allegro5/allegro.h"
 #include "allegro5/allegro_native_dialog.h"
 #include "allegro5/internal/aintern_android.h"

addons/native_dialog/dialog.c

@@ -1,3 +1,5 @@
+#define ALLEGRO_INTERNAL_UNSTABLE
+
 #include "allegro5/allegro.h"
 #include "allegro5/allegro_native_dialog.h"
 #include "allegro5/internal/aintern_dtor.h"

addons/native_dialog/menu.c

@@ -1,3 +1,5 @@
+#define ALLEGRO_INTERNAL_UNSTABLE
+
 #include "allegro5/allegro.h"
 #include "allegro5/allegro_native_dialog.h"
 #include "allegro5/internal/aintern_native_dialog.h"

addons/native_dialog/osx_dialog.m

@@ -4,6 +4,8 @@
 #if MAC_OS_X_VERSION_MIN_REQUIRED >= 110000
 #include <UniformTypeIdentifiers/UniformTypeIdentifiers.h>
 #endif
+
+#define ALLEGRO_INTERNAL_UNSTABLE
 #include "allegro5/allegro.h"
 #include "allegro5/allegro_native_dialog.h"
 #include "allegro5/internal/aintern_native_dialog.h"

addons/native_dialog/textlog.c

@@ -1,3 +1,5 @@
+#define ALLEGRO_INTERNAL_UNSTABLE
+
 #include <stdarg.h>
 #include <stdio.h>
 #include "allegro5/allegro.h"

addons/native_dialog/win_dialog.c

@@ -8,6 +8,7 @@
  *
  */
 
+#define ALLEGRO_INTERNAL_UNSTABLE
 #include "allegro5/allegro.h"
 #include "allegro5/allegro_native_dialog.h"
 #include "allegro5/internal/aintern.h"

addons/video/video.c

@@ -37,6 +37,7 @@
  * - Additional drivers. Also redo the API a bit so not everything
  *   has to be done by the driver.
  */
+#define ALLEGRO_INTERNAL_UNSTABLE
 
 #include "allegro5/allegro5.h"
 #include "allegro5/allegro_video.h"

allegro5.cfg

@@ -146,7 +146,7 @@ webp_quality_level = lossless
 # joysticks and force feedback joysticks. Xinput is the more modern
 # system, but DirectInput has more force feedback capabilities for older
 # joysticks.
-driver=XINPUT
+driver=
 
 # Windows: Use this to force an XInput DLL version, example "3" forces
 # xinput1_3.dll. By default, the latest version is used.

cmake/FileList.cmake

@@ -134,7 +134,6 @@ set(ALLEGRO_SRC_X_FILES
 
 set(ALLEGRO_SRC_MACOSX_FILES
     src/macosx/hidjoy.m
-    src/macosx/hidjoy-10.4.m
     src/macosx/hidman.m
     src/macosx/keybd.m
     src/macosx/qzmouse.m

docs/src/refman/joystick.txt

@@ -6,13 +6,11 @@ These functions are declared in the main Allegro header file:
  #include <allegro5/allegro.h>
 ~~~~
 
-On Windows there are two joystick drivers, a DirectInput one and an Xinput
-one. If support for XInput was compiled in, then it can be enabled by
-calling al_set_config_value(al_get_system_config(), "joystick", "driver",
-"xinput") before calling al_install_joystick, or by setting the same
-option in the allegro5.cfg configuration file. The Xinput and DirectInput
-drivers are mutually exclusive. The haptics subsystem will use the
-same driver as the joystick system does.
+As of version 5.2.11, Allegro provides two types of joysticks. If a joystick is
+recognized, with the help of a mapping file specified by
+`al_set_joystick_mappings`, then it is treated as a gamepad, will buttons and
+axes behaving in a cross-platform consistent manner.
+
 
 ## API: ALLEGRO_JOYSTICK
 
@@ -40,10 +38,66 @@ See also: [al_get_joystick_state]
 * ALLEGRO_JOYFLAG_DIGITAL  - the stick provides digital input
 * ALLEGRO_JOYFLAG_ANALOGUE - the stick provides analogue input
 
-(this enum is a holdover from the old API and may be removed)
-
 See also: [al_get_joystick_stick_flags]
 
+## API: ALLEGRO_JOYSTICK_TYPE
+
+* ALLEGRO_JOYSTICK_TYPE_UNKNOWN - unknown joystick type
+* ALLEGRO_JOYSTICK_TYPE_GAMEPAD - a gamepad. This buttons and sticks have
+  semantics specified by `ALLEGRO_GAMEPAD_BUTTON` and `ALLEGRO_GAMEPAD_STICK`.
+
+Since: 5.2.11
+
+See also: [al_set_joystick_mappings], [ALLEGRO_GAMEPAD_BUTTON], [ALLEGRO_GAMEPAD_STICK]
+
+> *[Unstable API]:* New API.
+
+## API: ALLEGRO_JOYSTICK_GUID
+
+A GUID associated with a joystick.
+
+Since: 5.2.11
+
+See also: [al_set_joystick_guid]
+
+> *[Unstable API]:* New API.
+
+## API: ALLEGRO_GAMEPAD_BUTTON
+
+* ALLEGRO_GAMEPAD_BUTTON_A - A button
+* ALLEGRO_GAMEPAD_BUTTON_B - B button
+* ALLEGRO_GAMEPAD_BUTTON_X - X button
+* ALLEGRO_GAMEPAD_BUTTON_Y - Y button
+* ALLEGRO_GAMEPAD_BUTTON_LEFT_SHOULDER - left shoulder button
+* ALLEGRO_GAMEPAD_BUTTON_RIGHT_SHOULDER - right shoulder button
+* ALLEGRO_GAMEPAD_BUTTON_BACK - back button (also called select sometimes)
+* ALLEGRO_GAMEPAD_BUTTON_START - start button
+* ALLEGRO_GAMEPAD_BUTTON_GUIDE - guide/home button (this sometimes is
+  intercepted on the OS level, so do not rely on being able to handle it)
+* ALLEGRO_GAMEPAD_BUTTON_LEFT_THUMB - button on the left thumb stick
+* ALLEGRO_GAMEPAD_BUTTON_RIGHT_THUMB - button on the right thumb stick
+
+Since: 5.2.11
+
+See also: [al_set_joystick_mappings], [ALLEGRO_JOYSTICK_TYPE]
+
+> *[Unstable API]:* New API.
+
+## API: ALLEGRO_GAMEPAD_STICK
+
+* ALLEGRO_GAMEPAD_STICK_DPAD - D-pad stick, it has the
+  `ALLEGRO_JOYFLAG_DIGITAL` set. It has two axes.
+* ALLEGRO_GAMEPAD_STICK_LEFT_THUMB - Left thumb stick. It has two axes.
+* ALLEGRO_GAMEPAD_STICK_RIGHT_THUMB - Right thumb stick. It has two axes.
+* ALLEGRO_GAMEPAD_STICK_LEFT_TRIGGER - Left trigger. It has one axis, ranging from 0 to 1.
+* ALLEGRO_GAMEPAD_STICK_RIGHT_TRIGGER - Right trigger. It has one axis, ranging from 0 to 1.
+
+Since: 5.2.11
+
+See also: [al_set_joystick_mappings], [ALLEGRO_JOYSTICK_TYPE]
+
+> *[Unstable API]:* New API.
+
 ## API: al_install_joystick
 
 Install a joystick driver, returning true if successful.  If a
@@ -202,3 +256,54 @@ See also: [ALLEGRO_JOYSTICK_STATE], [al_get_joystick_num_buttons],
 Returns the global joystick event source.  All
 [joystick events][ALLEGRO_EVENT_JOYSTICK_AXIS] are generated by
 this event source.
+
+## API: al_get_joystick_type
+
+Returns the joystick type. If the type is `ALLEGRO_JOYSTICK_TYPE_GAMEPAD`, then
+you can use the [ALLEGRO_GAMEPAD_BUTTON] and [ALLEGRO_GAMEPAD_STICK] to
+interpret the button/stick events and states more easily. Joystick types will
+typically be unknown unless [al_set_joystick_mappings] is called first.
+
+Since: 5.2.11
+
+See also: [al_set_joystick_mappings], [ALLEGRO_JOYSTICK_TYPE]
+
+> *[Unstable API]:* New API.
+
+## API: al_get_joystick_guid
+
+Returns the joystick GUID, that can be used to distinguish joysticks hardware.
+Despite the name, these do not need to be actually unique to do the limitations
+of the system that computes them. This can be all zeros when unknown.
+
+Since: 5.2.11
+
+See also: [ALLEGRO_JOYSTICK_GUID]
+
+> *[Unstable API]:* New API.
+
+## API: al_set_joystick_mappings
+
+Sets the joystick mappings from a file. This can be called multiple times,
+adding to and overriding existing mappings. This uses the SDL version 2.0.16
+format mappings. This can and typically should be called before calling
+`al_install_joystick`.
+
+Since: 5.2.11
+
+See also: [al_set_joystick_mappings_f]
+
+> *[Unstable API]:* New API.
+
+## API: al_set_joystick_mappings_f
+
+Sets the joystick mappings from a file object. This can be called multiple
+times, adding to and overriding existing mappings. This uses the SDL version
+2.0.16 format mappings. This can and typically should be called before calling
+`al_install_joystick`.
+
+Since: 5.2.11
+
+See also: [al_set_joystick_mappings_f]
+
+> *[Unstable API]:* New API.