Tutorial 4: Augmented Reality

One of the most common ways to use HVR content is in augmented reality (AR). To make this as easy as possible, Argo provides an optional library of AR tools and integrations. This library is called HvrAr.

1. Add the Gradle dependencies to your Project

Open your module (application) level build.gradle file, and add the following dependencies:

android {
    ...
    packagingOptions {
        exclude 'lib/arm64-v8a/*.so'
    }
}

dependencies {
    ...
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
    implementation 'com.github.8i.argo-android:HvrAr:0.3-preview.1'
}
Note: Don’t forget to add the HvrSDK dependencies as shown in Tutorial 1: Getting Started.

2. Add the AAR dependencies to the project

HvrAr requires two third-party .aar dependencies to function correctly. These dependencies enable ARCore and Tango functionality, and are found in the following locations:

  1. https://developers.google.com/tango/downloads

    Download the Support Library for the Java APIs. The name of the file should “TangoSupport_Ikariotikos_Java.aar”. This .aar file should be added to the “libs” folder of the module that will use HvrAr.

  2. https://developers.google.com/ar/develop/downloads

    Download the Android SDK. This will provide you with a file named “arcore-android-sdk-preview.zip”. Open this .zip file and find “/arcore-android-sdk-master/libraries/arcore_client.aar”. This .aar file should be added to the “libs” folder of the module that will use HvrAr.

3. Request the Camera Permission

Make sure that you request the camera permission from users.

4. Use the ArPlayer

The most important part of HvrAr is an implementation of HvrPlayer called ArPlayer. ArPlayer handles almost all AR integration, including the camera background and tracking.

An ArPlayer is used in the same way as the BasicPlayer used in previous tutorials. The major difference is that the ArPlayer is not ready to use until the ArSystem owned by the ArPlayer has a state of ArSystem.STATE_TRACKING. This means that any placement of HvrActors will be incorrect until the ArSystem is ArSystem.STATE_TRACKING. The example below shows one way that this problem can be solved.

class MainActivity extends Activity {
  
    private ArPlayer player;
    private File actorFile = /*This needs to be the location of an HVRS file*/;
      
    @Override
    public void onCreate(Bundle savedInstanceState){
        HvrSdk.initialise(getApplication());
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
      
        HvrTextureView hvrView = findViewById(R.id.hvr_texture_view);
        // Create the ArPlayer, and set the HvrTextureView to use it.
        player = ArPlayer(this);
        hvrView.setPlayer(player);
      
        // Listen to changes in ArPlayer's tracking state. When the state becomes
        // "STATE_TRACKING", we will call the "placeActor" method, and then
        // stop listening to changes in ArPlayer's tracking state. 
        player.getArSystem().setTrackingStateListener((state)->{
            if(state == ArSystem.STATE_TRACKING){
                placeActor();
                player.getArSystem().setTrackingStateListener(null);
            }
        });
    }

    @Override
    private void placeActor(){
        // Create a new HvrActor from the actorFile
        HvrActor actor = player.getRenderer().addActor(actorFile);
        // Get a Vector2f that represents a point halfway across the screen,
        // and about 2/3rds down.
        Vector2f screenPosition = new Vector2f(hvrView.width * 0.5f, hvrView.height * 0.66f);
        // Use the ArSystem to turn this screen position into a world position
        Vector2f worldPosition = player.arSystem.getWorldPosition(screenPosition);
        // Set the position of our new HvrActor to be the world position point that
        // we found.
        actor.transform.setPosition(worldPosition.x, worldPosition.y, worldPosition.z);
    }
}

Next Steps

This ends the tutorial series for now.