Introduce PolyBuffer; use it to handle color space conversion in LXLa…

…yeredComponent.

src/heronarts/lx/Buffer.java

@@ -0,0 +1,5 @@
+package heronarts.lx;
+
+public interface Buffer {
+    public Object getArray();  // should return an array of a color type
+}

src/heronarts/lx/LXBuffer.java

@@ -20,6 +20,6 @@
 
 package heronarts.lx;
 
-public interface LXBuffer {
+public interface LXBuffer extends Buffer {
   public int[] getArray();
 }

src/heronarts/lx/LXEffect.java

@@ -57,6 +57,12 @@ public class Timer {
 
   private int index = -1;
 
+  // An alias for the 8-bit color buffer array, for compatibility with old-style
+  // implementations of run(deltaMs, amount) that directly read from and write
+  // into the "colors" array.  Newer subclasses should instead implement
+  // run(deltaMs, amount, preferredSpace) and use polyBuffer.getArray(space).
+  protected int[] colors = null;
+
   protected LXEffect(LX lx) {
     super(lx);
     this.label.setDescription("The name of this effect");
@@ -171,21 +177,46 @@ public final LXEffect disable() {
   @Override
   public final void onLoop(double deltaMs) {
     long runStart = System.nanoTime();
-    double enabledDamped = this.enabledDamped.getValue();
-    if (enabledDamped > 0) {
-      run(deltaMs, enabledDamped);
+    if (enabledDamped.getValue() > 0) {
+      run(deltaMs, enabledDamped.getValue(), polyBuffer.getFreshSpace());
     }
     this.timer.runNanos = System.nanoTime() - runStart;
   }
 
   /**
-   * Implementation of the effect. Subclasses need to override this to implement
-   * their functionality.
+   * Old-style subclasses override this method to implement the effect
+   * by reading and modifying the "colors" array.  New-style subclasses
+   * should override the other run() method instead; see below.
+   *
+   * @param deltaMs Number of milliseconds elapsed since last invocation
+   * @param enabledAmount The amount of the effect to apply, scaled from 0-1
+   */
+  @Deprecated
+  protected /* abstract */ void run(double deltaMs, double enabledAmount) { }
+
+  /**
+   * Implements the effect.  Subclasses should override this method to
+   * apply their effect to an array obtained from the polyBuffer.
    *
    * @param deltaMs Number of milliseconds elapsed since last invocation
    * @param enabledAmount The amount of the effect to apply, scaled from 0-1
+   * @param preferredSpace A hint as to which color space to operate in for
+   *     the greatest efficiency (performing the effect in a different color
+   *     space will still work, but will necessitate color space conversion)
    */
-  protected abstract void run(double deltaMs, double enabledAmount);
+  protected void run(double deltaMs, double enabledAmount, PolyBuffer.Space preferredSpace) {
+    // For compatibility, this invokes the method that previous subclasses were
+    // supposed to implement.  Implementations of run(deltaMs, enabledAmount)
+    // are assumed to operate only on the "colors" array, and are not expected
+    // to have marked the buffer, so we mark the buffer modified here.
+    colors = polyBuffer.getArray();
+    run(deltaMs, enabledAmount);
+    polyBuffer.markModified();
+
+    // New subclasses should override and replace this method with one that
+    // obtains a color array using polyBuffer.getArray(space), writes into
+    // that buffer, and then calls polyBuffer.markModified(space).
+  }
 
   @Override
   public void noteOnReceived(MidiNoteOn note) {

src/heronarts/lx/LXLayer.java

@@ -21,36 +21,79 @@
 package heronarts.lx;
 
 /**
- * A layer is a components that has a run method and operates on some other
+ * A layer is a component that has a run method and operates on some other
  * buffer component. The layer does not actually own the color buffer. An
  * effect is an example of a layer, or patterns may compose themselves from
  * multiple layers.
  */
 public abstract class LXLayer extends LXLayeredComponent {
+  /** The requested color space.  See setPreferredSpace(). */
+  protected PolyBuffer.Space preferredSpace = PolyBuffer.Space.RGB8;
+
+  // An alias for the 8-bit color buffer array, for compatibility with old-style
+  // implementations of run(deltaMs) that directly read from and write
+  // into the "colors" array.  Newer subclasses should instead implement
+  // run(deltaMs, preferredSpace) and use polyBuffer.getArray(space).
+  protected int[] colors = null;
 
   protected LXLayer(LX lx) {
     super(lx);
   }
 
-  protected LXLayer(LX lx, LXDeviceComponent buffer) {
-    super(lx, buffer);
+  protected LXLayer(LX lx, LXDeviceComponent component) {
+    super(lx, component);
   }
 
   @Override
   public String getLabel() {
     return "Layer";
   }
 
+  /**
+   * Sets the color space in which this layer is requested to operate.
+   * This is a request for the run() method to operate in a particular
+   * color space, for efficiency.  The run() method is not required to honor
+   * this request; this merely provides the information that using a
+   * different color space will necessitate an additional conversion.
+   * @param space
+   */
+  public void setPreferredSpace(PolyBuffer.Space space) {
+    preferredSpace = space;
+  }
+
   @Override
   protected final void onLoop(double deltaMs) {
-    run(deltaMs);
+    run(deltaMs, preferredSpace);
   }
 
   /**
-   * Run this layer.
+   * Old-style subclasses override this method to run the layer
+   * by reading and writing the "colors" array.  New-style subclasses
+   * should override the other run() method instead; see below.
    *
    * @param deltaMs Milliseconds elapsed since last frame
    */
-  public abstract void run(double deltaMs);
+  public /* abstract */ void run(double deltaMs) { }
 
+  /**
+   * Runs the layer.  Subclasses should override this method.
+   *
+   * @param deltaMs Milliseconds elapsed since last frame
+   * @param preferredSpace A hint as to which color space to operate in for
+   *     the greatest efficiency (writing the pattern in a different color
+   *     space will still work, but will necessitate color space conversion)
+   */
+  protected void run(double deltaMs, PolyBuffer.Space preferredSpace) {
+    // For compatibility, this invokes the method that previous subclasses
+    // were supposed to implement.  Implementations of run(deltaMs) are
+    // assumed to operate only on the "colors" array, and are not expected
+    // to have marked the buffer, so we mark the buffer modified here.
+    colors = polyBuffer.getArray();
+    run(deltaMs);
+    polyBuffer.markModified();
+
+    // New subclasses should override and replace this method with one that
+    // obtains a color array using polyBuffer.getArray(space), writes into
+    // that buffer, and then calls polyBuffer.markModified(space).
+  }
 }