Android

In this section we will discuss how you can use ApertusVR's main features from Android and Java, the installations process and the developement of applications.

Requirements

  • Android Studio v. 3.6 or later versions (any other tools related with Android Studio will be discussed in the Configuring Android Studio section)

  • Git for Windows

  • ApertusVR we recommend the latest build (but if you want an earlier one, you must chose one that contains the android libraries

Configuring Android Studio

For Android Studio to work properly, you will need the following toolsets:

  1. Android SDK

  2. Android NDK

Android SDK

ApertusVR supports Android 6.0 (Marshmallow) or higher versions. In correlation with this, the library works with API level 23, or later releases. This implies, that according to the SDK Platform release notes, the minimum requirement is:

  • Android SDK Platform-tools r23

  • Android SDK Tools 24.3.4

If Android Studio does not find any of the Android SDK versions, it will offer you to download the latest release. This may not be the version you want (e.g. your debugging Anroid device only supports former versions), so you can also download other releases in Settings > System Settings > Android SDK > SDK Tools.

Android NDK

The ApertusVR library is written in C++, which means, in order to build on Android, we use the native language toolset provided by Google, called Android NDK (native developement kit). For more information see the official Android NDK documentation.

The version we use is 21.0.611369. You can download it with Android Studio's SDK Manager. Go Settings > Appearance & Behavior > System Settings > Android SDK > SDK Tools. Then click Show Package Details in the bottom right corner. Choose NDK (Side by side) 20.0.5594570 or 21.0.611369, but do not click on Apply yet.

ApertusVR uses CMake as its main build tool. Good news is that Android Studio accidentally has support for CMake projects too. In order to use it, on the same page where you picked the NDK version, you can mark the appropriate CMake version, which is 3.10.2.

NDK and CMake in the Android SDK manager.

Then click Apply, and wait until the install finishes.

Debug configurations

The fact, that we changed the default build directory implies, that Android Studio's debugger won't find our native libraries, thus we can not debug native code, if we don't tell the debugger, where it can find them.

So first open Android Studio, and go File > Open, then navigate to the project folder C:\ApertusVR\plugins\scene\androidSampleScene, and click on androidsample then click Ok to open the project file. When it is opened, it may takes some time for Android Studio to configure the project. If it is done, open the left panel called 1:Project:

Assume that you didn't changed the buildDir variable in the project's build.gradle file, so your build directory is at C:\ApertusVR\build\android. Now if you successfully built the project, then you should have directories there like: C:\ApertusVR\build\android\ApertusVR\apertusvr\intermediates\cmake\debug\obj\<abi>. Where <abi> is one of the three supported ABIs (arm64-v8a, armeabi-v7a, x86). In those folders there are several *.so files. To be able to debug native code, we will tell Android Studio, that it can find these libraries there to fill its symbol table for debugging.

To do this, go Run > Edit Configurations > Debugger. Then here, we should fill in the Symbol Directories field. Click on the + button in the top right corner, like you see on the image:

Then navigate to the directories we just discovered in a few lines above. Then add all the ABI named folders:

If you did it right, then you should see something like this:

Now everything is set up, you can start programming and debugging your app!

Sample app

First you need to open the project in android studio and go File > Open, then navigate to the project:

There are 2 options:

  • C:\ApertusVR\plugins\virtualLearningFactory\android

  • C:\ApertusVR\plugins\scene\androidSampleScene\androidsample

In the first you can choose a room to connect to. In the second it automatically loads in a scene.

For running both basic sample appa, you have to copy their resources to your Android device. The basic sample apps use the models available in the ApertusVR/sample/virtualLearningFactoryToolkit/models folder.

After you connected your debug Android device, open the Device Explorer in the left right corner.

Then copy the model files to data/data/org.apertusvr.app/files:

If you did everything right, you can start the sample app by clicking Run > Run 'app'. Then after installing, you should see something similar to the picture presented here: