FloatControl.java

/*
 * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code 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 General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.sound.sampled;

/**
 * A <code>FloatControl</code> object provides control over a range of
 * floating-point values.  Float controls are often
 * represented in graphical user interfaces by continuously
 * adjustable objects such as sliders or rotary knobs.  Concrete subclasses
 * of <code>FloatControl</code> implement controls, such as gain and pan, that
 * affect a line's audio signal in some way that an application can manipulate.
 * The <code>{@link FloatControl.Type}</code>
 * inner class provides static instances of types that are used to
 * identify some common kinds of float control.
 * <p>
 * The <code>FloatControl</code> abstract class provides methods to set and get
 * the control's current floating-point value.  Other methods obtain the possible
 * range of values and the control's resolution (the smallest increment between
 * returned values).  Some float controls allow ramping to a
 * new value over a specified period of time.  <code>FloatControl</code> also
 * includes methods that return string labels for the minimum, maximum, and midpoint
 * positions of the control.
 *
 * @see Line#getControls
 * @see Line#isControlSupported
 *
 * @author David Rivas
 * @author Kara Kytle
 * @since 1.3
 */
public abstract class FloatControl extends Control {


    // INSTANCE VARIABLES


    // FINAL VARIABLES

    /**
     * The minimum supported value.
     */
    private float minimum;

    /**
     * The maximum supported value.
     */
    private float maximum;

    /**
     * The control's precision.
     */
    private float precision;

    /**
     * The smallest time increment in which a value change
     * can be effected during a value shift, in microseconds.
     */
    private int updatePeriod;


    /**
     * A label for the units in which the control values are expressed,
     * such as "dB" for decibels.
     */
    private final String units;

    /**
     * A label for the minimum value, such as "Left."
     */
    private final String minLabel;

    /**
     * A label for the maximum value, such as "Right."
     */
    private final String maxLabel;

    /**
     * A label for the mid-point value, such as "Center."
     */
    private final String midLabel;


    // STATE VARIABLES

    /**
     * The current value.
     */
    private float value;



    // CONSTRUCTORS


    /**
     * Constructs a new float control object with the given parameters
     *
     * @param type the kind of control represented by this float control object
     * @param minimum the smallest value permitted for the control
     * @param maximum the largest value permitted for the control
     * @param precision the resolution or granularity of the control.
     * This is the size of the increment between discrete valid values.
     * @param updatePeriod the smallest time interval, in microseconds, over which the control
     * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
     * @param initialValue the value that the control starts with when constructed
     * @param units the label for the units in which the control's values are expressed,
     * such as "dB" or "frames per second"
     * @param minLabel the label for the minimum value, such as "Left" or "Off"
     * @param midLabel the label for the midpoint value, such as "Center" or "Default"
     * @param maxLabel the label for the maximum value, such as "Right" or "Full"
     *
     * @throws IllegalArgumentException if {@code minimum} is greater
     *     than {@code maximum} or {@code initialValue} does not fall
     *     within the allowable range
     */
    protected FloatControl(Type type, float minimum, float maximum,
            float precision, int updatePeriod, float initialValue,
            String units, String minLabel, String midLabel, String maxLabel) {

        super(type);

        if (minimum > maximum) {
            throw new IllegalArgumentException("Minimum value " + minimum
                    + " exceeds maximum value " + maximum + ".");
        }
        if (initialValue < minimum) {
            throw new IllegalArgumentException("Initial value " + initialValue
                    + " smaller than allowable minimum value " + minimum + ".");
        }
        if (initialValue > maximum) {
            throw new IllegalArgumentException("Initial value " + initialValue
                    + " exceeds allowable maximum value " + maximum + ".");
        }


        this.minimum = minimum;
        this.maximum = maximum;

        this.precision = precision;
        this.updatePeriod = updatePeriod;
        this.value = initialValue;

        this.units = units;
        this.minLabel = ( (minLabel == null) ? "" : minLabel);
        this.midLabel = ( (midLabel == null) ? "" : midLabel);
        this.maxLabel = ( (maxLabel == null) ? "" : maxLabel);
    }


    /**
     * Constructs a new float control object with the given parameters.
     * The labels for the minimum, maximum, and mid-point values are set
     * to zero-length strings.
     *
     * @param type the kind of control represented by this float control object
     * @param minimum the smallest value permitted for the control
     * @param maximum the largest value permitted for the control
     * @param precision the resolution or granularity of the control.
     * This is the size of the increment between discrete valid values.
     * @param updatePeriod the smallest time interval, in microseconds, over which the control
     * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
     * @param initialValue the value that the control starts with when constructed
     * @param units the label for the units in which the control's values are expressed,
     * such as "dB" or "frames per second"
     *
     * @throws IllegalArgumentException if {@code minimum} is greater
     *     than {@code maximum} or {@code initialValue} does not fall
     *     within the allowable range
     */
    protected FloatControl(Type type, float minimum, float maximum,
            float precision, int updatePeriod, float initialValue, String units) {
        this(type, minimum, maximum, precision, updatePeriod,
                initialValue, units, "", "", "");
    }



