How to configure

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

ApertusVR provides configuration possibility for each of its plug-ins by .json files. This is not different in the case of the Filament render plugin on Android. On this page, we will shortly discuss how and what you can configure.

Creating the configuraiton file

In the page of how to use the JNI-plugin, we mentionted, that in order to use configuration files, you have to place the file into your application's asset folder. In our case, the configuration file should named as apeFilamentRenderPlugin.json.

For a brighter explanation let us assume, that your configuration folder path in the asset folder is /configFiles. This means that when you start ApertusVR with the following command:

if (!apeSystem.isRunning()) {
    apeSystem.start("configFiles",getAssets());
}

and start the Filement plug-in as it was discussed a page earlier, then it will search for the file at /configFiles/apeFilamentRenderPlugin.json. In the plug-in it looks like this:

String configFolderPath = apeCoreConfig.getConfigFolderPath();
try {
    ByteBuffer buffer = readUncompressedAsset(
            configFolderPath + "/apeFilamentRenderJavaPlugin.json");
    // ...
}
// ...

Editing the configuration file

There are plenty of configuration options in the render plug-in, which are:

• Camera options

• Shadow options

• Sun lighting options

• Skybox options

• Resource locations

Camera options

Configuring the camera is pretty obvious, the following code block will show a possible configuration in the apeFilamentRenderJavaPlugin.json file:

"camera" : {
    "fov" : 45.0,
    "nearClip" : 0.1,
    "farClip" : 1000.0,
    "controller" : {
        "position" : [0, 120, -180],
        "horizontal" : 3.1415,
        "vertical" : 0.0,
        "speed" : 2.0,
        "rotateSpeed" : 0.001
    }
},

The controller block needs further explanation. Filament render takes care of controlling the camera in the scene, by listening to user inputs (e.g. taps). This is done by the apeCameraController class. In the "controller" block, we can set its initial position and orientation (horizontal and vertical angle), as well the its linear and angular speed.

Shadow options

Filament makes it available to render shadows on our scenes. From the configuration file we can enable this functionality, and set the corresponding values which are controlling the shadow. In the configuration file we can set the followings:

• mapSize

• shadowFar

• shadowNearHint

• shadowFarHint

• maxShadowDistance

To learn what these parameters do, check the LightManager.h file in Filament's GitHub repository for an in source documentation.

Sun lighting

Filament can only provide one directional light on our scene. This makes it hard when working with ApertusVR, which allows multiple directional lights. To solve this, we can set Sun light in the configuration file, which is just a special directional light. We can set its intensity and direction, and also we can enable or disable this functionality:

"sunLight" : {
    "enable" : true,
    "intensity" : 1.1e5,
    "direction" : [-1.0, -1.0, 0.0]
},

Skybox

We can set skybox for the scene from the configuration file. Basically the format required is rgb32f. You can generate files with this format from hdr images with the Filament tool called cmgen. To laod it for your scene, you have place the generated cube-map into your application's asset folder. Then you have to tell the plugin where it can find your skybox in the configuration file. E.g. assume your cube-map is in the /envs folder and its name is skyBox (so your generated rgb32f files are in /envs/skyBox), then your configurations should look like this:

"skybox" : {
    "enable" : true,
    "skyboxName" : "skyBox",
    "resourcePath" : "envs",
    "iblIntensity" : 40000.0
},

Note that, you can also enable/disable the skybox, and set the intensity of the image based lighting.

Filament uses global illumination, therefore the ambient colors of the renderable objects on the scene are calculated from the skybox.

Resources

The resources used by the plugin are placed on the application user's Android device. For each application there is a unique folder on the device where it can put its resources and caches. We have to tell the render plug-in that inside this folder where it can find the resources.

However there is one other problem we have to face with. When an events like GEOMETRY_FILE_FILENAME are fired in ApertusVR, the filename in the entity (which the event's subjectName refers to) points to a directory which is assumed to be available on Windows, but not on Android. This means that it has a prefix we should throw away from the file path to find the actual file on the android device. We can also set this prefix in the configuration file.

For an example, assume that we place our 3D resources into the /models folder, and the equivalent folder for the Windows application is ../../samples/sampleName/models. Then our configuration file should look like this:

"resources" : {
    "resourcePath" : "/models",
    "resourcePrefix" : "../../samples/sampleName/models/"
}

When ApertusVR sends us a GEOMETRY_FILE_FILENAME event which refers to the Bar.obj file in the Foo folder, the GeometryFile entity will have "../../samples/sampleName/models/Foo/Bar.obj" in its fileName member variable. However, we have told the plug-in that it should avoid the prefix, thus it will search for the file: <filesDir>/models/Foo/Bar.obj instead of <filesDir>/../../samples/sampleName/models/Foo/Bar.obj.