Package net.paulhertz.pixelaudio.granular

Class PABurstGranularSource

java.lang.Object
net.paulhertz.pixelaudio.granular.PABurstGranularSource
All Implemented Interfaces:
PAFloatSource, PASource
public final class PABurstGranularSource extends Object implements PASource
Windowed granular source that renders one scheduled burst of grains.

PABurstGranularSource is the sample-level renderer created by PAGranularInstrumentDirector. Each instance represents one gesture event. Within that event it may render one or more grains, spaced in time by timeHopSamples and advanced through the source buffer by indexHopSamples.

The source reads from a mono float[] buffer, applies an optional grain window, performs linear interpolation for fractional pitch-ratio playback, and adds its samples to the output block. When overlapping grains contribute to the same block sample, the source performs in-place overlap-add normalization.

This source reports PitchPolicy.SOURCE_GRANULAR because pitch is already handled internally by pitchRatio; the instrument should not apply a second playback-rate transposition on top of it.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final int
    baseIndex
     
    private final int
    burstGrains
     
    private float
    gain
     
    private int
    grainLength
     
    private ddf.minim.analysis.WindowFunction
    grainWindow
     
    private final int
    indexHopSamples
     
    private boolean
    noteStarted
     
    private long
    noteStartSample
     
    private final float
    pitchRatio
     
    private final float[]
    source
     
    private final int
    timeHopSamples
     
    private float[]
    windowCurve
     
    private float[]
    wsum
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    PABurstGranularSource(float[] source, int baseIndex, int grainLengthSamples, int burstGrains, int timeHopSamples, int indexHopSamples, float pitchRatio)
    Creates a burst granular source.

  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    ensureWSum(int blockSize)
     
    float
    getGain()
    Returns the optional source-local gain scalar.
    long
    lengthSamples()
    Returns the duration of the burst in samples.
    PitchPolicy
    pitchPolicy()
    Reports that this source handles pitch internally.
    private static float
    readLinear(float[] buf, float pos)
    Reads a linearly interpolated value from an audio buffer.
    void
    renderBlock(long blockStart, int blockSize, float[] outL, float[] outR)
    Renders this burst into an audio block.
    void
    seekTo(long absoluteSample)
    Sets the absolute output-sample time at which this burst begins.
    void
    setGain(float gain)
    Sets an optional source-local gain scalar.
    void
    setGrainWindow(ddf.minim.analysis.WindowFunction wf, int grainLenSamples)
    Sets the grain window and authoritative grain length for rendering.

    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.granular.PASource

    getMultiChannelBuffer

  • Field Details

    • source

      private final float[] source

    • baseIndex

      private final int baseIndex

    • burstGrains

      private final int burstGrains

    • timeHopSamples

      private final int timeHopSamples

    • indexHopSamples

      private final int indexHopSamples

    • pitchRatio

      private final float pitchRatio

    • gain

      private float gain

    • grainLength

      private int grainLength

    • grainWindow

      private ddf.minim.analysis.WindowFunction grainWindow

    • windowCurve

      private float[] windowCurve

    • noteStartSample

      private long noteStartSample

    • noteStarted

      private boolean noteStarted

    • wsum

      private float[] wsum

  • Constructor Details

    • PABurstGranularSource

      public PABurstGranularSource(float[] source, int baseIndex, int grainLengthSamples, int burstGrains, int timeHopSamples, int indexHopSamples, float pitchRatio)
      Creates a burst granular source.
      Parameters:
      source - mono source buffer to read from
      baseIndex - start index in source for the first grain
      grainLengthSamples - grain length in samples; values below 1 are clamped to 1
      burstGrains - number of grains in this event; values below 1 are clamped to 1
      timeHopSamples - spacing, in output samples, between grains in the burst
      indexHopSamples - spacing, in source-buffer samples, between grain start positions
      pitchRatio - playback pitch ratio for each grain; non-positive values use 1.0
      Throws:
      IllegalArgumentException - if source is null

  • Method Details

    • setGain

      public void setGain(float gain)
      Sets an optional source-local gain scalar.

      The current director applies event gain outside this source, and the current render path does not apply this value. It is retained for callers that track source-local gain metadata or for future source-level gain support.

      Parameters:
      gain - gain scalar; finite negative values are clamped to 0

    • getGain

      public float getGain()
      Returns the optional source-local gain scalar.
      Returns:
      source-local gain

    • seekTo

      public void seekTo(long absoluteSample)
      Sets the absolute output-sample time at which this burst begins.
      Specified by:
      seekTo in interface PASource
      Parameters:
      absoluteSample - absolute sample time for the first grain in the burst

    • renderBlock

      public void renderBlock(long blockStart, int blockSize, float[] outL, float[] outR)
      Renders this burst into an audio block.

      The method adds samples to outL and, when supplied, outR. It assumes that output arrays are at least blockSize samples long. If this source has not been started with seekTo(long), rendering is skipped.

      Specified by:
      renderBlock in interface PAFloatSource
      Parameters:
      blockStart - absolute sample index of the first sample in the output block
      blockSize - number of samples in the output block
      outL - left output buffer to mix into
      outR - right output buffer to mix into; may be null or the same array as outL

    • lengthSamples

      public long lengthSamples()
      Returns the duration of the burst in samples.
      Specified by:
      lengthSamples in interface PAFloatSource
      Returns:
      sample span from the start of the first grain to the end of the last grain

    • pitchPolicy

      public PitchPolicy pitchPolicy()
      Reports that this source handles pitch internally.
      Specified by:
      pitchPolicy in interface PASource
      Returns:
      PitchPolicy.SOURCE_GRANULAR

    • setGrainWindow

      public void setGrainWindow(ddf.minim.analysis.WindowFunction wf, int grainLenSamples)
      Sets the grain window and authoritative grain length for rendering.

      When wf is null, the source uses a rectangular window. Otherwise the requested curve is obtained from WindowCache and reused during block rendering.

      Specified by:
      setGrainWindow in interface PASource
      Parameters:
      wf - window function to apply, or null for rectangular grains
      grainLenSamples - grain length in samples; values below 1 are clamped to 1
      See Also:

    • ensureWSum

      private void ensureWSum(int blockSize)

    • readLinear

      private static float readLinear(float[] buf, float pos)
      Reads a linearly interpolated value from an audio buffer.
      Parameters:
      buf - audio buffer used to generate grains
      pos - fractional position in the buffer
      Returns:
      interpolated sample value at pos