Since I found out that both Linux and my cheap USB joystick support force feedback, I'm interested in developing support for force feedback, or for haptic devices for short, also in Allegro. Now, on the PC platform, and certainly on Linux, almost no game uses haptic effects since no one knows how to program them. So support for haptic devices in Allegro would be nice. Also, SDL2 will also support haptic effects, so that's another reason I don't want Allegro to fall behind.

Anyway, I started work on this, but Thomas suggested that I first post the API I suggest here, so we can discuss and improve it. So please read this proposal for allegro5/haptic.h and tell me what you like, dislike and find unclear about it. Without more ado, here is the content of the file (also attached for use at your leasure).

One "danger" with these things is always that you write for one platform and then other platforms do things completely differently. You end up with a "biased" api. If you haven't already, I think you should look at Windows and Mac OS X and see how things are done there (even if you can't write drivers for those.) Then find a common set of functions and an API that is not targetted at a single platform.

NOTE: You may have already done this. I see a lot of very specific information here and that made me wonder if this wasn't just a thin wrapper over Linux apis.

I don't have access to windows or mac OS-X, so to get some ideas of who to structure the API, I had to take a look at the SDL 2 sources (which are under the same license as Allegro, so no problem there). They too use a Linux-ish API as the smallest common denominator for most platforms . So I went for that with some nuances, such as using doubles to get device independent value for time , and relative values for intensity in there.

But I also know from SDL2 that it's possible to fit Windows and OS-X into this Linux-ish API, so I thought it would be OK. But if you have better ideas, then please do make suggestions.

I'll probably only be able to supply a Linux driver anyway, so I'd love to hear from people who want to implement te Windows or OS-X, or Iphone, or Android drivers for this and I'd like those people to tell me how we could modify this proposal so it will make it easy for them to write their drivers.

Well yes, but I don' t use SDL exactly because I like the Allegro API better, so their API doesn't have to be the end-all be-all. If possible I'd like an API that is easier to use than SDL.

It's true, I should RTFM, but since I don't have a chance to test the other platforms, I doubt I would learn much more from RTFM than from the SDL code. I'd rather listen to the opinion of people who had hands on experience with those API's. Or people who are willing to gain this experience.

To be blunt, Trent, would you be willing to do the Windows or OSX port of this? You can get a USB joystick that supports rumble cheaply and easily enough, and then you can try to make it work using the Windows or OSX API. Like that you'll get valuable hands-on experience and we'll be able to decide how too proceed with ALLEGRO_HAPTICS much better.

Thanks a lot! I know you are busy with your game project, but I think for an action RPG, rumble effects certainly will be an extra selling point. Even if you can't write the whole driver, your explorations will hopefully shed some light on the right approach.

I'll share with you the whole patch of all other changes I made versus Allegro git so far while I was working on the Linux driver, if and when you need it, so feel free to request it whenever.

Maybe you can tell me what out of this is common between your header and this. We can then try and make something that works well with stuff in common from them. For things that are in one but not the other, we can optionally drop them or keep them with fallbacks to something close where not supported.

