DirectInputDirectInput® 9.0® 9.0

C. Shane Evans / Bernard GeorgeC. Shane Evans / Bernard George

Program ManagerProgram ManagerDirectXDirectX

MicrosoftMicrosoft®® Corporation Corporation

AgendaAgenda

Mission: UsabilityMission: Usability New FeaturesNew Features ImprovementsImprovements What’s Next?What’s Next?

New FeaturesNew Features

Frame-based InputFrame-based Input Keyboard TextKeyboard Text New Device Enumeration ModelNew Device Enumeration Model New Device Object Enumeration ModelNew Device Object Enumeration Model Device Plug/Unplug NotificationsDevice Plug/Unplug Notifications Modern Device SupportModern Device Support

Frame-based InputFrame-based Input

MotivationMotivation State tracking of buttons and axes are State tracking of buttons and axes are

common to the most gamescommon to the most games Games are inherently frame-basedGames are inherently frame-based Why isn’t DirectInput also frame-based?Why isn’t DirectInput also frame-based?

AdvantagesAdvantages Application does not need to parse Application does not need to parse

buffered databuffered data Objects’ current states are reportedObjects’ current states are reported Developers won’t complain (as much)!Developers won’t complain (as much)!

Frame-based InputFrame-based Input

Application can query DirectInput for Application can query DirectInput for events since the last “frame”events since the last “frame”

Data reported in each frame is tailored Data reported in each frame is tailored to particular controls on a deviceto particular controls on a device ButtonsButtons Relative AxesRelative Axes Absolute Axes/POVsAbsolute Axes/POVs

Frame-based InputFrame-based InputButtonsButtons Four states to summarize the state of a Four states to summarize the state of a

buttonbutton InactiveInactive ActiveActive Still ActiveStill Active Changed/Still ActiveChanged/Still Active

Frame-based InputFrame-based InputRelative AxesRelative Axes Multiple axis events may occur between Multiple axis events may occur between

framesframesActual input is < 15 | 20 30 | 3 | 10 8 >Actual input is < 15 | 20 30 | 3 | 10 8 >

To “smooth” these axes events, DirectInput To “smooth” these axes events, DirectInput reports their averagereports their average

Application receives < 15 | 25 | 3 | 9 >Application receives < 15 | 25 | 3 | 9 >

Frame-based InputFrame-based InputAbsolute Axes/POVsAbsolute Axes/POVs DirectInput simply reports the current DirectInput simply reports the current

position of absolute axesposition of absolute axes

POVs are reported with the current POVs are reported with the current single position (still as angle from N).single position (still as angle from N).

Single report is given because that’s Single report is given because that’s what games use.what games use.

Frame-based InputFrame-based InputCommon DataCommon Data The following detailed data is provided The following detailed data is provided

for all types of controls for each framefor all types of controls for each frame dwCurrentdwCurrent

Current value of the controlCurrent value of the control dwStartdwStart

Value at beginning of frameValue at beginning of frame dwMindwMin

Minimum value at during frameMinimum value at during frame dwMaxdwMax

Maximum value at during frameMaximum value at during frame

Keyboard TextKeyboard Text

MotivationMotivation Constructing strings by treating keys as Constructing strings by treating keys as

objects and retrieving objects and retrieving DIPROP_KEYNAMEDIPROP_KEYNAME can be cumbersomecan be cumbersome Declare a Declare a DIPROPSTRINGDIPROPSTRING variable variable Determine ID of key that is pressedDetermine ID of key that is pressed Call Call IDirectInputDevice8::GetProperty IDirectInputDevice8::GetProperty to to

recover the stringrecover the string

Can be slow as well, since the a key’s text Can be slow as well, since the a key’s text is looked up on the flyis looked up on the fly

Keyboard TextKeyboard Text

Application can enable new text input Application can enable new text input with with IDirectInput9::EnableKBTextIDirectInput9::EnableKBText An internal lookup table for keys is createdAn internal lookup table for keys is created Key lookups are much fasterKey lookups are much faster

Application must keep track of the state Application must keep track of the state of the shift keyof the shift key

Call IDirectInput9::GetKeyText with the Call IDirectInput9::GetKeyText with the key’s object ID and shift status to key’s object ID and shift status to recover a key’s textrecover a key’s text

New Device Enumeration New Device Enumeration ModelModel MotivationMotivation

General shift toward “pull model” in General shift toward “pull model” in DirectXDirectX®®

Callback functions can be complicatedCallback functions can be complicated

AdvantagesAdvantages Developer has more controlDeveloper has more control Simpler!Simpler!

New Device Enumeration New Device Enumeration ModelModel Application can call Application can call

