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.

The Wheel API is designed to minimize the amount of data that is uploaded to the device. The API also gives you full control of when data is transferred. Whenever possible, the API uses a single transaction to transfer multiple items.

Equations

Force-feedback wheel devices support up to 16 force-feedback equations, each of which is referenced by index (in the range [0, 15]). Force-feedback equations are comprised of a series of one or more assembly language instructions that are defined by your application. Before they can be used, these equations must be compiled into a compact byte-code representation and uploaded to the device, where they are processed in index order.

Important Reference documentation for the assembly language that defines force-feedback equations is shipped as PDF files with the Xbox One XDK. These PDFs are located under your XDK installation at %DurangoXDK%\xdk\Extensions\Xbox Wheel API\8.0\Documentation.

Parameters

Parameters for force-feedback equations can be any of the following:

Physical readings from the wheel device, such as the rotation angle of the wheel or the position of the throttle.
Values computed by the equation itself or by other equations.
Variables in the device’s application memory, which is a section of memory on the device that is writable by your application. For more information about application memory, see the Application memory section in this topic.

States

Your application can control the state of each force-feedback equation individually. The following table lists the possible states for the equation at a specified index on the wheel device.

State	Description
Unset	No equation is defined for the specified index. An equation that is placed into this state will be removed from the device, and a new equation can be created in its place.
Stopped	An equation is defined at the specified index, but it is not running. Equations can place themselves in the Stopped state.
Running	The equation is currently running.
Paused	Execution of the equation is currently paused.
Faulted	The equation has caused a run-time error. Because equations can be interdependent, all equations are placed in the Stopped state if any equation faults. You can move the equation out of the Faulted state by putting it in the Stopped, Running, or Unset state. You should determine why the run-time error occured and fix the equation on the device. Equation faults are reported up from the device, and are available to your application through an EquationFaultEvent delegate. Note Faulted is the only state that cannot be set by your application.

Updating equations

Before a force-feedback equation can be used, it must be compiled into a compact byte-code representation and uploaded to the wheel device. To do this, call the Wheel.CreateEquationOnDevice method. If the equation refers to a variable that has not been declared by your application, this call will cause an error and prevent the equation from being uploaded. The same is true if the equation contains assembler errors.

To remove an equation from the device, call the Wheel.ClearEquation method. You can also call the Wheel.ClearAllEquations method to remove all equations from the device. Clearing an equation frees up all memory that is used by the equation. The device is responsible for managing memory to avoid fragmentation.

Changing the state of an equation (such as starting or pausing the equation) is a multiple-step process that allows you to upload multiple equation operations as a batch, which can reduce USB traffic. Because of the limitation on the number of transactions that can occur during a single game frame (generally around four), this can significantly improve USB bus efficiency. Changing the state of an equation on the device requires the following steps:

Mark the equation as requesting a state change by calling the appropriate method (for example, Wheel.StopEquation). This call does not affect the equation on the device.
Call the Wheel.UpdateEquationsToDevice method, which updates all equations on the device.

Application memory

Every force-feedback wheel device contains two kilobytes of application memory that force-feedback equations can read from and write to. This memory can also be written through the API, and can be read through the API for debugging purposes. Application memory is represented as an array of 512 4-byte values that are addressed by index (in the range [0, 511]) instead of by byte offset.

Force-feedback equations utilize application memory through defined variables in the assembly code, referring to them by a human-readable name. Variable names are Unicode, can be of any length, are not case-sensitive, and must contain only alphanumeric and underscore (“_”) characters. Variable names must begin with either an underscore or an alphabetic character.

Variables in application memory are typeless. When an equation is run, any executed assembly language instructions define the type of their operands. If an operand is a variable in application memory, the value is read as the type that the instruction specifies, regardless of the data that is contained in the variable.

When an equation is created on the device, the available memory that remains on the device is distributed to the equation. The equation can use any amount of this remaining available memory. Attempting to create an equation that requires more than the available memory will cause an E_OUTOFMEMORY exception.

Updating application memory

Before a variable can be used, it must be uploaded to application memory on the wheel device. To do this, call the Wheel.CreateVariable method.

Equations which reference variables depend on the variables for the entire lifetime of the equation. To avoid problems that could arise from this dependence, variables cannot be unallocated without first clearing all equations. The only way to remove a variable from application memory is to call the Wheel.ResetDevice method, which clears all equations and variables on the device.

Changing the value of a variable in application memory requires the following steps:

Mark the variable as requesting a value change by calling the Wheel.SetVariableFloat or Wheel.SetVariableUnsigned method. This call does not affect the variable on the device.
Call the Wheel.UpdateVariablesToDevice method, which updates up to ten variables on the device. Because the number of transactions per frame is limited, you should be aware of the number of transactions this instruction will generate, and control it accordingly. After this call, the state of the updated variables is cleared so that the values will not be uploaded by subsequent calls to the UpdateVariablesToDevice method until the next time that they are modified by the application.