DirectXInput: Action Mapping
Author: Jack Hoxley
Written: 20th June 2002
Contact: [EMail]
Download: IN3_ActMap.Zip (15kb)

Contents of this lesson
1. Introduction
2. About Genre's
3. Initialization and Configuration
4. Interpreting and understanding 
5. Conclusion

1. Introduction

Welcome to the third tutorial in the DirectXInput series. DirectInput is one of the simplest parts of the DirectX API - most people will be content with using just the keyboard mouse and joystick to control their applications. Once these three have been learnt there's not much else to do!

However, there is one last thing - Action Mapping, a new addition in DirectX8, and probably about as advanced and interesting as input-programming gets. I'm surprised its taken this long to work its way into the DirectX API really; DirectInput has always been about abstracting the input interfaces - you access the mouse and DI will sort out if its a 1-button/10 button, 2 axis/3 axis mouse and give you the data you want. Action Mapping goes one step beyond this - you tell it what data you want and it'll do the rest - whatever device it comes from.

For example, in the sample that this tutorial covers (a simple racing game) the input can come from the keyboard, mouse or joystick - and your application doesn't need to differentiate between them. When using action mapping an 'Accelerate' or 'Turn Left' message is just that, an 'Accelerate' message from the joystick is not different from an 'Accelerate' message from the keyboard.

2. About Genre's

