LX (LX API)

java.lang.Object
- heronarts.lx.LX

Direct Known Subclasses:

P3LX
```
public class LX
extends Object
```
Core controller for a LX instance. Each instance drives a 3-d collection of nodes defined by a dynamic model.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`LX.Error`
`static class`	`LX.Flags`
`static class`	`LX.InitProfiler`
`static class`	`LX.InstantiationException`
`static interface`	`LX.Listener` Listener for top-level events
`static class`	`LX.Media`
`static interface`	`LX.Permissions`
`static interface`	`LX.ProjectListener`

Field Summary

Fields
Modifier and Type	Field and Description
`LXClipboard`	`clipboard` Clipboard for copy/paste
`LXCommandEngine`	`command` Command engine, utilized by higher-level UIs to manage engine state and undo operations.
`LXEngine`	`engine` The animation engine.
`MutableParameter`	`errorChanged` Parameter that is bang()-ed every time errors change
`StringParameter`	`failure` This parameter will be set if a critical, unrecoverable error occurs.
`LX.Flags`	`flags` Configuration flags
`static double`	`HALF_PI`
`static float`	`HALF_PIf`
`static LX.InitProfiler`	`initProfiler`
`static boolean`	`LOG_WARNINGS`
`protected LXModel`	`model` The pixel model.
`protected LX.Permissions`	`permissions` Permissions
`static float`	`PIf`
`LXPreferences`	`preferences` Global preferences stored in persistent file
`LXRegistry`	`registry` Registry for classes
`LXScheduler`	`scheduler` The project scheduler
`LXStructure`	`structure` The lighting system structure
`static double`	`TWO_PI`
`static float`	`TWO_PIf`
`static String`	`VERSION`

Constructor Summary

Constructors
Modifier	Constructor and Description
	`LX()` Creates an LX instance with no nodes.
	`LX(LX.Flags flags)`
