Tutorial 1: Getting Started

Welcome to the Argo Android tutorial series. In this series of tutorials, you will build several different applications with Argo to gain a basic knowledge of the Argo SDK. Later tutorials will build on code you have written in earlier tutorials.

In this tutorial, you will create a simple Android application that displays an HVR file.

To see the code in action, download the Argo Samples, and open GettingStartedActivity.

Shortcut: If you're already an awesome Argo developer, you'll probably want to check out the Cheat Sheet

0. Prerequisites

To complete this guide, you will need the following:

  • Android Studio 3.0 and an empty Android project
  • Some experience building Android applications
  • A physical device running at least API level 21 (Android 5.0), and supporting OpenGL ES 3

1. Add the Gradle dependency to your Project

Open your project level build.gradle file, and add the following repositories:

allprojects {
    ...
    repositories {
        ...
        maven {
            url "https://jitpack.io"
        }
        maven {
            url "https://oss.sonatype.org/content/repositories/snapshots/"
        }
    }
}

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

dependencies {
    ...
    implementation "com.github.8i.argo-android:HvrSDK:0.3-preview.1"
}

2. Add an HvrView

Open the layout file that you want to add HVR content to. Assuming you've started from a new empty project, this layout will likely be activity_main. Add a new HvrView View to this layout file. Once you've added this HvrView to your Activity's layout, you will also need to make a call to HvrSdk.initialise in your Activity, before you call setContentView.

Example activity_main layout file:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="match_parent">
  
    <com.eighti.hvrsdk.view.HvrView
        android:id="@+id/myHvrView"
        android:layout_width="match_parent"
        android:layout_height="match_parent">
    </com.eighti.hvrsdk.view.HvrView>

</FrameLayout>

Example MainActivity:

public class MainActivity extends Activity{
    @Override
    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
        HvrSdk.initialise(getApplication());
        setContentView(R.layout.activity_main);
    }
}

Once you've done this, you should be able to run your application. Don't worry, not much will happen - you should expect to see a black screen.

The next step is to start drawing something on this black screen!

3. Add an HvrActor to your HvrView

To add an HvrActor to an HvrView, the basic workflow is:

  1. Get a reference to the HvrView
  2. Set an HvrPlayer to that HvrView
  3. Add an actor to the HvrPlayer's HvrRenderer
  4. Set the position of the HvrRenderer's camera
public class MainActivity extends Activity {
    @Override 
    public void onCreate(Bundle savedInstanceState){
        // Initialise the HvrSdk and then set the layout used by this activity
        HvrSdk.initialise(getApplication());  
      
        super.onCreate(savedInstanceState); 
        setContentView(R.layout.activity_main);

        // Get the path to a .hvrs file on local storage,
        // and copy a file from the assets folder to that path.
        // If you prefer to manually place a file on your device, and hardcode a path,
        // that will work as well. The important thing is that there is an HVRS file
        // on your device's storage somewhere that is accessible by your application.
        File actorFile = new File(getFilesDir(), "myAsset.hvrs")
        HvrAndroidUtils.copyAsset(getAssets(), "myAsset.hvrs", actorFile.getAbsolutePath())

        // 1. Grab the HvrView that we are using
        HvrView hvrView = (HvrView) findViewById(R.id.myHvrView);

        // 2. Create a new HvrPlayer, and then set the HvrPlayer of the HvrView
        HvrPlayer hvrPlayer = new BasicPlayer();
        hvrView.setPlayer(hvrPlayer);

        // 3. We're going to post an action to the HvrPlayer. Why we do this will be explained
        // in upcoming tutorials. The action we post will add an HvrActor based on our 
        // ActorFile, and then make sure that the HvrActor and Camera are in a position 
        // where the Camera can see the HvrActor.
        hvrPlayer.post(() -> {
            HvrActor actor = hvrPlayer.getRenderer().addActor(actorFile);

        // 4. Set the position of the actor and the camera. 
        // The camera uses the a right handed coordinate system where X is right, Y is up 
        // and -Z is forward. Therefore, we put the HvrActor at a 
        // position in the world that is 2 meters in front of the 
        // camera, and move the camera up by 1 meter so that we're not looking at the HvrActor's feet. 
            actor.getTransform().setPosition(0.0f, 0.0f, -2.0f);
            hvrPlayer.getCamera().setPosition(0.0f, 1.0f, 0.0f);
        });
    }
}

HvrPlayer is an abstract class, and requires that you override the onRender method. For now, we will be using an HvrPlayer called BasicPlayer, which is a very simple implementation of HvrPlayer, suitable for basic rendering of HvrActors. If you're interested in custom rendering, check out the page on Advanced Rendering.

What can go wrong?

  • If you do not call HvrSdk.initialise before setContentView, you'll likely crash the application. When you call setContentView, you're creating an HvrView as defined in your layout file. If the HvrSdk is not initialised, this will fail.
  • If you try to add an HvrActor outside of the hvrPlayer.post Runnable you'll likely crash the application. Why this happens is explained in Tutorial 2: Understanding
  • If you forget the last two lines, which set the position of the Camera and HvrActor. If you forget to do this, both the Camera and the HvrActor will be at position (0, 0, 0), where the Camera will be unable to see the HvrActor. By moving these components, we make sure we're properly showing something on screen.

Next Steps

Now that you're rendering HvrActors on screen, it's time to understand exactly how all these Hvr* classes fit together, and what their individual responsibilities are.

Tutorial 2: Understanding