Using the Oculus Rift Sensor Input Events

The new Torque 3D Oculus Rift input device provides a number of head tracking sensor input events that may be used with Torque 3D's action map system. There are a few different ways to use the Oculus Rift input device, which are set up using global TorqueScript variables.

Action Map Device Type

When binding a TorqueScript function to an Oculus Rift sensor input event using Torque 3D's action map system, the device name to use is oculusvr. As all connected Oculus Rift sensors and any stand alone sensors are handled through the same input device there is no need to append a device instance number to the end of the device name. The following is an example of setting up a proper action map binding:

moveMap.bind( oculusvr, ovr_sensorrotang0, OVRSensorRotEuler );

Sensor Absolute Rotation Events

The OculusVR sensor is able to detect an absolute rotation in space. This means that the sensor that is included within the Oculus Rift head mounted display is able to report the head's absolute rotation. While in theory the OculusVR SDK supports more than one sensor plugged into your computer, individual sensors are not currently available for testing. Because of this Torque 3D currently only supports a single OculusVR sensor -- the one that is within the Oculus Rift. This sensor is reported as index 0. It is straight forward to expand the number of supported sensors when and if Oculus starts offering individual ones for sale.

Sensor rotation events may be reported in two different way: using an angled axis or using Euler angles. One or both of these forms may be chosen and it depends on your own application. To activate the angled axis form of rotation reporting you may set the TorqueScript global variable $OculusVR::GenerateAngleAxisRotationEvents to true. To activate the Euler angle form, set the TorqueScript global variable $OculusVR::GenerateEulerRotationEvents to true.

The following action map input events are available depending on how these two global variables are set:

• ovr_sensorrot0 - Absolute rotation in angled axis form (vector plus angle)
• ovr_sensorrotang0 - Absolute rotation in Euler angle form (about x, y, and z axis)

Normally when working with rotation events you would want to work with the angled axis form. This prevents issues such as gimbal lock and Torque 3D's internal structures make it easy to work with (you could convert it to a forward vector with a couple of TorqueScript functions, for example). Both the Leap Motion and Razer Hydra input devices operate this way.

However, for the Oculus Rift there is a special use case that often has you turn to using Euler angles. As the sensor's rotation represents the user's head rotation you often want to supplement this with input from a mouse or gamepad (joystick). By adding in the relative input from one of these devices you may effectively turn the player's head in-game without requiring the actual user to spin in their chair 360 degrees (or more). The Player class does this internally when combined with the ExtendedMove class and the appropriate GameConnection control scheme is set, for example. Under this use case you will want to use the ovr_sensorrotang0 form of the rotation input event.

Using Rotation Input Events

You bind OculusVR sensor rotation events to an action map just like any other input event. Here is an example of making use of the rotation (the Euler angle version) events generated by the Oculus Rift sensor (place it in scripts/client/default.bind.cs):

// This function receives the Euler angle input event with rotation
// about the x, y, and z axis.
function OVRSensorRotEuler(%pitch, %roll, %yaw)
{
   // Output the absolute rotation of the Oculus Rift's sensor
   echo("Sensor Euler: " @ %pitch SPC %roll SPC %yaw);
}

// Turn off angled axis reporting and turn on Euler angle reporting
$OculusVR::GenerateAngleAxisRotationEvents = false;
$OculusVR::GenerateEulerRotationEvents = true;
moveMap.bind( oculusvr, ovr_sensorrotang0, OVRSensorRotEuler );

Sensor as Thumb Stick Input Events

Torque 3D allows an OculusVR sensor to be used like a gamepad thumb stick. Imagine that a thumb stick is coming out of the top of the sensor when in a neutral rotation and you move it by tilting the sensor.

To activate these thumb stick input events we set the $OculusVR::GenerateRotationAsAxisEvents global TorqueScript variable to true. With that variable set the following action map input events are available:

• ovr_sensorrotaxisx0 - thumb stick like x-axis motion in the range of -1.0 to 1.0
• ovr_sensorrotaxisy0 - thumb stick like y-axis motion in the range of -1.0 to 1.0

Internally, these x and y axis values are normalized to ensure the length of their vector is never more than 1, just like a real thumb stick.

In order to calculate the -1.0 to 1.0 range, the tilt of the sensor with respect to a vector pointing straight up (technically this vector is normal to the plane of the sensor's neutral rotation) is used. When this sensor to up vector angle reaches the $OculusVR::MaximumAxisAngle global script variable value (the default is 25 degrees) then the virtual thumb stick is considered all the way over. Adjusting $OculusVR::MaximumAxisAngle for your application determines how far over the user must tilt their sensor for a 100% value.