toxiclibs 0.4.0 → 0.8.0

data/src/toxi/math/waves/AMFMSineWave.java

@@ -0,0 +1,143 @@
+/*
+ *   __               .__       .__  ._____.           
+ * _/  |_  _______  __|__| ____ |  | |__\_ |__   ______
+ * \   __\/  _ \  \/  /  |/ ___\|  | |  || __ \ /  ___/
+ *  |  | (  <_> >    <|  \  \___|  |_|  || \_\ \\___ \ 
+ *  |__|  \____/__/\_ \__|\___  >____/__||___  /____  >
+ *                   \/       \/             \/     \/ 
+ *
+ * Copyright (c) 2006-2011 Karsten Schmidt
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * 
+ * http://creativecommons.org/licenses/LGPL/2.1/
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+package toxi.math.waves;
+
+/**
+ * <p>
+ * Amplitude and frequency modulated sine wave. Uses 2 secondary waves to
+ * modulate the shape of the main wave.
+ * </p>
+ * 
+ * <p>
+ * <strong>Note:</strong> You must NEVER call the update() method on the
+ * modulating waves.
+ * </p>
+ */
+public class AMFMSineWave extends AbstractWave {
+
+    /**
+     *
+     */
+    public AbstractWave fmod;
+
+    /**
+     *
+     */
+    public AbstractWave amod;
+
+    /**
+     * Creates a new instance from
+     * 
+     * @param phase
+     * @param freq
+     * @param fmod
+     * @param amod
+     */
+    public AMFMSineWave(float phase, float freq, AbstractWave fmod,
+            AbstractWave amod) {
+        super(phase, freq);
+        this.amod = amod;
+        this.fmod = fmod;
+    }
+
+    /**
+     * @param phase
+     * @param freq
+     * @param offset
+     * @param fmod
+     * @param amod
+     */
+    public AMFMSineWave(float phase, float freq, float offset,
+            AbstractWave fmod, AbstractWave amod) {
+        super(phase, freq, 1, offset);
+        this.amod = amod;
+        this.fmod = fmod;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see toxi.math.waves.AbstractWave#pop()
+     */
+
+    /**
+     *
+     */
+    
+    @Override
+    public void pop() {
+        super.pop();
+        amod.pop();
+        fmod.pop();
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see toxi.math.waves.AbstractWave#push()
+     */
+
+    /**
+     *
+     */
+    
+    @Override
+    public void push() {
+        super.push();
+        amod.push();
+        fmod.push();
+    }
+
+    /**
+     * Resets this wave and its modulating waves as well.
+     * 
+     * @see toxi.math.waves.AbstractWave#reset()
+     */
+    @Override
+    public void reset() {
+        super.reset();
+        fmod.reset();
+        amod.reset();
+    }
+
+    /**
+     * Progresses the wave and updates the result value. You must NEVER call the
+     * update() method on the 2 modulating wave since this is handled
+     * automatically by this method.
+     * 
+     * @return 
+     * @see toxi.math.waves.AbstractWave#update()
+     */
+    @Override
+    public float update() {
+        amp = amod.update();
+        value = amp * (float) Math.sin(phase) + offset;
+        cyclePhase(frequency + fmod.update());
+        return value;
+    }
+}

data/src/toxi/math/waves/AbstractWave.java

@@ -0,0 +1,248 @@
+/*
+ *   __               .__       .__  ._____.           
+ * _/  |_  _______  __|__| ____ |  | |__\_ |__   ______
+ * \   __\/  _ \  \/  /  |/ ___\|  | |  || __ \ /  ___/
+ *  |  | (  <_> >    <|  \  \___|  |_|  || \_\ \\___ \ 
+ *  |__|  \____/__/\_ \__|\___  >____/__||___  /____  >
+ *                   \/       \/             \/     \/ 
+ *
+ * Copyright (c) 2006-2011 Karsten Schmidt
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * 
+ * http://creativecommons.org/licenses/LGPL/2.1/
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+package toxi.math.waves;
+
+import java.util.Stack;
+
+/**
+ * Abstract wave oscillator type which needs to be subclassed to implement
+ * different waveforms. Please note that the frequency unit is radians, but
+ * conversion methods to & from Hertz ({@link #hertzToRadians(float, float)})
+ * are included in this base class.
+ */
+public abstract class AbstractWave {
+
+    /**
+     *
+     */
+    public static final float PI = 3.14159265358979323846f;
+
+    /**
+     *
+     */
+    public static final float TWO_PI = 2 * PI;
+
+    /**
+     * Converts a frequency in Hertz into radians.
+     * 
+     * @param hz
+     *            frequency to convert (in Hz)
+     * @param sampleRate
+     *            sampling rate in Hz (equals period length @ 1 Hz)
+     * @return frequency in radians
+     */
+    public static final float hertzToRadians(float hz, float sampleRate) {
+        return hz / sampleRate * TWO_PI;
+    }
+
+    /**
+     * Converts a frequency from radians to Hertz.
+     * 
+     * @param f
+     *            frequency in radians
+     * @param sampleRate
+     *            sampling rate in Hz (equals period length @ 1 Hz)
+     * @return freq in Hz
+     */
+    public static final float radiansToHertz(float f, float sampleRate) {
+        return f / TWO_PI * sampleRate;
+    }
+
+    /**
+     * Current wave phase
+     */
+    public float phase;
+
+    /**
+     *
+     */
+    public float frequency;
+
+    /**
+     *
+     */
+    public float amp;
+
+    /**
+     *
+     */
+    public float offset;
+
+    /**
+     *
+     */
+    public float value;
+
+    /**
+     *
+     */
+    protected float origPhase;
+
+    /**
+     *
+     */
+    protected Stack<WaveState> stateStack;
+
+    /**
+     *
+     */
+    public AbstractWave() {
+    }
+
+    /**
+     * @param phase
+     */
+    public AbstractWave(float phase) {
+        this(phase, 0, 1, 0);
+    }
+
+    /**
+     * 
+     * @param phase
+     * @param freq
+     */
+    public AbstractWave(float phase, float freq) {
+        this(phase, freq, 1, 0);
+    }
+
+    /**
+     * @param phase
+     * @param freq
+     * @param amp
+     * @param offset
+     */
+    public AbstractWave(float phase, float freq, float amp, float offset) {
+        setPhase(phase);
+        this.frequency = freq;
+        this.amp = amp;
+        this.offset = offset;
+    }
+
+    /**
+     * Ensures phase remains in the 0...TWO_PI interval.
+     * 
+     * @return current phase
+     */
+    public final float cyclePhase() {
+        phase %= TWO_PI;
+        if (phase < 0) {
+            phase += TWO_PI;
+        }
+        return phase;
+    }
+
+    /**
+     * Progresses phase and ensures it remains in the 0...TWO_PI interval.
+     * 
+     * @param freq
+     *            normalized progress frequency
+     * @return update phase value
+     */
+    public final float cyclePhase(float freq) {
+        phase = (phase + freq) % TWO_PI;
+        if (phase < 0) {
+            phase += TWO_PI;
+        }
+        return phase;
+    }
+
+    /**
+     *
+     */
+    public void pop() {
+        if (stateStack == null || (stateStack != null && stateStack.empty())) {
+            throw new IllegalStateException("no wave states on stack");
+        }
+        WaveState s = stateStack.pop();
+        phase = s.phase;
+        frequency = s.frequency;
+        amp = s.amp;
+        offset = s.offset;
+    }
+
+    /**
+     *
+     */
+    public void push() {
+        if (stateStack == null) {
+            stateStack = new Stack<>();
+        }
+        stateStack.push(new WaveState(phase, frequency, amp, offset));
+    }
+
+    /**
+     * Resets the wave phase to the last set phase value (via
+     * {@link #setPhase(float)}.
+     */
+    public void reset() {
+        phase = origPhase;
+    }
+
+    /**
+     * Starts the wave from a new phase. The new phase position will also be
+     * used for any later call to {{@link #reset()}
+     * 
+     * @param phase
+     *            new phase
+     */
+    public final void setPhase(float phase) {
+        this.phase = phase;
+        cyclePhase();
+        this.origPhase = phase;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see java.lang.Object#toString()
+     */
+
+    /**
+     *
+     * @return
+     */
+    
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append(this.getClass().getName()).append(" phase: ").append(phase);
+        sb.append(" frequency: ").append(frequency);
+        sb.append(" amp: ").append(amp);
+        sb.append(" offset: ").append(offset);
+        return sb.toString();
+    }
+
+    /**
+     * Updates the wave and returns new value. Implementing classes should
+     * manually ensure the phase remains in the 0...TWO_PI interval or by
+     * calling {@link #cyclePhase()}.
+     * 
+     * @return current (newly calculated) wave value
+     */
+    public abstract float update();
+}

data/src/toxi/math/waves/ConstantWave.java

@@ -0,0 +1,48 @@
+/*
+ *   __               .__       .__  ._____.           
+ * _/  |_  _______  __|__| ____ |  | |__\_ |__   ______
+ * \   __\/  _ \  \/  /  |/ ___\|  | |  || __ \ /  ___/
+ *  |  | (  <_> >    <|  \  \___|  |_|  || \_\ \\___ \ 
+ *  |__|  \____/__/\_ \__|\___  >____/__||___  /____  >
+ *                   \/       \/             \/     \/ 
+ *
+ * Copyright (c) 2006-2011 Karsten Schmidt
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * 
+ * http://creativecommons.org/licenses/LGPL/2.1/
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+package toxi.math.waves;
+
+/**
+ * Implements a constant value as waveform.
+ */
+public class ConstantWave extends AbstractWave {
+
+    /**
+     *
+     * @param value
+     */
+    public ConstantWave(float value) {
+        super();
+        this.value = value;
+    }
+
+    @Override
+    public final float update() {
+        return value;
+    }
+}

data/src/toxi/math/waves/FMHarmonicSquareWave.java

@@ -0,0 +1,155 @@
+/*
+ *   __               .__       .__  ._____.           
+ * _/  |_  _______  __|__| ____ |  | |__\_ |__   ______
+ * \   __\/  _ \  \/  /  |/ ___\|  | |  || __ \ /  ___/
+ *  |  | (  <_> >    <|  \  \___|  |_|  || \_\ \\___ \ 
+ *  |__|  \____/__/\_ \__|\___  >____/__||___  /____  >
+ *                   \/       \/             \/     \/ 
+ *
+ * Copyright (c) 2006-2011 Karsten Schmidt
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * 
+ * http://creativecommons.org/licenses/LGPL/2.1/
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+package toxi.math.waves;
+
+/**
+ * <p>
+ * Frequency modulated <strong>bandwidth-limited</strong> square wave using a
+ * fourier series of harmonics. Also uses a secondary wave to modulate the
+ * frequency of the main wave.
+ * </p>
+ * 
+ * <p>
+ * <strong>Note:</strong> You must NEVER call the update() method on the
+ * modulating wave.
+ * </p>
+ */
+public class FMHarmonicSquareWave extends AbstractWave {
+
+    /**
+     *
+     */
+    public AbstractWave fmod;
+
+    /**
+     * Maximum harmonics to add (make sure you stay under Nyquist freq), default
+     * = 9
+     */
+    public int maxHarmonics = 3;
+
+    /**
+     *
+     * @param phase
+     * @param freq
+     * @param fmod
+     */
+    public FMHarmonicSquareWave(float phase, float freq, AbstractWave fmod) {
+        super(phase, freq);
+        this.fmod = fmod;
+    }
+
+    /**
+     * Convenience constructor to create a non frequency modulated square wave
+     * 
+     * @param phase
+     * @param freq
+     *            base frequency (in radians)
+     * @param amp
+     * @param offset
+     */
+    public FMHarmonicSquareWave(float phase, float freq, float amp, float offset) {
+        this(phase, freq, amp, offset, new ConstantWave(0));
+    }
+
+    /**
+     *
+     * @param phase
+     * @param freq
+     * @param amp
+     * @param offset
+     * @param fmod
+     */
+    public FMHarmonicSquareWave(float phase, float freq, float amp,
+            float offset, AbstractWave fmod) {
+        super(phase, freq, amp, offset);
+        this.fmod = fmod;
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see toxi.math.waves.AbstractWave#pop()
+     */
+
+    /**
+     *
+     */
+    
+    @Override
+    public void pop() {
+        super.pop();
+        fmod.pop();
+    }
+
+    /*
+     * (non-Javadoc)
+     * 
+     * @see toxi.math.waves.AbstractWave#push()
+     */
+
+    /**
+     *
+     */
+    
+    @Override
+    public void push() {
+        super.push();
+        fmod.push();
+    }
+
+    /**
+     * Resets this wave and its modulating wave as well.
+     * 
+     * @see toxi.math.waves.AbstractWave#reset()
+     */
+    @Override
+    public void reset() {
+        super.reset();
+        fmod.reset();
+    }
+
+    /**
+     * Progresses the wave and updates the result value. You must NEVER call the
+     * update() method on the modulating wave since this is handled
+     * automatically by this method.
+     * 
+     * @return 
+     * @see toxi.math.waves.AbstractWave#update()
+     */
+    @Override
+    public float update() {
+        value = 0;
+        for (int i = 1; i <= maxHarmonics; i += 2) {
+            value += 1.0 / i * (float) Math.sin(i * phase);
+        }
+        value *= amp;
+        value += offset;
+        cyclePhase(frequency + fmod.update());
+        return value;
+    }
+}