IDirectInput9::GetDeviceCount IDirectInput9::GetDeviceCount to to retrieve the number of devices on the retrieve the number of devices on the systemsystem Flags can optionally be passed to indicate Flags can optionally be passed to indicate

that only subset of available devices that only subset of available devices should be enumeratedshould be enumerated

Each device is internally assigned an index Each device is internally assigned an index between 0 and the number of pertinent between 0 and the number of pertinent devices – 1 inclusivedevices – 1 inclusive

New Device Enumeration New Device Enumeration ModelModel Devices are now addressed by indexDevices are now addressed by index IDirectInput9::CheckDeviceIDirectInput9::CheckDevice can can

test a device’s capabilitiestest a device’s capabilities Force feedback Force feedback Action mappingAction mapping

New Device Enumeration New Device Enumeration ModelModel As before, devices are created by As before, devices are created by

calling calling CreateDeviceCreateDevice method method Accepts device indexAccepts device index Sets a pointer to an Sets a pointer to an

IDirectInputDevice9 IDirectInputDevice9 interfaceinterface

Don’t need to set co-op level!Don’t need to set co-op level! Otherwise Otherwise IDirectInput9IDirectInput9 can be used can be used

as you would expectas you would expect

New Device Object New Device Object Enumeration ModelEnumeration Model ““Pull model” as with device Pull model” as with device

enumerationenumeration Application can call Application can call

IDirectInputDevice9::GetObjectCountIDirectInputDevice9::GetObjectCount to retrieve the number of objects on a to retrieve the number of objects on a devicedevice Flags can optionally be passed to indicate Flags can optionally be passed to indicate

that only subset of available objects should that only subset of available objects should be enumeratedbe enumerated

Each object is internally assigned an index Each object is internally assigned an index between 0 and the number of pertinent between 0 and the number of pertinent objects – 1 inclusiveobjects – 1 inclusive

New Device Object New Device Object Enumeration ModelEnumeration Model Each object can now be referenced by Each object can now be referenced by

its indexits index Calling Calling

IDirectInputDevice9::GetObject IDirectInputDevice9::GetObject retrieves a retrieves a DIDEVICEOBJECTINSTANCE DIDEVICEOBJECTINSTANCE structurestructure

dwOfsNativedwOfsNative member added to member added to DIDEVICEOBJECTINSTANCE DIDEVICEOBJECTINSTANCE

Plug/Unplug NotificationsPlug/Unplug Notifications

Applications can request to be notified Applications can request to be notified when a device is plugged in or when a device is plugged in or unpluggedunplugged Call Call RegisterWindowMessageRegisterWindowMessage with with

DIRECTINPUT_NOTIFICATION_DEVICEPLUG DIRECTINPUT_NOTIFICATION_DEVICEPLUG message string (dinput.h)message string (dinput.h)

Plug/Unplug NotificationsPlug/Unplug Notifications

When a When a DIRECTINPUT_NOTIFICATION_DEVICEDIRECTINPUT_NOTIFICATION_DEVICEPLUG PLUG message is receivedmessage is received wParam wParam is the device’s indexis the device’s index lParam lParam indicates the device’s statusindicates the device’s status

0 value means the device is now unplugged0 value means the device is now unplugged Nonzero means the device is now plugged inNonzero means the device is now plugged in

Plug/Unplug NotificationsPlug/Unplug Notifications

If a device is new to an applicationIf a device is new to an application wParam wParam is is 0xFFFFFFFF0xFFFFFFFF lParam lParam is nonzero (plugged)is nonzero (plugged) The device can be created by calling The device can be created by calling

CreateDeviceCreateDevice with the index previously with the index previously returned by returned by GetDeviceCountGetDeviceCount + 1 + 1

Modern Device SupportModern Device Support

Support for new controls on today’s Support for new controls on today’s complex devicescomplex devices Proportional ButtonsProportional Buttons Independent Axis SetsIndependent Axis Sets

Modern Device SupportModern Device Support Proportional ButtonsProportional Buttons

dwButtonDatadwButtonData member added to member added to DIDEVICEOBJECTDATA DIDEVICEOBJECTDATA to represent to represent degree to which button is presseddegree to which button is pressed

Can also behave like standard buttonsCan 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 Threshold implemented in property

DIPROP_BUTTONTHRESHOLDDIPROP_BUTTONTHRESHOLD IDirectInput::Get/SetButtonThreshold IDirectInput::Get/SetButtonThreshold

can manipulate thresholdcan manipulate threshold Default is 10% of rangeDefault is 10% of range

Modern Device SupportModern Device Support

Independent Axis SetsIndependent Axis Sets Mainly a hardware thing. Games should Mainly a hardware thing. Games should

