IDirectInput8::ConfigureDevices Method

Displays property pages for connected input devices and enables the user to map actions to device controls.

Syntax

HRESULT ConfigureDevices(      

    LPDICONFIGUREDEVICESCALLBACK lpdiCallback,
    LPDICONFIGUREDEVICESPARAMS lpdiCDParams,
    DWORD dwFlags,
    LPVOID pvRefData
);

Parameters

lpdiCallback
Address of a callback function to be called each time the contents of the surface change. See DIConfigureDevicesCallback. Pass NULL if the application does not handle the display of the property sheet. In this case, Microsoft?DirectInput?displays the property sheet and returns control to the application when the user closes the property sheet. If you supply a callback pointer, you must also supply a valid surface pointer in the lpUnkDDSTarget member of the DICONFIGUREDEVICESPARAMS structure.
lpdiCDParams
Address of a DICONFIGUREDEVICESPARAMS structure that contains information about users and genres for the game, as well as information about how the user interface is displayed.
dwFlags
DWORD value that specifies the mode in which the control panel should be invoked. The dwFlags parameter must be one of the following values.
DICD_DEFAULT
Open the property sheet in view-only mode.
DICD_EDIT
Open the property sheet in edit mode. This mode enables the user to change action-to-control mappings. After the call returns, the application should assume current devices are no longer valid, release all device interfaces, and reinitialize them by calling IDirectInput8::EnumDevicesBySemantics.
pvRefData
Application-defined value to pass to the callback function.

Return Value

If the method succeeds, the return value is DI_OK.
If the method fails, the return value can be one of the following:
DIERR_INVALIDPARAM An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard Component Object Model (COM) return value.
DIERR_OUTOFMEMORY The DirectInput subsystem couldn't allocate sufficient memory to complete the call. This value is equal to the E_OUTOFMEMORY standard COM return value.

Remarks

IDirectInput8::ConfigureDevices was designed to work in the Microsoft Direct3D?8.x environment. Developers should use the DIConfig Sample to produce the same results in the Direct3D 9.0 environment.
Hardware vendors provide bitmaps and other display information for their device.
Before calling the method, an application can modify the text labels associated with each action by changing the value in the lptszActionName member of the DIACTION structure.
Configuration is stored for each user of each device for each game. The information can be retrieved by the IDirectInputDevice8::BuildActionMap method.
By default, acceleration is supported for these pixel formats:
A1R5G5B5
16-bit pixel format with 5 bits reserved for each color and 1 bit reserved for alpha (transparent texel).
A8R8G8B8
32-bit ARGB pixel format with alpha.
R9G8B8
24-bit RGB pixel format.
X1R5G5B5
16-bit pixel format with 5 bits reserved for each color.
X8R8G8B8
32-bit RGB pixel format with 8 bits reserved for each color.
Other formats will result in color conversion and dramatically slow the frame rate.
Note Even if the cooperative level for the application is disabling the Microsoft Windows?logo key passively through an exclusive cooperative level or actively through use of the DISCL_NOWINKEY flag, that key will be active while the default action mapping user interface (UI) is displayed.

DIERR_INVALIDPARAM	An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard Component Object Model (COM) return value.
DIERR_OUTOFMEMORY	The DirectInput subsystem couldn't allocate sufficient memory to complete the call. This value is equal to the E_OUTOFMEMORY standard COM return value.