Package com.google.android.filament.utils

Class AutomationEngine

  • public class AutomationEngine
extends java.lang.Object
    The AutomationEngine makes it easy to push a bag of settings values to Filament. It can also be used to iterate through settings permutations for testing purposes. When creating an automation engine for testing purposes, clients give it a JSON string that tells it how to generate permutations of settings. Automation is always in one of two states: running or idle. The running state can be entered immediately (startRunning) or by requesting batch mode (startBatchMode). When executing a test, clients should call tick() after each frame is rendered, which provides an opportunity to push settings to Filament, increment the current test index (if enough time has elapsed), and request an asychronous screenshot. The time to sleep between tests is configurable and can be set to zero. Automation also waits a specified minimum number of frames between tests. Batch mode is meant for non-interactive applications. In batch mode, automation defers applying the first test case until the client unblocks it via signalBatchMode(). This is useful when waiting for a large model file to become fully loaded. Batch mode also offers a query (shouldClose) that is triggered after the last test has been invoked.

    • Constructor Summary

      Constructors 
      Constructor Description
      AutomationEngine()
      Creates an automation engine for the sole purpose of pushing settings, or for executing the default test sequence.
      AutomationEngine​(java.lang.String jsonSpec)
      Creates an automation engine from a JSON specification.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void applySettings​(java.lang.String settingsJson, AutomationEngine.ViewerContent content)
      Mutates a set of client-owned Filament objects according to a JSON string.
      protected void finalize()  
      com.google.android.filament.ColorGrading getColorGrading​(com.google.android.filament.Engine engine)
      Gets a color grading object that corresponds to the latest settings.
      AutomationEngine.ViewerOptions getViewerOptions()
      Gets the current viewer options.
      void setOptions​(AutomationEngine.Options options)
      Configures the automation engine for users who wish to set up a custom sleep time between tests, etc.
      boolean shouldClose()
      Returns true if automation is in batch mode and all tests have finished.
      void signalBatchMode()
      Signals that batch mode can begin.
      void startBatchMode()
      Activates the automation test, but enters a paused state until the user calls signalBatchMode().
      void startRunning()
      Activates the automation test.
      void stopRunning()
      Cancels an in-progress automation session.
      void tick​(AutomationEngine.ViewerContent content, float deltaTime)
      Notifies the automation engine that time has passed and a new frame has been rendered.

      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • AutomationEngine

        public AutomationEngine​(@NonNull
                        java.lang.String jsonSpec)
        Creates an automation engine from a JSON specification. An example of a JSON spec can be found by searching the repo for DEFAULT_AUTOMATION. This is documented using a JSON schema (look for viewer/schemas/automation.json).
        Parameters:
        jsonSpec - Valid JSON string that conforms to the automation schema.

      • AutomationEngine

        public AutomationEngine()
        Creates an automation engine for the sole purpose of pushing settings, or for executing the default test sequence. To see how the default test sequence is generated, search for DEFAULT_AUTOMATION.

    • Method Detail

      • setOptions

        public void setOptions​(@NonNull
                       AutomationEngine.Options options)
        Configures the automation engine for users who wish to set up a custom sleep time between tests, etc.

      • startRunning

        public void startRunning()
        Activates the automation test. During the subsequent call to tick(), the first test is applied and automation enters the running state.

      • startBatchMode

        public void startBatchMode()
        Activates the automation test, but enters a paused state until the user calls signalBatchMode().

      • tick

        public void tick​(@NonNull
                 AutomationEngine.ViewerContent content,
                 float deltaTime)
        Notifies the automation engine that time has passed and a new frame has been rendered. This is when settings get applied, screenshots are (optionally) exported, and the internal test counter is potentially incremented.
        Parameters:
        content - Contains the Filament View, Materials, and Renderer that get modified.
        deltaTime - The amount of time that has passed since the previous tick in seconds.

      • applySettings

        public void applySettings​(@NonNull
                          java.lang.String settingsJson,
                          @NonNull
                          AutomationEngine.ViewerContent content)
        Mutates a set of client-owned Filament objects according to a JSON string. This method is an alternative to tick(). It allows clients to use the automation engine as a remote control, as opposed to iterating through a predetermined test sequence. This updates the stashed Settings object, then pushes those settings to the given Filament objects. Clients can optionally call getColorGrading() after calling this method.
        Parameters:
        settingsJson - Contains the JSON string with a set of changes that need to be pushed.
        content - Contains a set of Filament objects that you want to mutate.

      • getViewerOptions

        @NonNull
public AutomationEngine.ViewerOptions getViewerOptions()
        Gets the current viewer options. NOTE: Focal length here might be different from the user-specified value, due to DoF options.

      • getColorGrading

        @NonNull
public com.google.android.filament.ColorGrading getColorGrading​(@NonNull
                                                                com.google.android.filament.Engine engine)
        Gets a color grading object that corresponds to the latest settings. This method either returns a cached instance, or it destroys the cached instance and creates a new one.

      • signalBatchMode

        public void signalBatchMode()
        Signals that batch mode can begin. Call this after all meshes and textures finish loading.

      • stopRunning

        public void stopRunning()
        Cancels an in-progress automation session.

      • shouldClose

        public boolean shouldClose()
        Returns true if automation is in batch mode and all tests have finished.

      • finalize

        protected void finalize()
                 throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable