Function gvr_sys::gvr_controller_state_get_orientation [−] [src]

pub unsafe extern "C" fn gvr_controller_state_get_orientation(
    state: *const gvr_controller_state
) -> gvr_quatf

Returns the current controller orientation, in Start Space. The Start Space is the same space as the headset space and has these three axes (right-handed):

  • The positive X axis points to the right.
  • The positive Y axis points upwards.
  • The positive Z axis points backwards.

The definition of "backwards" and "to the right" are based on the position of the controller when tracking started. For Daydream, this is when the controller was first connected in the "Connect your Controller" screen which is shown when the user enters VR.

The definition of "upwards" is given by gravity (away from the pull of gravity). This API may not work in environments without gravity, such as space stations or near the center of the Earth.

Since the coordinate system is right-handed, rotations are given by the right-hand rule. For example, rotating the controller counter-clockwise on a table top as seen from above means a positive rotation about the Y axis, while clockwise would mean negative.

Note that this is the Start Space for the controller, which initially coincides with the Start Space for the headset, but they may diverge over time due to controller/headset drift. A recentering operation will bring the two spaces back into sync.

Remember that a unit quaternion expresses a rotation. Given a rotation of theta radians about the (x, y, z) axis, the corresponding quaternion (in xyzw order) is:

(x * sin(theta/2), y * sin(theta/2), z * sin(theta/2), cos(theta/2))

Here are some examples of orientations of the controller and their corresponding quaternions, all given in xyzw order:

  • Initial pose, pointing forward and lying flat on a surface: identity quaternion (0, 0, 0, 1). Corresponds to "no rotation".

  • Flat on table, rotated 90 degrees counter-clockwise: (0, 0.7071, 0, 0.7071). Corresponds to a +90 degree rotation about the Y axis.

  • Flat on table, rotated 90 degrees clockwise: (0, -0.7071, 0, 0.7071). Corresponds to a -90 degree rotation about the Y axis.

  • Flat on table, rotated 180 degrees (pointing backwards): (0, 1, 0, 0). Corresponds to a 180 degree rotation about the Y axis.

  • Pointing straight up towards the sky: (0.7071, 0, 0, 0.7071). Corresponds to a +90 degree rotation about the X axis.

  • Pointing straight down towards the ground: (-0.7071, 0, 0, 0.7071). Corresponds to a -90 degree rotation about the X axis.

  • Banked 90 degrees to the left: (0, 0, 0.7071, 0.7071). Corresponds to a +90 degree rotation about the Z axis.

  • Banked 90 degrees to the right: (0, 0, -0.7071, 0.7071). Corresponds to a -90 degree rotation about the Z axis.

@param state The controller state to get the orientation from. @return The unit quaternion orientation from the controller state.