Package net.paulhertz.pixelaudio.sampler

# Class PASamplerInstrumentPool

java.lang.Object
net.paulhertz.pixelaudio.sampler.PASamplerInstrumentPool

All Implemented Interfaces:
  `PAPlayable`, `PASamplerPlayable`

public class PASamplerInstrumentPool extends Object implements PASamplerPlayable, PAPlayable
PASamplerInstrumentPool Manages a group of PASamplerInstruments sharing the same source buffer and audio output. Provides polyphony management, buffer swapping, and per-instrument voice recycling.

-- TODO Uses a Minim MultiChannelBuffer for its audio sample storage. This could change.

Features:

- Sample-based instruments with ADSR envelopes
- Configurable pool size (number of instruments)
- Configurable max voices per instrument
- Safe buffer and sample rate propagation
- Voice stealing via release or stop()
- Looping detection
- Thread-safe access

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `private ddf.minim.MultiChannelBuffer`
  `buffer`
  `private float`
  `bufferSampleRate`
  `private ADSRParams`
  `defaultEnv`
  `private float`
  `globalPan`
  `private float`
  `globalPitch`
  `private boolean`
  `isClosed`
  `private int`
  `maxVoices`
  `private PASharedBufferSampler.MixProfile`
  `mixProfile`
  `private final ddf.minim.AudioOutput`
  `out`
  `private int`
  `outputBufferSize`
  `private float`
  `outputSampleRate`
  `private final List<PASamplerInstrument>`
  `pool`
  `private float`
  `poolGain`
  `private int`
  `poolSize`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, float sampleRate, int poolSize, int perInstrumentVoices, ddf.minim.AudioOutput out, ADSRParams defaultEnv)`
  Full backward-compatible constructor with a MultiChannelBuffer argument.
  `PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize)`
  Convenience constructor: default env, bufferSampleRate = out.sampleRate().
  `PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize, float bufferSampleRate, ADSRParams env)`
  Full constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `private static float`
  `clampPan(float pan)`
  `void`
  `close()`
  Close all instruments and free audio resources.
  `PASharedBufferSampler.MixProfile`
  `cycleMixProfile()`
  Convenience: advance to the next mix profile and apply it pool-wide.
  `void`
  `fadeOutAll()`
  Smoothly release all active voices on all instruments.
  `private PASamplerInstrument`
  `getAvailableInstrument()`
  Find a free instrument; otherwise least-busy; otherwise smooth-steal one.
  `float`
  `getBufferSampleRate()`
  `ADSRParams`
  `getDefaultEnv()`
  `float`
  `getGain()`
  `float`
  `getGainDb()`
  `float`
  `getGlobalPan()`
  `float`
  `getGlobalPitch()`
  `List<PASamplerInstrument>`
  `getInstruments()`
  `int`
  `getMaxVoices()`
  `PASharedBufferSampler.MixProfile`
  `getMixProfile()`
  `int`
  `getOutputBufferSize()`
  `float`
  `getOutputSampleRate()`
  `int`
  `getPoolSize()`
  `private void`
  `initPool()`
  `boolean`
  `isClosed()`
  Check whether the pool has been closed.
  `boolean`
  `isLooping()`
  `int`
  `play(float amplitude, float pitch, float pan)`
  The most basic play command, plays the entire buffer.
  `int`
  `play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  The primary play command, with all common arguments in standard order.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude)`
  Play subrange with amplitude only.
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, float pitch)`
  Play subrange with amplitude and pitch (no envelope).
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)`
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env)`
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)`
  `int`
  `playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  Play a subrange of the buffer with full parameters.
  `int`
  `playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)`
  `int`
  `playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  `private void`
  `propagateParentGain()`
  `private void`
  `reinitInstruments()`
  Resize the pool gracefully without disrupting existing instruments unnecessarily.
  `void`
  `releaseAll()`
  Alias for fadeOutAll(), if you prefer the same naming style as instruments.
  `void`
  `schedulePlayAtFrame(long frameIndex, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  Hook: schedule by audio-frame index (frame = one AudioOutput callback).
  `void`
  `schedulePlayAtMillis(long triggerTimeMillis, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)`
  Hook: schedule by (future) wallclock ms — will be wired to TimedLocation later.
  `void`
  `setBuffer(float[] newBuffer, float newBufferSampleRate)`
  Propagate a new float[] buffer to all instruments in this pool.
  `void`
  `setBuffer(ddf.minim.MultiChannelBuffer newBuffer)`
  Swap the pool's shared buffer; keeps existing bufferSampleRate.
  `void`
  `setBuffer(ddf.minim.MultiChannelBuffer newBuffer, float newBufferSampleRate)`
  Swap the pool's shared buffer and update its buffer sample rate.
  `void`
  `setDefaultEnv(ADSRParams env)`
  `void`
  `setGain(float linear)`
  `void`
  `setGainDb(float db)`
  `void`
  `setGlobalPan(float pan)`
  `void`
  `setGlobalPitch(float pitch)`
  `void`
  `setMaxVoices(int maxVoices)`
  `void`
  `setMixProfile(PASharedBufferSampler.MixProfile profile)`
  Set the sampler bus mix behavior for every instrument in the pool.
  `void`
  `setPoolSize(int newSize)`
  `void`
  `stop()`
  Stop playback immediately (implementation-defined).
  `void`
  `stopAll()`
  `void`
  `updateRateFromOutput()`
  Re-sync instruments to current AudioOutput sample rate (if device changes).

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

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

  ### Methods inherited from interface net.paulhertz.pixelaudio.sampler.PAPlayable

  `play, play, play, play, play`

  ### Methods inherited from interface net.paulhertz.pixelaudio.sampler.PASamplerPlayable

  `playSample, playSample, playSample, playSample, playSample`

- ## Field Details

  - ### out

    private final ddf.minim.AudioOutput out

  - ### buffer

    private ddf.minim.MultiChannelBuffer buffer

  - ### pool

    private final List<PASamplerInstrument> pool

  - ### poolSize

    private int poolSize

  - ### maxVoices

    private int maxVoices

  - ### defaultEnv

    private ADSRParams defaultEnv

  - ### globalPitch

    private float globalPitch

  - ### globalPan

    private float globalPan

  - ### outputBufferSize

    private int outputBufferSize

  - ### bufferSampleRate

    private float bufferSampleRate

  - ### outputSampleRate

    private float outputSampleRate

  - ### poolGain

    private volatile float poolGain

  - ### mixProfile

    private volatile PASharedBufferSampler.MixProfile mixProfile

  - ### isClosed

    private boolean isClosed

- ## Constructor Details

  - ### PASamplerInstrumentPool

    public PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, float sampleRate, int poolSize, int perInstrumentVoices, ddf.minim.AudioOutput out, ADSRParams defaultEnv)
    Full backward-compatible constructor with a MultiChannelBuffer argument. Envelope is supplied, pitch and pan default to globalPitch and globalPan. Note that the MultiChannelBuffer we supply is not copied, we use it directly for storage. Calling applications should not modify the buffer.
    Parameters:
      `buffer` - shared MultiChannelBuffer
      `sampleRate` - nominal sample rate of the buffer (Hz)
      `poolSize` - number of instruments in the pool
      `perInstrumentVoices` - number of voices per instrument
      `out` - AudioOutput to patch instruments into
      `defaultEnv` - default ADSR envelope for all instruments

  - ### PASamplerInstrumentPool

    public PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize, float bufferSampleRate, ADSRParams env)
    Full constructor.
    Parameters:
      `buffer` - shared MultiChannelBuffer
      `out` - target AudioOutput
      `poolSize` - number of instruments to preallocate
      `bufferSampleRate` - nominal sample rate of buffer (Hz)
      `env` - default ADSR (nullable)

  - ### PASamplerInstrumentPool

    public PASamplerInstrumentPool(ddf.minim.MultiChannelBuffer buffer, ddf.minim.AudioOutput out, int poolSize)
    Convenience constructor: default env, bufferSampleRate = out.sampleRate().

