Using the Java Support Library UX Package

This page describes how to use features of the Support Library UX package for Java. For more information about the features themselves, see our guide on Tango UX.

You should also take a look at our Support Library UX reference pages.

Installation instructions

Follow the instructions to add the Tango Support Library for Java to your project. Make sure to include support-base as a dependency.

If you use your own build system, download and include the Java Support Library package in your project.

UX package tutorial

These code snippets show how to use the UX package, and how to implement common tasks for Java applications.

Initialization

Make sure to handle any issues that come up during Tango startup.

mTango = new Tango(MainActivity.this, new Runnable() {
    @Override
    public void run() {
        synchronized (MainActivity.this) {
            try {
                mConfig = setupTangoConfig(mTango);
                mTango.connect(mConfig);
                startupTango();
            } catch (TangoOutOfDateException e) {
                Log.e(TAG, getString(R.string.exception_out_of_date), e);
            } catch (TangoErrorException e) {
                Log.e(TAG, getString(R.string.exception_tango_error), e);
            } catch (TangoInvalidException e) {
                Log.e(TAG, getString(R.string.exception_tango_invalid), e);
            }
        }
    }
});

Starting the UX Framework

To use the UX package in Java, add the TangoUx object. The TangoUx class manages all of the UX package functionality.

mTangoUx = new TangoUx(context);

Now that you've created a TangoUx object, you need to start() it:

mTangoUx.start();
mTango.connect();

When you are disconnecting from the Tango service, make sure to also stop TangoUx:

mTango.disconnect();
mTangoUx.stop();

Waiting for valid data

As mentioned in the UX overview, you should wait for valid data before rendering an interactive UI. This code snippet only updates the camera when we get a valid pose. You could also show a loading or splash screen until we get the first valid pose.

TangoPoseData lastFramePose = TangoSupport.getPoseAtTime(0,
       TangoPoseData.COORDINATE_FRAME_START_OF_SERVICE,
       TangoPoseData.COORDINATE_FRAME_DEVICE,
       TangoSupport.TANGO_SUPPORT_ENGINE_OPENGL,
       TangoSupport.TANGO_SUPPORT_ENGINE_OPENGL,
       mDisplayRotation);
if (lastFramePose.statusCode == TangoPoseData.POSE_VALID) {
   mRenderer.updateCameraPose(lastFramePose);
}

Exception Event Listener

We'll cover this in more detail in the Exception Handling section.

Forwarding the sensor data

You need to forward the Tango sensor data received by OnTangoUpdateListener callbacks to the UX library:

OnTangoUpdateListener listener = new
    OnTangoUpdateListener() {
        @Override
        public void onPoseAvailable(final TangoPoseData pose) {
            if (mTangoUx != null) {
                mTangoUx.updatePoseStatus(pose.statusCode);
            }
        }

        @Override
        public void onPointCloudAvailable(TangoPointCloudData pointCloud) {
          if (mTangoUx != null) {
            mTangoUx.updatePointCloud(pointCloud);
          }
        }

        @Override
        public void onTangoEvent(TangoEvent event) {
            if (mTangoUx != null) {
                mTangoUx.updateTangoEvent(event);
            }
        }

        @Override
        public void onFrameAvailable(int cameraId) {
            // ...
        }
    };

UX errors and exceptions

The application can get notifications per event type by using the UxExceptionEventListener. In this example, we're creating an exception event listener that will set a boolean value when the framework detects that the device is lying on a surface:

private UxExceptionEventListener mUxExceptionEventListener = new UxExceptionEventListener() {
    @Override
    public void onUxExceptionEvent(UxExceptionEvent event) {
        if (event.getType() == UxExceptionEvent.TYPE_LYING_ON_SURFACE) {
            boolean isDeviceLyingOnSurface = event.getStatus() == UxExceptionEvent.STATUS_DETECTED;
        }
    }
};

mTangoUx.setUxExceptionEventListener(mUxExceptionEventListener);

Note that in the last line, we set an existing TangoUx to use the UxExceptionEventListener we just created.

For a list of the possible exception event types returned by UxExceptionEvent.getType(), see the Java reference page for UxExceptionEvent.

Hold Posture exceptions

The Hold Posture is a special exception which specifys how the user should hold the device while using your application.

The available postures are:

  • TYPE_HOLD_POSTURE_NONE: All directions are allowed, exception never shown.
  • TYPE_HOLD_POSTURE_FORWARD: The device should point forward.
  • TYPE_HOLD_POSTURE_UP: The device should point up, towards the sky.
  • TYPE_HOLD_POSTURE_DOWN: The device should point down, towards the ground.

The default posture is TYPE_HOLD_POSTURE_NONE.

Holding device in an incorrect way will result in a UxExceptionEvent of type TYPE_HOLD_POSTURE.

You can set a different posture anytime during the app lifecycle by calling mTangoUx.setHoldPosture(TYPE);, where TYPE is one of the four posture options. You should change the hold posture whenever necessary. For example, imagine a game has a setup phase where you point the tablet down to find the floor, then a play phase where you can roam around freely. The hold posture should be set to TYPE_HOLD_POSTURE_DOWN during the setup phase and TYPE_HOLD_POSTURE_NONE during the play phase.

Send feedback about...

Tango Java API
Tango Java API