Action Mapping is built upon the principle of Genre's - any game that you write should be able to pick its input to match with that typical of one of the genre's. This doesn't mean that if you're writing a racing game you HAVE to use the racing-game genre's - if the flight-sim genre matches better you can use that. Also, if a particular genre doesn't have all the controls that you need you can always add additional control handles (as we'll see later).

The following tree shows all the genre's defined in DirectInput8:
• Action Genres
     • Hand-to-Hand ( _FIGHTINGH_ , DIVIRTUAL_FIGHTING_HAND2HAND)
     • Shooting ( _FPS_ , DIVIRTUAL_FIGHTING_FPS)
     • Third Person Action ( _TPS_ , DIVIRTUAL_FIGHTING_THIRDPERSON)
• Arcade Genres
     • Platform ( _ARCADEP_ , DIVIRTUAL_ARCADE_PLATFORM)
     • Side-to-Side ( _ARCADES_ , DIVIRTUAL_ARCADE_SIDE2SIDE)
• CAD Genres
     • 2D Object ( _2DCONTROL_ , DIVIRTUAL_CAD_2DCONTROL)
     • 3D Model ( _CADM_ , DIVIRTUAL_CAD_MODEL)
     • 3D Navigation ( _CADF_ , DIVIRTUAL_CAD_FLYBY)
     • 3D Object ( _3DCONTROL_ , DIVIRTUAL_CAD_3DCONTROL)
• Control Genres
     • Browser ( _BROWSER_ , DIVIRTUAL_BROWSER_CONTROL)
     • Remote Control ( _REMOTE_ , DIVIRTUAL_REMOTE_CONTROL)
• Driving Genres
     • Combat Racing ( _DRIVINGC_ , DIVIRTUAL_DRIVING_COMBAT)
     • Mechanical Fighting ( _MECHA_ , DIVIRTUAL_DRIVING_MECHA)
     • Racing ( _DRIVINGR_ , DIVIRTUAL_DRIVING_RACE)
     • Tank ( _DRIVINGT_ , DIVIRTUAL_DRIVING_TANK)
• Flight Genres
     • Air Combat ( _FLYINGM_ , DIVIRTUAL_FLYING_MILITARY)
     • Civilian Flight ( _FLYINGC_ , DIVIRTUAL_FLYING_CIVILIAN)
     • Helicopter Flight ( _FLYINGH_ , DIVIRTUAL_FLYING_HELICOPTER)
     • Space Combat ( _SPACESIM_ , DIVIRTUAL_SPACESIM)
• Sports Genres
     • Baseball Batting ( _BASEBALLB_ , DIVIRTUAL_SPORTS_BASEBALL_BAT)
     • Baseball Fielding ( _BASEBALLF_ , DIVIRTUAL_SPORTS_BASEBALL_FIELD)
     • Baseball Pitching ( _BASEBALLP_ , DIVIRTUAL_SPORTS_BASEBALL_PITCH)
     • Basketball Defense ( _BBALLD_ , DIVIRTUAL_SPORTS_BASKETBALL_DEFENSE)
     • Basketball Offense ( _BBALLO_ , DIVIRTUAL_SPORTS_BASKETBALL_OFFENSE)
     • Fishing ( _FISHING_ , DIVIRTUAL_SPORTS_FISHING)
     • Football Defense ( _FOOTBALLD_ , DIVIRTUAL_SPORTS_FOOTBALL_DEFENSE)
     • Football Offense ( _FOOTBALLO_ , DIVIRTUAL_SPORTS_FOOTBALL_OFFENSE)
     • Football Play ( _FOOTBALLP_ , DIVIRTUAL_SPORTS_FOOTBALL_FIELD)
     • Football Quarterback ( _FOOTBALLQ_ , DIVIRTUAL_SPORTS_FOOTBALL_QBCK)
     • Golf ( _GOLF_ , DIVIRTUAL_SPORTS_GOLF)
     • Hockey Defense ( _HOCKEYD_ , DIVIRTUAL_SPORTS_HOCKEY_DEFENSE)
     • Hockey Goalie ( _HOCKEYG_ , DIVIRTUAL_SPORTS_HOCKEY_GOALIE)
     • Hockey Offense ( _HOCKEYO_ , DIVIRTUAL_SPORTS_HOCKEY_OFFENSE)
     • Hunting ( _HUNTING_ , DIVIRTUAL_SPORTS_HUNTING)
     • Mountain Biking ( _BIKINGM_ , DIVIRTUAL_SPORTS_BIKING_MOUNTAIN)
     • Racquet ( _RACQUET_ , DIVIRTUAL_SPORTS_RACQUET)
     • Skiing ( _SKIING_ , DIVIRTUAL_SPORTS_SKIING)
     • Soccer Defense ( _SOCCERD_ , DIVIRTUAL_SPORTS_SOCCER_DEFENSE)
     • Soccer Offense ( _SOCCERO_ , DIVIRTUAL_SPORTS_SOCCER_OFFENSE)
• Strategy Genres
     • Role Playing ( _STRATEGYR_ , DIVIRTUAL_STRATEGY_ROLEPLAYING)
     • Turn Based ( _STRATEGYT_ , DIVIRTUAL_STRATEGY_TURN)

A fairly long list! The two values in the parenthesis: first one represents a string you can use to search the SDK help files and/or VB object browser for a complete list of the controls for that genre, second one is the genre's 'name' - the use for which you'll see in a little while.

3. Initialization and Configuration

90% of the work to get action mapping is done when the application starts or when the end-user decides to alter their control settings.

The first step is to construct a default set of controls for the application - you assign one of the controls from a genre listed above to a particular internal constant and give it a name. Secondly we query the system about the proposed action map, it will then return a list of devices attached to the system that are compatible/necessary for the given action map. We then create an instance of each device that the system "recommended", configuring them as we go.

Before we actually execute any code we need  a list of constants - some are just for convenience, others are requirements. It is necessary to have a list of internal constants representing each control - later on we'll send these values to the action map, and DirectInput will use these as the basis for returning information back to us.

Above is all fairly straightforward, pay particular attention to AppGUID and AppUserName - these should be changed if you use Action Mapping in your own programs. AppGUID is a unique value generated by DX.CreateNewGUID( ) - you should create a new one for each application you make. The reason for this being that DirectInput is clever and saves action maps to the hard drive for future sessions, and it uses this GUID (and the user name) to differentiate between multiple maps. If, for example, you used the same GUID for all your games and one person installed more than one game on their system you'd start to get conflicts (one game would overwrite another's settings).

Now we move onto the actual inialisation routine, aptly named InitDirectInput( ). Because this function can be called multiple times (it's called each time the user changes the control settings) we need to start off by erasing any history of existing action maps and/or devices:

Next we're going to setup the default action map. The actions you specify now will be the only ones visible to the end-user - if you didn't set a default for DIAXIS_DRIVINGR_STEER then it wouldn't automatically appear, and the user would not be allowed to use axis-steering.

once we've configured our default control setup we can show it to the user and allow them to further customize it to their style. The sample does this now, but a real-world application would probably want to hide this next part in an options screen.

An important note here: ConfigureDevices( ) actually displays a default DirectInput dialog box to the end user. Whilst it is a very nice, functional, window I highly doubt it will fit into the majority of real-world game environments. The following image is the window:

A very tasteful black-and-green :)

The three tabs along the top of the screen represent the (valid) devices currently attached to the system - in my case a cheap gamepad, a keyboard and a mouse. If multiple players are active/playing then they will appear in the "Player" drop-down list box.

