Wheel Devices

Xbox One provides expanded capabilities for force-feedback wheel devices, allowing you to completely define and control your own force-feedback equations.

This topic contains the following sections:

Overview

Wheels have a number of fixed characteristics and features. These values often differ from model to model, but remain static for a specific device. Fixed values include the bits of precision for the brake and the wheel’s rotation angle, the number of vibration motors on the device, and so on.

Some wheel devices support force feedback. Force feedback simulates how a steering wheel in a real vehicle would respond to events such as collisions and track conditions. It does this by using a motor that can programatically change the rotation of the wheel device, governed by equations. Using the Xbox One XDK, you can fully define your own force-feedback equations and parameters, upload them to the wheel device, and then run the equations from within your game. For more information, see Force Feedback.

Wheel devices report their current state to the application at speeds of up to four milliseconds per reading. Device state is reported only when the state of the device changes, with an additional state request that is made by the underlying driver during initialization. Wheel devices avoid spamming the bus with extraneous reports; however, it is not unusual to see reports without any apparent changes (other than the timestamp).

Transactions with the device are limited to 64 bytes every four milliseconds. In an application running at 60 frames per second (about 16.7ms per frame), this means that up to four transactions can be sent to the device per frame. The API is designed to give you more control over and visibility into the number of transactions. Naming conventions indicate which calls generate one or more transactions with the device.

Setting up your project

To use the Wheel API, you must first reference the Wheel .winmd file from your project.

To reference the Wheel .winmd file from your project

  1. Load your project in Microsoft Visual Studio.
  2. On the View menu, click Solution Explorer.
  3. In the Solution Explorer pane, right-click the name of your project and then click Properties.
  4. In the Common Properties section of the Property Pages dialog box, select Framework and References.
  5. In the Framework and References property page, click Add New Reference.
  6. In the Add Reference dialog box, click the Browse button at the bottom right.
  7. In the Select the files to reference dialog box, do the following:
    1. Navigate to “%DurangoXDK%\xdk\Extensions\Xbox Wheel API\8.0\References\CommonConfiguration\neutral”.
    2. Select the Microsoft.Xbox.Input.Wheel.winmd file.
    3. Click Add.

If the project was set up correctly and the DLL is in the same folder as Microsoft.Xbox.Input.Wheel.winmd, the following <Extension> element should have been automatically added to the main package object of your project’s appxmanifest.xml file.

<Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
        <InProcessServer>
            <Path>Microsoft.Xbox.Input.Wheel.dll</Path>
            <ActivatableClass  ActivatableClassId="Microsoft.Xbox.Input.Wheel" ThreadingModel="both" />
        </InProcessServer>
    </Extension>
</Extensions>

This performs the proper registration, which indicates that the wheel DLL contains the listed type class.

The appxmanifest.xml file and the Microsoft.Xbox.Input.Wheel.dll will be placed in your project’s layout\image\loose folder when built from Microsoft Visual Studio. During deployment, files in this folder are overwritten with the application executable.

Getting information about the capabilities of a wheel

A Wheel object represents a single instance of a wheel device attached to a Xbox One console. It provides the GetCurrentReading method, which retrieves the current state of the device. It also provides the GetStaticConfiguration method, which gets the physical capabilities of the device.

Unlike the Gamepad class, there is no static list of the wheels connected to the console—you must enumerate the devices yourself. Alternatively, you can listen for controller connection events on the IController interface, determine whether the new controller is a wheel, and then cast appropriately, as shown in the following example.

Important Problems can arise if you mistakenly identify other input devices as wheels. To avoid these issues, make sure to get a valid pointer when trying to cast to IWheel.

C++

void OnControllerAdded(IController^ pIController)
{
    if (dynamic_cast<Microsoft::Xbox::Input::IWheel^>(pIController) != nullptr)
    {
        auto^ pWheel = (Microsoft::Xbox::Input::Wheel ^)(pIController);
        auto^ pIWheel = (Microsoft::Xbox::Input::IWheel^)(pIController);
    }
}

The user that is associated with a wheel can be retrieved from the Controller object.

C++

void OnControllerAdded_(IController^ pIController)
{
    if (dynamic_cast<Microsoft::Xbox::Input::IWheel^>(pIController) != nullptr)
    {
        Windows::Xbox::System::User^ user = pIController->User;
    }
}

Alternatively, you can get the user from the Wheel object (which implements IController).

C++

void OnControllerAdded_(IController^ pIController)
{
    if (dynamic_cast<Microsoft::Xbox::Input::IWheel^>(pIController) != nullptr)
    {
        Microsoft::Xbox::Input::Wheel^ pWheel = (Wheel^)(pIController);
        Windows::Xbox::System::User^ user = pWheel->User;
    }
}

Once you have retrieved the user object, you can cast directly to an IUser interface.

C++

Windows::Xbox::System::IUser^ pIUser = user;

The Wheel class and IWheel interface implement the INavigationController interface, and can be directly cast to this type.

C++

auto^ pIWheel = (Microsoft::Xbox::Input::IWheel^)(pIController);
auto^ pINavController = (Windows::Xbox::Input::INavigationController ^)pIWheel;

Getting the current state of a wheel

The WheelReading class represents a single reading from an wheel device. It provides information about the current state of the wheel’s rotation angle, as well as the current state of the brake, clutch, shifter, buttons, and so on.

Troubleshooting

How do I avoid Warning C4691?

After including the provided reference Microsoft.Xbox.Wheel.dll you may see a few warnings similar to the following.

application.cpp(672): warning C4691: 'Windows::Foundation::DateTime' : type referenced was expected in unreferenced assembly 'Windows.Foundation',
type defined in current translation unit used instead
This diagnostic occurred while importing type 'Microsoft::Xbox::IWheelReading ' from assembly 'Microsoft.Xbox.Wheel, Version=255.255.255.255,
Culture=neutral, PublicKeyToken=null'.

This is caused by types pulled in both by the wheel DLL and by your application. The warning can be safely ignored. In Microsoft Visual Studio, you can suppress this warning for your entire project or for individual files. To do this, open the property page for the project or file. Expand Configuration Properties, expand C/C++, and then select Advanced. Add the warning number to the Disable Specific Warnings list.

In this section

Force Feedback for Wheel Devices
Xbox One provides expanded capabilities for force-feedback wheel devices, allowing you to completely define and control your own force-feedback equations.

See also

Overview

Input Technologies and Devices Overviews

Reference

Wheel Class

WheelReading Class

WheelStaticConfiguration Class