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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	LXEngine.Dispatch
static class	LXEngine.Frame
class	LXEngine.NetworkThread
class	LXEngine.Output
class	LXEngine.Profiler

Nested classes/interfaces inherited from class heronarts.lx.LXComponent

LXComponent.Placeholder, LXComponent.Renamable

Nested classes/interfaces inherited from interface heronarts.lx.LXSerializable

LXSerializable.Utils

Field Summary

Fields

Modifier and Type	Field and Description
LXAudioEngine	audio
LXClipEngine	clips
BoundedParameter	framesPerSecond
BooleanParameter	isChannelMultithreaded
BooleanParameter	isMultithreaded
BooleanParameter	isNetworkMultithreaded
LXMappingEngine	mapping
LXMidiEngine	midi
LXMixerEngine	mixer
LXModulationEngine	modulation
LXEngine.NetworkThread	networkThread
long	nowMillis Globally accessible counter of the current millisecond clock
LXOscEngine	osc
LXEngine.Output	output
LXPalette	palette
LXEngine.Profiler	profiler
LXSnapshotEngine	snapshots
BoundedParameter	speed
Tempo	tempo

Fields inherited from class heronarts.lx.LXComponent

controlSurfaceSemaphore, KEY_CLASS, KEY_COMPONENT_ID, KEY_ID, KEY_PARAMETER_PATH, KEY_PATH, label, lx, modulationColor

Method Summary

Modifier and Type	Method and Description
LXEngine	addLoopTask(LXLoopTask loopTask) Add a task to be run on every loop of the engine thread.
LXEngine	addOutput(LXOutput output) Sets the output driver
LXEngine	addTask(Runnable runnable) Add a task to be run once on the engine thread.
void	beforeP3LXDraw() Utility method for P3LX mode, invoked from the Processing draw thread to give a chance to change the threading state before the draw loop.
void	copyFrameThreadSafe(LXEngine.Frame frame) This should be used when in threaded mode.
void	dispose() Invoked when a component is being removed from the system and will no longer be used at all.
float	getActualFrameRate() Gets the active frame rate of the engine when in threaded mode
float	getCpuLoad() Gets a very rough estimate of the CPU load the engine is using before maxing out.
void	getFrameNonThreadSafe(LXEngine.Frame frame) Non-thread safe accessor of the render buffer.
LXModulationEngine	getModulationEngine()
String	getPath() Accessor for the path of this object.
boolean	isPaused()
boolean	isThreaded() Returns whether the engine is actively threaded
void	load(LX lx, JsonObject obj) Loads the LX component.
void	logProfiler()
void	onParameterChanged(LXParameter p) Subclasses are free to override this if desired.
LXEngine	registerComponent(String path, LXComponent component) Register a component with the engine.
LXEngine	removeLoopTask(LXLoopTask loopTask) Remove a task from the list run on every loop invocation
void	run() This is the core run loop of the LXEngine.
LXEngine	setFixedDeltaMs(double deltaMs) Utility for when rendering offline videos.
LXEngine	setInputDispatch(LXEngine.Dispatch inputDispatch)
LXEngine	setPaused(boolean paused) Pause the engine from running
LXEngine	setSpeed(double speed) Sets a global speed factor on the core animation engine.
LXEngine	setThreaded(boolean threaded) Sets the engine to threaded or non-threaded mode.
void	start() Starts the engine thread.
void	stop() Stops the engine thread.

Methods inherited from class heronarts.lx.LXComponent

addArray, addChild, addInternalParameter, addParameter, addParameter, contains, copyParameters, getChild, getComponentName, getComponentName, getComponentName, getId, getLabel, getLX, getOscAddress, getOscLabel, getOscPath, getParameter, getParameters, getParent, handleOscMessage, loadParameters, removeParameter, removeParameter, save, saveParameters, setParent, toString, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface heronarts.lx.osc.LXOscComponent

getOscAddress, handleOscMessage

Methods inherited from interface heronarts.lx.LXPath

get, get, getCanonicalLabel, getCanonicalLabel, getCanonicalPath, getCanonicalPath, getComponent, getComponent, getParameter, getParameter

Field Detail

palette

public final LXPalette palette

tempo

public final Tempo tempo

clips

public final LXClipEngine clips

mixer

public final LXMixerEngine mixer

midi

public final LXMidiEngine midi

audio

public final LXAudioEngine audio

mapping

public final LXMappingEngine mapping

osc

public final LXOscEngine osc

output

public final LXEngine.Output output

framesPerSecond

public final BoundedParameter framesPerSecond

speed

public final BoundedParameter speed

modulation

public final LXModulationEngine modulation

snapshots

public final LXSnapshotEngine snapshots

profiler

public final LXEngine.Profiler profiler

isMultithreaded

public final BooleanParameter isMultithreaded

isChannelMultithreaded

public final BooleanParameter isChannelMultithreaded

isNetworkMultithreaded

public final BooleanParameter isNetworkMultithreaded

networkThread

public final LXEngine.NetworkThread networkThread

nowMillis

public long nowMillis

Globally accessible counter of the current millisecond clock

Method Detail

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

beforeP3LXDraw

public void beforeP3LXDraw()

Utility method for P3LX 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

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

Specified by:

getModulationEngine in interface LXModulationContainer

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 P3LX, 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

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