Step 3: Mapping Actions to Devices

Once the desired mapping has been defined, it must be applied to physical devices. IDirectInput8::EnumDevicesBySemantics begins this process in the following code fragment, where m_pDI is a previously defined IDirectInput8 object.

HRESULT hr;

hr = m_pDI->EnumDevicesBySemantics(m_strUserName, &m_diaf, 
                                EnumSuitableDevicesCB, this, 0L);

The first parameter, m_strUserName is useful in the case of multiple users who might have different mapping preferences. However, in the case of this example, this value is NULL, indicating the user currently logged onto the system.

The second parameter is the address of the DIACTIONFORMAT structure containing the mapping information.

The third parameter is the address of a callback function that is called for each device found on the system. The function used in the sample is based on the DIEnumDevicesBySemanticsCallback function.

The fourth parameter could be any 32-bit value that you want to make available to the callback function. Here, this is a this pointer to the class object used by the MultiMapper sample for the various action-mapping setup and manipulation functions. This gives the callback function access to the class' functions.

The final parameter is used for flags. None are used in this example.

The EnumSuitableDevicesCB callback function calls the application-defined function AddDevices, which in turn calls the IDirectInputDevice8::BuildActionMap function on the device pdidDevice currently being enumerated. This call is shown in the following code fragment.

hr = pdidDevice->BuildActionMap( &m_diaf, m_strUserName, 0L );

The first parameter is once again the address of the DIACTIONFORMAT structure containing the action map.

The second parameter is again the name of the user if desired, though NULL in this case.

The final parameter holds control flags, with none being passed in this case.

IDirectInputDevice8::BuildActionMap takes the list of control assignments specified in the DIACTIONFORMAT structure and attempts to map them to specific device objects on the device being enumerated. The results of the mapping are returned in the same structure. Each pass maps different controls depending on the nature of the currently enumerated device. A keyboard, for instance, maps controls that specify a mapping to a particular key, but leaves controls that specify buttons, sliders, or axes unmapped. If a joystick is enumerated next, IDirectInputDevice8::BuildActionMap ignores those controls mapped to keyboard keys, but it attempts to map the buttons, sliders, and axes to the joystick's device objects.

The results of this default mapping can be examined and manipulated. This is done in Step 4: Configuring and Applying the Action Map.