    // METHODS


    /**
     * Sets the current value for the control.  The default implementation
     * simply sets the value as indicated.  If the value indicated is greater
     * than the maximum value, or smaller than the minimum value, an
     * IllegalArgumentException is thrown.
     * Some controls require that their line be open before they can be affected
     * by setting a value.
     * @param newValue desired new value
     * @throws IllegalArgumentException if the value indicated does not fall
     * within the allowable range
     */
    public void setValue(float newValue) {

        if (newValue > maximum) {
            throw new IllegalArgumentException("Requested value " + newValue + " exceeds allowable maximum value " + maximum + ".");
        }

        if (newValue < minimum) {
            throw new IllegalArgumentException("Requested value " + newValue + " smaller than allowable minimum value " + minimum + ".");
        }

        value = newValue;
    }


    /**
     * Obtains this control's current value.
     * @return the current value
     */
    public float getValue() {
        return value;
    }


    /**
     * Obtains the maximum value permitted.
     * @return the maximum allowable value
     */
    public float getMaximum() {
        return maximum;
    }


    /**
     * Obtains the minimum value permitted.
     * @return the minimum allowable value
     */
    public float getMinimum() {
        return minimum;
    }


    /**
     * Obtains the label for the units in which the control's values are expressed,
     * such as "dB" or "frames per second."
     * @return the units label, or a zero-length string if no label
     */
    public String getUnits() {
        return units;
    }


    /**
     * Obtains the label for the minimum value, such as "Left" or "Off."
     * @return the minimum value label, or a zero-length string if no label      * has been set
     */
    public String getMinLabel() {
        return minLabel;
    }


    /**
     * Obtains the label for the mid-point value, such as "Center" or "Default."
     * @return the mid-point value label, or a zero-length string if no label    * has been set
     */
    public String getMidLabel() {
        return midLabel;
    }


    /**
     * Obtains the label for the maximum value, such as "Right" or "Full."
     * @return the maximum value label, or a zero-length string if no label      * has been set
     */
    public String getMaxLabel() {
        return maxLabel;
    }


    /**
     * Obtains the resolution or granularity of the control, in the units
     * that the control measures.
     * The precision is the size of the increment between discrete valid values
     * for this control, over the set of supported floating-point values.
     * @return the control's precision
     */
    public float getPrecision() {
        return precision;
    }


    /**
     * Obtains the smallest time interval, in microseconds, over which the control's value can
     * change during a shift.  The update period is the inverse of the frequency with which
     * the control updates its value during a shift.  If the implementation does not support value shifting over
     * time, it should set the control's value to the final value immediately
     * and return -1 from this method.
     *
     * @return update period in microseconds, or -1 if shifting over time is unsupported
     * @see #shift
     */
    public int getUpdatePeriod() {
        return updatePeriod;
    }


    /**
     * Changes the control value from the initial value to the final
     * value linearly over the specified time period, specified in microseconds.
     * This method returns without blocking; it does not wait for the shift
     * to complete.  An implementation should complete the operation within the time
     * specified.  The default implementation simply changes the value
     * to the final value immediately.
     *
     * @param from initial value at the beginning of the shift
     * @param to final value after the shift
     * @param microseconds maximum duration of the shift in microseconds
     *
     * @throws IllegalArgumentException if either {@code from} or {@code to}
     *     value does not fall within the allowable range
     *
     * @see #getUpdatePeriod
     */
    public void shift(float from, float to, int microseconds) {
        // test "from" value, "to" value will be tested by setValue()
        if (from < minimum) {
            throw new IllegalArgumentException("Requested value " + from
                    + " smaller than allowable minimum value " + minimum + ".");
        }
        if (from > maximum) {
            throw new IllegalArgumentException("Requested value " + from
                    + " exceeds allowable maximum value " + maximum + ".");
        }
        setValue(to);
    }


    // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL


    /**
     * Provides a string representation of the control
     * @return a string description
     */
    public String toString() {
        return new String(getType() + " with current value: " + getValue() + " " + units +
                          " (range: " + minimum + " - " + maximum + ")");
    }


    // INNER CLASSES


    /**
     * An instance of the <code>FloatControl.Type</code> inner class identifies one kind of
     * float control.  Static instances are provided for the
     * common types.
     *
     * @author Kara Kytle
     * @since 1.3
     */
    public static class Type extends Control.Type {


        // TYPE DEFINES


        // GAIN TYPES

