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).

Actually I'm guilty as charged there.

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.

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:

What you say?

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 *));

Yes, I see the point about al_reconfigure_joysticks. Perhhaps that's what al_reconfigure_haptics will do on the side of the haptic devices then?

Oh, and it went easier than I thought, I set up a copy of the Allegro development branch on Github. You need the "haptics" branch specifically, get it here:

https://github.com/beoran/allegro/tree/haptic

Ah git... It's sometimes a bit difficult to use, but in functionality, it's "king"!

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

git checkout 653125e2e3c80953d153c0a3f34326e940e8cadc
git checkout -b haptic

To get the repository in working state.

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.

Yeah that makes sense to me. I just couldn't articulate it.

OK, I'll reinstate the int handle based API. Or should I use a ALLEGRO_HAPTIC_PLAYBACK * , a bit like the sound API?

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...

Ah yes, joy sticks like these ones too:
http://therionorteline.files.wordpress.com/2012/09/usb-vibrator.jpg?w=1092

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 say
al_joystick_upload_haptic_effect, al_joystick_upload_play_effect, etc?