Package net.paulhertz.pixelaudio.voices

# Class PASamplerInstrumentPool

java.lang.Object
net.paulhertz.pixelaudio.voices.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. -- TODO Duplicates the MultiChannelBuffer. This may be overkill. Features: - 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 final ddf.minim.AudioOutput`
  `out`
  `private int`
  `outputBufferSize`
  `private float`
  `outputSampleRate`
  `private final List<PASamplerInstrument>`
  `pool`
  `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.
  `private PASamplerInstrument`
  `getAvailableInstrument()`
  Find a free instrument; otherwise least-busy; otherwise smooth-steal one.
  `float`
  `getBufferSampleRate()`
  `ADSRParams`
  `getDefaultEnv()`
  `float`
  `getGlobalPan()`
  `float`
  `getGlobalPitch()`
  `List<PASamplerInstrument>`
  `getInstruments()`
  `int`
  `getMaxVoices()`
  `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`
  `reinitInstruments()`
  Resize the pool gracefully without disrupting existing instruments unnecessarily.
  `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`
  `setGlobalPan(float pan)`
  `void`
  `setGlobalPitch(float pitch)`
  `void`
  `setMaxVoices(int maxVoices)`
  `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.voices.PAPlayable

  `play, play, play, play, play`

  ### Methods inherited from interface net.paulhertz.pixelaudio.voices.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

  - ### 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()

  - ### 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).

  - ### 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.