# Head tracking

# Head tracking

Functions for managing head tracking.

## Summary

| ### Functions ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1ga1fee0bcb23ef9f22ccc7282d9f8ec920(const https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr, https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f head_space_from_start_space_rotation, float factor)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f` Applies a simple neck model translation based on the rotation of the provided head pose. |
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1gadf789916980dbd465500e2fa658c8df1(const https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr, const https://developers.google.com/vr/reference/android-ndk/struct/gvr-clock-time-point#structgvr__clock__time__point time)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f` **[Deprecated.](https://developers.google.com/vr/reference/android-ndk/deprecated/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. |
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1ga012a104b2dd330ce4722fd9b023516cc(const https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr, const https://developers.google.com/vr/reference/android-ndk/struct/gvr-clock-time-point#structgvr__clock__time__point time)` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f` Gets the position and rotation from start space to head space. |
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1ga3ce252705c9932b10107838952594a59()` | `https://developers.google.com/vr/reference/android-ndk/struct/gvr-clock-time-point#structgvr__clock__time__point` Gets the current monotonic system time. |
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1ga46dc7a999b9f22064c020b561619e07d(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr)` | `void` Pauses head tracking, disables all sensors (to save power). |
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1gac2313522b1dc5dc66bff87b9b2fcd070(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr)` | `void` Recenters the head orientation (resets the yaw to zero, leaving pitch and roll unmodified). |
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1gaadbdbc68dcfaa83fc50f0c1b3b3dff45(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr)` | `void` **[Deprecated.](https://developers.google.com/vr/reference/android-ndk/deprecated/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). |
| `https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1ga5b3e41d5daf13173f5fed781230b093c(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *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.

<br />

| 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()](https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1gadf789916980dbd465500e2fa658c8df1). | | `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.](https://developers.google.com/vr/reference/android-ndk/deprecated/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.

<br />

| 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.

<br />

| 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.

<br />

| 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).

<br />

| 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.

<br />

| 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.](https://developers.google.com/vr/reference/android-ndk/deprecated/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.

<br />

| 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.

<br />

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