Home > Devices > Fire Phone

Retrieving Head-Tracking Data Using Native Code

Introduction

The native-code HeadTracking API for Fire phone offers a way to poll for data on the position of the user's head relative to the phone. The API makes the following types of data available:

  • The timestamp of the latest head-tracking event.
  • Whether the software currently detects the user's face and is actively tracking the user's head.
  • The position of the head relative to the screen orientation of the phone, as X, Y, and Z coordinates.
  • The angle at which the head is inclined right or left relative to the screen orientation of the phone.

You can get this head-tracking data by supplying a HeadTrackingPoller object with an empty or recycled HeadTrackingEvent when you call HeadTrackingPoller.sample(). HeadTrackingPoller fills the empty or recycled HeadTrackingEvent object with the latest head-tracking data.

You get the HeadTrackingPoller object from a HeadTrackingManager object. The HeadTrackingManager provides methods for creating a HeadTrackingPoller object with configurations defined by a HeadTrackingConfiguration object. The HeadTrackingConfiguration object contains fields that let you control the tradeoffs between the accuracy of head-tracking data and battery consumption. The Fidelity field controls whether the polling object, HeadTrackingPoller, uses less power to produce less accurate head-tracking data or higher power to produce more accurate data. The Filter field controls whether only camera data is used for head tracking or camera data along with motion sensor data. Using camera data alone consumes less power.

You poll for head-tracking data by passing a pointer to the HeadTrackingEvent object to the HeadTrackingPoller->sample() method. This method updates the fields of the HeadTrackingEvent instance with the current data. It is also advisable to check whether the system is tracking a head to make sure that the data is valid. You can then extract this data from the HeadTrackingEvent instance and use it in your app.

In the following procedure, the example code is from the NativeHeadTrackingSample example app included with the SDK.

To Retrieve Head-Tracking Data

  1. Get instances of HeadTrackingManager, HeadTrackingConfiguration, and HeadTrackingEvent, for example:
    HeadTrackingManager * manager = HeadTrackingManager::getInstance();
    HeadTrackingConfiguration * config = HeadTrackingConfiguration::createInstance();
    HeadTrackingEvent * event = HeadTrackingEvent::createInstance();
    If any of these calls returns a null pointer, it indicates that the head tracking library is not available. You may choose to have your app degrade gracefully or simply exit.
  2. Set the values of the HeadTrackingConfiguration object and pass it to HeadTrackingManager to get a HeadTrackingPollerobject, for example:
    config->setFidelity(HeadTrackingConfiguration::NORMAL);
    config->setFilterType(HeadTrackingConfiguration::HT_SENSOR_FUSION);
  3. Poll HeadTrackingPoller for current head-tracking data by calling sample() with the HeadTrackingEvent object, and extract that data from the updated HeadTrackingEventobject, for example:
    if ((headTrackingPoller->sample(*headTrackingEvent) == 0) && (headTrackingEvent->isTracking()))
        { // Retrieve data
        x = headTrackingEvent->getX_mm();
        y = headTrackingEvent->getY_mm();
        z = headTrackingEvent->getZ_mm();}