        /**
         * Represents a control for the overall gain on a line.
         * <p>
         * Gain is a quantity in decibels (dB) that is added to the intrinsic
         * decibel level of the audio signal--that is, the level of
         * the signal before it is altered by the gain control.  A positive
         * gain amplifies (boosts) the signal's volume, and a negative gain
         * attenuates (cuts) it.
         * The gain setting defaults to a value of 0.0 dB, meaning the signal's
         * loudness is unaffected.   Note that gain measures dB, not amplitude.
         * The relationship between a gain in decibels and the corresponding
         * linear amplitude multiplier is:
         *
         *<CENTER><CODE> linearScalar = pow(10.0, gainDB/20.0) </CODE></CENTER>
         * <p>
         * The <code>FloatControl</code> class has methods to impose a maximum and
         * minimum allowable value for gain.  However, because an audio signal might
         * already be at a high amplitude, the maximum setting does not guarantee
         * that the signal will be undistorted when the gain is applied to it (unless
         * the maximum is zero or negative). To avoid numeric overflow from excessively
         * large gain settings, a gain control can implement
         * clipping, meaning that the signal's amplitude will be limited to the maximum
         * value representable by its audio format, instead of wrapping around.
         * <p>
         * These comments apply to gain controls in general, not just master gain controls.
         * A line can have more than one gain control.  For example, a mixer (which is
         * itself a line) might have a master gain control, an auxiliary return control,
         * a reverb return control, and, on each of its source lines, an individual aux
         * send and reverb send.
         *
         * @see #AUX_SEND
         * @see #AUX_RETURN
         * @see #REVERB_SEND
         * @see #REVERB_RETURN
         * @see #VOLUME
         */
        public static final Type MASTER_GAIN            = new Type("Master Gain");

        /**
         * Represents a control for the auxiliary send gain on a line.
         *
         * @see #MASTER_GAIN
         * @see #AUX_RETURN
         */
        public static final Type AUX_SEND                       = new Type("AUX Send");

        /**
         * Represents a control for the auxiliary return gain on a line.
         *
         * @see #MASTER_GAIN
         * @see #AUX_SEND
         */
        public static final Type AUX_RETURN                     = new Type("AUX Return");

        /**
         * Represents a control for the pre-reverb gain on a line.
         * This control may be used to affect how much
         * of a line's signal is directed to a mixer's internal reverberation unit.
         *
         * @see #MASTER_GAIN
         * @see #REVERB_RETURN
         * @see EnumControl.Type#REVERB
         */
        public static final Type REVERB_SEND            = new Type("Reverb Send");

        /**
         * Represents a control for the post-reverb gain on a line.
         * This control may be used to control the relative amplitude
         * of the signal returned from an internal reverberation unit.
         *
         * @see #MASTER_GAIN
         * @see #REVERB_SEND
         */
        public static final Type REVERB_RETURN          = new Type("Reverb Return");


        // VOLUME

        /**
         * Represents a control for the volume on a line.
         */
        /*
         * $$kk: 08.30.99: ISSUE: what units?  linear or dB?
         */
        public static final Type VOLUME                         = new Type("Volume");


        // PAN

        /**
         * Represents a control for the relative pan (left-right positioning)
         * of the signal.  The signal may be mono; the pan setting affects how
         * it is distributed by the mixer in a stereo mix.  The valid range of values is -1.0
         * (left channel only) to 1.0 (right channel
         * only).  The default is 0.0 (centered).
         *
         * @see #BALANCE
         */
        public static final Type PAN                            = new Type("Pan");


        // BALANCE

        /**
         * Represents a control for the relative balance of a stereo signal
         * between two stereo speakers.  The valid range of values is -1.0 (left channel only) to 1.0 (right channel
         * only).  The default is 0.0 (centered).
         *
         * @see #PAN
         */
        public static final Type BALANCE                        = new Type("Balance");


        // SAMPLE RATE

        /**
         * Represents a control that changes the sample rate of audio playback.  The net effect
         * of changing the sample rate depends on the relationship between
         * the media's natural rate and the rate that is set via this control.
         * The natural rate is the sample rate that is specified in the data line's
         * <code>AudioFormat</code> object.  For example, if the natural rate
         * of the media is 11025 samples per second and the sample rate is set
         * to 22050 samples per second, the media will play back at twice the
         * normal speed.
         * <p>
         * Changing the sample rate with this control does not affect the data line's
         * audio format.  Also note that whenever you change a sound's sample rate, a
         * change in the sound's pitch results.  For example, doubling the sample
         * rate has the effect of doubling the frequencies in the sound's spectrum,
         * which raises the pitch by an octave.
         */
        public static final Type SAMPLE_RATE            = new Type("Sample Rate");


        // CONSTRUCTOR

        /**
         * Constructs a new float control type.
         * @param name  the name of the new float control type
         */
        protected Type(String name) {
            super(name);
        }

    } // class Type

} // class FloatControl