DirectInput® 9.0 C. Shane Evans / Bernard George Program Manager DirectX Microsoft ® Corporation

Agenda Mission: Usability Mission: Usability New Features New Features Improvements Improvements Whats Next? Whats Next?

New Features Frame-based Input Frame-based Input Keyboard Text Keyboard Text New Device Enumeration Model New Device Enumeration Model New Device Object Enumeration Model New Device Object Enumeration Model Device Plug/Unplug Notifications Device Plug/Unplug Notifications Modern Device Support Modern Device Support

Frame-based Input Motivation Motivation State tracking of buttons and axes are common to the most games State tracking of buttons and axes are common to the most games Games are inherently frame-based Games are inherently frame-based Why isnt DirectInput also frame-based? Why isnt DirectInput also frame-based? Advantages Advantages Application does not need to parse buffered data Application does not need to parse buffered data Objects current states are reported Objects current states are reported Developers wont complain (as much)! Developers wont complain (as much)!

Frame-based Input Application can query DirectInput for events since the last frame Application can query DirectInput for events since the last frame Data reported in each frame is tailored to particular controls on a device Data reported in each frame is tailored to particular controls on a device Buttons Buttons Relative Axes Relative Axes Absolute Axes/POVs Absolute Axes/POVs

Frame-based Input Buttons Four states to summarize the state of a button Four states to summarize the state of a button Inactive Inactive Active Active Still Active Still Active Changed/Still Active Changed/Still Active

Frame-based Input Relative Axes Multiple axis events may occur between frames Multiple axis events may occur between frames Actual input is Actual input is To smooth these axes events, DirectInput reports their average To smooth these axes events, DirectInput reports their average Application receives Application receives

Frame-based Input Absolute Axes/POVs DirectInput simply reports the current position of absolute axes DirectInput simply reports the current position of absolute axes POVs are reported with the current single position (still as angle from N). POVs are reported with the current single position (still as angle from N). Single report is given because thats what games use. Single report is given because thats what games use.

Frame-based Input Common Data The following detailed data is provided for all types of controls for each frame The following detailed data is provided for all types of controls for each frame dwCurrent dwCurrent Current value of the control dwStart dwStart Value at beginning of frame dwMin dwMin Minimum value at during frame dwMax dwMax Maximum value at during frame

Keyboard Text Motivation Motivation Constructing strings by treating keys as objects and retrieving DIPROP_KEYNAME can be cumbersome Constructing strings by treating keys as objects and retrieving DIPROP_KEYNAME can be cumbersome Declare a DIPROPSTRING variable Declare a DIPROPSTRING variable Determine ID of key that is pressed Determine ID of key that is pressed Call IDirectInputDevice8::GetProperty to recover the string Call IDirectInputDevice8::GetProperty to recover the string Can be slow as well, since the a keys text is looked up on the fly Can be slow as well, since the a keys text is looked up on the fly

Keyboard Text Application can enable new text input with IDirectInput9::EnableKBText Application can enable new text input with IDirectInput9::EnableKBText An internal lookup table for keys is created An internal lookup table for keys is created Key lookups are much faster Key lookups are much faster Application must keep track of the state of the shift key Application must keep track of the state of the shift key Call IDirectInput9::GetKeyText with the keys object ID and shift status to recover a keys text Call IDirectInput9::GetKeyText with the keys object ID and shift status to recover a keys text

New Device Enumeration Model Motivation Motivation General shift toward pull model in DirectX ® General shift toward pull model in DirectX ® Callback functions can be complicated Callback functions can be complicated Advantages Advantages Developer has more control Developer has more control Simpler! Simpler!

New Device Enumeration Model Application can call IDirectInput9::GetDeviceCount to retrieve the number of devices on the system Application can call IDirectInput9::GetDeviceCount to retrieve the number of devices on the system Flags can optionally be passed to indicate that only subset of available devices should be enumerated Flags can optionally be passed to indicate that only subset of available devices should be enumerated Each device is internally assigned an index between 0 and the number of pertinent devices – 1 inclusive Each device is internally assigned an index between 0 and the number of pertinent devices – 1 inclusive

New Device Enumeration Model Devices are now addressed by index Devices are now addressed by index IDirectInput9::CheckDevice can test a devices capabilities IDirectInput9::CheckDevice can test a devices capabilities Force feedback Force feedback Action mapping Action mapping

New Device Enumeration Model As before, devices are created by calling CreateDevice method As before, devices are created by calling CreateDevice method Accepts device index Accepts device index Sets a pointer to an IDirectInputDevice9 interface Sets a pointer to an IDirectInputDevice9 interface Dont need to set co-op level! Dont need to set co-op level! Otherwise IDirectInput9 can be used as you would expect Otherwise IDirectInput9 can be used as you would expect

New Device Object Enumeration Model Pull model as with device enumeration Pull model as with device enumeration Application can call IDirectInputDevice9::GetObjectCount to retrieve the number of objects on a device Application can call IDirectInputDevice9::GetObjectCount to retrieve the number of objects on a device Flags can optionally be passed to indicate that only subset of available objects should be enumerated Flags can optionally be passed to indicate that only subset of available objects should be enumerated Each object is internally assigned an index between 0 and the number of pertinent objects – 1 inclusive Each object is internally assigned an index between 0 and the number of pertinent objects – 1 inclusive

New Device Object Enumeration Model Each object can now be referenced by its index Each object can now be referenced by its index Calling IDirectInputDevice9::GetObject retrieves a DIDEVICEOBJECTINSTANCE structure Calling IDirectInputDevice9::GetObject retrieves a DIDEVICEOBJECTINSTANCE structure dwOfsNative member added to DIDEVICEOBJECTINSTANCE dwOfsNative member added to DIDEVICEOBJECTINSTANCE

