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/pitchRatio) override 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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `GestureEventParams.Builder`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final float[]`
  `gain`
  Optional: per-event linear gain scalar; length == n, or null => use texture.gainLinear.
  `final int`
  `n`
  Number of events (must match schedule.size()).
  `final float[]`
  `pan`
  Optional: per-event pan in [-1..1]; length == n, or null => use texture.pan.
  `final float[]`
  `pitchRatio`
  Optional: per-event pitch ratio (>0); length == n, or null => use texture.pitchRatio.
  `final int`
  `scheduleId`
  Optional: a free-form identity marker for debugging/caching.
  `final int[]`
  `startIndices`
  Required: per-event start indices into mono buffer; length == n.
  `final int`
  `version`
  Optional user-managed version tag.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `private`
  `GestureEventParams(GestureEventParams.Builder b)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static GestureEventParams.Builder`
  `builder(int n)`
  `private static float`
  `clampPan(float p)`
  `float`
  `gainAt(int i, float defaultGain)`
  Returns per-event gain if present; otherwise returns defaultGain.
  `static GestureEventParams`
  `ofStartIndices(int[] startIndices)`
  Create a params object with required indices only.
  `float`
  `panAt(int i, float defaultPan)`
  Returns per-event pan if present; otherwise returns defaultPan.
  `float`
  `pitchAt(int i, float defaultPitch)`
  Returns per-event pitch ratio if present; otherwise returns defaultPitch.
  `String`
  `toString()`
  `GestureEventParams`
  `withGain(float[] newGain)`
  Return a copy with updated gain array (other fields preserved).
  `GestureEventParams`
  `withPan(float[] newPan)`
  Return a copy with updated pan array (other fields preserved).
  `GestureEventParams`
  `withPitchRatio(float[] newPitchRatio)`
  Return a copy with updated pitchRatio array (other fields preserved).
  `GestureEventParams`
  `withStartIndices(int[] newStartIndices)`
  Return a copy with updated startIndices (other fields preserved).

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### n

    public final int n
    Number of events (must match schedule.size()).

  - ### startIndices

    public final int[] startIndices
    Required: per-event start indices into mono buffer; length == n.

  - ### pan

    public final float[] pan
    Optional: per-event pan in [-1..1]; length == n, or null => use texture.pan.

  - ### gain

    public final float[] gain
    Optional: per-event linear gain scalar; length == n, or null => use texture.gainLinear.

  - ### pitchRatio

    public final float[] pitchRatio
    Optional: per-event pitch ratio (>0); length == n, or null => use texture.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)

- ## Method Details

  - ### builder

    public static GestureEventParams.Builder builder(int n)

  - ### ofStartIndices

    public static GestureEventParams ofStartIndices(int[] startIndices)
    Create a params object with required indices only.

  - ### withStartIndices

    public GestureEventParams withStartIndices(int[] newStartIndices)
    Return a copy with updated startIndices (other fields preserved).

  - ### withPan

    public GestureEventParams withPan(float[] newPan)
    Return a copy with updated pan array (other fields preserved).

  - ### withGain

    public GestureEventParams withGain(float[] newGain)
    Return a copy with updated gain array (other fields preserved).

  - ### withPitchRatio

    public GestureEventParams withPitchRatio(float[] newPitchRatio)
    Return a copy with updated pitchRatio array (other fields preserved).

  - ### panAt

    public float panAt(int i, float defaultPan)
    Returns per-event pan if present; otherwise returns defaultPan.

  - ### gainAt

    public float gainAt(int i, float defaultGain)
    Returns per-event gain if present; otherwise returns defaultGain.

  - ### pitchAt

    public float pitchAt(int i, float defaultPitch)
    Returns per-event pitch ratio if present; otherwise returns defaultPitch.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### clampPan

    private static float clampPan(float p)