001 /*
002 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sound.sampled;
027
028 /**
029 * A <code>FloatControl</code> object provides control over a range of
030 * floating-point values. Float controls are often
031 * represented in graphical user interfaces by continuously
032 * adjustable objects such as sliders or rotary knobs. Concrete subclasses
033 * of <code>FloatControl</code> implement controls, such as gain and pan, that
034 * affect a line's audio signal in some way that an application can manipulate.
035 * The <code>{@link FloatControl.Type}</code>
036 * inner class provides static instances of types that are used to
037 * identify some common kinds of float control.
038 * <p>
039 * The <code>FloatControl</code> abstract class provides methods to set and get
040 * the control's current floating-point value. Other methods obtain the possible
041 * range of values and the control's resolution (the smallest increment between
042 * returned values). Some float controls allow ramping to a
043 * new value over a specified period of time. <code>FloatControl</code> also
044 * includes methods that return string labels for the minimum, maximum, and midpoint
045 * positions of the control.
046 *
047 * @see Line#getControls
048 * @see Line#isControlSupported
049 *
050 * @author David Rivas
051 * @author Kara Kytle
052 * @version 1.23, 07/05/05
053 * @since 1.3
054 */
055 public abstract class FloatControl extends Control {
056
057 // INSTANCE VARIABLES
058
059 // FINAL VARIABLES
060
061 /**
062 * The minimum supported value.
063 */
064 private float minimum;
065
066 /**
067 * The maximum supported value.
068 */
069 private float maximum;
070
071 /**
072 * The control's precision.
073 */
074 private float precision;
075
076 /**
077 * The smallest time increment in which a value change
078 * can be effected during a value shift, in microseconds.
079 */
080 private int updatePeriod;
081
082 /**
083 * A label for the units in which the control values are expressed,
084 * such as "dB" for decibels.
085 */
086 private final String units;
087
088 /**
089 * A label for the minimum value, such as "Left."
090 */
091 private final String minLabel;
092
093 /**
094 * A label for the maximum value, such as "Right."
095 */
096 private final String maxLabel;
097
098 /**
099 * A label for the mid-point value, such as "Center."
100 */
101 private final String midLabel;
102
103 // STATE VARIABLES
104
105 /**
106 * The current value.
107 */
108 private float value;
109
110 // CONSTRUCTORS
111
112 /**
113 * Constructs a new float control object with the given parameters
114 *
115 * @param type the kind of control represented by this float control object
116 * @param minimum the smallest value permitted for the control
117 * @param maximum the largest value permitted for the control
118 * @param precision the resolution or granularity of the control.
119 * This is the size of the increment between discrete valid values.
120 * @param updatePeriod the smallest time interval, in microseconds, over which the control
121 * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
122 * @param initialValue the value that the control starts with when constructed
123 * @param units the label for the units in which the control's values are expressed,
124 * such as "dB" or "frames per second"
125 * @param minLabel the label for the minimum value, such as "Left" or "Off"
126 * @param midLabel the label for the midpoint value, such as "Center" or "Default"
127 * @param maxLabel the label for the maximum value, such as "Right" or "Full"
128 */
129 protected FloatControl(Type type, float minimum, float maximum,
130 float precision, int updatePeriod, float initialValue,
131 String units, String minLabel, String midLabel,
132 String maxLabel) {
133
134 super (type);
135
136 this .minimum = minimum;
137 this .maximum = maximum;
138
139 this .precision = precision;
140 this .updatePeriod = updatePeriod;
141 this .value = initialValue;
142
143 this .units = units;
144 this .minLabel = ((minLabel == null) ? "" : minLabel);
145 this .midLabel = ((midLabel == null) ? "" : midLabel);
146 this .maxLabel = ((maxLabel == null) ? "" : maxLabel);
147 }
148
149 /**
150 * Constructs a new float control object with the given parameters.
151 * The labels for the minimum, maximum, and mid-point values are set
152 * to zero-length strings.
153 *
154 * @param type the kind of control represented by this float control object
155 * @param minimum the smallest value permitted for the control
156 * @param maximum the largest value permitted for the control
157 * @param precision the resolution or granularity of the control.
158 * This is the size of the increment between discrete valid values.
159 * @param updatePeriod the smallest time interval, in microseconds, over which the control
160 * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
161 * @param initialValue the value that the control starts with when constructed
162 * @param units the label for the units in which the control's values are expressed,
163 * such as "dB" or "frames per second"
164 */
165 protected FloatControl(Type type, float minimum, float maximum,
166 float precision, int updatePeriod, float initialValue,
167 String units) {
168 this (type, minimum, maximum, precision, updatePeriod,
169 initialValue, units, "", "", "");
170 }
171
172 // METHODS
173
174 /**
175 * Sets the current value for the control. The default implementation
176 * simply sets the value as indicated. If the value indicated is greater
177 * than the maximum value, or smaller than the minimum value, an
178 * IllegalArgumentException is thrown.
179 * Some controls require that their line be open before they can be affected
180 * by setting a value.
181 * @param newValue desired new value
182 * @throws IllegalArgumentException if the value indicated does not fall
183 * within the allowable range
184 */
185 public void setValue(float newValue) {
186
187 if (newValue > maximum) {
188 throw new IllegalArgumentException("Requested value "
189 + newValue + " exceeds allowable maximum value "
190 + maximum + ".");
191 }
192
193 if (newValue < minimum) {
194 throw new IllegalArgumentException("Requested value "
195 + newValue
196 + " smaller than allowable minimum value "
197 + minimum + ".");
198 }
199
200 value = newValue;
201 }
202
203 /**
204 * Obtains this control's current value.
205 * @return the current value
206 */
207 public float getValue() {
208 return value;
209 }
210
211 /**
212 * Obtains the maximum value permitted.
213 * @return the maximum allowable value
214 */
215 public float getMaximum() {
216 return maximum;
217 }
218
219 /**
220 * Obtains the minimum value permitted.
221 * @return the minimum allowable value
222 */
223 public float getMinimum() {
224 return minimum;
225 }
226
227 /**
228 * Obtains the label for the units in which the control's values are expressed,
229 * such as "dB" or "frames per second."
230 * @return the units label, or a zero-length string if no label
231 */
232 public String getUnits() {
233 return units;
234 }
235
236 /**
237 * Obtains the label for the minimum value, such as "Left" or "Off."
238 * @return the minimum value label, or a zero-length string if no label * has been set
239 */
240 public String getMinLabel() {
241 return minLabel;
242 }
243
244 /**
245 * Obtains the label for the mid-point value, such as "Center" or "Default."
246 * @return the mid-point value label, or a zero-length string if no label * has been set
247 */
248 public String getMidLabel() {
249 return midLabel;
250 }
251
252 /**
253 * Obtains the label for the maximum value, such as "Right" or "Full."
254 * @return the maximum value label, or a zero-length string if no label * has been set
255 */
256 public String getMaxLabel() {
257 return maxLabel;
258 }
259
260 /**
261 * Obtains the resolution or granularity of the control, in the units
262 * that the control measures.
263 * The precision is the size of the increment between discrete valid values
264 * for this control, over the set of supported floating-point values.
265 * @return the control's precision
266 */
267 public float getPrecision() {
268 return precision;
269 }
270
271 /**
272 * Obtains the smallest time interval, in microseconds, over which the control's value can
273 * change during a shift. The update period is the inverse of the frequency with which
274 * the control updates its value during a shift. If the implementation does not support value shifting over
275 * time, it should set the control's value to the final value immediately
276 * and return -1 from this method.
277 *
278 * @return update period in microseconds, or -1 if shifting over time is unsupported
279 * @see #shift
280 */
281 public int getUpdatePeriod() {
282 return updatePeriod;
283 }
284
285 /**
286 * Changes the control value from the initial value to the final
287 * value linearly over the specified time period, specified in microseconds.
288 * This method returns without blocking; it does not wait for the shift
289 * to complete. An implementation should complete the operation within the time
290 * specified. The default implementation simply changes the value
291 * to the final value immediately.
292 *
293 * @param from initial value at the beginning of the shift
294 * @param to final value after the shift
295 * @param microseconds maximum duration of the shift in microseconds
296 *
297 * @see #getUpdatePeriod
298 */
299 public void shift(float from, float to, int microseconds) {
300 setValue(to);
301 }
302
303 // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
304
305 /**
306 * Provides a string representation of the control
307 * @return a string description
308 */
309 public String toString() {
310 return new String(getType() + " with current value: "
311 + getValue() + " " + units + " (range: " + minimum
312 + " - " + maximum + ")");
313 }
314
315 // INNER CLASSES
316
317 /**
318 * An instance of the <code>FloatControl.Type</code> inner class identifies one kind of
319 * float control. Static instances are provided for the
320 * common types.
321 *
322 * @author Kara Kytle
323 * @version 1.23, 07/05/05
324 * @since 1.3
325 */
326 public static class Type extends Control.Type {
327
328 // TYPE DEFINES
329
330 // GAIN TYPES
331
332 /**
333 * Represents a control for the overall gain on a line.
334 * <p>
335 * Gain is a quantity in decibels (dB) that is added to the intrinsic
336 * decibel level of the audio signal--that is, the level of
337 * the signal before it is altered by the gain control. A positive
338 * gain amplifies (boosts) the signal's volume, and a negative gain
339 * attenuates (cuts) it.
340 * The gain setting defaults to a value of 0.0 dB, meaning the signal's
341 * loudness is unaffected. Note that gain measures dB, not amplitude.
342 * The relationship between a gain in decibels and the corresponding
343 * linear amplitude multiplier is:
344 *
345 *<CENTER><CODE> linearScalar = pow(10.0, gainDB/20.0) </CODE></CENTER>
346 * <p>
347 * The <code>FloatControl</code> class has methods to impose a maximum and
348 * minimum allowable value for gain. However, because an audio signal might
349 * already be at a high amplitude, the maximum setting does not guarantee
350 * that the signal will be undistorted when the gain is applied to it (unless
351 * the maximum is zero or negative). To avoid numeric overflow from excessively
352 * large gain settings, a gain control can implement
353 * clipping, meaning that the signal's amplitude will be limited to the maximum
354 * value representable by its audio format, instead of wrapping around.
355 * <p>
356 * These comments apply to gain controls in general, not just master gain controls.
357 * A line can have more than one gain control. For example, a mixer (which is
358 * itself a line) might have a master gain control, an auxiliary return control,
359 * a reverb return control, and, on each of its source lines, an individual aux
360 * send and reverb send.
361 *
362 * @see #AUX_SEND
363 * @see #AUX_RETURN
364 * @see #REVERB_SEND
365 * @see #REVERB_RETURN
366 * @see #VOLUME
367 */
368 public static final Type MASTER_GAIN = new Type("Master Gain");
369
370 /**
371 * Represents a control for the auxiliary send gain on a line.
372 *
373 * @see #MASTER_GAIN
374 * @see #AUX_RETURN
375 */
376 public static final Type AUX_SEND = new Type("AUX Send");
377
378 /**
379 * Represents a control for the auxiliary return gain on a line.
380 *
381 * @see #MASTER_GAIN
382 * @see #AUX_SEND
383 */
384 public static final Type AUX_RETURN = new Type("AUX Return");
385
386 /**
387 * Represents a control for the pre-reverb gain on a line.
388 * This control may be used to affect how much
389 * of a line's signal is directed to a mixer's internal reverberation unit.
390 *
391 * @see #MASTER_GAIN
392 * @see #REVERB_RETURN
393 * @see EnumControl.Type#REVERB
394 */
395 public static final Type REVERB_SEND = new Type("Reverb Send");
396
397 /**
398 * Represents a control for the post-reverb gain on a line.
399 * This control may be used to control the relative amplitude
400 * of the signal returned from an internal reverberation unit.
401 *
402 * @see #MASTER_GAIN
403 * @see #REVERB_SEND
404 */
405 public static final Type REVERB_RETURN = new Type(
406 "Reverb Return");
407
408 // VOLUME
409
410 /**
411 * Represents a control for the volume on a line.
412 */
413 /*
414 * $$kk: 08.30.99: ISSUE: what units? linear or dB?
415 */
416 public static final Type VOLUME = new Type("Volume");
417
418 // PAN
419
420 /**
421 * Represents a control for the relative pan (left-right positioning)
422 * of the signal. The signal may be mono; the pan setting affects how
423 * it is distributed by the mixer in a stereo mix. The valid range of values is -1.0
424 * (left channel only) to 1.0 (right channel
425 * only). The default is 0.0 (centered).
426 *
427 * @see #BALANCE
428 */
429 public static final Type PAN = new Type("Pan");
430
431 // BALANCE
432
433 /**
434 * Represents a control for the relative balance of a stereo signal
435 * between two stereo speakers. The valid range of values is -1.0 (left channel only) to 1.0 (right channel
436 * only). The default is 0.0 (centered).
437 *
438 * @see #PAN
439 */
440 public static final Type BALANCE = new Type("Balance");
441
442 // SAMPLE RATE
443
444 /**
445 * Represents a control that changes the sample rate of audio playback. The net effect
446 * of changing the sample rate depends on the relationship between
447 * the media's natural rate and the rate that is set via this control.
448 * The natural rate is the sample rate that is specified in the data line's
449 * <code>AudioFormat</code> object. For example, if the natural rate
450 * of the media is 11025 samples per second and the sample rate is set
451 * to 22050 samples per second, the media will play back at twice the
452 * normal speed.
453 * <p>
454 * Changing the sample rate with this control does not affect the data line's
455 * audio format. Also note that whenever you change a sound's sample rate, a
456 * change in the sound's pitch results. For example, doubling the sample
457 * rate has the effect of doubling the frequencies in the sound's spectrum,
458 * which raises the pitch by an octave.
459 */
460 public static final Type SAMPLE_RATE = new Type("Sample Rate");
461
462 // CONSTRUCTOR
463
464 /**
465 * Constructs a new float control type.
466 * @param name the name of the new float control type
467 */
468 protected Type(String name) {
469 super (name);
470 }
471
472 } // class Type
473
474 } // class FloatControl
|