//filament-android/com.google.android.filament/Engine

Engine

open class Engine

Engine is filament's main entry-point.

An Engine instance main function is to keep track of all resources created by the user and manage the rendering thread as well as the hardware renderer.

To use filament, an Engine instance must be created first:

import com.google.android.filament.*

Engine engine = Engine.create();

Engine essentially represents (or is associated to) a hardware context (e.g. an OpenGL ES context).

Rendering typically happens in an operating system's window (which can be full screen), such window is managed by a Renderer.

A typical filament render loop looks like this:

import com.google.android.filament.*

Engine engine        = Engine.create();
SwapChain swapChain  = engine.createSwapChain(nativeWindow);
Renderer renderer    = engine.createRenderer();
Scene scene          = engine.createScene();
View view            = engine.createView();

view.setScene(scene);

do {
    // typically we wait for VSYNC and user input events
    if (renderer.beginFrame(swapChain)) {
        renderer.render(view);
        renderer.endFrame();
    }
} while (!quit);

engine.destroyView(view);
engine.destroyScene(scene);
engine.destroyRenderer(renderer);
engine.destroySwapChain(swapChain);
engine.destroy();

Resource Tracking

Each Engine instance keeps track of all objects created by the user, such as vertex and index buffers, lights, cameras, etc... The user is expected to free those resources, however, leaked resources are freed when the engine instance is destroyed and a warning is emitted in the console.

Thread safety

An Engine instance is not thread-safe. The implementation makes no attempt to synchronize calls to an Engine instance methods. If multi-threading is needed, synchronization must be external.

Multi-threading

When created, the Engine instance starts a render thread as well as multiple worker threads, these threads have an elevated priority appropriate for rendering, based on the platform's best practices. The number of worker threads depends on the platform and is automatically chosen for best performance.

On platforms with asymmetric cores (e.g. ARM's Big.Little), Engine makes some educated guesses as to which cores to use for the render thread and worker threads. For example, it'll try to keep an OpenGL ES thread on a Big core.

Swap Chains

A swap chain represents an Operating System's native renderable surface. Typically it's a window or a view. Because a SwapChain is initialized from a native object, it is given to filament as an Object, which must be of the proper type for each platform filament is running on.

See also

Types

Functions