How to use

This pages shows how to use the Filament render plugin on Android

On this page, we will go through on how to use the render plugin in a simple Android app which only contains a MainActivity. The basic usage of the plugin is easy, but we have to pay attention on several tasks.

Add dependency

The render plug-in is placed into a separate module called apefilamentrender. This means that when building our application, we do not just have to add the apertusvr module to our dependency list, but the apefilamentrender, as well:

build.gradle (Module: app)

dependencies {
    // ... 

    implementation project(":apertusvr")
    implementation project(":apefilamentrender")
}

Import classes

The plug-in itself contains sever classes, but when we using this module, our only concern is about the apeFilamentRenderPlugin. This is the one class, which contains everything we need to render on Android:

public final class apeFilamentRenderPlugin implements apePlugin {

// ...

}

So in our MainActivity.java file we import this class:

import org.apertusvr.render.apefilamentrenderplugin;

Init the plugin

It is not a surprise that we have to create every resource and init the plug-in, before using it. Assuming we want to use the plugin right from the application's starting, we have to do our job in the MainActivity.onCreate(/*...*/) funciton. So gather what resources we have to obtain there:

1. The context, which is the reference to the activity, which started the plugin,

2. the context's lifecycle,

3. a SurfaceView, which we can render onto,
4. the context's resources folder

5. the context's asset folder,

6. an optional userNode.

The first five is pretty trivial if our MainActivity is derived from AppCompatActivity:

SurfaceView surfaceView = new SurfaceView(this);

apeFilamentRenderPlugin renderPlugin = new apeFilamentRenderPlugin(
                this, getLifecycle(), surfaceView,
                getResources(), getAssets(), /* ... */);

1. The context is a reference to our MainActivity.

2. AppCompatActivity implements the LifecycleOwner interface, therefore it has getLifecycle() method.
3. We can easily get the activity's SurfaceView by new SurfaceView(this).

4. The resource folder can be obtained with the getResources() method.

5. The asset folder can be obtained with the getAssets() method.

So what about the 6th parameter, the userNode? We need this in order to be able to propagate our camera's position into ApertusVR. If we do not need this feature in our application, just set the 6th parameter to null. Otherwise, we have to use the ApertusVR Java-API to create a userNode, possibly with some avatar geometry (e.g. a cone). Without further explanation the following code block shows an example for this:

String userName = /* get userName */;
String GUID = apeCoreConfig.getNetworkGUID();
apeNode userNode = apeSceneManager.createNode(userName, true, GUID);

if (userNode != null && userNode.isValid()) {
    apeManualMaterial userMaterial = Objects.requireNonNull(
    apeSceneManager.createEntity(
        userName + "_Material",
        apeEntity.Type.MATERIAL_MANUAL,
        true, GUID))
    .cast(new apeManualMaterial.apeManualMaterialBuilder());

    if(userMaterial != null && userMaterial.isValid()) {
        apeColor color = new apeColor(255f,105f,180f);
    
        userMaterial.setDiffuseColor(color);
        userMaterial.setSpecularColor(color);
    
        apeNode userConeNode = apeSceneManager.createNode(
                userName + "_ConeNode", true, GUID);
    
        if (userConeNode != null && userConeNode.isValid()) {
            userConeNode.setParentNode(userNode);
           
            apeConeGeometry userCone = Objects.requireNonNull(
                apeSceneManager.createEntity(
                    userName + "_ConeGeometry",
                    apeEntity.Type.GEOMETRY_CONE,
                    true, GUID))
                .cast(new apeConeGeometry.apeConeBuilder());
    
            if (userCone != null && userCone.isValid()) {
                userCone.setParentNode(userConeNode);
                userCone.setMaterial(userMaterial);
            }
        }
    }
}

Now we have userNode, so just we set it as the 6th parameter.

Great! What is left? The only task remained is to add our plugin as a lifecycle observer:

getLifecycle().addObserver(renderPlugin).

If you did everything as discussed and also paid attention on how to set up the ApertusVR system for applications, then the render plugin will give response for all the events occouring in ApertusVR while MainActivity is running.

For basic usage this is all you need to know. However to be able to custumize the plug-in for your own wish, see the next page on how to configure.