| /* |
| * Copyright (c) 1999, 2017, 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} 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} implement controls, such as gain and pan, |
| * that affect a line's audio signal in some way that an application can |
| * manipulate. The {@link FloatControl.Type} inner class provides static |
| * instances of types that are used to identify some common kinds of float |
| * control. |
| * <p> |
| * The {@code FloatControl} 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} also includes methods that |
| * return string labels for the minimum, maximum, and midpoint positions of the |
| * control. |
| * |
| * @author David Rivas |
| * @author Kara Kytle |
| * @see Line#getControls |
| * @see Line#isControlSupported |
| * @since 1.3 |
| */ |
| public abstract class FloatControl extends Control { |
| |
| /** |
| * The minimum supported value. |
| */ |
| private final float minimum; |
| |
| /** |
| * The maximum supported value. |
| */ |
| private final float maximum; |
| |
| /** |
| * The control's precision. |
| */ |
| private final float precision; |
| |
| /** |
| * The smallest time increment in which a value change can be effected |
| * during a value shift, in microseconds. |
| */ |
| private final 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; |
| |
| /** |
| * The current value. |
| */ |
| private float value; |
| |
| /** |
| * 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, "", "", ""); |
| } |
| |
| /** |
| * 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 |
| * {@code 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); |
| } |
| |
| /** |
| * Provides a string representation of the control. |
| * |
| * @return a string description |
| */ |
| @Override |
| public String toString() { |
| return new String(getType() + " with current value: " + getValue() + " " + units + |
| " (range: " + minimum + " - " + maximum + ")"); |
| } |
| |
| /** |
| * An instance of the {@code FloatControl.Type} 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 { |
| |
| /** |
| * 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: |
| * <p style="text-align:center"> |
| * {@code linearScalar = pow(10.0, gainDB/20.0)} |
| * <p> |
| * The {@code FloatControl} 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"); |
| |
| /** |
| * 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"); |
| |
| /** |
| * 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"); |
| |
| /** |
| * 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"); |
| |
| /** |
| * 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} 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"); |
| |
| /** |
| * Constructs a new float control type. |
| * |
| * @param name the name of the new float control type |
| */ |
| protected Type(final String name) { |
| super(name); |
| } |
| } |
| } |