`protected`	`LX(LX.Flags flags, LXModel model)`
	`LX(LXModel model)` Constructs an LX instance with the given pixel model

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected static void`	`_error(String prefix, Exception x, String message)`
`protected static void`	`_error(String prefix, String message)`
`protected static void`	`_log(PrintStream stream, String message)`
`protected static void`	`_log(PrintStream stream, Throwable throwable, String prefix, String message)`
`protected static void`	`_log(String prefix, String message)`
`LX`	`addEffect(LXEffect effect)` Add an effect to the FX chain.
`LX`	`addEffects(LXEffect[] effects)` Add multiple effects to the chain
`LX`	`addListener(LX.Listener listener)`
`LX`	`addOutput(LXOutput output)` Adds an output driver
`LX`	`addProjectListener(LX.ProjectListener listener)`
`protected static void`	`bootstrapMediaPath(LX.Flags flags)`
`protected static void`	`bootstrapMediaPath(LX.Flags flags, String dirName)`
`protected void`	`confirmChangesSaved(String message, Runnable confirm)`
`LX`	`disableAutoCycle()` Stops patterns from automatically rotating
`void`	`dispose()` Shut down resources of the LX instance.
`LX`	`enableAutoCycle(int autoCycleThreshold)` Sets the patterns to rotate automatically
`static void`	`error(Exception x)`
`static void`	`error(String message)`
`static void`	`error(String prefix, Throwable x)`
`static void`	`error(Throwable x, String message)`
`protected void`	`fail(Exception x)`
`LXComponent`	`getComponent(int componentId)` Gets a component by its raw component id
`LX.Error`	`getError()`
`File`	`getMediaFile(LX.Media type, String path)` Retrieves a file handle to a file that can be saved.
`File`	`getMediaFile(LX.Media type, String path, boolean create)` Retrieves a file handle to a file that can be saved.
`File`	`getMediaFile(String path)` Retrieves a file handle to a file that can be saved.
`File`	`getMediaFolder(LX.Media type)` Retrieves a file handle to the folder used to store the given type of media
`File`	`getMediaFolder(LX.Media type, boolean create)` Retrieves a file handle to the folder used to store the given type of media
`String`	`getMediaPath()` Get the root media path for storage of LX-related objects and extensions
`String`	`getMediaPath(LX.Media type, File file)` Gets the path to a file relative to a base media path.
`LXModel`	`getModel()` Returns the model in use
`List<LXPattern>`	`getPatterns()` Gets the current set of patterns on the main channel.
`LX.Permissions`	`getPermissions()`
`File`	`getProject()`
`LXComponent`	`getProjectComponent(int projectId)` Gets a component by its id from the project file (which may have been remapped)
`LX`	`goIndex(int i)` Sets the main channel to a pattern of the given index
`LX`	`goNext()` Sets the main channel to the next pattern.
`LX`	`goPattern(LXPattern pattern)` Sets the main channel to a given pattern instance.
`LX`	`goPrev()` Sets the main channel to the previous pattern.
`static void`	`headless(LX.Flags flags, File projectFile)`
`static int`	`hsa(float h, float s, float a)` Shorthand for LXColor.hsa()
`static int`	`hsb(float h, float s, float b)` Shorthand for LXColor.hsb()
`LXBlend`	`instantiateBlend(Class<? extends LXBlend> cls)`
`LXBlend`	`instantiateBlend(String className)`
`<T extends LXComponent> T`	`instantiateComponent(Class<? extends T> cls, Class<T> type)`
`<T extends LXComponent> T`	`instantiateComponent(String className, Class<T> type)`
`LXEffect`	`instantiateEffect(Class<? extends LXEffect> cls)`
`LXEffect`	`instantiateEffect(String className)`
`LXFixture`	`instantiateFixture(Class<? extends LXFixture> cls)`
`LXFixture`	`instantiateFixture(String className)`
`LXModel`	`instantiateModel(String className)`
`LXModulator`	`instantiateModulator(Class<? extends LXModulator> cls)`
`LXModulator`	`instantiateModulator(String className)`
`LXPattern`	`instantiatePattern(Class<? extends LXPattern> cls)`
`LXPattern`	`instantiatePattern(String className)`
`protected LXRegistry`	`instantiateRegistry(LX lx)` Subclasses may override to provide an enhanced registry with support for more types
`boolean`	`isPaused()` Whether the engine is currently running.
`static void`	`log(String message)`
`static void`	`logInitProfiler()`
`static void`	`main(String[] args)` Runs a headless version of LX
`void`	`newProject()`
`void`	`openProject(File file)`
`LX`	`popError()`
`LX`	`pushError(Exception exception)`
`LX`	`pushError(Exception exception, String message)`
`LX`	`pushError(LX.Error error)`
`LX`	`registerExternal(String key, LXSerializable serializable)`
`LX`	`removeEffect(LXEffect effect)` Remove an effect from the chain
`LX`	`removeListener(LX.Listener listener)`
`LX`	`removeProjectListener(LX.ProjectListener listener)`
`static int`	`rgb(int r, int g, int b)` Shorthand for LXColor.rgb()
`void`	`saveProject()`
`void`	`saveProject(File file)`
`protected static void`	`setLogFile(File file)`
`void`	`setModelImportFlag(boolean modelImport)`
`LX`	`setPatterns(LXPattern[] patterns)` Specifies the set of patterns to be run.
`LX`	`setPaused(boolean paused)` Pause the engine from running
`protected void`	`setProject(File file, LX.ProjectListener.Change change)`
`void`	`setScheduleLoadingFlag(boolean scheduleLoading)`
`LX`	`setSpeed(double speed)` Sets the speed of the entire system.
`void`	`setSystemClipboardString(String str)`
`protected void`	`showConfirmUnsavedProjectDialog(String message, Runnable confirm)`
`LX`	`togglePaused()` Toggles the running state of the engine.
`static String`	`version()` Returns the version of the library.
`static void`	`warning(String message)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- VERSION
```
public static final String VERSION
```
  See Also:
  
  Constant Field Values
- HALF_PI
```
public static final double HALF_PI
```
  See Also:
  
  Constant Field Values
- TWO_PI
```
public static final double TWO_PI
```
  See Also:
  
  Constant Field Values
- PIf
```
public static final float PIf
```
  See Also:
  
  Constant Field Values