see better mappings from DirectInput.see better mappings from DirectInput. Simple way of organizing axes on a deviceSimple way of organizing axes on a device Sets of axes are assigned ordinalsSets of axes are assigned ordinals Ordinals differentiate between multiple, Ordinals differentiate between multiple,

say, X - axessay, X - axes

ImprovementsImprovements

Joystick Control PanelJoystick Control Panel Default Cooperative LevelDefault Cooperative Level Simpler Device PropertiesSimpler Device Properties

Joystick Control PanelJoystick Control Panel

““Test” pageTest” page Device image Device image

addedadded

Historically Historically confusing confusing “Apply” button “Apply” button removedremoved

Joystick Control PanelJoystick Control Panel

Settings PageSettings Page Racing Wheels Racing Wheels

pedal mode pedal mode configuration configuration for legacy for legacy gamesgames

Historically Historically confusing confusing “Apply” button “Apply” button removedremoved

Joystick Control PanelJoystick Control Panel

CalibrationCalibration Better use of space in calibration wizardBetter use of space in calibration wizard Additional racing wheel-specific calibrationAdditional racing wheel-specific calibration

New steering wheel position indicatorNew steering wheel position indicator Accelerator/Brake discovery and calibrationAccelerator/Brake discovery and calibration

Joystick Control PanelJoystick Control Panel

Joystick Control PanelJoystick Control Panel

Joystick Control PanelJoystick Control Panel

Default Cooperative LevelDefault Cooperative Level Cooperative level need not be explicitly Cooperative level need not be explicitly

setset Default cooperative level set during Default cooperative level set during

device creationdevice creation Similar to Similar to DISCL_FOREGROUND | DISCL_FOREGROUND |

DISCL_NONEXCLUSIVEDISCL_NONEXCLUSIVE with added benefits with added benefits Works for Force Feedback devicesWorks for Force Feedback devices

Default Cooperative LevelDefault Cooperative Level

Devices do not need to be explicitly Devices do not need to be explicitly reacquiredreacquired Use Use DISCL_FOCUSACQUIREDISCL_FOCUSACQUIRE in in

IDirectInputDevice9:: IDirectInputDevice9:: SetCooperativeLevelSetCooperativeLevel

Automatic acquisition when application Automatic acquisition when application gains focusgains focus

Only valid with foreground cooperative Only valid with foreground cooperative levelslevels

Simpler Device PropertiesSimpler Device Properties

Separate methods to set each property Separate methods to set each property rather than just rather than just IDirectInputDevice8::Get/SetPropertyIDirectInputDevice8::Get/SetProperty

MUCH simpler than beforeMUCH simpler than before

Simpler Device PropertiesSimpler Device PropertiesDirectInput 8.0 ExampleDirectInput 8.0 Example For example, the following code is needed to For example, the following code is needed to

set the range of the X-axis with DirectInput 8.0 set the range of the X-axis with DirectInput 8.0 // DirectX 8.0 code for changing a // DirectX 8.0 code for changing a

// property// property

DIPROPRANGE diprg;DIPROPRANGE diprg;

ZeroMemory(&diprg, sizeof(diprg));ZeroMemory(&diprg, sizeof(diprg));

diprg.diph.dwObj = DIJOFS_X;diprg.diph.dwObj = DIJOFS_X;

diprg.lMin = -1000;diprg.lMin = -1000;

diprg.lMax = +1000;diprg.lMax = +1000;

err = pDIDev->SetProperty(DIPROP_RANGE, err = pDIDev->SetProperty(DIPROP_RANGE, &diprg.diph); &diprg.diph);

Simpler Device PropertiesSimpler Device PropertiesDirectInput 9.0 ExampleDirectInput 9.0 Example The same task can now be done with The same task can now be done with

the following codethe following code// Equivalent DirectX 9.0 code// Equivalent DirectX 9.0 code

err = pDIDev->SetAxisRange(AXIS_X, err = pDIDev->SetAxisRange(AXIS_X, -1000, +1000);-1000, +1000);

Device Image Display ObjectDevice Image Display Object

SDK sample code that performs simple SDK sample code that performs simple device image rendering tasksdevice image rendering tasks

Very easy to incorporate device images Very easy to incorporate device images into your gameinto your game

Exposes simple methods to perform Exposes simple methods to perform common but often code-intensive tasks common but often code-intensive tasks Display deviceDisplay device Change viewChange view Show callout, display textShow callout, display text Highlight calloutHighlight callout

DirectInput® 9.0 DirectInput® 9.0

Questions?Questions?

Contact: Contact: ShaneE@microsoft.comShaneE@microsoft.com