FloatControl


1   /*
2    * @(#)FloatControl.java    1.16 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.sound.sampled;
9   
10  /**
11   * A <code>FloatControl</code> object provides control over a range of
12   * floating-point values.  Float controls are often
13   * represented in graphical user interfaces by continuously
14   * adjustable objects such as sliders or rotary knobs.  Concrete subclasses
15   * of <code>FloatControl</code> implement controls, such as gain and pan, that
16   * affect a line's audio signal in some way that an application can manipulate.
17   * The <code>{@link FloatControl.Type}</code>
18   * inner class provides static instances of types that are used to
19   * identify some common kinds of float control.
20   * <p>
21   * The <code>FloatControl</code> abstract class provides methods to set and get
22   * the control's current floating-point value.  Other methods obtain the possible
23   * range of values and the control's resolution (the smallest increment between
24   * returned values).  Some float controls allow ramping to a
25   * new value over a specified period of time.  <code>FloatControl</code> also
26   * includes methods that return string labels for the minimum, maximum, and midpoint
27   * positions of the control.
28   *
29   * @see Line#getControls
30   * @see Line#isControlSupported
31   *
32   * @author David Rivas
33   * @author Kara Kytle
34   * @version 1.16, 03/12/19
35   * @since 1.3
36   */
37  public abstract class FloatControl extends Control   {
38      
39      
40      // INSTANCE VARIABLES
41      
42      
43      // FINAL VARIABLES
44      
45      /**
46       * The minimum supported value.
47       */
48      private float minimum;
49      
50      /**
51       * The maximum supported value.
52       */
53      private float maximum;
54      
55      /**
56       * The control's precision.
57       */
58      private float precision;
59      
60      /**
61       * The smallest time increment in which a value change
62       * can be effected during a value shift, in microseconds.
63       */
64      private int updatePeriod;
65      
66      
67      /**
68       * A label for the units in which the control values are expressed,
69       * such as "dB" for decibels.
70       */
71      private final String   units;
72      
73      /**
74       * A label for the minimum value, such as "Left."
75       */
76      private final String   minLabel;
77      
78      /**
79       * A label for the maximum value, such as "Right."
80       */
81      private final String   maxLabel;
82      
83      /**
84       * A label for the mid-point value, such as "Center."
85       */
86      private final String   midLabel;
87      
88      
89      // STATE VARIABLES
90      
91      /**
92       * The current value.
93       */
94      private float value;
95      
96      
97      
98      // CONSTRUCTORS
99      
100     
101     /**
102      * Constructs a new float control object with the given parameters
103      *
104      * @param type the kind of control represented by this float control object
105      * @param minimum the smallest value permitted for the control
106      * @param maximum the largest value permitted for the control
107      * @param precision the resolution or granularity of the control.
108      * This is the size of the increment between discrete valid values.
109      * @param updatePeriod the smallest time interval, in microseconds, over which the control
110      * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
111      * @param initialValue the value that the control starts with when constructed
112      * @param units the label for the units in which the control's values are expressed,
113      * such as "dB" or "frames per second"
114      * @param minLabel the label for the minimum value, such as "Left" or "Off"
115      * @param midLabel the label for the midpoint value, such as "Center" or "Default"
116      * @param maxLabel the label for the maximum value, such as "Right" or "Full"
117      */
118     protected FloatControl(Type type, float minimum, float maximum,
119                float precision, int updatePeriod, float initialValue,
120                String   units, String   minLabel, String   midLabel, String   maxLabel) {
121     
122     super(type);
123     
124     this.minimum = minimum;
125     this.maximum = maximum;
126     
127     this.precision = precision;
128     this.updatePeriod = updatePeriod;
129     this.value = initialValue;
130     
131     this.units = units;
132     this.minLabel = ( (minLabel == null) ? "" : minLabel);
133     this.midLabel = ( (midLabel == null) ? "" : midLabel);
134     this.maxLabel = ( (maxLabel == null) ? "" : maxLabel);
135     }
136     
137     
138     /**
139      * Constructs a new float control object with the given parameters.
140      * The labels for the minimum, maximum, and mid-point values are set
141      * to zero-length strings.
142      *
143      * @param type the kind of control represented by this float control object
144      * @param minimum the smallest value permitted for the control
145      * @param maximum the largest value permitted for the control
146      * @param precision the resolution or granularity of the control.
147      * This is the size of the increment between discrete valid values.
148      * @param updatePeriod the smallest time interval, in microseconds, over which the control
149      * can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
150      * @param initialValue the value that the control starts with when constructed
151      * @param units the label for the units in which the control's values are expressed,
152      * such as "dB" or "frames per second"
153      */
154     protected FloatControl(Type type, float minimum, float maximum,
155                float precision, int updatePeriod, float initialValue, String   units) {
156     this(type, minimum, maximum, precision, updatePeriod, initialValue, units, "", "", "");
157     }
158     
159     
160     
161     // METHODS
162     
163     
164     /**
165      * Sets the current value for the control.  The default implementation
166      * simply sets the value as indicated.  If the value indicated is greater
167      * than the maximum value, or smaller than the minimum value, an
168      * IllegalArgumentException is thrown.
169      * Some controls require that their line be open before they can be affected
170      * by setting a value.
171      * @param newValue desired new value
172      * @throws IllegalArgumentException if the value indicated does not fall
173      * within the allowable range
174      */
175     public void setValue(float newValue) {
176     
177     if (newValue > maximum) {
178         throw new IllegalArgumentException  ("Requested value " + newValue + " exceeds allowable maximum value " + maximum + ".");
179     }
180     
181     if (newValue < minimum) {
182         throw new IllegalArgumentException  ("Requested value " + newValue + " smaller than allowable minimum value " + minimum + ".");
183     }
184     
185     value = newValue;
186     }
187     
188     
189     /**
190      * Obtains this control's current value.
191      * @return the current value
192      */
193     public float getValue() {
194     return value;
195     }
196     
197     
198     /**
199      * Obtains the maximum value permitted.
200      * @return the maximum allowable value
201      */
202     public float getMaximum() {
203     return maximum;
204     }
205     
206     
207     /**
208      * Obtains the minimum value permitted.
209      * @return the minimum allowable value
210      */
211     public float getMinimum() {
212     return minimum;
213     }
214     
215     
216     /**
217      * Obtains the label for the units in which the control's values are expressed,
218      * such as "dB" or "frames per second."
219      * @return the units label, or a zero-length string if no label
220      */
221     public String   getUnits() {
222     return units;
223     }
224     
225     
226     /**
227      * Obtains the label for the minimum value, such as "Left" or "Off."
228      * @return the minimum value label, or a zero-length string if no label  * has been set
229      */
230     public String   getMinLabel() {
231     return minLabel;
232     }
233     
234     
235     /**
236      * Obtains the label for the mid-point value, such as "Center" or "Default."
237      * @return the mid-point value label, or a zero-length string if no label    * has been set
238      */
239     public String   getMidLabel() {
240     return midLabel;
241     }
242     
243     
244     /**
245      * Obtains the label for the maximum value, such as "Right" or "Full."
246      * @return the maximum value label, or a zero-length string if no label  * has been set
247      */
248     public String   getMaxLabel() {
249     return maxLabel;
250     }
251     
252     
253     /**
254      * Obtains the resolution or granularity of the control, in the units
255      * that the control measures.
256      * The precision is the size of the increment between discrete valid values
257      * for this control, over the set of supported floating-point values.
258      * @return the control's precision
259      */
260     public float getPrecision() {
261     return precision;
262     }
263     
264     
265     /**
266      * Obtains the smallest time interval, in microseconds, over which the control's value can
267      * change during a shift.  The update period is the inverse of the frequency with which
268      * the control updates its value during a shift.  If the implementation does not support value shifting over
269      * time, it should set the control's value to the final value immediately
270      * and return -1 from this method.
271      *
272      * @return update period in microseconds, or -1 if shifting over time is unsupported
273      * @see #shift
274      */
275     public int getUpdatePeriod() {
276     return updatePeriod;
277     }
278     
279     
280     /**
281      * Changes the control value from the initial value to the final
282      * value linearly over the specified time period, specified in microseconds.
283      * This method returns without blocking; it does not wait for the shift
284      * to complete.  An implementation should complete the operation within the time
285      * specified.  The default implementation simply changes the value
286      * to the final value immediately.
287      *
288      * @param from initial value at the beginning of the shift
289      * @param to final value after the shift
290      * @param microseconds maximum duration of the shift in microseconds
291      *
292      * @see #getUpdatePeriod
293      */
294     public void shift(float from, float to, int microseconds) {
295     setValue(to);
296     }
297     
298     
299     // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
300     
301     
302     /**
303      * Provides a string representation of the control
304      * @return a string description
305      */
306     public String   toString() {
307     return new String  (getType() + " with current value: " + getValue() + " " + units +
308               " (range: " + minimum + " - " + maximum + ")");
309     }
310     
311     
312     // INNER CLASSES
313     
314     
315     /**
316      * An instance of the <code>FloatControl.Type</code> inner class identifies one kind of
317      * float control.  Static instances are provided for the
318      * common types.
319      *
320      * @author Kara Kytle
321      * @version 1.16, 03/12/19
322      * @since 1.3
323      */
324     public static class Type extends Control.Type   {
325     
326     
327     // TYPE DEFINES
328     
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("Reverb Return");
406     
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     
419     // PAN
420     
421     /**
422      * Represents a control for the relative pan (left-right positioning)
423      * of the signal.  The signal may be mono; the pan setting affects how
424      * it is distributed by the mixer in a stereo mix.  The valid range of values is -1.0
425      * (left channel only) to 1.0 (right channel
426      * only).  The default is 0.0 (centered).
427      *
428      * @see #BALANCE
429      */
430     public static final Type PAN                = new Type("Pan");
431     
432     
433     // BALANCE
434     
435     /**
436      * Represents a control for the relative balance of a stereo signal
437      * between two stereo speakers.  The valid range of values is -1.0 (left channel only) to 1.0 (right channel
438      * only).  The default is 0.0 (centered).
439      *
440      * @see #PAN
441      */
442     public static final Type BALANCE            = new Type("Balance");
443     
444     
445     // SAMPLE RATE
446     
447     /**
448      * Represents a control that changes the sample rate of audio playback.  The net effect
449      * of changing the sample rate depends on the relationship between
450      * the media's natural rate and the rate that is set via this control.
451      * The natural rate is the sample rate that is specified in the data line's
452      * <code>AudioFormat</code> object.  For example, if the natural rate
453      * of the media is 11025 samples per second and the sample rate is set
454      * to 22050 samples per second, the media will play back at twice the
455      * normal speed.
456      * <p>
457      * Changing the sample rate with this control does not affect the data line's
458      * audio format.  Also note that whenever you change a sound's sample rate, a
459      * change in the sound's pitch results.  For example, doubling the sample
460      * rate has the effect of doubling the frequencies in the sound's spectrum,
461      * which raises the pitch by an octave.
462      */
463     public static final Type SAMPLE_RATE        = new Type("Sample Rate");
464     
465     
466     // CONSTRUCTOR
467     
468     /**
469      * Constructs a new float control type.
470      * @param name  the name of the new float control type
471      */
472     protected Type(String   name) {
473         super(name);
474     }
475     
476     } // class Type
477     
478 } // class FloatControl
479
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags