SDL/include
Sam Lantinga 2be75c6a61 Fixed bug 5028 - Virtual Joysticks (new joystick backend)
David Ludwig

I have created a new driver for SDL's Joystick and Game-Controller subsystem: a Virtual driver.  This driver allows one to create a software-based joystick, which to SDL applications will look and react like a real joystick, but whose state can be set programmatically.  A primary use case for this is to help enable developers to add touch-screen joysticks to their apps.

The driver comes with a set of new, public APIs, with functions to attach and detach joysticks, set virtual-joystick state, and to determine if a joystick is a virtual-one.

Use of virtual joysticks goes as such:

1. Attach one or more virtual joysticks by calling SDL_JoystickAttachVirtual.  If successful, this returns the virtual-device's joystick-index.
2. Open the virtual joysticks (using indicies returned by SDL_JoystickAttachVirtual).
3. Call any of the SDL_JoystickSetVirtual* functions when joystick-state changes.  Please note that virtual-joystick state will only get applied on the next call to SDL_JoystickUpdate, or when pumping or polling for SDL events (via SDL_PumpEvents or SDL_PollEvent).


Here is a listing of the new, public APIs, at present and subject to change:

------------------------------------------------------------

/**
 * Attaches a new virtual joystick.
 * Returns the joystick's device index, or -1 if an error occurred.
 */
extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type, int naxes, int nballs, int nbuttons, int nhats);

/**
 * Detaches a virtual joystick
 * Returns 0 on success, or -1 if an error occurred.
 */
extern DECLSPEC int SDLCALL SDL_JoystickDetachVirtual(int device_index);

/**
 * Indicates whether or not a virtual-joystick is at a given device index.
 */
extern DECLSPEC SDL_bool SDLCALL SDL_JoystickIsVirtual(int device_index);

/**
 * Set values on an opened, virtual-joystick's controls.
 * Returns 0 on success, -1 on error.
 */
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualAxis(SDL_Joystick * joystick, int axis, Sint16 value);
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualBall(SDL_Joystick * joystick, int ball, Sint16 xrel, Sint16 yrel);
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualButton(SDL_Joystick * joystick, int button, Uint8 value);
extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick * joystick, int hat, Uint8 value);

------------------------------------------------------------

Miscellaneous notes on the initial patch, which are also subject to change:

1. no test code is present in SDL, yet.  This should, perhaps, change.  Initial development was done with an ImGui-based app, which potentially is too thick for use in SDL-official.  If tests are to be added, what kind of tests?  Automated?  Graphical?

2. virtual game controllers can be created by calling SDL_JoystickAttachVirtual with a joystick-type of SDL_JOYSTICK_TYPE_GAME_CONTROLLER, with naxes (num axes) set to SDL_CONTROLLER_AXIS_MAX, and with nbuttons (num buttons) set to SDL_CONTROLLER_BUTTON_MAX.  When updating their state, values of type SDL_GameControllerAxis or SDL_GameControllerButton can be casted to an int and used for the control-index (in calls to SDL_JoystickSetVirtual* functions).

3. virtual joysticks' guids are mostly all-zeros with the exception of the last two bytes, the first of which is a 'v', to indicate that the guid is a virtual one, and the second of which is a SDL_JoystickType that has been converted into a Uint8.

4. virtual joysticks are ONLY turned into virtual game-controllers if and when their joystick-type is set to SDL_JOYSTICK_TYPE_GAMECONTROLLER.  This is controlled by having SDL's default list of game-controllers have a single entry for a virtual game controller (of guid, "00000000000000000000000000007601", which is subject to the guid-encoding described above).

5. regarding having to call SDL_JoystickUpdate, either directly or indirectly via SDL_PumpEvents or SDL_PollEvents, before new virtual-joystick state becomes active (as specified via SDL_JoystickSetVirtual* function-calls), this was done to match behavior found in SDL's other joystick drivers, almost all of which will only update SDL-state during SDL_JoystickUpdate.

6. the initial patch is based off of SDL 2.0.12

7. the virtual joystick subsystem is disabled by default.  It should be possible to enable it by building with SDL_JOYSTICK_VIRTUAL=1



Questions, comments, suggestions, or bug reports very welcome!
2020-03-13 19:08:45 -07:00
..
SDL.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_assert.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_atomic.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_audio.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_bits.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_blendmode.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_clipboard.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config.h.cmake Fixed bug 5028 - Virtual Joysticks (new joystick backend) 2020-03-13 19:08:45 -07:00
SDL_config.h.in Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_android.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_iphoneos.h Added support for the Steam Controller on mobile devices 2020-01-29 20:09:11 -08:00
SDL_config_macosx.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_minimal.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_os2.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_pandora.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_psp.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_windows.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_winrt.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_config_wiz.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_copying.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_cpuinfo.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_egl.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_endian.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_error.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_events.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_filesystem.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_gamecontroller.h Fixed bug 5028 - Virtual Joysticks (new joystick backend) 2020-03-13 19:08:45 -07:00
SDL_gesture.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_haptic.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_hints.h Fixed bug 4854 - Add a way to extend the values in controller_type.h 2020-03-02 10:37:28 -08:00
SDL_joystick.h Fixed bug 5028 - Virtual Joysticks (new joystick backend) 2020-03-13 19:08:45 -07:00
SDL_keyboard.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_keycode.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_loadso.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_log.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_main.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_messagebox.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_metal.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_mouse.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_mutex.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_name.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_opengl.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_opengl_glext.h Don't have Windows headers define min/max, in case they're defined by application code 2019-09-11 15:08:37 -07:00
SDL_opengles.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_opengles2.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_opengles2_gl2.h Fixed crash if initialization of EGL failed but was tried again later. 2015-06-21 17:33:46 +02:00
SDL_opengles2_gl2ext.h Fixed crash if initialization of EGL failed but was tried again later. 2015-06-21 17:33:46 +02:00
SDL_opengles2_gl2platform.h Fixed crash if initialization of EGL failed but was tried again later. 2015-06-21 17:33:46 +02:00
SDL_opengles2_khrplatform.h Fixed crash if initialization of EGL failed but was tried again later. 2015-06-21 17:33:46 +02:00
SDL_pixels.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_platform.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_power.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_quit.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_rect.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_render.h Clarified that the clip rectangle is defined relative to the viewport, and added a clip test to testviewport.c 2020-03-08 21:02:40 -07:00
SDL_revision.h revert files I didnt mean to commit! 2017-09-29 10:15:44 -07:00
SDL_rwops.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_scancode.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_sensor.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_shape.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_stdinc.h Fixed bug 5001 - Feature request: SDL_isupper & SDL_islower 2020-03-02 15:21:07 -08:00
SDL_surface.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_system.h Made SDL_GetAndroidSDKVersion() available for applications 2020-02-17 13:54:45 -08:00
SDL_syswm.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_assert.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_common.h test: Reimplemented SDLTest_CommonUsage() to restore binary compatibility. 2020-02-12 13:09:38 -05:00
SDL_test_compare.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_crc32.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_font.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_fuzzer.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_harness.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_images.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_log.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_md5.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_memory.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_test_random.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_thread.h Make it possible for the application to use different C runtime begin/end thread functions 2020-02-11 08:26:46 -08:00
SDL_timer.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_touch.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_types.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_version.h Backed out changeset 51622f74dc85 2020-03-10 18:35:31 -07:00
SDL_video.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
SDL_vulkan.h Fixed bug 4570 - Support Vulkan Portability rather than MoltenVK specifically 2019-06-11 18:13:46 -07:00
begin_code.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00
close_code.h Updated copyright date for 2020 2020-01-16 20:49:25 -08:00