Back to index...

	/*
	* 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

Back to index...