EDIT2: After reading over your API fully and comparing it to DirectInput, it's mostly the same. I think there are a few types of effect that are missing in DirectInput and I didn't see anything about replays (if there is no replay in DirectInput I think we could put the onus on the user to replay effects, I'm not sure about this though.)

One thing I think that should be done is to somehow merge this with the joystick (and mouse?) apis somewhat. Like perhaps we could have a function like ALLEGRO_JOYSTICK *al_get_haptic_joystick and maybe the reverse.

OK, I'll set up my allegro branch at github for this, it might be tomorrow or Monday though before I get this done.

I quicly read the info linked too and it seems Directinput supports a few effects that Linux doesn't, and generally formats it's parameters differently, and is somewhat more convoluted. Especially when it comes to the position of the effect. Linux only supports an angle, (or 2 carthesian axes for a condition effect, IIRC), but DI supports much more. My idea was to only support spherical coordinates , and let the divers translate those as needed.

The Directinput API does allow on to upload, play and stop a sample, but it doesn't give you a "play id" like Linux does, you have to use the effect object, which means you can't reuse the object for different replays. This means that it may be easier to implement the API if we drop the play id and always use an ALLEGRO_HAPTIC_EFFECT * to control playback and stopping:

Rumble is just a very simple "rumble" effect, normally you replace this by a periodic sine wave (or other supported wave) of the required amplitude. Actually, Linux supports rumble because the driver does an internal translation for you. I still want to have a "rumble" for the simples use case where all you want is a bit of vibration in the joystick.

Oh, and for integrating ALLEGRO_HAPTIC devices with joystick and mouse, I think al_get_haptic_from_mouse and al_get_haptic_from_joystick should be enough for now. Normally I'd imagine you first install the joysticks and then enable the haptic effects on them. We could probably put that in the docs too and perhaps even require this, although I still haven't figured out yet how to make this work with the pluggable joysticks feature.

And yes, that was an oversight. The proper signature is of course AL_FUNC(bool, al_stop_all_haptic_effects , (ALLEGRO_HAPTIC *));

I think the ALLEGRO_HAPTIC for any joystick should behave exactly like the ALLEGRO_JOYSTICKs. If it's unplugged or one is plugged in the current state remains valid. Those devices become usable/unusable once you call al_reconfigure_joysticks. I guess with mice or other devices we just not support hotplugging at least at this time.

Depends. Besides gamepads, what other haptic devices are there that will be supported? DirectInput only supports haptics on gamepads. On Linux we could do something like we do for joysticks already, but I don't know if hot pluggable haptic devices are as important as joysticks. Do other haptic devices on Linux get /dev/input/js* devices or something else? If so they'd probably be treated like joysticks with no buttons or whatever, and al_reconfigure_joysticks would take care of them automatically.

In linux, any input device can have haptic capabilities. So it's not linked to /dev/input/js0 at all, really. At least in theory, linux can have haptic keyboards, haptic trackerballs, haptic mise, haptic tablets, haptic touch screens, etc.

Another reason why haptic devices may not be integrated in joystics is on mobile platforms. Iphones and android can vibrate the whole phone, which isn't connected to the input. I though this should probably be modeled in Allegro as a haptic device too.

And the code isn't in compiling state, sorry for that. I just blasted it there quickly so we could "git" going. :p

Edit: to solve your git problem, after clning the repository, go into the seemingly empty cloned allegro subdir and do

I tested it, if you do git clone and then get that message, you should find a seemingly empty allegro directory. That means the cloning actually worked, just the checkout didn't.

Necause git's not able to find the right branch (it expects master but that doesn't exist), it checks out nothing and leaves the allegro directory seemingly empty. So you must manually check out the latest revision and tell it that is the haptic branch.

You provide a filled-in effect structure to al_upload_haptic_effect, but then you must provide the same address to al_play_haptic_effect? I think the previous design was cleaner, where the ALLEGRO_HAPTIC object owns the effect after uploading, and returns a handle for you to work with.

Maybe ALLEGRO_HAPTIC_EFFECT_ID (not a pointer) if we were to match the audio API.

Do we need the stuff to enumerate/reconfigure/get/release individual ALLEGRO_HAPTIC objects? I'm assuming that haptic devices could be a component of some other objects, mainly ALLEGRO_JOYSTICK. For vibrating the whole phone, we might use the ALLEGRO_DISPLAY as the parent (or introduce something different). This might simplify the API a bit.

I'll take another look at the audio API and try to see how I can match that best with an ALLEGRO_HAPTIC_EFFECT_ID.

As for simplifying the API, unfortunately, some haptic devices are not connected to another device such as a display, screen or a joystick. Think of the PS2 Rez "Trance Vibrator" or other similar haptic devices. We have to think of everything...

True, we could model such a no-input haptic device as a joystick (that does not return events), but I feel that that doesn't make much sense now if that makes sense. Also mice and keyboards can be haptic as well.

However, perhaps a few joystick wrapper functions could be useful, like sayal_joystick_upload_haptic_effect, al_joystick_upload_play_effect, etc?