DirectX Input API Reference

The DirectX Input API provides a robust framework for handling user input from various devices such as keyboards, mice, gamepads, joysticks, and more. It allows developers to efficiently process input events, manage device states, and integrate with the graphics pipeline for interactive experiences.

Getting Started

To begin using the DirectX Input API, you typically need to initialize the DirectInput COM object, enumerate available input devices, and create input devices for the types you intend to use. This involves interacting with core interfaces like IDirectInput8 and IDirectInputDevice8.

Here's a simplified outline of the initialization process:


    HRESULT hr;
    IDirectInput8* pDI = nullptr;
    // Initialize the COM library
    CoInitialize(nullptr);
    // Create a DirectInput object
    hr = DirectInput8Create(
        GetModuleHandle(NULL),
        DIRECTINPUT_VERSION,
        IID_IDirectInput8,
        (void**)&pDI,
        nullptr
    );
    if (FAILED(hr)) {
        // Handle error
        return hr;
    }
    // ... further steps to enumerate and acquire devices

Device Interfaces

The core of input handling revolves around device interfaces. These interfaces allow you to query device capabilities, set data formats, retrieve input data, and manage device acquisition.

IDirectInput8

The main interface for interacting with the DirectInput subsystem. Used for creating device objects and enumerating devices.

Methods:

  • CreateDevice: Creates an instance of a device object.
  • EnumDevices: Enumerates all input devices attached to the system.
  • FindDevice: Finds a device object based on a GUID.

IDirectInputDevice8

Represents a specific input device. Used for configuring and reading data from a device.

Methods:

  • SetDataFormat: Sets the data format for the device.
  • Acquire: Acquires the device, making it available for input.
  • Unacquire: Releases the device.
  • GetDeviceState: Retrieves the current state of the device.
  • GetDeviceData: Retrieves buffered input data.
  • EnumEffects: Enumerates available effects (e.g., force feedback).

IDirectInputEffect

Represents a specific effect on a device, typically used for force feedback.

Methods:

  • SetParameters: Sets the parameters for an effect.
  • Start: Starts playing an effect.
  • Stop: Stops an effect.

Key Structures and Enums

DirectInput utilizes several structures and enumerations to define device types, data formats, and input states.

Structures

DIDEVCAPS

Describes the capabilities of a device.


    typedef struct DIDEVCAPS {
        DWORD  dwSize;
        DWORD  dwFlags;
        DWORD  dwDevType;
        DWORD  dwAxes;
        DWORD  dwPOVs;
        DWORD  dwFFSamplePeriod;
        DWORD  dwFFMaxTextLength;
        DWORD  dwFFNumEffects;
        DWORD  dwFFConcurrentEffects;
        // ... more members
    } DIDEVCAPS, *LPDIDEVCAPS;

DIJOYSTATE2

Represents the state of a joystick or gamepad, including buttons, axes, and point-of-view controls.


    typedef struct DIJOYSTATE2 {
        LONG  lX;
        LONG  lY;
        LONG  lZ;
        LONG  lRX;
        LONG  lRY;
        LONG  lRZ;
        LONG  prdX;
        LONG  prdY;
        LONG  prdZ;
        DWORD rgdwPOV[4];
        DWORD dwButtons[4];
        DWORD dwVavle[112];
        // ... more members
    } DIJOYSTATE2, *LPDISJOYSTATE2;

Enumerations

DIPROPERTY

Specifies properties that can be set or retrieved for a device or effect.


    typedef enum DIPROPERTY_GET {
        DIPROP_APPLY                  = 0x00000000,
        DIPROP_KEY                   = 0x00000001,
        DIPROP_RANGE                 = 0x00000002,
        DIPROP_DEADZONE              = 0x00000003,
        DIPROP_SATURATION            = 0x00000004,
        DIPROP_Vsetlength            = 0x00000005,
        DIPROP_FFGAIN                = 0x00000006,
        // ... more properties
    } DIPROPERTY;

DIDFT

Defines the type of data format for a device.


    typedef enum DIDFT_ {
        DIDFT_ALL                    = 0,
        DIDFT_BUTTON                 = 1,
        DIDFT_POV                    = 2,
        DIDFT_AXIS                   = 4,
        DIDFT_COLLECTION             = 8,
        DIDFT_NODATA                 = 16,
        // ... more types
    } DIDFT;

Note on Data Formats

Understanding and setting the correct data format using SetDataFormat is crucial. DirectInput provides predefined formats like c_dfDIJoystick and allows custom formats for specific device layouts.

Core Functions

DirectInput8Create

Creates an instance of the DirectInput COM object.


    HRESULT DirectInput8Create(
        HINSTANCE hinst,
        DWORD     dwVersion,
        REFIID    riidltf,
        LPVOID    *ppvOut,
        LPUNKNOWN pUnkOuter
    );

Parameters:

hinst: Instance handle of the client application.
dwVersion: The DirectInput version. Use DIRECTINPUT_VERSION.
riidltf: The IID of the interface to create (IID_IDirectInput8).
ppvOut: Address of a pointer to be filled with the created object.
pUnkOuter: For COM aggregation. Typically nullptr.

IDirectInputDevice8::Acquire

Acquires the input device, making it ready to receive input.


    HRESULT Acquire();

Remarks

The application must acquire a device before it can read data from it. Acquiring a device typically grants it exclusive or non-exclusive access to the device's input stream, depending on the application's needs.

IDirectInputDevice8::GetDeviceState

Retrieves the current state of the device.


    HRESULT GetDeviceState(
        DWORD     cbData,
        LPVOID    lpvData
    );

Parameters:

cbData: Size of the buffer pointed to by lpvData.
lpvData: Pointer to a buffer that will receive the device state. The structure type depends on the device's data format.

Advanced Topics