- ## Method Details

  - ### initPool

    private void initPool()

  - ### getAvailableInstrument

    private PASamplerInstrument getAvailableInstrument()
    Find a free instrument; otherwise least-busy; otherwise smooth-steal one.

  - ### play

    public int play(float amplitude, float pitch, float pan)
    The most basic play command, plays the entire buffer.
    Specified by:
      `play` in interface `PAPlayable`
    Parameters:
      `amplitude` - gain multiplier (0..1+)
      `pitch` - playback rate or pitch factor (implementation-defined)
      `pan` - stereo pan (-1 left .. +1 right)
    Returns:
      non-zero if a voice/event was triggered

  - ### stop

    public void stop()
    Description copied from interface: `PAPlayable`
    Stop playback immediately (implementation-defined).
    Specified by:
      `stop` in interface `PAPlayable`

  - ### play

    public int play(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    The primary play command, with all common arguments in standard order. The playSample(...) methods provide the greatest flexibility in method signatures and will call this method.
    Specified by:
      `play` in interface `PASamplerPlayable`

  - ### isLooping

    public boolean isLooping()

  - ### stopAll

    public void stopAll()

  - ### fadeOutAll

    public void fadeOutAll()
    Smoothly release all active voices on all instruments. Preferred for live transitions and endings.

  - ### releaseAll

    public void releaseAll()
    Alias for fadeOutAll(), if you prefer the same naming style as instruments.

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Description copied from interface: `PASamplerPlayable`
    Play a subrange of the buffer with full parameters.
    Specified by:
      `playSample` in interface `PASamplerPlayable`

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, float pitch, float pan)

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude)
    Description copied from interface: `PASamplerPlayable`
    Play subrange with amplitude only.
    Specified by:
      `playSample` in interface `PASamplerPlayable`

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, float pitch)
    Description copied from interface: `PASamplerPlayable`
    Play subrange with amplitude and pitch (no envelope).
    Specified by:
      `playSample` in interface `PASamplerPlayable`

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env)

  - ### playSample

    public int playSample(int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)

  - ### playSample

    public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)

  - ### playSample

    public int playSample(ddf.minim.MultiChannelBuffer buffer, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch)

  - ### setBuffer

    public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer)
    Swap the pool's shared buffer; keeps existing bufferSampleRate.
    Parameters:
      `newBuffer` - a new MultiChannelBuffer as audio source for this instrument

  - ### setBuffer

    public void setBuffer(ddf.minim.MultiChannelBuffer newBuffer, float newBufferSampleRate)
    Swap the pool's shared buffer and update its buffer sample rate.
    Parameters:
      `newBuffer` -
      `newBufferSampleRate` -

  - ### setBuffer

    public void setBuffer(float[] newBuffer, float newBufferSampleRate)
    Propagate a new float[] buffer to all instruments in this pool.

  - ### updateRateFromOutput

    public void updateRateFromOutput()
    Re-sync instruments to current AudioOutput sample rate (if device changes).

  - ### setGain

    public void setGain(float linear)

  - ### getGain

    public float getGain()

  - ### setGainDb

    public void setGainDb(float db)

  - ### getGainDb

    public float getGainDb()

  - ### propagateParentGain

    private void propagateParentGain()

  - ### setMixProfile

    public void setMixProfile(PASharedBufferSampler.MixProfile profile)
    Set the sampler bus mix behavior for every instrument in the pool.
    Parameters:
      `profile` - desired PASharedBufferSampler mix profile

  - ### getMixProfile

    public PASharedBufferSampler.MixProfile getMixProfile()
    Returns:
      the pool-wide sampler mix profile

  - ### cycleMixProfile

    public PASharedBufferSampler.MixProfile cycleMixProfile()
    Convenience: advance to the next mix profile and apply it pool-wide.
    Returns:
      the newly selected profile

  - ### setGlobalPitch

    public void setGlobalPitch(float pitch)

  - ### getGlobalPitch

    public float getGlobalPitch()

  - ### setGlobalPan

    public void setGlobalPan(float pan)

  - ### getGlobalPan

    public float getGlobalPan()

  - ### setDefaultEnv

    public void setDefaultEnv(ADSRParams env)

  - ### getDefaultEnv

    public ADSRParams getDefaultEnv()

  - ### getMaxVoices

    public int getMaxVoices()

  - ### setMaxVoices

    public void setMaxVoices(int maxVoices)

  - ### getPoolSize

    public int getPoolSize()

  - ### setPoolSize

    public void setPoolSize(int newSize)

  - ### getOutputSampleRate

    public float getOutputSampleRate()

  - ### getOutputBufferSize

    public int getOutputBufferSize()

  - ### getBufferSampleRate

    public float getBufferSampleRate()

  - ### reinitInstruments

    private void reinitInstruments()
    Resize the pool gracefully without disrupting existing instruments unnecessarily. Active instruments are preserved whenever possible.

  - ### getInstruments

    public List<PASamplerInstrument> getInstruments()

  - ### schedulePlayAtMillis

    public void schedulePlayAtMillis(long triggerTimeMillis, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Hook: schedule by (future) wallclock ms — will be wired to TimedLocation later.

  - ### schedulePlayAtFrame

    public void schedulePlayAtFrame(long frameIndex, int samplePos, int sampleLen, float amplitude, ADSRParams env, float pitch, float pan)
    Hook: schedule by audio-frame index (frame = one AudioOutput callback).

  - ### clampPan

    private static float clampPan(float pan)

  - ### close

    public void close()
    Close all instruments and free audio resources.

  - ### isClosed

    public boolean isClosed()
    Check whether the pool has been closed.