Package 

Class Engine

  • 
public 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();

    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.

    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.

    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.

    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.

    • Method Detail

      • create

        @NonNull() static Engine create()

        Creates an instance of Engine using the default Backend

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

      • create

        @NonNull() static Engine create(@NonNull() Object sharedContext)

        Creates an instance of Engine using the 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 contextwhen creating filament's internal context.

      • destroy

         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 beendestroyed, 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();

      • enableAccurateTranslations

         void enableAccurateTranslations()

        Helper to enable accurate translations.If you need this Engine to handle a very large world space, one way to achieve thisautomatically is to enable accurate translations in the TransformManager. This helperprovides a convenient way of doing that.This is typically called once just after creating the Engine.

      • setActiveFeatureLevel

        @NonNull() Engine.FeatureLevel setActiveFeatureLevel(@NonNull() Engine.FeatureLevel featureLevel)

        Activate all features of a given feature level. If an explicit feature level is not specifiedat Engine initialization time via featureLevel, the default feature level is FEATURE_LEVEL_0 on devices not compatible with GLES 3.0; otherwise, thedefault is ::FEATURE_LEVEL_1. The selected feature level must not behigher than the value returned by getActiveFeatureLevel and it's not possible lowerthe active feature level. Additionally, it is not possible to modify the feature level at allif the Engine was initialized at FEATURE_LEVEL_0.

        Parameters:
        featureLevel - the feature level to activate.

      • setAutomaticInstancingEnabled

         void setAutomaticInstancingEnabled(boolean enable)

        Enables or disables automatic instancing of render primitives. Instancing of render primitivecan greatly reduce CPU overhead but requires the instanced primitives to be identical(i.e. use the same geometry) and use the same MaterialInstance. If it is known that thescene doesn't contain any identical primitives, automatic instancing can have someoverhead and it is then best to disable it.Disabled by default.

        Parameters:
        enable - true to enable, false to disable automatic instancing.

      • getConfig

        @NonNull() Engine.Config getConfig()

        Retrieves the configuration settings of this Engine.This method returns the configuration object that was supplied to the Engine's method during the creation of this Engine. If the ::config method was not explicitly called (or called with null), this method returns the defaultconfiguration settings.

      • getMaxStereoscopicEyes

         long getMaxStereoscopicEyes()

        Returns the maximum number of stereoscopic eyes supported by Filament. The actual number ofeyes rendered is set at Engine creation time with the stereoscopicEyeCount setting.

      • isValidRenderer

         boolean isValidRenderer(@NonNull() Renderer object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidView

         boolean isValidView(@NonNull() View object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidScene

         boolean isValidScene(@NonNull() Scene object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidFence

         boolean isValidFence(@NonNull() Fence object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidStream

         boolean isValidStream(@NonNull() Stream object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidMaterial

         boolean isValidMaterial(@NonNull() Material object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidSkybox

         boolean isValidSkybox(@NonNull() Skybox object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidTexture

         boolean isValidTexture(@NonNull() Texture object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • isValidSwapChain

         boolean isValidSwapChain(@NonNull() SwapChain object)

        Returns whether the object is valid.

        Parameters:
        object - Object to check for validity

      • createCamera

        @NonNull() Camera createCamera(int entity)

        Creates and adds a Camera component to a given entity.

        Parameters:
        entity - entity to add the camera component to

      • destroyCameraComponent

         void destroyCameraComponent(int entity)

        Destroys the Camera component associated with the given entity.

        Parameters:
        entity - an entity

      • destroyEntity

         void destroyEntity(int entity)

        Destroys all Filament-known components from this entity.

        This method destroys Filament components only, not the entity itself. To destroythe entity use EntityManager#destroy.It is recommended to destroy components individually before destroying theirentity, this gives more control as to when the destruction really happens.Otherwise, orphaned components are garbage collected, which can happen at a later time.Even when component are garbage collected, the destruction of their entityterminates their participation immediately.

        Parameters:
        entity - the entity to destroy

      • flushAndWait

         void flushAndWait()

        Kicks the hardware thread (e.g.: the OpenGL, Vulkan or Metal thread) and blocks untilall commands to this point are executed. Note that this does guarantee that thehardware is actually finished.

        This is typically used right after destroying the SwapChain,in cases where a guarantee about the SwapChain destruction is needed in a timely fashion,such as when responding to Android's surfaceDestroyed.

      • flushAndWait

         boolean flushAndWait(long timeout)

        Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks untilall commands to this point are executed. Note that does guarantee that thehardware is actually finished.A timeout can be specified, if for some reason this flushAndWait doesn't complete before the timeout, it willreturn false, true otherwise.

        This is typically used right after destroying the SwapChain,in cases where a guarantee about the SwapChain destruction is needed in atimely fashion, such as when responding to Android'sandroid.view.SurfaceHolder.Callback.surfaceDestroyed

        Parameters:
        timeout - A timeout in nanoseconds

      • flush

         void flush()

        Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) but does not waitfor commands to be either executed or the hardware finished.

        This is typically used after creating a lot of objects to start draining the commandqueue which has a limited size.

      • isPaused

         boolean isPaused()

        Get paused state of rendering thread.

        Warning: This is an experimental API.

      • setPaused

         void setPaused(boolean paused)

        Pause or resume the rendering thread.

        Warning: This is an experimental API. In particular, note the following caveats.

        • Buffer callbacks will never be called as long as the rendering thread is paused.Do not rely on a buffer callback to unpause the thread.
        • While the rendering thread is paused, rendering commands will continue to be queued until thebuffer limit is reached. When the limit is reached, the program will abort.

      • unprotected

         void unprotected()

        Switch the command queue to unprotected mode. Protected mode can be activated viaRenderer::beginFrame() using a protected SwapChain.

      • getSteadyClockTimeNano

         static native long getSteadyClockTimeNano()

        Get the current time. This is a convenience function that simply returns thetime in nanosecond since epoch of std::chrono::steady_clock.

      • hasFeatureFlag

         boolean hasFeatureFlag(@NonNull() String name)

        Checks if a feature flag exists

        Parameters:
        name - name of the feature flag to check

      • setFeatureFlag

         boolean setFeatureFlag(@NonNull() String name, boolean value)

        Set the value of a non-constant feature flag.

        Parameters:
        name - name of the feature flag to set
        value - value to set

      • getFeatureFlag

         boolean getFeatureFlag(@NonNull() String name)

        Retrieves the value of any feature flag.

        Parameters:
        name - name of the feature flag