JDK14/Java14源码在线阅读
/*
* 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
/**代码未完, 请加载全部代码(NowJava.com).**/
关注时代Java
关注时代Java