Configuring the Action Map

As each device is enumerated, you can obtain a pointer to it, retrieve the default action map, make changes in the default map, and apply the final mappings.

1. Obtaining the Device

Obtain the IDirectInputDevice8 interface pointer for each enumerated device from the lpdid parameter of the enumeration callback. See DIEnumDevicesBySemanticsCallback. If you want to save the device interface for use in your application, call AddRef on the pointer and assign it to a global variable.

To obtain the default action map for the device, call IDirectInputDevice8::BuildActionMap. Microsoft® DirectInput® takes the list of virtual controls specified in your DIACTIONFORMAT structure and attempts to map these to physical device objects, returning the results in the same structure. You should examine the dwHow member of each DIACTION element to determine whether the control was successfully mapped. If it was, you can also ascertain what criterion was used in choosing the object—for example, configuration by the user or by the device manufacturer.

You now have the option of changing the default mappings, although it is not recommended that you do so. After examining the dwSemantic member of the DIACTION structure to determine which device object was mapped to an action, you can change that value. For example, if an action is mapped to DIJOFS_BUTTON9, but you want that action to be mapped to the trigger button instead, change the value to DIJOFS_BUTTON0 before applying the action map.

When you are satisfied that the DIACTIONFORMAT structure contains suitable mappings for the device, call IDirectInputDevice8::SetActionMap. The value you assigned to the uAppData member of each DIACTION structure now becomes bound to the control specified in the dwSemantic member, which in turn is bound to a particular device object.

Repeat steps 1 though 4 for each device you want to use in your application. Suppose you want to map actions to both a joystick and the keyboard. In the racing-game example, the action defined in the game as eB_DRIVERVIEW was mapped to a keyboard key in the following element of the DIACTION array.

{eB_DRIVERVIEW, DIKEYBOARD_1, "Driver View", },

In that example, when BuildActionMap is called on any device that is not a keyboard, the lHow member of the DIACTION structure for that element is set to DIAH_UNMAPPED. Continue examining the lHow member as each device in turn is enumerated, until a value other than DIAH_UNMAPPED is returned. This indicates that the device being currently mapped is a keyboard and the action has been successfully mapped to the requested key.

Even actions that have been successfully mapped can be mapped to another device. In the example, eB_UPSHIFT is given two DIACTION structures, as follows:

{eB_UPSHIFT, DIBUTTON_DRIVINGR_SHIFTUP, 0, "Upshift", },
...
{eB_UPSHIFT, DIKEYBOARD_PRIOR,          0, "Upshift", },

To show the user how actions have been mapped to devices, pass the DICD_DEFAULT flag to IDirectInput8::ConfigureDevices. The property sheet for the device, containing a graphical representation of mappings, is displayed in view-only mode as in the following diagram. For more information on the mechanics of displaying the image, refer to the Using Action Mapping tutorial.