Package heronarts.lx

Class LXEngine

java.lang.Object
heronarts.lx.LXComponent
heronarts.lx.LXEngine
All Implemented Interfaces:
LXPath, LXSerializable, LXModulationContainer, LXOscComponent, LXParameterListener
public class LXEngine extends LXComponent implements LXOscComponent, LXModulationContainer
The engine is the core class that runs the internal animations. An engine is comprised of top-level modulators, then a number of channels, each of which has a set of patterns that it may transition between. These channels are blended together, and effects are then applied.

  • Field Details

  • Method Details

    • logProfiler

      public void logProfiler()

    • getPath

      public String getPath()
      Description copied from class: LXComponent
      Accessor for the path of this object. Returns the path this component was registered with. Some subclasses may override this if path structure is dynamic.
      Specified by:
      getPath in interface LXPath
      Overrides:
      getPath in class LXComponent
      Returns:
      path of this component relative to its parent

    • setInputDispatch

      public LXEngine setInputDispatch(LXEngine.Dispatch inputDispatch)

    • onParameterChanged

      public void onParameterChanged(LXParameter p)
      Description copied from class: LXComponent
      Subclasses are free to override this if desired. It will automatically fire for any listenable parameter that is registered with this component.
      Specified by:
      onParameterChanged in interface LXParameterListener
      Overrides:
      onParameterChanged in class LXComponent
      Parameters:
      p - Parameter that has a value change

    • getActualFrameRate

      public float getActualFrameRate()
      Gets the active frame rate of the engine when in threaded mode
      Returns:
      How many FPS the engine is running

    • getCpuLoad

      public float getCpuLoad()
      Gets a very rough estimate of the CPU load the engine is using before maxing out.
      Returns:
      Estimated CPU load

    • setFixedDeltaMs

      public LXEngine setFixedDeltaMs(double deltaMs)
      Utility for when rendering offline videos. Ignore how much real-time has passed between frames and compute animations based upon the given deltaMs
      Parameters:
      deltaMs - Fixed deltaMs between rendered frames
      Returns:
      this

    • start

      public void start()
      Starts the engine thread.

    • stop

      public void stop()
      Stops the engine thread.

    • isThreaded

      public boolean isThreaded()
      Returns whether the engine is actively threaded
      Returns:
      Whether engine is threaded

    • setThreaded

      public LXEngine setThreaded(boolean threaded)
      Sets the engine to threaded or non-threaded mode. Should only be called from the Processing animation thread.
      Parameters:
      threaded - Whether engine should run on its own thread
      Returns:
      this

    • onP4DidDispose

      public LXEngine onP4DidDispose()
      Utility method to shut down and join the engine thread, only when specifically in P4 mode.
      Returns:
      this

    • beforeP4LXDraw

      public void beforeP4LXDraw()
      Utility method for P4LX mode, invoked from the Processing draw thread to give a chance to change the threading state before the draw loop.

    • setSpeed

      public LXEngine setSpeed(double speed)
      Sets a global speed factor on the core animation engine. This does not impact the tempo object.
      Parameters:
      speed - Global speed multiplier
      Returns:
      this

    • setPaused

      public LXEngine setPaused(boolean paused)
      Pause the engine from running
      Parameters:
      paused - Whether to pause the engine to pause
      Returns:
      this

    • isPaused

      public boolean isPaused()

    • registerComponent

      public LXEngine registerComponent(String path, LXComponent component)
      Register a component with the engine. It will be saved and loaded.
      Parameters:
      path - Unique path key for saving and loading component
      component - Component
      Returns:
      this

    • addTask

      public LXEngine addTask(Runnable runnable)
      Add a task to be run once on the engine thread.
      Parameters:
      runnable - Task to run
      Returns:
      this

    • addLoopTask

      public LXEngine addLoopTask(LXLoopTask loopTask)
      Add a task to be run on every loop of the engine thread.
      Parameters:
      loopTask - Task to run on each engine loop
      Returns:
      this

    • removeLoopTask

      public LXEngine removeLoopTask(LXLoopTask loopTask)
      Remove a task from the list run on every loop invocation
      Parameters:
      loopTask - Task to stop running on every loop
      Returns:
      this

    • addTimeout

      public LXEngine.Timer addTimeout(double timerMs, Runnable runnable)
      Add a task to the engine that will run if the specified duration of milliseconds expires and the timeout has not been canceled. The timer is automatically canceled once it has run.
      Parameters:
      timerMs - Timeout in milliseconds
      runnable - Function to run after timeout expires
      Returns:
      Timer object which can be stopped via cancel()

    • addInterval

      public LXEngine.Timer addInterval(double intervalMs, Runnable runnable)
      Add a task to the engine that will run periodically every time the interval has passed, until explicitly canceled.
      Parameters:
      intervalMs - Interval in milliseconds
      runnable - Function to run whenever interval has passed
      Returns:
      Timer object which can be stopped via cancel()

    • addOutput

      public LXEngine addOutput(LXOutput output)
      Sets the output driver
      Parameters:
      output - Output driver, or null for no output
      Returns:
      this

    • getModulationEngine

      public LXModulationEngine getModulationEngine()
      Description copied from interface: LXModulationContainer
      Get the modulation engine implementation for this component
      Specified by:
      getModulationEngine in interface LXModulationContainer
      Returns:
      Modulation engine

    • run

      public void run()
      This is the core run loop of the LXEngine. It can be invoked from various places, such as the EngineThread when running in multi-threaded mode, or from a Processing sketch when in P4LX, or from another application framework. Unless you are writing your own new application framework using LX (this is not recommended), you should never call this method directly. It is only public to make it accessible to these other frameworks.

    • copyFrameThreadSafe

      public void copyFrameThreadSafe(LXEngine.Frame frame)
      This should be used when in threaded mode. It synchronizes on the double-buffer and duplicates the internal copy buffer into the provided buffer.
      Parameters:
      frame - Frame buffer to copy into

    • getFrameNonThreadSafe

      public void getFrameNonThreadSafe(LXEngine.Frame frame)
      Non-thread safe accessor of the render buffer. Directly copies from it, which if in multi-threaded mode could happen during modification. Basically, never call this from the non-engine thread.
      Parameters:
      frame - Frame buffer to copy into

    • handleOscMessage

      public boolean handleOscMessage(OscMessage message, String[] parts, int index)
      Description copied from class: LXComponent
      Handles an OSC message sent to this component. By default this method handles registered components and parameters, but subclasses may override this method to handle different types of OSC messages.
      Specified by:
      handleOscMessage in interface LXOscComponent
      Overrides:
      handleOscMessage in class LXComponent
      Parameters:
      message - Full OSC message object
      parts - The OSC address pattern, broken into an array of parts
      index - Which index into the parts array corresponds to this component's children
      Returns:
      true if the OSC message was handled and should be considered consumed, false otherwise

    • load

      public void load(LX lx, JsonObject obj)
      Description copied from class: LXComponent
      Loads the LX component. Restores the ID of the component, as well as its internal and user-facing parameters. Any explicitly registered children will be automatically loaded, so long as they are direct descendants. Dynamic arrays will not be automatically loaded, this is left to subclasses to implement.
      Specified by:
      load in interface LXSerializable
      Overrides:
      load in class LXComponent
      Parameters:
      lx - LX instance
      obj - Object to deserialize

    • dispose

      public void dispose()
      Description copied from class: LXComponent
      Invoked when a component is being removed from the system and will no longer be used at all. This unregisters the component and should free up any resources and parameter listeners. Ideally after this method is called the object should be eligible for garbage collection. Subclasses are generally expected to override this method to handle their particular cleanup work. They should also generally call super.dispose() at the appropriate time to perform the basic cleanup, which may need to happen either before or after cleaning up other objects.
      Overrides:
      dispose in class LXComponent