Package com.google.android.filament

Class Engine

  • public class Engine
extends java.lang.Object
    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.*

 Engin 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:
    SwapChain, Renderer

    • Method Detail

      • create

        @NonNull
public static Engine create()
        Creates an instance of Engine using the default Engine.Backend

        This method is one of the few thread-safe methods.

        Returns:
        A newly created Engine, or null if the GPU driver couldn't be initialized, for instance if it doesn't support the right version of OpenGL or OpenGL ES.
        Throws:
        java.lang.IllegalStateException - can be thrown if there isn't enough memory to allocate the command buffer.

      • create

        @NonNull
public static Engine create​(@NonNull
                            Engine.Backend backend)
        Creates an instance of Engine using the specified Engine.Backend

        This method is one of the few thread-safe methods.

        Parameters:
        backend - driver backend to use
        Returns:
        A newly created Engine, or null if the GPU driver couldn't be initialized, for instance if it doesn't support the right version of OpenGL or OpenGL ES.
        Throws:
        java.lang.IllegalStateException - can be thrown if there isn't enough memory to allocate the command buffer.

      • create

        @NonNull
public static Engine create​(@NonNull
                            java.lang.Object sharedContext)
        Creates an instance of Engine using the Engine.Backend.OPENGL and a shared OpenGL context.

        This method is one of the few thread-safe methods.

        Parameters:
        sharedContext - A platform-dependant OpenGL context used as a shared context when creating filament's internal context. On Android this parameter must be an instance of EGLContext.
        Returns:
        A newly created Engine, or null if the GPU driver couldn't be initialized, for instance if it doesn't support the right version of OpenGL or OpenGL ES.
        Throws:
        java.lang.IllegalStateException - can be thrown if there isn't enough memory to allocate the command buffer.

      • isValid

        public boolean isValid()
        Returns:
        true if this Engine is initialized properly.

      • destroy

        public void destroy()
        Destroy the Engine instance and all associated resources.

        This method is one of the few thread-safe methods.

        destroy() should be called last and after all other resources have been destroyed, it ensures all filament resources are freed.

        Destroy performs the following tasks:

      • Destroy all internal software and hardware resources.
      • Free all user allocated resources that are not already destroyed and logs a warning.

        This indicates a "leak" in the user's code.

      • Terminate the rendering engine's thread.
        •  Engine engine = Engine.create();
 engine.destroy();