Once the end user has configured the devices, we can move on to creating the devices. By using the GetDevicesBySemantics( ) function we can retrieve the list of devices that match the current genre and/or are going to be used by the system. With this list we need to go through and create each device and store a pointer to it.

that's initialization completed now. Assuming the above code executes successfully you are ready to properly make use of action mapping. The last thing I want to cover in this section is termination. It's always a good idea to properly terminate any DirectX interfaces that you use - particularly so with DirectInput. The following code is executed just before the application closes:

4. Interpreting and understanding 

Now that DirectInput is configured and ready to send us input data we need to be ready to receive and process it. When using action mapping we have to use a method similar to polling - whilst for keyboard/button input it works just the same as event-based (which is best) it is necessary for axis-based devices to be polled. For a further discussion of event-based vs polling see the first lesson - keyboard access.

Exactly what you do once you've received input from attached devices is entirely dependent on you. This sample code does no more than output a list to the screen of the input received, a real-world application would then want to apply these controls to the current character (for example).

As mentioned, we're going to use a polling method - so the basic code structure looks like this:

This loop would, in a real-world application, have a rendering function, AI, physics, logic etc... system attached. You've already seen the InitDirectInput( ) function (section #3 above). I'm now going to be focusing on the UpdateUserInput( ) function.

The basic idea behind the UpdateUserInput( ) process is to:
1. Loop through all created devices
2. receive any new input from the device
3. Process this input.

the first part, and the general function outline is as simple as this:

the DevData( ) array is very important, this is refreshed for each device and gives us a list of up to 20 events that have occurred since we last checked the device (last frame). JOYSTICK_SATURATION is important when we deal with the joystick a bit later on.

Now that we have the main loop setup we can treat each input generically - such as the following code to collect input from the devices:

The first three parts are very important - firstly we should check to make sure the pointer is still valid - it is possible that we could loose a device (another application can steal it for example), in which case the DevList(I) will be a null pointer. Next we must attempt to aquire the device - should it have been somehow unaquired (similar to being lost, but not as bad). Next we have to poll the device - basically tell it to collect the current state of the hardware (it'll go and check the axis positions on the joypad for example). Lastly we use GetDeviceData( ) to get DirectInput to return us a formatted list of events.

We can then loop through this formatted input (it'll be formatted based on our action map) as shown in the following piece of code:

With this piece of code we will cycle through each event from the device (there will usually only be one or two). We then split apart incoming message using a Select Case tree. Remember the constants we defined at the beginning of this tutorial? well they appear back here again - the wonders of action mapping has meant that regardless of the raw control data all we get back is a generic, custom value.

What you actually do within each branch of the logic tree is completely up to you. However, I shall demonstrate two useful pieces of code for processing input.

You can see a more complete set of examples if you download the source code for this tutorial. But in general they all follow this pattern.

for axis-based input the .lData value will contain the current value on the device's axis scaled according to the values in .lAxisMax and .lAxisMin. Take a joystick for example, each axis goes from -ve to +ve (left->right or top->bottom). Therefore if .lData is a negative number it is somewhere towards the left or top (depending on which axis the user selected, either way does not matter to us). If .lData is a positive number then it lies somewhere towards the right or bottom. Fairly simple really. I've made it more complicated based on some testing and general knowledge that I have of joysticks... even if you push them all the way to the left you will rarely get the maximum -ve number, and if you don't touch the joystick at all then it rarely stays at 0. This may be different with digital controllers and/or more elegant designs (my joystick is laughable at best!). What I did to combat this was to implement a saturation value: in order for the new data to be considered a significant change it MUST be greater than a certain value. .lAxisMax and .lAxisMin determine the max/min possible values, and JOYSTICK_SATURATION is a scalar multiplier.

As seen above, I set JOYSTICK_SATURATION to be 0.4; given that the range defined earlier is [-100,+100] this logic implies that the new value must be less than -40 or greater than +40 to be considered a change. You could allow your users to specify how sensitive they want their controls using this method.

5. Conclusion

That is all there is to a basic DirectInput8-Action Mapping sample. Obviously, you can make it more complicated if necessary - but to get a basic generic input based system working this is all you need. One useful thing to note is that there are an additional set of control constants you can use for DirectPlay Voice Communications and also a set of generic non-controller specific constants (search for _ANY_ ).

The source code for this tutorial can be download here, or from the top of the page.