Platform SDK: DirectX

Creating a DirectInput Device

To get input data from a device, you first have to create an object to represent that device.

[C++]

The IDirectInput7::CreateDeviceEx method is used to obtain a pointer to the IDirectInputDevice7 interface. Methods of this interface are then used to manipulate the device and obtain data.

The code following example, where lpdi is a pointer to the IDirectInput7 interface, creates a keyboard device:

LPDIRECTINPUTDEVICE7  lpdiKeyboard; 
lpdi->CreateDeviceEx(GUID_SysKeyboard, IID_IDirectInputDevice7,
        (void**)&lpdiKeyboard, NULL); 

The first parameter in IDirectInput7::CreateDeviceEx is an instance GUID that identifies the instance of the device for which the interface is to be created. DirectInput has two predefined GUIDs, GUID_SysMouse and GUID_SysKeyboard, which represent the system mouse and keyboard. You can pass these identifiers into the CreateDeviceEx method. The global variable GUID_Joystick should not be used as a parameter for CreateDeviceEx because it is a product GUID, not an instance GUID.

Note  If the computer has more than one mouse, input from all of them is combined to form the system device. The same is true for multiple keyboards.

DirectInput provides four other predefined GUIDs primarily for testing. These are GUID_SysKeyboardEm, GUID_SysKeyboardEm2, GUID_SysMouseEm, and GUID_SysMouseEm2. Passing one of these GUIDs to CreateDeviceEx grants access to the system keyboard or mouse through an emulation layer, at either level 1 or level 2. These GUIDs always represent the system mouse or keyboard. They are aliases for GUID_SysKeyboard and GUID_SysMouse, so they are not enumerated by IDirectInput7::EnumDevices unless the DIEDFL_INCLUDEALIASES flag is passed.

For devices other than the system mouse or keyboard, use the instance GUID for the device returned by IDirectInput7::EnumDevices. The instance GUID for a device is always the same. You can allow the user to select a device from a list of those enumerated, then save the GUID to a configuration file and use it again in future sessions.

[Visual Basic]

The DirectInput.CreateDevice method is used to obtain a DirectInputDevice object. Methods of this interface are then used to manipulate the device and obtain data.

The following code example, where di is the DirectInput object, creates a keyboard device:

Dim diDev As DirectInputDevice
Set diDev = di.CreateDevice("GUID_SysKeyboard")

The parameter is an alias for a GUID that identifies the instance of the device for which the interface is to be created. DirectInput provides two predefined GUIDs, GUID_SysMouse and GUID_SysKeyboard, which represent the system mouse and keyboard, and you can pass either of these to the CreateDevice method.

Note  If the computer has more than one mouse, input from all of them is combined to form the system device. The same is true for multiple keyboards.

For devices other than the system mouse or keyboard, use the instance GUID for the device obtained from DirectInputDeviceInstance.GetGuidInstance. The instance GUID for a device is always the same. You can allow the user to select a device from a list of those enumerated, then save the GUID to a configuration file and use it again in future sessions.

In the following code example, it is presumed that the application has enumerated devices and found a suitable one, diDevInstance, which is to be created as a DirectInputDevice:

Dim guid As String
guid = diDevInstance.GetGuidInstance
Set diDev = di.CreateDevice(guid)

For more information on obtaining the DirectInputDeviceInstance object, see DirectInput Device Enumeration.