Package net.paulhertz.pixelaudio

Class WaveData

java.lang.Object
net.paulhertz.pixelaudio.WaveData
public class WaveData extends Object
Provides data storage for WaveSynth operators and performs optimized updating of output.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    WaveData.WaveState
    enumeration of wave states: muted, solo, etc.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    float
    amp
    amplitude
    int
    animSteps
    number of animation steps, animSteps is typically an external value from a WaveSynth or application context
    private float
    c
    cos(currentPhase)
    private float
    cs
    cos(deltaPhasePerPos)
    float
    dc
    DC offset/bias to add to generated amplitude values, default 0
    static int
    defaultAnimSteps
    convenience variable, 30 seconds of animation at 24 frames per second, also context dependent
    private boolean
    framePrepared
    track whether a frame is prepared
    float
    freq
    frequency
    boolean
    isMuted
    runtime variable for muting
    float
    phase
    fraction of TWO_PI in the range 0..1
    float
    phaseCycles
    number of times to cycle through TWO_PI over the duration of the animation
    float
    phaseInc
    increment to the phase for each step of animation = (cycles * TWO_PI)/(animation steps) Should be set when animation begins, otherwise is set to 0, unchanging.
    static final boolean
    phaseScalesTwoPI
    support for old JSON format where phase was already scaled by TWO_PI in the new format phase ranges over the open interval (0, 1), so we scale it by TWO_PI and store the result in phaseTwoPi, which tracks phase information.
    float
    phaseTwoPi
    TWO_PI * phase, used internally to calculate wave value
    private int
    preparedFrame
    frame number for oscillator state, currently not used
    private static final int
    RENORM_PERIOD
    how many steps between renormalizations, to keep the oscillator stable
    private float
    s
    sin(currentPhase)
    private float
    sn
    sin(deltaPhasePerPos)
    private int
    stepsSinceRenorm
    optional: for occasional renormalization to fight drift
    int
    waveColor
    color associated with the wave
    WaveData.WaveState
    waveState
    tracking variable for mute, solo, etc.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    WaveData()
    A default WaveData instance, initialized at 440Hz, 0.5 amplitude, etc.
     
    WaveData(float f, float a, float p, float dc, float cycles, int c)
    Constructor for WaveData when animation steps are not known
     
    WaveData(float f, float a, float p, float dc, float cycles, int c, int steps)
    Preferred constructor for WaveData
    private
    WaveData(float f, float a, float p, float dc, float cycles, int c, int animSteps, boolean phaseScalesTwoPi)
    Legacy code, to be dropped in later releases.

  • Method Summary

    Modifier and Type
    Method
    Description
    WaveData
    clone()
    Creates a deep copy of this WaveData object.
    void
    invalidateFrameState()
    If you ever need to force this oscillator to be rebuilt next frame.
    static float
    mapToPositivePhase(float value, float a, float b)
    Maps a value to a specified range (of a cyclic function) Explanation: 1.
    float
    nextValue()
    Get the next value along the path, using oscillator recurrence.
    float
    phaseAtFrame(int frame)
    Calculate the phase value for a given frame, mapped to the range [0, TWO_PI).
    void
    prepareFrame(int frame, float mapInc)
    Prepare oscillator state for this frame, assuming a constant freq and a constant mapInc for pos stepping.
    void
    prepareFrame(int frame, float mapInc, float freqShift)
    Variant that includes a per-frame freqShift.
    float
    rawPhaseAtFrame(int frame)
    Calculate the raw phase value for a given frame, without mapping it to a specific range.
    float
    scaledPhaseAtFrame(int frame)
    Calculate the scaled phase value for a given frame, mapped to the range [0, 1).
    void
    setAmp(float a)
    Set new amplitude value for WaveData.
    void
    setAnimationSteps(int newSteps)
    Set new animSteps value for WaveData, and recalculate phaseInc accordingly, using the existing cycles value.
    void
    setCycles(float cycles)
    Set new cycles value for WaveData, and recalculate phaseInc accordingly, using the existing animSteps value.
    void
    setCycles(float cycles, int steps)
    Set new cycles and animSteps values for WaveData, and recalculate phaseInc accordingly.
    void
    setDc(float newDc)
    Set new DC offset value for WaveData.
    void
    setFreq(float f)
    Set new frequency value for WaveData.
    void
    setPhase(float p)
    Set new phase value for WaveData, assuming the input phase is a fraction of TWO_PI (the preferred format).
    (package private) void
    setPhase(float p, boolean phaseScalesTwoPi)
    Deprecated.
    void
    setWaveColor(int c)
    Set new color value for WaveData.
    void
    setWaveState(WaveData.WaveState newWaveState)
    Set new wave state for WaveData.
    String
    toString()
    Returns a string representation of the WaveData object, with frequency, amplitude, phase, DC offset, cycles, and color: all values shown in Operators control panel GUI.
    void
    updateWaveData(float f, float a, float p, float cycles, int c, int steps)
    Update multiple fields of WaveData at once, for efficiency and to ensure consistency of related fields.
    static ArrayList<WaveData>
    waveDataListCopy(ArrayList<WaveData> wdList)
    Creates a deep copy of a list of WaveData objects.
    float
    waveValue(int frame, int pos, float mapInc)
    Calculate the amplitude value of the wave for a given frame and position along the signal path, using the sine function.
    float
    waveValue(int frame, int pos, float freqShift, float mapInc)
    Experimenting with noise to change the wave forms.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • freq

      public float freq
      frequency

    • amp

      public float amp
      amplitude

    • phase

      public float phase
      fraction of TWO_PI in the range 0..1

    • phaseTwoPi

      public float phaseTwoPi
      TWO_PI * phase, used internally to calculate wave value

    • phaseCycles

      public float phaseCycles
      number of times to cycle through TWO_PI over the duration of the animation

    • phaseInc

      public float phaseInc
      increment to the phase for each step of animation = (cycles * TWO_PI)/(animation steps) Should be set when animation begins, otherwise is set to 0, unchanging.

    • dc

      public float dc
      DC offset/bias to add to generated amplitude values, default 0

    • waveColor

      public int waveColor
      color associated with the wave

    • isMuted

      public boolean isMuted
      runtime variable for muting

    • waveState

      public WaveData.WaveState waveState
      tracking variable for mute, solo, etc.

    • animSteps

      public int animSteps
      number of animation steps, animSteps is typically an external value from a WaveSynth or application context

    • defaultAnimSteps

      public static int defaultAnimSteps
      convenience variable, 30 seconds of animation at 24 frames per second, also context dependent

    • phaseScalesTwoPI

      public static final boolean phaseScalesTwoPI
      support for old JSON format where phase was already scaled by TWO_PI in the new format phase ranges over the open interval (0, 1), so we scale it by TWO_PI and store the result in phaseTwoPi, which tracks phase information.
      See Also:

    • s

      private float s
      sin(currentPhase)

    • c

      private float c
      cos(currentPhase)

    • cs

      private float cs
      cos(deltaPhasePerPos)

    • sn

      private float sn
      sin(deltaPhasePerPos)

    • preparedFrame

      private int preparedFrame
      frame number for oscillator state, currently not used

    • framePrepared

      private boolean framePrepared
      track whether a frame is prepared

    • stepsSinceRenorm

      private int stepsSinceRenorm
      optional: for occasional renormalization to fight drift

    • RENORM_PERIOD

      private static final int RENORM_PERIOD
      how many steps between renormalizations, to keep the oscillator stable
      See Also:

  • Constructor Details

    • WaveData

      private WaveData(float f, float a, float p, float dc, float cycles, int c, int animSteps, boolean phaseScalesTwoPi)
      Legacy code, to be dropped in later releases.

    • WaveData

      public WaveData(float f, float a, float p, float dc, float cycles, int c, int steps)
      Preferred constructor for WaveData
      Parameters:
      f - frequency
      a - amplitude
      p - phase, decimal fraction of TWO_PI, typically in the range [0..1]
      dc - DC component added to wave values
      cycles - number of cyles over one animation period
      c - color associated with this WaveData object
      steps - number of frames for animation

    • WaveData

      public WaveData(float f, float a, float p, float dc, float cycles, int c)
      Constructor for WaveData when animation steps are not known
      Parameters:
      f - frequency
      a - amplitude
      p - phase, decimal fraction of TWO_PI, typically in the range [0..1]
      dc - DC component added to wave values
      cycles - number of cyles over one animation period
      c - color associated with this WaveData object

    • WaveData

      public WaveData()
      A default WaveData instance, initialized at 440Hz, 0.5 amplitude, etc.

  • Method Details

    • updateWaveData

      public void updateWaveData(float f, float a, float p, float cycles, int c, int steps)
      Update multiple fields of WaveData at once, for efficiency and to ensure consistency of related fields.
      Parameters:
      f - frequency
      a - amplitude
      p - phase, decimal fraction of TWO_PI, typically in the range [0..1]
      cycles - number of cycles over one animation period
      c - color associated with this WaveData object
      steps - number of frames for animation

    • setFreq

      public void setFreq(float f)
      Set new frequency value for WaveData.
      Parameters:
      f - new frequency value for WaveData

    • setAmp

      public void setAmp(float a)
      Set new amplitude value for WaveData.
      Parameters:
      a - new amplitude value for WaveData

    • setPhase

      @Deprecated void setPhase(float p, boolean phaseScalesTwoPi)
      Deprecated.
      Set new phase value for WaveData, with option to specify whether the input phase is already scaled by TWO_PI. This method is deprecated because we want to move towards a consistent format where phase is always a fraction of TWO_PI, and we handle the scaling internally.
      Parameters:
      p -
      phaseScalesTwoPi -

    • setPhase

      public void setPhase(float p)
      Set new phase value for WaveData, assuming the input phase is a fraction of TWO_PI (the preferred format).
      Parameters:
      p - new phase value for WaveData

    • setCycles

      public void setCycles(float cycles, int steps)
      Set new cycles and animSteps values for WaveData, and recalculate phaseInc accordingly. This method is useful when you want to change the speed or duration of the wave animation, which depends on both the number of cycles over the animation period and the number of animation steps (frames). Changing either of these parameters affects the phase increment per frame, so we recalculate it to ensure the wave animates correctly over the specified number of cycles and frames.
      Parameters:
      cycles - new cycles value for WaveData
      steps - new animSteps value for WaveData

    • setCycles

      public void setCycles(float cycles)
      Set new cycles value for WaveData, and recalculate phaseInc accordingly, using the existing animSteps value.
      Parameters:
      cycles - new cycles value for WaveData

    • setAnimationSteps

      public void setAnimationSteps(int newSteps)
      Set new animSteps value for WaveData, and recalculate phaseInc accordingly, using the existing cycles value.
      Parameters:
      newSteps - new animSteps value for WaveData

    • setDc

      public void setDc(float newDc)
      Set new DC offset value for WaveData. DC offset is added to the generated wave values, allowing you to shift the baseline of the wave up or down and by extension make the contribution of a WaveData color brighter or darker, without changing the amplitude of the wave itself.
      Parameters:
      newDc - new dc value for WaveData

    • setWaveColor

      public void setWaveColor(int c)
      Set new color value for WaveData.
      Parameters:
      c - new color value for WaveData

    • setWaveState

      public void setWaveState(WaveData.WaveState newWaveState)
      Set new wave state for WaveData.
      Parameters:
      newWaveState - new WaveState for WaveData

    • waveValue

      public float waveValue(int frame, int pos, float freqShift, float mapInc)
      Experimenting with noise to change the wave forms.
      Parameters:
      frame - current frame
      pos - pixel/audio sample index on signal path
      freqShift - experiment with shifting frequency
      mapInc - the increment in phase over the image pixels, typically TWO_PI / image size
      Returns:
      amplitude value of wave for frame and pos

    • waveValue

      public float waveValue(int frame, int pos, float mapInc)
      Calculate the amplitude value of the wave for a given frame and position along the signal path, using the sine function.
      Parameters:
      frame - current frame
      pos - pixel/audio sample index on signal path
      mapInc - the increment in phase over the image pixels, typically TWO_PI / image size
      Returns:
      amplitude value of wave for frame and pos

    • prepareFrame

      public void prepareFrame(int frame, float mapInc)
      Prepare oscillator state for this frame, assuming a constant freq and a constant mapInc for pos stepping. Call once per frame (per WaveData) before stepping pos with nextValue().

    • prepareFrame

      public void prepareFrame(int frame, float mapInc, float freqShift)
      Variant that includes a per-frame freqShift. Use when you want global detune / modulation per frame, not per pixel.

    • nextValue

      public float nextValue()
      Get the next value along the path, using oscillator recurrence. Must be called AFTER prepareFrame(...), and then repeatedly for pos = 0,1,2,... in order.

    • invalidateFrameState

      public void invalidateFrameState()
      If you ever need to force this oscillator to be rebuilt next frame.

    • rawPhaseAtFrame

      public float rawPhaseAtFrame(int frame)
      Calculate the raw phase value for a given frame, without mapping it to a specific range. This method returns the phase value before applying any modulo operation to wrap it within a specific range.
      Parameters:
      frame -
      Returns:

    • phaseAtFrame

      public float phaseAtFrame(int frame)
      Calculate the phase value for a given frame, mapped to the range [0, TWO_PI).
      Parameters:
      frame -
      Returns:

    • scaledPhaseAtFrame

      public float scaledPhaseAtFrame(int frame)
      Calculate the scaled phase value for a given frame, mapped to the range [0, 1).
      Parameters:
      frame -
      Returns:

    • mapToPositivePhase

      public static float mapToPositivePhase(float value, float a, float b)
      Maps a value to a specified range (of a cyclic function) Explanation: 1. Subtract a: Translates the interval to [0,b−a)[0,b−a). 2. value % range: Reduces the value to (−range,range). 3. Adding range: Ensures the result is positive. 4. Final % range: Maps the result to [0,range)[0,range). 5. Adding a: Shifts the result back to the original interval [a,b).
      Parameters:
      value - float value to be mapped
      a - lower bound
      b - upper bound
      Returns:
      value mapped to interval [a,b)

    • waveDataListCopy

      public static ArrayList<WaveData> waveDataListCopy(ArrayList<WaveData> wdList)
      Creates a deep copy of a list of WaveData objects.
      Parameters:
      wdList - the list to copy
      Returns:
      a new list containing clones of the original WaveData objects

    • clone

      public WaveData clone()
      Creates a deep copy of this WaveData object.
      Overrides:
      clone in class Object
      Returns:
      a new WaveData object with the same field values as this one

    • toString

      public String toString()
      Returns a string representation of the WaveData object, with frequency, amplitude, phase, DC offset, cycles, and color: all values shown in Operators control panel GUI.
      Overrides:
      toString in class Object