Android

In this short guide you can learn how to build the source code of the ApertusVR libraray for Android.

Introduction

ApertusVR is a cross platform library, which means, we support various operating systems, included Android, as well.

The following guide will go through a step-by-step tutorial on how you can build the source code for Android using a Windows PC.

If you are new to Android development, we highly recommend you to read the official Android documentations. From now on, we will assume, that you are familiar, at least with the basics.

Requirements

For the cross compilation process, you have to obtain the following softwares:

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

Download Android build source.

Just like the other parts of the library, the Android source files are hosted on GitHub. To obtain it, you have to make a folder for it on your personal Windows device. In this tutorial we will assume, that your chosen folder is C:\ApertusVR.

Clone the default branch from ApertusVR github:

$ git clone https://github.com/MTASZTAKI/ApertusVR.git

If everything worked properly, you should see something similar to the picture below

For building from source you will have to build the apertusvr and the filamentRender modules separately. We will discuss both of them and the setting up of Android S

tudio in the following paragraphs.

Configuring Android Studio

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

Android SDK
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) 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.

Then click Apply, and wait until the install finishes.

Building the ApertusVR library

If you deployed everything as discussed above, we can actually start to build our source files. However, before we dive into it, we will go through some important notes, which helps you understand the build process.

Project structure

Now if you open the C:\ApertusVR\plugins\languageAPI\ folder, you should see something like this:

Here the most important for us, is the java subfolder, which contains the Android Studio project. Let's see what we can find in it!

Open Android Studio, and go File > Open, then navigate to the project folder, and 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:

If it is not in Android view, change it:

Now we can see how the project structure actually looks like. The following lines will explain what you see on the right picture.

The apertusvrAndroid library containing java (and c++) files. This librarie will become Android archive files (*.aar), similar to a Java archive file (*.jar). It contains the ApertusCore C++ library, and the consisting JNI-binds and wrappers. If you are not familiar with the ApertusVR architecture, check out the Developers/Architecture chapter in the documentation.

The module embraces the whole ApertusVR C++ project, which consists of shared libraries. These shared libs are all linked against the apeJNIStarter, which is also a shared library. Then apeJNIStarter and apeJNIPlugin (the library which implements the JNI-binds) are loaded in the ApertusJNI class file with Java's System.loadLibrary().

Dependencies

In this subsection we discuss what are the dependencies of the Android build, and what you should know about them.

ApertusVR is dependent on several 3rd party libraries. The three most important for ApertusCore are the followings:

And we use the mentioned Filament engine for rendering. All of them are included as a prebuilt library except RakNet, which was added as a subdirectory in the CMake project.

The prebuilt C++ library dependencies are stored in the ApertusVR\androidx\libs folder. Note that, because cURL is dependent on the OpenSSL library, you can find its prebuilt *.so files in the libs folder too. If you want your own build (e.g. you need a specific version) you have to build them for each supported Android ABI. To do that follow the instructions in OpenSSL's and cURL's github repository:

You can also build your own Zip version for Android. The easiest way to do it, is with CMake and Ninja, by providing a toolchain file for cross-compiling (the same you use for the ApertusVR-Android) build, e.g. the android.toolchain.cmake file in the ...\AndroidSdk\ndk\<ndk-version>\build\cmake folder.

Then you should manually set the CMake flags for a specific ABI, generate, then repeate with an other ABI... Then you can obtain the builds using Ninja.

Lastly, Filament is included as an Android archive file, you can find it in: ApertusVR\plugins\render\apefilamentrender\libs\. If you want newer version, you have to replace what you found in this folder, then modify the build.gradle file (see in the next subsection).

Gradle

Android Studio uses the build automation tool called Gradle. We will only discuss what we need to build the source code, but further information about the build tool can be found on the official website.

For each existing component of our project (e.g. libraries) we have a corresponding build.gradle file. Other than that, we also have a build.gradle file for the whole project, where you can configure options for all modules globally. And lastly there is a settings.gradle file, where you can modify the project settings (e.g. including other modules). You can see these on the picture below.

What is most important for us, in the first place is the build.gradle (ApertusVR). If you open it, you should see in the allprojects configuration that there's a variable called buildDir. Currently it looks like this:

allprojects {
    repositories {
        google()
        jcenter()
    }

    buildDir = "c:/ApertusVR/build/android/${rootProject.name}/${project.name}"
}

Here you can see, that the basic configuration is that the build directory of your project will be C:\ApertusVR\build\android. If you want your built files put somewhere else, you should set this variable to point to the appropriate directory. So, if you want your build files to be at D:\FooBar\, then type buildDir = "d:/FooBar/${rootProject.name}/${project.name}".

CMake and NDK

As you know, the ApertusVR library is written in C++14, and we use CMake for build automation. When you look at the build.gradle (:apertusvr) file, you should see the following commands:

externalNativeBuild {
    cmake {
        path file('../../../CMakeLists.txt')
    }
}

This tells Gradle, that we want to include a CMake project into our Android library, but we also have to tell Gradle where is our root CMakeLists.txt file. If, for some reason you want to change the project structure, you should modify this for Gradle, to be able to find the CMake project, which builds the ApertusVR C++ library. If it is done, then the rest of the native build is only depends on the CMake project.

The second thing, you should pay attention to, is in the defaultConfig:

externalNativeBuild {
    cmake {
        cppFlags "-std=c++14"
    }
}

ndk {
    abiFilters 'arm64-v8a', 'armeabi-v7a', 'x86'
}

With these commands, we tell Gradtle, that:

We want C++14 version support of STL for our native C++ project.
Our native project only works with 'arm64-v8a', 'armeabi-v7a' and 'x86' ABI filters.

SDK version

As it has been said, basically we support AndroidSDK version 23 and higher. You can change this per module in the defualtConfig:

defaultConfig {

        //...
        
        minSdkVersion 23
        targetSdkVersion 29
        
        //...

}

Dependencies in Filamnetrender

First you need to open the filamentrender module:

Open Android Studio, and go File > Open, then navigate to the project folder C:\ApertusVR\plugins\render\filamentRender, and 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:

The 3rd party JVM dependencies used by the modules (like Filament) are included with the api command. E.g. in the Filament case it looks like this in build.gradle(:apefilamentrender)

dependencies {
    //...

    api(name: 'filament-20200403-android', ext: 'aar')
    api(name: 'apertusvr-091-android', ext: 'aar')
}

If you want to add other dependencies, or change Filament to a new version, you have to copy it's *.aar file into the .../<modulename>/libs/ folder, or if you want to use other folder, you have to change the flatDir in build.gradle(ApertusVR-Android):

allprojects {
    repositories {
        // ...
        flatDir {
            dirs 'libs'
        }
    }
    // ...
}

Start the build

If you configured both apertusvr and filamentRender projects for your own wish, based on the text below, you can finally start the build by clicking Build > Make Project (or by using the small green hammer) for both.

First you will need to build apertusvr.

You will get several warning during the build process, but you shouldn't bother yourself with them, they won't cause any runtime misbehaviour. So if you see something similar like on the picture below, your build is fine:

If the build is successful then you need to copy the generated .aar file from here: C:\ApertusVR\build\android\ApertusVR\apertusvr\outputs\aar\ into here: C:\ApertusVR\plugins\render\filamentRender\apefilamentrender\libs and rename it to apertusvr-091-android.

However, there's one thing remaining before you can enjoy the pleasures of programming with ApertusVR on Android.