Plug/Unplug Notifications Applications can request to be notified when a device is plugged in or unplugged Applications can request to be notified when a device is plugged in or unplugged Call RegisterWindowMessage with DIRECTINPUT_NOTIFICATION_DEVICEPLUG message string (dinput.h) Call RegisterWindowMessage with DIRECTINPUT_NOTIFICATION_DEVICEPLUG message string (dinput.h)

Plug/Unplug Notifications When a DIRECTINPUT_NOTIFICATION_DEVICE PLUG message is received When a DIRECTINPUT_NOTIFICATION_DEVICE PLUG message is received wParam is the devices index wParam is the devices index lParam indicates the devices status lParam indicates the devices status 0 value means the device is now unplugged 0 value means the device is now unplugged Nonzero means the device is now plugged in Nonzero means the device is now plugged in

Plug/Unplug Notifications If a device is new to an application If a device is new to an application wParam is 0xFFFFFFFF wParam is 0xFFFFFFFF lParam is nonzero (plugged) lParam is nonzero (plugged) The device can be created by calling CreateDevice with the index previously returned by GetDeviceCount + 1 The device can be created by calling CreateDevice with the index previously returned by GetDeviceCount + 1

Modern Device Support Support for new controls on todays complex devices Support for new controls on todays complex devices Proportional Buttons Proportional Buttons Independent Axis Sets Independent Axis Sets

Modern Device Support Proportional Buttons Proportional Buttons dwButtonData member added to DIDEVICEOBJECTDATA to represent degree to which button is pressed dwButtonData member added to DIDEVICEOBJECTDATA to represent degree to which button is pressed Can also behave like standard buttons Can also behave like standard buttons If button pressed past threshold, it is active If button pressed past threshold, it is active Threshold implemented in property DIPROP_BUTTONTHRESHOLD Threshold implemented in property DIPROP_BUTTONTHRESHOLD IDirectInput::Get/SetButtonThreshold can manipulate threshold IDirectInput::Get/SetButtonThreshold can manipulate threshold Default is 10% of range Default is 10% of range

Modern Device Support Independent Axis Sets Independent Axis Sets Mainly a hardware thing. Games should see better mappings from DirectInput. Mainly a hardware thing. Games should see better mappings from DirectInput. Simple way of organizing axes on a device Simple way of organizing axes on a device Sets of axes are assigned ordinals Sets of axes are assigned ordinals Ordinals differentiate between multiple, say, X - axes Ordinals differentiate between multiple, say, X - axes

Improvements Joystick Control Panel Joystick Control Panel Default Cooperative Level Default Cooperative Level Simpler Device Properties Simpler Device Properties

Joystick Control Panel Test page Test page Device image added Device image added Historically confusing Apply button removed Historically confusing Apply button removed

Joystick Control Panel Settings Page Settings Page Racing Wheels pedal mode configuration for legacy games Racing Wheels pedal mode configuration for legacy games Historically confusing Apply button removed Historically confusing Apply button removed

Joystick Control Panel Calibration Calibration Better use of space in calibration wizard Better use of space in calibration wizard Additional racing wheel-specific calibration Additional racing wheel-specific calibration New steering wheel position indicator New steering wheel position indicator Accelerator/Brake discovery and calibration Accelerator/Brake discovery and calibration

Joystick Control Panel

Default Cooperative Level Cooperative level need not be explicitly set Cooperative level need not be explicitly set Default cooperative level set during device creation Default cooperative level set during device creation Similar to DISCL_FOREGROUND | DISCL_NONEXCLUSIVE with added benefits Similar to DISCL_FOREGROUND | DISCL_NONEXCLUSIVE with added benefits Works for Force Feedback devices Works for Force Feedback devices

Default Cooperative Level Devices do not need to be explicitly reacquired Devices do not need to be explicitly reacquired Use DISCL_FOCUSACQUIRE in IDirectInputDevice9:: SetCooperativeLevel Use DISCL_FOCUSACQUIRE in IDirectInputDevice9:: SetCooperativeLevel Automatic acquisition when application gains focus Automatic acquisition when application gains focus Only valid with foreground cooperative levels Only valid with foreground cooperative levels

Simpler Device Properties Separate methods to set each property rather than just IDirectInputDevice8::Get/SetProperty Separate methods to set each property rather than just IDirectInputDevice8::Get/SetProperty MUCH simpler than before MUCH simpler than before

Simpler Device Properties DirectInput 8.0 Example For example, the following code is needed to set the range of the X-axis with DirectInput 8.0 For example, the following code is needed to set the range of the X-axis with DirectInput 8.0 // DirectX 8.0 code for changing a // property DIPROPRANGE diprg; ZeroMemory(&diprg, sizeof(diprg)); diprg.diph.dwObj = DIJOFS_X; diprg.lMin = -1000; diprg.lMax = +1000; err = pDIDev->SetProperty(DIPROP_RANGE, &diprg.diph);

Simpler Device Properties DirectInput 9.0 Example The same task can now be done with the following code The same task can now be done with the following code // Equivalent DirectX 9.0 code err = pDIDev->SetAxisRange(AXIS_X, -1000, +1000);

Device Image Display Object SDK sample code that performs simple device image rendering tasks SDK sample code that performs simple device image rendering tasks Very easy to incorporate device images into your game Very easy to incorporate device images into your game Exposes simple methods to perform common but often code-intensive tasks Exposes simple methods to perform common but often code-intensive tasks Display device Display device Change view Change view Show callout, display text Show callout, display text Highlight callout Highlight callout

DirectInput® 9.0 Questions? Contact: