Package net.paulhertz.pixelaudio.granular

Class GestureEventParams

java.lang.Object
net.paulhertz.pixelaudio.granular.GestureEventParams
public final class GestureEventParams extends Object
Immutable, schedule-aligned per-event parameters for gesture playback where each event accepts a buffer sample index and optional pan, gain, and pitch modifiers.

All arrays (when present) are parallel arrays with the same cardinality n matching the GestureSchedule.size() used to generate them.

Design intent:

  • startIndices is the primary "mapping result" (typically from PixelAudioMapper).
  • Optional arrays (pan, gain, and pitchRatio) override GestureGranularParams defaults per event.
  • Persist and reuse this object across re-triggers; refresh only the fields that depend on buffer/mapping.

Immutability note: By default, this class defensively copies arrays in GestureEventParams.Builder.build(). If you want to avoid copying for performance, call GestureEventParams.Builder.noCopy() and treat the provided arrays as immutable thereafter.

  • Field Details

    • n

      public final int n
      Number of events; must match the associated gesture schedule size.

    • startIndices

      public final int[] startIndices
      Required per-event start indices into a mono source buffer; length equals n.

    • pan

      public final float[] pan
      Optional per-event pan in [-1, 1]; length equals n, or null to use GestureGranularParams.pan.

    • gain

      public final float[] gain
      Optional per-event linear gain scalar; length equals n, or null to use GestureGranularParams.gainLinear.

    • pitchRatio

      public final float[] pitchRatio
      Optional per-event pitch ratio greater than 0; length equals n, or null to use GestureGranularParams.pitchRatio.

    • version

      public final int version
      Optional user-managed version tag. Handy for invalidation/caching in app code. (e.g., mapperVersion, bufferRotationVersion, etc.)

    • scheduleId

      public final int scheduleId
      Optional: a free-form identity marker for debugging/caching. Example: System.identityHashCode(schedule), or a stable schedule id in your app.

  • Constructor Details

    • GestureEventParams

      private GestureEventParams(GestureEventParams.Builder b)
      Private constructor; use Builder to create instances.
      Parameters:
      b - a GestureEventParams.Builder instance

  • Method Details

    • builder

      public static GestureEventParams.Builder builder(int n)
      Creates a builder for the given number of gesture events.
      Parameters:
      n - the number of schedule events this parameter set will describe
      Returns:
      a new builder
      Throws:
      IllegalArgumentException - if n < 1

    • ofStartIndices

      public static GestureEventParams ofStartIndices(int[] startIndices)
      Creates a parameter set with only the required start-index array.
      Parameters:
      startIndices - per-event start indices into the mono source buffer
      Returns:
      a new parameter set whose n equals startIndices.length
      Throws:
      NullPointerException - if startIndices is null

    • withStartIndices

      public GestureEventParams withStartIndices(int[] newStartIndices)
      Returns a copy with updated start indices and all other fields preserved.
      Parameters:
      newStartIndices - replacement per-event start indices; length must equal n
      Returns:
      a new parameter set with the supplied start indices
      Throws:
      NullPointerException - if newStartIndices is null
      IllegalArgumentException - if newStartIndices.length != n

    • withPan

      public GestureEventParams withPan(float[] newPan)
      Returns a copy with an updated per-event pan array and all other fields preserved.

      Pass null to clear the per-event override and use GestureGranularParams.pan.

      Parameters:
      newPan - replacement per-event pan values; null is allowed, otherwise length must equal n
      Returns:
      a new parameter set with the supplied pan array
      Throws:
      IllegalArgumentException - if newPan is non-null and newPan.length != n

    • withGain

      public GestureEventParams withGain(float[] newGain)
      Returns a copy with an updated per-event gain array and all other fields preserved.

      Pass null to clear the per-event override and use GestureGranularParams.gainLinear.

      Parameters:
      newGain - replacement per-event gain values; null is allowed, otherwise length must equal n
      Returns:
      a new parameter set with the supplied gain array
      Throws:
      IllegalArgumentException - if newGain is non-null and newGain.length != n

    • withPitchRatio

      public GestureEventParams withPitchRatio(float[] newPitchRatio)
      Returns a copy with an updated per-event pitch-ratio array and all other fields preserved.

      Pass null to clear the per-event override and use GestureGranularParams.pitchRatio.

      Parameters:
      newPitchRatio - replacement per-event pitch ratios; null is allowed, otherwise length must equal n
      Returns:
      a new parameter set with the supplied pitch-ratio array
      Throws:
      IllegalArgumentException - if newPitchRatio is non-null and newPitchRatio.length != n

    • panAt

      public float panAt(int i, float defaultPan)
      Returns the pan value for one event.

      If no per-event pan array is present, this method returns defaultPan. Otherwise it returns pan[i] clamped to the range [-1, 1].

      Parameters:
      i - event index
      defaultPan - pan value to use when no per-event pan array is present
      Returns:
      the resolved pan value
      Throws:
      ArrayIndexOutOfBoundsException - if i is outside the pan array

    • gainAt

      public float gainAt(int i, float defaultGain)
      Returns the gain value for one event.

      If no per-event gain array is present, this method returns defaultGain. Otherwise it returns gain[i], with negative values clamped to 0.

      Parameters:
      i - event index
      defaultGain - gain value to use when no per-event gain array is present
      Returns:
      the resolved gain value
      Throws:
      ArrayIndexOutOfBoundsException - if i is outside the gain array

    • pitchAt

      public float pitchAt(int i, float defaultPitch)
      Returns the pitch ratio for one event.

      If no per-event pitch-ratio array is present, this method returns defaultPitch. Otherwise it returns pitchRatio[i], falling back to defaultPitch for non-positive values.

      Parameters:
      i - event index
      defaultPitch - pitch ratio to use when no per-event pitch-ratio array is present
      Returns:
      the resolved pitch ratio
      Throws:
      ArrayIndexOutOfBoundsException - if i is outside the pitch-ratio array

    • toString

      public String toString()
      String representation of this object's settings and array lengths (not contents).
      Overrides:
      toString in class Object
      Returns:
      a string representation of this object

    • clampPan

      private static float clampPan(float p)