- HALF_PIf
```
public static final float HALF_PIf
```
  See Also:
  
  Constant Field Values
- TWO_PIf
```
public static final float TWO_PIf
```
  See Also:
  
  Constant Field Values
- initProfiler
```
public static final LX.InitProfiler initProfiler
```
- preferences
```
public final LXPreferences preferences
```
  Global preferences stored in persistent file
- flags
```
public final LX.Flags flags
```
  Configuration flags
- permissions
```
protected LX.Permissions permissions
```
  Permissions
- errorChanged
```
public final MutableParameter errorChanged
```
  Parameter that is bang()-ed every time errors change
- failure
```
public StringParameter failure
```
  This parameter will be set if a critical, unrecoverable error occurs. It will only be set one time, and it should be assumed that the engine is no longer running if this is the case.
- structure
```
public final LXStructure structure
```
  The lighting system structure
- model
```
protected LXModel model
```
  The pixel model.
- clipboard
```
public final LXClipboard clipboard
```
  Clipboard for copy/paste
- engine
```
public final LXEngine engine
```
  The animation engine.
- command
```
public final LXCommandEngine command
```
  Command engine, utilized by higher-level UIs to manage engine state and undo operations.
- registry
```
public final LXRegistry registry
```
  Registry for classes
- scheduler
```
public final LXScheduler scheduler
```
  The project scheduler
- LOG_WARNINGS
```
public static boolean LOG_WARNINGS
```

Constructor Detail

LX
```
public LX()
```
Creates an LX instance with no nodes.

LX
```
public LX(LXModel model)
```
Constructs an LX instance with the given pixel model

Parameters:

model - Pixel model

LX
```
public LX(LX.Flags flags)
```

LX

protected LX(LX.Flags flags,
             LXModel model)

Method Detail

version
```
public static String version()
```
Returns the version of the library.

Returns:

String

logInitProfiler
```
public static void logInitProfiler()
```

fail
```
protected void fail(Exception x)
```

getPermissions

public LX.Permissions getPermissions()

pushError

public LX pushError(Exception exception)

pushError

public LX pushError(Exception exception,
                    String message)

pushError
```
public LX pushError(LX.Error error)
```

popError
```
public LX popError()
```

getError
```
public LX.Error getError()
```

instantiateRegistry
```
protected LXRegistry instantiateRegistry(LX lx)
```
Subclasses may override to provide an enhanced registry with support for more types

Parameters:

lx - LX instance

Returns:

LXRegistry to use for dynamic class stuff

addListener

public LX addListener(LX.Listener listener)

removeListener

public LX removeListener(LX.Listener listener)

addProjectListener

public LX addProjectListener(LX.ProjectListener listener)

removeProjectListener

public LX removeProjectListener(LX.ProjectListener listener)

getComponent
```
public LXComponent getComponent(int componentId)
```
Gets a component by its raw component id

Parameters:

componentId - Component ID

Returns:

Component with that ID, or null if none exists

getProjectComponent
```
public LXComponent getProjectComponent(int projectId)
```
Gets a component by its id from the project file (which may have been remapped)

Parameters:

projectId - Component ID from loaded project file

Returns:

Component with that ID in the project file, may have a different component ID now

getModel
```
public LXModel getModel()
```
Returns the model in use

Returns:

model

dispose
```
public void dispose()
```
Shut down resources of the LX instance.

hsb
```
public static int hsb(float h,
                      float s,
                      float b)
```
Shorthand for LXColor.hsb()

Parameters:

h - Hue 0-360

s - Saturation 0-100

b - Brightness 0-100

Returns:

Color

hsa

public static int hsa(float h,
                      float s,
                      float a)

Shorthand for LXColor.hsa()

Parameters:: h - Hue 0-360; s - Saturation 0-100; a - Alpha 0-1
Returns:: Color

rgb
```
public static int rgb(int r,
                      int g,
                      int b)
```
Shorthand for LXColor.rgb()

Parameters:

r - Red 0-255

g - Green 0-255

b - Blue 0-255

Returns:

color

setSpeed
```
public LX setSpeed(double speed)
```
Sets the speed of the entire system. Default is 1.0, any modification will mutate deltaMs values system-wide.

