/*
* Copyright 1999-2003 Sun Microsystems, Inc. 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. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.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"
*/
protected FloatControl(Type type, float minimum, float maximum,
float precision, int updatePeriod, float initialValue,
String units, String minLabel, String midLabel, String maxLabel) {
super(type);
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"
*/
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
*
* @see #getUpdatePeriod
*/
public void shift(float from, float to, int microseconds) {
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