Step 5: Displaying the Action Map

In addition to the advantage of action mapping in enabling the developer to define game actions independently of specific controller hardware, action mapping also benefits the user by providing a user interface (UI) for easy reconfiguration.

The UI can be displayed in two forms, text-only or graphics. In addition, each of those two options can be viewed in two modes: view-only or edit.

To display the UI, some initial setup is involved. First, a DICOLORSET structure is declared and initialized. This structure, as its name implies, describes the color set used to display the UI. The following code fragment shows the setup of this structure.

DICOLORSET dics;
ZeroMemory(&dics, sizeof(DICOLORSET));
dics.dwSize = sizeof(DICOLORSET);

By using the ZeroMemory function to set the memory block to zeroes, it indicates that the default color scheme should be used. Beyond this, the only element that requires initialization is the dwSize member, which is set equal to the size of the DICOLORSET structure.

The DICOLORSET structure is then included as part of a larger DICONFIGUREDEVICESPARAMS structure as seen in this code fragment.

DICONFIGUREDEVICESPARAMS dicdp;
ZeroMemory(&dicdp, sizeof(dicdp));
dicdp.dwSize = sizeof(dicdp);
dicdp.dwcUsers       = 1;
dicdp.lptszUserNames = m_strUserName;

dicdp.dwcFormats     = 1;
dicdp.lprgFormats    = &m_diaf;
dicdp.hwnd           = m_hWnd;
dicdp.lpUnkDDSTarget = NULL;

The DICONFIGUREDEVICESPARAMS structure is declared and its allotted memory is set to contain nothing but zeroes. Once again, the dwSize member is set to the size of the structure. Only the currently logged user is being used in this example, so dwcUsers is set to 1. Recall that the m_strUserName variable is set to NULL so that the user's name is the name of the user currently logged onto the system.

Only one DIACTIONFORMAT structure containing the action map is being passed, so dwcFormats is set to 1 and the address of the DIACTIONFORMAT structure is passed as lprgFormats.

The hwnd variable is assigned the handle of the application window and the lpUnkDDSTarget is set to NULL to indicate that the Microsoft?Windows® Windows Graphics Device Interface (GDI) functions should be used to draw the configuration user interface image.

The initialized DICONFIGUREDEVICESPARAMS structure is then passed to IDirectInput8::ConfigureDevices as illustrated in this code fragment.

hr = m_pDI->ConfigureDevices(NULL, &dicdp, dwFlags, NULL);

The first and last parameters, which are used with an optional callback function, are set to NULL as they are not used in this sample.

The second parameter is the address of the DICONFIGUREDEVICESPARAMS structure containing the data to be displayed and other auxiliary information.

The third parameter is used for flags that determine whether the display is in read-only or edit mode. If you want to display the configuration for informational purposes without giving the user the option of changing it, you use the DICD_DEFAULT flag in this parameter. However, in this sample the dwFlags variable had been set earlier to DICD_EDIT, so the display allows user configuration. This is discussed in Step 6: User Configuration of the Action Map.