diff options
author | Sam Lantinga <slouken@libsdl.org> | 2020-03-13 19:08:45 -0700 |
---|---|---|
committer | Sam Lantinga <slouken@libsdl.org> | 2020-03-13 19:08:45 -0700 |
commit | 970721b0e5acd9dba714e82b7670ab59960ec3a0 (patch) | |
tree | 14e499d7d5cd594cab3aeae2f248c09e769084ba /include/SDL_joystick.h | |
parent | 134c3c6fbe45bc3901875fb47ae6bf46a5402d7f (diff) | |
download | sdl-970721b0e5acd9dba714e82b7670ab59960ec3a0.tar.gz |
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!
Diffstat (limited to 'include/SDL_joystick.h')
-rw-r--r-- | include/SDL_joystick.h | 31 |
1 files changed, 31 insertions, 0 deletions
diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h index a0dd7205d..b31f6786e 100644 --- a/include/SDL_joystick.h +++ b/include/SDL_joystick.h @@ -105,6 +105,7 @@ typedef enum SDL_JOYSTICK_POWER_MAX } SDL_JoystickPowerLevel; + /* Function prototypes */ /** @@ -200,6 +201,36 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromPlayerIndex(int player_index); /** + * 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); + +/** * Return the name for this currently opened joystick. * If no name can be found, this function returns NULL. */ |