Head tracking

Functions for managing head tracking.

Summary

Functions

gvr_apply_neck_model(const gvr_context *gvr, gvr_mat4f head_space_from_start_space_rotation, float factor)
Applies a simple neck model translation based on the rotation of the provided head pose.
gvr_get_head_space_from_start_space_rotation(const gvr_context *gvr, const gvr_clock_time_point time) Deprecated. Calls to this method can be safely replaced by calls to gvr_get_head_space_from_start_space_transform. The new API reflects that the call can return a full 6DoF transform when supported by both the host platform and the client application.
gvr_get_head_space_from_start_space_transform(const gvr_context *gvr, const gvr_clock_time_point time)
Gets the position and rotation from start space to head space.
gvr_get_time_point_now()
Gets the current monotonic system time.
gvr_pause_tracking(gvr_context *gvr)
void
Pauses head tracking, disables all sensors (to save power).
gvr_recenter_tracking(gvr_context *gvr)
void
Recenters the head orientation (resets the yaw to zero, leaving pitch and roll unmodified).
gvr_reset_tracking(gvr_context *gvr)
void
Deprecated. Calls to this method can be safely replaced by calls to gvr_recenter_tracking. This accomplishes the same effects but avoids the undesirable side-effects of a full reset (temporary loss of tracking quality).
gvr_resume_tracking(gvr_context *gvr)
void
Resumes head tracking, re-enables all sensors.

Functions

gvr_apply_neck_model

gvr_mat4f gvr_apply_neck_model(
  const gvr_context *gvr,
  gvr_mat4f head_space_from_start_space_rotation,
  float factor
)

Applies a simple neck model translation based on the rotation of the provided head pose.

Note: Neck model application may not be appropriate for all tracking scenarios, e.g., when tracking is non-biological.

Details
Parameters
gvr
Pointer to the context instance from which the pose was obtained.
head_space_from_start_space_rotation
The head rotation as returned by gvr_get_head_space_from_start_space_rotation().
factor
A scaling factor for the neck model offset, clamped from 0 to
  1. This should be 1 for most scenarios, while 0 will effectively disable neck model application. This value can be animated to smoothly interpolate between alternative (client-defined) neck models.
Returns
The new head pose with the neck model applied.

gvr_get_head_space_from_start_space_rotation

gvr_mat4f gvr_get_head_space_from_start_space_rotation(
  const gvr_context *gvr,
  const gvr_clock_time_point time
)

Deprecated. Calls to this method can be safely replaced by calls to gvr_get_head_space_from_start_space_transform. The new API reflects that the call can return a full 6DoF transform when supported by both the host platform and the client application.

Gets the rotation from start space to head space. The head space is a space where the head is at the origin and faces the -Z direction.

Details
Parameters
gvr
Pointer to the gvr instance from which to get the pose.
time
The time at which to get the head pose. The time should be in the future. If the time is not in the future, it will be clamped to now.
Returns
A matrix representation of the rotation from start space (the space where the head was last reset) to head space (the space with the head at the origin, and the axes aligned to the view vector).

gvr_get_head_space_from_start_space_transform

gvr_mat4f gvr_get_head_space_from_start_space_transform(
  const gvr_context *gvr,
  const gvr_clock_time_point time
)

Gets the position and rotation from start space to head space.

The head space is a space where the head is at the origin and faces the -Z direction.

For platforms that support 6DoF head tracking, the app may also be required to declare support for 6DoF in order to receive a fully formed 6DoF pose, e.g., on Android, this requires declaration of support for at least version 1 of the "android.hardware.vr.headtracking" feature in the manifest.

Details
Parameters
gvr
Pointer to the gvr instance from which to get the pose.
time
The time at which to get the head pose. The time should be in the future. If the time is not in the future, it will be clamped to now.
Returns
A matrix representation of the position and rotation from start space (the space where the head was last reset) to head space (the space with the head at the origin, and the axes aligned to the view vector).

gvr_get_time_point_now

gvr_clock_time_point gvr_get_time_point_now()

Gets the current monotonic system time.

Details
Returns
The current monotonic system time.

gvr_pause_tracking

void gvr_pause_tracking(
  gvr_context *gvr
)

Pauses head tracking, disables all sensors (to save power).

Details
Parameters
gvr
Pointer to the gvr instance for which tracking will be paused and sensors disabled.

gvr_recenter_tracking

void gvr_recenter_tracking(
  gvr_context *gvr
)

Recenters the head orientation (resets the yaw to zero, leaving pitch and roll unmodified).

Only to be used by Cardboard apps. Daydream apps must not call this. On the Daydream platform, recentering is handled automatically and should never be triggered programmatically by applications. Hybrid apps that support both Cardboard and Daydream must only call this function when in Cardboard mode (that is, when the phone is paired with a Cardboard viewer), never in Daydream mode.

Details
Parameters
gvr
Pointer to the gvr instance for which tracking will be recentered.

gvr_reset_tracking

void gvr_reset_tracking(
  gvr_context *gvr
)

Deprecated. Calls to this method can be safely replaced by calls to gvr_recenter_tracking. This accomplishes the same effects but avoids the undesirable side-effects of a full reset (temporary loss of tracking quality).

Resets head tracking.

Only to be used by Cardboard apps. Daydream apps must not call this. On the Daydream platform, recentering is handled automatically and should never be triggered programmatically by applications. Hybrid apps that support both Cardboard and Daydream must only call this function when in Cardboard mode (that is, when the phone is paired with a Cardboard viewer), never in Daydream mode.

Details
Parameters
gvr
Pointer to the gvr instance for which tracking will be reseted.

gvr_resume_tracking

void gvr_resume_tracking(
  gvr_context *gvr
)

Resumes head tracking, re-enables all sensors.

Details
Parameters
gvr
Pointer to the gvr instance for which tracking will be resumed.