We are currently migrating Bugzilla to GitHub issues.
Any changes made to the bug tracker now will be lost, so please do not post new bugs or make changes to them.
When we're done, all bug URLs will redirect to their equivalent location on the new bug tracker.

Bug 311

Summary: SDL does not support WM_XBUTTON events (mouse side buttons do not work)
Product: SDL Reporter: Forest Hale <lordhavoc>
Component: eventsAssignee: Ryan C. Gordon <icculus>
Status: RESOLVED FIXED QA Contact: Sam Lantinga <slouken>
Severity: normal    
Priority: P1    
Version: 1.2.11   
Hardware: x86   
OS: Windows (All)   
URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/userinput/mouseinput/mouseinputreference/mouseinputmessages/wm_xbuttondown.asp
Attachments: First shot at implementation for 1.2.

Description Forest Hale 2006-08-27 07:30:29 UTC 
Microsoft added WM_XBUTTONDOWN/UP GDI events for mouse buttons after the first 3, these buttons are used by Microsoft Intellimouse Explorer and later mice (which have two side buttons), modern Logitech mice (often having one or two side buttons, and sometimes other functionality), and probably some other vendors as well.

These events are usually sent as WM_XBUTTONUP and WM_XBUTTONDOWN, but as with other WM_*BUTTON* and WM_MOUSEMOTION events they can contain multiple button presses/releases at once, and consequently the wParam is a bitmask of the same format for all such events, the bitmasks for these are 0x0020 up to 0x0800 (7 buttons), I do not know the details for buttons beyond that (if any are possible).  However the MSDN page only defines MK_XBUTTON1 (0x0020) and MK_XBUTTON2 (0x0040), so buttons beyond this are hypothetical but likely to exist in the future.

It would be desirable to report these as additional buttons (6 and 7?) in the SDL_MOUSEBUTTONDOWN/UP events.

This bug (I consider it too severe to be merely a lacking feature) is discouraging people from using my DarkPlaces glquake engine's SDL client, instead resorting to the native Windows client simply for additional mouse button support.  (Note that the drivers often allow mapping certain mouse buttons to key presses, but these buttons are usually not allowed to be mapped to key presses)

More information can be found at the MSDN URL given.

It is worth noting for reference that the Logitech G5 Gaming Mouse has 1 side button, 2 sensitivity buttons (which can be mapped to key presses), and a tilt wheel (which can be mapped to keypresses for left/right tilt, besides the normal mouse wheel functionality), this equates to it being a 10 button mouse (counting wheel roll as two buttons), although the Windows drivers only allow mapping the side button to the mouse4 (MK_XBUTTON1) button.

Side buttons are very useful on mice in fast paced online FPS games such as Quake Deathmatch for special actions such as reloading or dropping a weapon, so I consider this to be a bug rather than an enhancement.

Example code can be found in the DarkPlaces source code here:
http://cvs.icculus.org/cvs/twilight/darkplaces/vid_wgl.c?view=auto
(Search for XBUTTON)
Comment 1 Ryan C. Gordon 2007-06-02 13:58:55 UTC 
Bumping a bunch of bugs to Priority 1 for consideration for the 1.2.12 release.

--ryan.
Comment 2 Ryan C. Gordon 2007-06-15 02:08:57 UTC 
Created attachment 214 [details]
First shot at implementation for 1.2.


Here's a patch against the latest Subversion revision of SDL 1.2 ... this is completely untested, and may not even compile.

This patch adds WM_XBUTTON support to the windib target. Buttons show up as indexes 6 and 7 to accomodate the mousewheel being buttons 4 and 5...this patch should handle buttons 8, 9, etc, if Windows supports more than XBUTTON1 and XBUTTON2 in the future.

The DirectInput code would need to use something newer than the DirectInput2 interfaces to get up to 8 buttons (DIMOUSESTATE supports 4, we need DIMOUSESTATE2). This patch does not touch that.

If someone with Windows and a mouse with a lot of buttons could test this, I'd appreciate it.

--ryan.
Comment 3 Forest Hale 2007-06-15 12:29:21 UTC 
WM_XBUTTON has been heavily tested in DarkPlaces previously, it's probably worth referring to the code here: http://svn.icculus.org/twilight/trunk/darkplaces/vid_wgl.c?view=markup

Your patch seems to assume that the wParam contains a button index, which is incorrect, they contain bit flags just like MK_LBUTTON, MK_RBUTTON, and MK_MBUTTON (which exist in the WM_[LRM]BUTTONDOWN/UP events), here are the values:
#ifndef MK_XBUTTON1
   #define MK_XBUTTON1         0x0020
   #define MK_XBUTTON2         0x0040
// LordHavoc: lets hope this allows more buttons in the future...
   #define MK_XBUTTON3         0x0080
   #define MK_XBUTTON4         0x0100
   #define MK_XBUTTON5         0x0200
   #define MK_XBUTTON6         0x0400
   #define MK_XBUTTON7         0x0800
#endif

The event could conceivably have multiple set (although I doubt that ever happens), which means multiple SDL button events need to be produced.
Comment 4 Ryan C. Gordon 2007-06-15 13:12:46 UTC 
> Your patch seems to assume that the wParam contains a button index, which is
> incorrect, they contain bit flags just like MK_LBUTTON, MK_RBUTTON, and
> MK_MBUTTON (which exist in the WM_[LRM]BUTTONDOWN/UP events), here are the
> values:

According to the MSDN link in the URL field, the low-order bits are a mask of currently-pressed buttons as you described, and is in fact what DarkPlaces uses. 

The high-order bits specify exactly one button, the one that triggered the event, and that works better for SDL's purposes.

--ryan.
Comment 5 Forest Hale 2007-06-15 13:29:29 UTC 
Ahh, that's very cool actually.  :)
Comment 6 Forest Hale 2007-06-15 17:22:06 UTC 
Okay, I have tested this patch and found one bug in it:
case WM_XBUTTONUP:
xbuttonval = GET_XBUTTON_WPARAM(wParam);
button = SDL_BUTTON_WHEELDOWN + xbuttonval;
state = SDL_PRESSED;
break;

Should use SDL_RELEASED

With that fixed, it works perfectly.
Comment 7 Ryan C. Gordon 2007-06-15 22:29:52 UTC 
(In reply to comment #6)
> Should use SDL_RELEASED

Crap, I always screw up cut-and-pastes.   :)

Thanks for catching that!

This is fixed in svn revision #3086 for the 1.2 branch (and will go into the upcoming 1.2.12 release), and #3088 for the 1.3 branch.

--ryan.
Comment 8 Forest Hale 2007-07-15 18:48:04 UTC 
In case SDL lacks DirectInput support for button4/5 this diff may be a useful reference:
http://svn.icculus.org/twilight/trunk/darkplaces/vid_wgl.c?r1=7317&r2=7489&p1=trunk/darkplaces/vid_wgl.c&p2=trunk/darkplaces/vid_wgl.c

As I don't see any such bug in the bugzilla I'm just mentioning this on this already resolved bug about button4 in GDI input.
Comment 9 Ryan C. Gordon 2007-07-16 02:23:28 UTC 
We'll update the DirectInput interface we use to a newer version for SDL 1.3, I'm sure, but we don't want to change the dependencies for 1.2 at this point.

--ryan.
Comment 10 Forest Hale 2007-07-16 02:47:19 UTC 
(In reply to comment #9)
> We'll update the DirectInput interface we use to a newer version for SDL 1.3,
> I'm sure, but we don't want to change the dependencies for 1.2 at this point.
> 
> --ryan.

Hmm?  DarkPlaces uses DirectInput 3, there's no older version.