Function ovr_sys::ovr_SpecifyTrackingOrigin

pub unsafe extern "C" fn ovr_SpecifyTrackingOrigin(
    session: ovrSession,
    originPose: ovrPosef
) -> ovrResult

Allows manually tweaking the sensor position and orientation.

This function is similar to ovr_RecenterTrackingOrigin in that it modifies the (x,y,z) positional components and the yaw orientation component of the tracking space for the HMD and controllers.

While ovr_RecenterTrackingOrigin resets the tracking origin in reference to the HMD’s current pose, ovr_SpecifyTrackingOrigin allows the caller to explicitly specify a transform for the tracking origin. This transform is expected to be an offset to the most recent recentered origin, so calling this function repeatedly with the same originPose will keep nudging the recentered origin in that direction.

There are several use cases for this function. For example, if the application decides to limit the yaw, or translation of the recentered pose instead of directly using the HMD pose the application can query the current tracking state via ovr_GetTrackingState, and apply some limitations to the HMD pose because feeding this pose back into this function. Similarly, this can be used to “adjust the seating position” incrementally in apps that feature seated experiences such as cockpit-based games.

This function can emulate ovr_RecenterTrackingOrigin as such:

let ts = ovr_GetTrackingState(session, 0.0, ovrFalse);
ovr_SpecifyTrackingOrigin(session, ts.HeadPose.ThePose);

The roll and pitch orientation components are determined by gravity and cannot be redefined. If you are using ovrTrackerPoses then you will need to call ovr_GetTrackerPose after this, because the sensor position(s) will change as a result of this.

For more info, see the notes on each ovrTrackingOrigin enumeration to understand how recenter will vary slightly in its behavior based on the current ovrTrackingOrigin setting.

session Specifies an ovrSession previously returned by ovr_Create.

originPose Specifies a pose that will be used to transform the current tracking origin.

Returns an ovrResult indicating success or failure. In the case of failure, use ovr_GetLastErrorInfo to get more information. Return values include but aren’t limited to:

• ovrSuccess: Completed successfully.
• ovrError_InvalidParameter: The heading direction in originPose was invalid, such as facing vertically. This can happen if the caller is directly feeding the pose of a position-tracked device such as an HMD or controller into this function.

see ovrTrackingOrigin, ovr_GetTrackerPose, ovr_RecenterTrackingOrigin