Parameters:

speed - Coefficient, 1 is normal speed

Returns:

this

addEffects
```
public LX addEffects(LXEffect[] effects)
```
Add multiple effects to the chain

Parameters:

effects - Array of effects

Returns:

this

addEffect
```
public LX addEffect(LXEffect effect)
```
Add an effect to the FX chain.

Parameters:

effect - Effect

Returns:

this

removeEffect
```
public LX removeEffect(LXEffect effect)
```
Remove an effect from the chain

Parameters:

effect - Effect

Returns:

this

setPaused
```
public LX setPaused(boolean paused)
```
Pause the engine from running

Parameters:

paused - Whether to pause the engine to pause

Returns:

this

isPaused
```
public boolean isPaused()
```
Whether the engine is currently running.

Returns:

State of the engine

togglePaused
```
public LX togglePaused()
```
Toggles the running state of the engine.

Returns:

this

goPrev
```
public LX goPrev()
```
Sets the main channel to the previous pattern.

Returns:

this

goNext
```
public LX goNext()
```
Sets the main channel to the next pattern.

Returns:

this

goPattern
```
public LX goPattern(LXPattern pattern)
```
Sets the main channel to a given pattern instance.

Parameters:

pattern - The pattern instance to run

Returns:

this

goIndex
```
public LX goIndex(int i)
```
Sets the main channel to a pattern of the given index

Parameters:

i - Index of the pattern to run

Returns:

this

disableAutoCycle
```
public LX disableAutoCycle()
```
Stops patterns from automatically rotating

Returns:

this

enableAutoCycle
```
public LX enableAutoCycle(int autoCycleThreshold)
```
Sets the patterns to rotate automatically

Parameters:

autoCycleThreshold - Number of milliseconds after which to cycle

Returns:

this

addOutput
```
public LX addOutput(LXOutput output)
```
Adds an output driver

Parameters:

output - Output

Returns:

this

setPatterns
```
public LX setPatterns(LXPattern[] patterns)
```
Specifies the set of patterns to be run.

Parameters:

patterns - Array of patterns

Returns:

this

getPatterns
```
public List<LXPattern> getPatterns()
```
Gets the current set of patterns on the main channel.

Returns:

The list of patters

setProject

protected void setProject(File file,
                          LX.ProjectListener.Change change)

getProject
```
public File getProject()
```

saveProject
```
public void saveProject()
```

saveProject
```
public void saveProject(File file)
```

registerExternal

public LX registerExternal(String key,
                           LXSerializable serializable)

newProject
```
public void newProject()
```

openProject
```
public void openProject(File file)
```

setModelImportFlag

public void setModelImportFlag(boolean modelImport)

setScheduleLoadingFlag

public void setScheduleLoadingFlag(boolean scheduleLoading)

confirmChangesSaved

protected final void confirmChangesSaved(String message,
                                         Runnable confirm)

showConfirmUnsavedProjectDialog

protected void showConfirmUnsavedProjectDialog(String message,
                                               Runnable confirm)

getMediaPath
```
public String getMediaPath()
```
Get the root media path for storage of LX-related objects and extensions

Returns:

File path to root storage location of LX-related content

getMediaPath
```
public String getMediaPath(LX.Media type,
                           File file)
```
Gets the path to a file relative to a base media path. Useful for writing file names into project files.

Parameters:

type - Media type

file - File

Returns:

Relative path to file, from media type base, or absolute if outside of media container

getMediaFolder
```
public File getMediaFolder(LX.Media type)
```
Retrieves a file handle to the folder used to store the given type of media

Parameters:

type - Media type

Returns:

File handle to directory for storage of this type of media

getMediaFolder
```
public File getMediaFolder(LX.Media type,
                           boolean create)
```
Retrieves a file handle to the folder used to store the given type of media

Parameters:

type - Media type

create - Create folder if true

Returns:

File handle to directory for storage of this type of media

getMediaFile
```
public File getMediaFile(LX.Media type,
                         String path)
```
Retrieves a file handle to a file that can be saved. Path is given relative to the root LX media directory, unless the given path is absolute.

Parameters:

type - Media type

path - File path relative to LX media dir, or absolute

Returns:

File handle to file that can be saved

getMediaFile
```
public File getMediaFile(LX.Media type,
                         String path,
                         boolean create)
```
Retrieves a file handle to a file that can be saved. Path is given relative to the root LX media directory, unless the given path is absolute.

Parameters:

type - Media type

path - File path relative to LX media dir, or absolute

create - Create folder if true

Returns:

File handle to file that can be saved

getMediaFile
```
public File getMediaFile(String path)
```
Retrieves a file handle to a file that can be saved. Path is given relative to the root LX media directory, unless the given path is absolute.

Parameters:

path - File path relative to LX media dir, or absolute

Returns:

File handle to file that can be saved

instantiateModel

public LXModel instantiateModel(String className)
                         throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateComponent

public <T extends LXComponent> T instantiateComponent(String className,
                                                      Class<T> type)
                                               throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateComponent

public <T extends LXComponent> T instantiateComponent(Class<? extends T> cls,
                                                      Class<T> type)
                                               throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateFixture

public LXFixture instantiateFixture(String className)
                             throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateFixture

public LXFixture instantiateFixture(Class<? extends LXFixture> cls)
                             throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateModulator

public LXModulator instantiateModulator(String className)
                                 throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateModulator

public LXModulator instantiateModulator(Class<? extends LXModulator> cls)
                                 throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiatePattern

public LXPattern instantiatePattern(String className)
                             throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiatePattern

public LXPattern instantiatePattern(Class<? extends LXPattern> cls)
                             throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateEffect

public LXEffect instantiateEffect(String className)
                           throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateEffect

public LXEffect instantiateEffect(Class<? extends LXEffect> cls)
                           throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateBlend

public LXBlend instantiateBlend(String className)
                         throws LX.InstantiationException

Throws:: LX.InstantiationException

instantiateBlend

public LXBlend instantiateBlend(Class<? extends LXBlend> cls)
                         throws LX.InstantiationException

Throws:: LX.InstantiationException

setSystemClipboardString

public void setSystemClipboardString(String str)

bootstrapMediaPath

protected static void bootstrapMediaPath(LX.Flags flags)

bootstrapMediaPath

protected static void bootstrapMediaPath(LX.Flags flags,
                                         String dirName)

log

public static void log(String message)

warning

public static void warning(String message)

error

public static void error(String message)

error

public static void error(Exception x)

error

public static void error(String prefix,
                         Throwable x)

error

public static void error(Throwable x,
                         String message)

_log

protected static void _log(String prefix,
                           String message)

_error

protected static void _error(String prefix,
                             Exception x,
                             String message)

_error

protected static void _error(String prefix,
                             String message)

_log

protected static void _log(PrintStream stream,
                           String message)

_log

protected static void _log(PrintStream stream,
                           Throwable throwable,
                           String prefix,
                           String message)

setLogFile

protected static void setLogFile(File file)

main
```
public static void main(String[] args)
```
Runs a headless version of LX

Parameters:

args - Command line arguments

headless

public static void headless(LX.Flags flags,
                            File projectFile)

Class LX

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

VERSION

HALF_PI

TWO_PI

PIf

HALF_PIf

TWO_PIf

initProfiler

preferences

flags

permissions

errorChanged

failure

structure

model

clipboard

engine

command

registry

scheduler

LOG_WARNINGS

Constructor Detail

LX

LX

LX

LX

Method Detail

version

logInitProfiler

fail

getPermissions

pushError

pushError

pushError

popError

getError

instantiateRegistry

addListener

removeListener

addProjectListener

removeProjectListener

getComponent

getProjectComponent

getModel

dispose

hsb

hsa

rgb

setSpeed

addEffects

addEffect

removeEffect

setPaused

isPaused

togglePaused

goPrev

goNext

goPattern

goIndex

disableAutoCycle

enableAutoCycle

addOutput

setPatterns

getPatterns

setProject

getProject

saveProject

saveProject

registerExternal

newProject

openProject

setModelImportFlag

setScheduleLoadingFlag

confirmChangesSaved