Tango Events

Primary events

The unique array of sensors on a Tango-capable device, and the data they receive and transmit, are essential to enabling the device to perform the core Tango activities: motion tracking, depth sensing, and area learning. As with any Android device, this data is received and passed along as "events." The primary Tango events are:

  • The pose (position and orientation) of the device.
  • Frames and textures from a camera.
  • Point clouds, which are generated via depth sensing.

To receive an event, you pass a callback to a function that listens for that event. The callback is called every time the event occurs.

To receive poses

There are are two ways to do this; we recommend that you poll for poses using TangoService_getPoseAtTime(). For a detailed explanation, see the Pose topic.

To receive notification of new camera textures

(This is useful to render the camera image in OpenGL for Augmented Reality)

Pass a callback to TangoService_OnTextureAvailable(). You will also need to call TangoService_updateTextureExternalOes in the GL thread to update the texture.

To receive frames from a camera

(Use this not for display, but for when you need to access the pixel data as an array of bytes.)

Pass a callback to TangoService_connectOnFrameAvailable().

To receive point clouds

Pass an OnPointCloudAvailable() callback to TangoService_connectOnPointCloudAvailable().

Status events

The TangoEvent notification callback signals important sensor status events, such as descriptions of error states. To receive a TangoEvent, attach an onTangoEvent() callback to TangoService_connectOnTangoEvent(). This callback is called every time a Tango status event occurs.

TangoEvent is defined as:

typedef struct TangoEvent {
  double timestamp;
  TangoEventType type;
  const char* event_key;
  const char* event_value;
} TangoEvent;

The timestamp indicates when the status event occurs, and can be compared to timestamps elsewhere in the Tango APIs.

The type is designated by the TangoEventType enumeration, and tells you which sensor triggered the event:

typedef enum {
} TangoEventType;

The event_key and event_value describe the specific status event that occurred. Here is a table of possible keys:

Event key Explanation
TangoServiceException The service has encountered an exception, and a text description is given in event_value.
FisheyeOverExposed The fisheye image is overexposed with average pixel value event_value px.
FisheyeUnderExposed The fisheye image is underexposed with average pixel value event_value px.
ColorOverExposed The color image is overexposed with average pixel value event_value px.
ColorUnderExposed The color image is underexposed with average pixel value event_value px.
TooFewFeaturesTracked Too few features were tracked in the fisheye image; number of features tracked is event_value.
Unknown Description unknown.

Based on the specific event description, you may choose to display instructions for users to correct the circumstances leading to the event. For example, if you are receiving ColorUnderExposed, it is likely that the user is in an area where it is too dark for the Tango framework to function well.

To learn about another way to handle these events, see the UX Framework.