Package 

Class AutomationEngine

  • 
public class AutomationEngine

    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 asynchronous 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(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).
      AutomationEngine() Creates an automation engine for the sole purpose of pushing settings, or for executingthe default test sequence.To see how the default test sequence is generated, search for DEFAULT_AUTOMATION.

    • Method Summary

      Modifier and Type Method Description
      void setOptions(@NonNull() AutomationEngine.Options options) Configures the automation engine for users who wish to set up a custom sleep timebetween tests, etc.
      void startRunning() Activates the automation test.
      void startBatchMode() Activates the automation test, but enters a paused state until the user callssignalBatchMode().
      void tick(@NonNull() Engine engine, @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 internaltest counter is potentially incremented.
      void applySettings(@NonNull() Engine engine, @NonNull() 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().
      AutomationEngine.ViewerOptions getViewerOptions() Gets the current viewer options.NOTE: Focal length here might be different from the user-specified value, due to DoF options.
      ColorGrading getColorGrading(@NonNull() 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 createsa new one.
      void signalBatchMode() Signals that batch mode can begin.
      void stopRunning() Cancels an in-progress automation session.
      boolean shouldClose() Returns true if automation is in batch mode and all tests have finished.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • AutomationEngine

        AutomationEngine(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

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

    • Method Detail

      • startRunning

         void startRunning()

        Activates the automation test. During the subsequent call to tick(), the first test isapplied and automation enters the running state.

      • startBatchMode

         void startBatchMode()

        Activates the automation test, but enters a paused state until the user callssignalBatchMode().

      • tick

         void tick(@NonNull() Engine engine, @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 internaltest counter is potentially incremented.

        Parameters:
        engine - The filament Engine of interest.
        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

         void applySettings(@NonNull() Engine engine, @NonNull() 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 aremote control, as opposed to iterating through a predetermined test sequence.This updates the stashed Settings object, then pushes those settings to the givenFilament objects. Clients can optionally call getColorGrading() after calling this method.

        Parameters:
        engine - Filament Engine to use.
        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.

      • getColorGrading

        @NonNull() ColorGrading getColorGrading(@NonNull() 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 createsa new one.

      • signalBatchMode

         void signalBatchMode()

        Signals that batch mode can begin. Call this after all meshes and textures finish loading.

      • stopRunning

         void stopRunning()

        Cancels an in-progress automation session.

      • shouldClose

         boolean shouldClose()

        Returns true if automation is in batch mode and all tests have finished.