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.

Nested Class Summary

Nested Classes

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

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

LXComponent.Hidden, LXComponent.Placeholder, LXComponent.Renamable

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

LXSerializable.Utils

Field Summary

Fields

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

Fields inherited from class heronarts.lx.LXComponent

children, internalParameters, KEY_CHILDREN, KEY_CLASS, KEY_COMPONENT_ID, KEY_ID, KEY_INTERNAL, KEY_PARAMETER_PATH, KEY_PARAMETERS, KEY_PATH, KEY_RESET, label, legacyInternalParameters, legacyParameters, lx, modulationColor, modulationControlsExpanded, modulationsExpanded, parameters, presetFile

Fields inherited from interface heronarts.lx.LXPath

ROOT, ROOT_PREFIX, ROOT_SLASH

Method Summary

Modifier and Type	Method	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	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.
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	handleOscMessage(OscMessage message, String[] parts, int index)	Handles an OSC message sent to this component.
boolean	isPaused()
boolean	isThreaded()	Returns whether the engine is actively threaded
void	load(LX lx, JsonObject obj)	Loads the LX component.
void	logProfiler()
LXEngine	onP4DidDispose()	Utility method to shut down and join the engine thread, only when specifically in P4 mode.
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, addLegacyInternalParameter, addLegacyParameter, addParameter, addParameter, addParameters, contains, copyParameters, getCategory, getChild, getComponentName, getComponentName, getComponentName, getDescription, getId, getLabel, getLX, getOscAddress, getOscLabel, getOscPath, getParameter, getParameters, getParent, hasParameter, isValidOscParameter, loadParameters, loadPreset, removeParameter, removeParameter, removeParameter, removeParameter, save, savePreset, setDescription, setParent, toOscQuery, toOscQuery, toOscQuery, 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

Methods inherited from interface heronarts.lx.LXPath

getCanonicalLabel, getCanonicalLabel, getCanonicalPath, getCanonicalPath, isDescendant

Field Details

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

dmx

public final LXDmxEngine dmx

output

public final LXEngine.Output output

framesPerSecond

public final BoundedParameter framesPerSecond

speed

public final BoundedParameter speed

performanceMode

public final BooleanParameter performanceMode

restricted

public final BooleanParameter restricted

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

nowNanoTime

public long nowNanoTime

Globally accessible counter of the current millisecond clock

nowMillis

public long nowMillis

PATH_FRAMERATE

public static final String PATH_FRAMERATE

See Also:

• Constant Field Values

PATH_OPEN_PROJECT

public static final String PATH_OPEN_PROJECT

See Also:

• Constant Field Values

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

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