1 /* 2 * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sound.sampled; 27 28 /** 29 * A <code>FloatControl</code> object provides control over a range of 30 * floating-point values. Float controls are often 31 * represented in graphical user interfaces by continuously 32 * adjustable objects such as sliders or rotary knobs. Concrete subclasses 33 * of <code>FloatControl</code> implement controls, such as gain and pan, that 34 * affect a line's audio signal in some way that an application can manipulate. 35 * The <code>{@link FloatControl.Type}</code> 36 * inner class provides static instances of types that are used to 37 * identify some common kinds of float control. 38 * <p> 39 * The <code>FloatControl</code> abstract class provides methods to set and get 40 * the control's current floating-point value. Other methods obtain the possible 41 * range of values and the control's resolution (the smallest increment between 42 * returned values). Some float controls allow ramping to a 43 * new value over a specified period of time. <code>FloatControl</code> also 44 * includes methods that return string labels for the minimum, maximum, and midpoint 45 * positions of the control. 46 * 47 * @see Line#getControls 48 * @see Line#isControlSupported 49 * 50 * @author David Rivas 51 * @author Kara Kytle 52 * @since 1.3 53 */ 54 public abstract class FloatControl extends Control { 55 56 57 // INSTANCE VARIABLES 58 59 60 // FINAL VARIABLES 61 62 /** 63 * The minimum supported value. 64 */ 65 private float minimum; 66 67 /** 68 * The maximum supported value. 69 */ 70 private float maximum; 71 72 /** 73 * The control's precision. 74 */ 75 private float precision; 76 77 /** 78 * The smallest time increment in which a value change 79 * can be effected during a value shift, in microseconds. 80 */ 81 private int updatePeriod; 82 83 84 /** 85 * A label for the units in which the control values are expressed, 86 * such as "dB" for decibels. 87 */ 88 private final String units; 89 90 /** 91 * A label for the minimum value, such as "Left." 92 */ 93 private final String minLabel; 94 95 /** 96 * A label for the maximum value, such as "Right." 97 */ 98 private final String maxLabel; 99 100 /** 101 * A label for the mid-point value, such as "Center." 102 */ 103 private final String midLabel; 104 105 106 // STATE VARIABLES 107 108 /** 109 * The current value. 110 */ 111 private float value; 112 113 114 115 // CONSTRUCTORS 116 117 118 /** 119 * Constructs a new float control object with the given parameters 120 * 121 * @param type the kind of control represented by this float control object 122 * @param minimum the smallest value permitted for the control 123 * @param maximum the largest value permitted for the control 124 * @param precision the resolution or granularity of the control. 125 * This is the size of the increment between discrete valid values. 126 * @param updatePeriod the smallest time interval, in microseconds, over which the control 127 * can change from one discrete value to the next during a {@link #shift(float,float,int) shift} 128 * @param initialValue the value that the control starts with when constructed 129 * @param units the label for the units in which the control's values are expressed, 130 * such as "dB" or "frames per second" 131 * @param minLabel the label for the minimum value, such as "Left" or "Off" 132 * @param midLabel the label for the midpoint value, such as "Center" or "Default" 133 * @param maxLabel the label for the maximum value, such as "Right" or "Full" 134 * 135 * @throws IllegalArgumentException if {@code minimum} is greater 136 * than {@code maximum} or {@code initialValue} does not fall 137 * within the allowable range 138 */ 139 protected FloatControl(Type type, float minimum, float maximum, 140 float precision, int updatePeriod, float initialValue, 141 String units, String minLabel, String midLabel, String maxLabel) { 142 143 super(type); 144 145 if (minimum > maximum) { 146 throw new IllegalArgumentException("Minimum value " + minimum 147 + " exceeds maximum value " + maximum + "."); 148 } 149 if (initialValue < minimum) { 150 throw new IllegalArgumentException("Initial value " + initialValue 151 + " smaller than allowable minimum value " + minimum + "."); 152 } 153 if (initialValue > maximum) { 154 throw new IllegalArgumentException("Initial value " + initialValue 155 + " exceeds allowable maximum value " + maximum + "."); 156 } 157 158 159 this.minimum = minimum; 160 this.maximum = maximum; 161 162 this.precision = precision; 163 this.updatePeriod = updatePeriod; 164 this.value = initialValue; 165 166 this.units = units; 167 this.minLabel = ( (minLabel == null) ? "" : minLabel); 168 this.midLabel = ( (midLabel == null) ? "" : midLabel); 169 this.maxLabel = ( (maxLabel == null) ? "" : maxLabel); 170 } 171 172 173 /** 174 * Constructs a new float control object with the given parameters. 175 * The labels for the minimum, maximum, and mid-point values are set 176 * to zero-length strings. 177 * 178 * @param type the kind of control represented by this float control object 179 * @param minimum the smallest value permitted for the control 180 * @param maximum the largest value permitted for the control 181 * @param precision the resolution or granularity of the control. 182 * This is the size of the increment between discrete valid values. 183 * @param updatePeriod the smallest time interval, in microseconds, over which the control 184 * can change from one discrete value to the next during a {@link #shift(float,float,int) shift} 185 * @param initialValue the value that the control starts with when constructed 186 * @param units the label for the units in which the control's values are expressed, 187 * such as "dB" or "frames per second" 188 * 189 * @throws IllegalArgumentException if {@code minimum} is greater 190 * than {@code maximum} or {@code initialValue} does not fall 191 * within the allowable range 192 */ 193 protected FloatControl(Type type, float minimum, float maximum, 194 float precision, int updatePeriod, float initialValue, String units) { 195 this(type, minimum, maximum, precision, updatePeriod, 196 initialValue, units, "", "", ""); 197 } 198 199 200 201 // METHODS 202 203 204 /** 205 * Sets the current value for the control. The default implementation 206 * simply sets the value as indicated. If the value indicated is greater 207 * than the maximum value, or smaller than the minimum value, an 208 * IllegalArgumentException is thrown. 209 * Some controls require that their line be open before they can be affected 210 * by setting a value. 211 * @param newValue desired new value 212 * @throws IllegalArgumentException if the value indicated does not fall 213 * within the allowable range 214 */ 215 public void setValue(float newValue) { 216 217 if (newValue > maximum) { 218 throw new IllegalArgumentException("Requested value " + newValue + " exceeds allowable maximum value " + maximum + "."); 219 } 220 221 if (newValue < minimum) { 222 throw new IllegalArgumentException("Requested value " + newValue + " smaller than allowable minimum value " + minimum + "."); 223 } 224 225 value = newValue; 226 } 227 228 229 /** 230 * Obtains this control's current value. 231 * @return the current value 232 */ 233 public float getValue() { 234 return value; 235 } 236 237 238 /** 239 * Obtains the maximum value permitted. 240 * @return the maximum allowable value 241 */ 242 public float getMaximum() { 243 return maximum; 244 } 245 246 247 /** 248 * Obtains the minimum value permitted. 249 * @return the minimum allowable value 250 */ 251 public float getMinimum() { 252 return minimum; 253 } 254 255 256 /** 257 * Obtains the label for the units in which the control's values are expressed, 258 * such as "dB" or "frames per second." 259 * @return the units label, or a zero-length string if no label 260 */ 261 public String getUnits() { 262 return units; 263 } 264 265 266 /** 267 * Obtains the label for the minimum value, such as "Left" or "Off." 268 * @return the minimum value label, or a zero-length string if no label * has been set 269 */ 270 public String getMinLabel() { 271 return minLabel; 272 } 273 274 275 /** 276 * Obtains the label for the mid-point value, such as "Center" or "Default." 277 * @return the mid-point value label, or a zero-length string if no label * has been set 278 */ 279 public String getMidLabel() { 280 return midLabel; 281 } 282 283 284 /** 285 * Obtains the label for the maximum value, such as "Right" or "Full." 286 * @return the maximum value label, or a zero-length string if no label * has been set 287 */ 288 public String getMaxLabel() { 289 return maxLabel; 290 } 291 292 293 /** 294 * Obtains the resolution or granularity of the control, in the units 295 * that the control measures. 296 * The precision is the size of the increment between discrete valid values 297 * for this control, over the set of supported floating-point values. 298 * @return the control's precision 299 */ 300 public float getPrecision() { 301 return precision; 302 } 303 304 305 /** 306 * Obtains the smallest time interval, in microseconds, over which the control's value can 307 * change during a shift. The update period is the inverse of the frequency with which 308 * the control updates its value during a shift. If the implementation does not support value shifting over 309 * time, it should set the control's value to the final value immediately 310 * and return -1 from this method. 311 * 312 * @return update period in microseconds, or -1 if shifting over time is unsupported 313 * @see #shift 314 */ 315 public int getUpdatePeriod() { 316 return updatePeriod; 317 } 318 319 320 /** 321 * Changes the control value from the initial value to the final 322 * value linearly over the specified time period, specified in microseconds. 323 * This method returns without blocking; it does not wait for the shift 324 * to complete. An implementation should complete the operation within the time 325 * specified. The default implementation simply changes the value 326 * to the final value immediately. 327 * 328 * @param from initial value at the beginning of the shift 329 * @param to final value after the shift 330 * @param microseconds maximum duration of the shift in microseconds 331 * 332 * @throws IllegalArgumentException if either {@code from} or {@code to} 333 * value does not fall within the allowable range 334 * 335 * @see #getUpdatePeriod 336 */ 337 public void shift(float from, float to, int microseconds) { 338 // test "from" value, "to" value will be tested by setValue() 339 if (from < minimum) { 340 throw new IllegalArgumentException("Requested value " + from 341 + " smaller than allowable minimum value " + minimum + "."); 342 } 343 if (from > maximum) { 344 throw new IllegalArgumentException("Requested value " + from 345 + " exceeds allowable maximum value " + maximum + "."); 346 } 347 setValue(to); 348 } 349 350 351 // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL 352 353 354 /** 355 * Provides a string representation of the control 356 * @return a string description 357 */ 358 public String toString() { 359 return new String(getType() + " with current value: " + getValue() + " " + units + 360 " (range: " + minimum + " - " + maximum + ")"); 361 } 362 363 364 // INNER CLASSES 365 366 367 /** 368 * An instance of the <code>FloatControl.Type</code> inner class identifies one kind of 369 * float control. Static instances are provided for the 370 * common types. 371 * 372 * @author Kara Kytle 373 * @since 1.3 374 */ 375 public static class Type extends Control.Type { 376 377 378 // TYPE DEFINES 379 380 381 // GAIN TYPES 382 383 /** 384 * Represents a control for the overall gain on a line. 385 * <p> 386 * Gain is a quantity in decibels (dB) that is added to the intrinsic 387 * decibel level of the audio signal--that is, the level of 388 * the signal before it is altered by the gain control. A positive 389 * gain amplifies (boosts) the signal's volume, and a negative gain 390 * attenuates (cuts) it. 391 * The gain setting defaults to a value of 0.0 dB, meaning the signal's 392 * loudness is unaffected. Note that gain measures dB, not amplitude. 393 * The relationship between a gain in decibels and the corresponding 394 * linear amplitude multiplier is: 395 * 396 *<CENTER><CODE> linearScalar = pow(10.0, gainDB/20.0) </CODE></CENTER> 397 * <p> 398 * The <code>FloatControl</code> class has methods to impose a maximum and 399 * minimum allowable value for gain. However, because an audio signal might 400 * already be at a high amplitude, the maximum setting does not guarantee 401 * that the signal will be undistorted when the gain is applied to it (unless 402 * the maximum is zero or negative). To avoid numeric overflow from excessively 403 * large gain settings, a gain control can implement 404 * clipping, meaning that the signal's amplitude will be limited to the maximum 405 * value representable by its audio format, instead of wrapping around. 406 * <p> 407 * These comments apply to gain controls in general, not just master gain controls. 408 * A line can have more than one gain control. For example, a mixer (which is 409 * itself a line) might have a master gain control, an auxiliary return control, 410 * a reverb return control, and, on each of its source lines, an individual aux 411 * send and reverb send. 412 * 413 * @see #AUX_SEND 414 * @see #AUX_RETURN 415 * @see #REVERB_SEND 416 * @see #REVERB_RETURN 417 * @see #VOLUME 418 */ 419 public static final Type MASTER_GAIN = new Type("Master Gain"); 420 421 /** 422 * Represents a control for the auxiliary send gain on a line. 423 * 424 * @see #MASTER_GAIN 425 * @see #AUX_RETURN 426 */ 427 public static final Type AUX_SEND = new Type("AUX Send"); 428 429 /** 430 * Represents a control for the auxiliary return gain on a line. 431 * 432 * @see #MASTER_GAIN 433 * @see #AUX_SEND 434 */ 435 public static final Type AUX_RETURN = new Type("AUX Return"); 436 437 /** 438 * Represents a control for the pre-reverb gain on a line. 439 * This control may be used to affect how much 440 * of a line's signal is directed to a mixer's internal reverberation unit. 441 * 442 * @see #MASTER_GAIN 443 * @see #REVERB_RETURN 444 * @see EnumControl.Type#REVERB 445 */ 446 public static final Type REVERB_SEND = new Type("Reverb Send"); 447 448 /** 449 * Represents a control for the post-reverb gain on a line. 450 * This control may be used to control the relative amplitude 451 * of the signal returned from an internal reverberation unit. 452 * 453 * @see #MASTER_GAIN 454 * @see #REVERB_SEND 455 */ 456 public static final Type REVERB_RETURN = new Type("Reverb Return"); 457 458 459 // VOLUME 460 461 /** 462 * Represents a control for the volume on a line. 463 */ 464 /* 465 * $$kk: 08.30.99: ISSUE: what units? linear or dB? 466 */ 467 public static final Type VOLUME = new Type("Volume"); 468 469 470 // PAN 471 472 /** 473 * Represents a control for the relative pan (left-right positioning) 474 * of the signal. The signal may be mono; the pan setting affects how 475 * it is distributed by the mixer in a stereo mix. The valid range of values is -1.0 476 * (left channel only) to 1.0 (right channel 477 * only). The default is 0.0 (centered). 478 * 479 * @see #BALANCE 480 */ 481 public static final Type PAN = new Type("Pan"); 482 483 484 // BALANCE 485 486 /** 487 * Represents a control for the relative balance of a stereo signal 488 * between two stereo speakers. The valid range of values is -1.0 (left channel only) to 1.0 (right channel 489 * only). The default is 0.0 (centered). 490 * 491 * @see #PAN 492 */ 493 public static final Type BALANCE = new Type("Balance"); 494 495 496 // SAMPLE RATE 497 498 /** 499 * Represents a control that changes the sample rate of audio playback. The net effect 500 * of changing the sample rate depends on the relationship between 501 * the media's natural rate and the rate that is set via this control. 502 * The natural rate is the sample rate that is specified in the data line's 503 * <code>AudioFormat</code> object. For example, if the natural rate 504 * of the media is 11025 samples per second and the sample rate is set 505 * to 22050 samples per second, the media will play back at twice the 506 * normal speed. 507 * <p> 508 * Changing the sample rate with this control does not affect the data line's 509 * audio format. Also note that whenever you change a sound's sample rate, a 510 * change in the sound's pitch results. For example, doubling the sample 511 * rate has the effect of doubling the frequencies in the sound's spectrum, 512 * which raises the pitch by an octave. 513 */ 514 public static final Type SAMPLE_RATE = new Type("Sample Rate"); 515 516 517 // CONSTRUCTOR 518 519 /** 520 * Constructs a new float control type. 521 * @param name the name of the new float control type 522 */ 523 protected Type(String name) { 524 super(name); 525 } 526 527 } // class Type 528 529 } // class FloatControl | 1 /* 2 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sound.sampled; 27 28 /** 29 * A {@code FloatControl} object provides control over a range of floating-point 30 * values. Float controls are often represented in graphical user interfaces by 31 * continuously adjustable objects such as sliders or rotary knobs. Concrete 32 * subclasses of {@code FloatControl} implement controls, such as gain and pan, 33 * that affect a line's audio signal in some way that an application can 34 * manipulate. The {@link FloatControl.Type} inner class provides static 35 * instances of types that are used to identify some common kinds of float 36 * control. 37 * <p> 38 * The {@code FloatControl} abstract class provides methods to set and get the 39 * control's current floating-point value. Other methods obtain the possible 40 * range of values and the control's resolution (the smallest increment between 41 * returned values). Some float controls allow ramping to a new value over a 42 * specified period of time. {@code FloatControl} also includes methods that 43 * return string labels for the minimum, maximum, and midpoint positions of the 44 * control. 45 * 46 * @author David Rivas 47 * @author Kara Kytle 48 * @see Line#getControls 49 * @see Line#isControlSupported 50 * @since 1.3 51 */ 52 public abstract class FloatControl extends Control { 53 54 /** 55 * The minimum supported value. 56 */ 57 private float minimum; 58 59 /** 60 * The maximum supported value. 61 */ 62 private float maximum; 63 64 /** 65 * The control's precision. 66 */ 67 private float precision; 68 69 /** 70 * The smallest time increment in which a value change can be effected 71 * during a value shift, in microseconds. 72 */ 73 private int updatePeriod; 74 75 /** 76 * A label for the units in which the control values are expressed, such as 77 * "dB" for decibels. 78 */ 79 private final String units; 80 81 /** 82 * A label for the minimum value, such as "Left". 83 */ 84 private final String minLabel; 85 86 /** 87 * A label for the maximum value, such as "Right". 88 */ 89 private final String maxLabel; 90 91 /** 92 * A label for the mid-point value, such as "Center". 93 */ 94 private final String midLabel; 95 96 /** 97 * The current value. 98 */ 99 private float value; 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. This is 108 * the size of the increment between discrete valid values. 109 * @param updatePeriod the smallest time interval, in microseconds, over 110 * which the control can change from one discrete value to the next 111 * during a {@link #shift(float,float,int) shift} 112 * @param initialValue the value that the control starts with when 113 * constructed 114 * @param units the label for the units in which the control's values are 115 * expressed, such as "dB" or "frames per second" 116 * @param minLabel the label for the minimum value, such as "Left" or "Off" 117 * @param midLabel the label for the midpoint value, such as "Center" or 118 * "Default" 119 * @param maxLabel the label for the maximum value, such as "Right" or 120 * "Full" 121 * @throws IllegalArgumentException if {@code minimum} is greater than 122 * {@code maximum} or {@code initialValue} does not fall within the 123 * allowable range 124 */ 125 protected FloatControl(Type type, float minimum, float maximum, 126 float precision, int updatePeriod, float initialValue, 127 String units, String minLabel, String midLabel, String maxLabel) { 128 129 super(type); 130 131 if (minimum > maximum) { 132 throw new IllegalArgumentException("Minimum value " + minimum 133 + " exceeds maximum value " + maximum + "."); 134 } 135 if (initialValue < minimum) { 136 throw new IllegalArgumentException("Initial value " + initialValue 137 + " smaller than allowable minimum value " + minimum + "."); 138 } 139 if (initialValue > maximum) { 140 throw new IllegalArgumentException("Initial value " + initialValue 141 + " exceeds allowable maximum value " + maximum + "."); 142 } 143 144 145 this.minimum = minimum; 146 this.maximum = maximum; 147 148 this.precision = precision; 149 this.updatePeriod = updatePeriod; 150 this.value = initialValue; 151 152 this.units = units; 153 this.minLabel = ( (minLabel == null) ? "" : minLabel); 154 this.midLabel = ( (midLabel == null) ? "" : midLabel); 155 this.maxLabel = ( (maxLabel == null) ? "" : maxLabel); 156 } 157 158 /** 159 * Constructs a new float control object with the given parameters. The 160 * labels for the minimum, maximum, and mid-point values are set to 161 * zero-length strings. 162 * 163 * @param type the kind of control represented by this float control object 164 * @param minimum the smallest value permitted for the control 165 * @param maximum the largest value permitted for the control 166 * @param precision the resolution or granularity of the control. This is 167 * the size of the increment between discrete valid values. 168 * @param updatePeriod the smallest time interval, in microseconds, over 169 * which the control can change from one discrete value to the next 170 * during a {@link #shift(float,float,int) shift} 171 * @param initialValue the value that the control starts with when 172 * constructed 173 * @param units the label for the units in which the control's values are 174 * expressed, such as "dB" or "frames per second" 175 * @throws IllegalArgumentException if {@code minimum} is greater than 176 * {@code maximum} or {@code initialValue} does not fall within the 177 * allowable range 178 */ 179 protected FloatControl(Type type, float minimum, float maximum, 180 float precision, int updatePeriod, float initialValue, String units) { 181 this(type, minimum, maximum, precision, updatePeriod, 182 initialValue, units, "", "", ""); 183 } 184 185 /** 186 * Sets the current value for the control. The default implementation simply 187 * sets the value as indicated. If the value indicated is greater than the 188 * maximum value, or smaller than the minimum value, an 189 * {@code IllegalArgumentException} is thrown. Some controls require that 190 * their line be open before they can be affected by setting a value. 191 * 192 * @param newValue desired new value 193 * @throws IllegalArgumentException if the value indicated does not fall 194 * within the allowable range 195 */ 196 public void setValue(float newValue) { 197 198 if (newValue > maximum) { 199 throw new IllegalArgumentException("Requested value " + newValue + " exceeds allowable maximum value " + maximum + "."); 200 } 201 202 if (newValue < minimum) { 203 throw new IllegalArgumentException("Requested value " + newValue + " smaller than allowable minimum value " + minimum + "."); 204 } 205 206 value = newValue; 207 } 208 209 /** 210 * Obtains this control's current value. 211 * 212 * @return the current value 213 */ 214 public float getValue() { 215 return value; 216 } 217 218 /** 219 * Obtains the maximum value permitted. 220 * 221 * @return the maximum allowable value 222 */ 223 public float getMaximum() { 224 return maximum; 225 } 226 227 /** 228 * Obtains the minimum value permitted. 229 * 230 * @return the minimum allowable value 231 */ 232 public float getMinimum() { 233 return minimum; 234 } 235 236 /** 237 * Obtains the label for the units in which the control's values are 238 * expressed, such as "dB" or "frames per second." 239 * 240 * @return the units label, or a zero-length string if no label 241 */ 242 public String getUnits() { 243 return units; 244 } 245 246 /** 247 * Obtains the label for the minimum value, such as "Left" or "Off". 248 * 249 * @return the minimum value label, or a zero-length string if no label has 250 * been set 251 */ 252 public String getMinLabel() { 253 return minLabel; 254 } 255 256 /** 257 * Obtains the label for the mid-point value, such as "Center" or "Default". 258 * 259 * @return the mid-point value label, or a zero-length string if no label 260 * has been set 261 */ 262 public String getMidLabel() { 263 return midLabel; 264 } 265 266 /** 267 * Obtains the label for the maximum value, such as "Right" or "Full". 268 * 269 * @return the maximum value label, or a zero-length string if no label has 270 * been set 271 */ 272 public String getMaxLabel() { 273 return maxLabel; 274 } 275 276 /** 277 * Obtains the resolution or granularity of the control, in the units that 278 * the control measures. The precision is the size of the increment between 279 * discrete valid values for this control, over the set of supported 280 * floating-point values. 281 * 282 * @return the control's precision 283 */ 284 public float getPrecision() { 285 return precision; 286 } 287 288 /** 289 * Obtains the smallest time interval, in microseconds, over which the 290 * control's value can change during a shift. The update period is the 291 * inverse of the frequency with which the control updates its value during 292 * a shift. If the implementation does not support value shifting over time, 293 * it should set the control's value to the final value immediately and 294 * return -1 from this method. 295 * 296 * @return update period in microseconds, or -1 if shifting over time is 297 * unsupported 298 * @see #shift 299 */ 300 public int getUpdatePeriod() { 301 return updatePeriod; 302 } 303 304 /** 305 * Changes the control value from the initial value to the final value 306 * linearly over the specified time period, specified in microseconds. This 307 * method returns without blocking; it does not wait for the shift to 308 * complete. An implementation should complete the operation within the time 309 * specified. The default implementation simply changes the value to the 310 * final value immediately. 311 * 312 * @param from initial value at the beginning of the shift 313 * @param to final value after the shift 314 * @param microseconds maximum duration of the shift in microseconds 315 * @throws IllegalArgumentException if either {@code from} or {@code to} 316 * value does not fall within the allowable range 317 * @see #getUpdatePeriod 318 */ 319 public void shift(float from, float to, int microseconds) { 320 // test "from" value, "to" value will be tested by setValue() 321 if (from < minimum) { 322 throw new IllegalArgumentException("Requested value " + from 323 + " smaller than allowable minimum value " + minimum + "."); 324 } 325 if (from > maximum) { 326 throw new IllegalArgumentException("Requested value " + from 327 + " exceeds allowable maximum value " + maximum + "."); 328 } 329 setValue(to); 330 } 331 332 /** 333 * Provides a string representation of the control. 334 * 335 * @return a string description 336 */ 337 public String toString() { 338 return new String(getType() + " with current value: " + getValue() + " " + units + 339 " (range: " + minimum + " - " + maximum + ")"); 340 } 341 342 /** 343 * An instance of the {@code FloatControl.Type} inner class identifies one 344 * kind of float control. Static instances are provided for the common 345 * types. 346 * 347 * @author Kara Kytle 348 * @since 1.3 349 */ 350 public static class Type extends Control.Type { 351 352 /** 353 * Represents a control for the overall gain on a line. 354 * <p> 355 * Gain is a quantity in decibels (dB) that is added to the intrinsic 356 * decibel level of the audio signal--that is, the level of the signal 357 * before it is altered by the gain control. A positive gain amplifies 358 * (boosts) the signal's volume, and a negative gain attenuates(cuts)it. 359 * The gain setting defaults to a value of 0.0 dB, meaning the signal's 360 * loudness is unaffected. Note that gain measures dB, not amplitude. 361 * The relationship between a gain in decibels and the corresponding 362 * linear amplitude multiplier is: 363 * 364 * <CENTER>{@code linearScalar = pow(10.0, gainDB/20.0)}</CENTER> 365 * <p> 366 * The {@code FloatControl} class has methods to impose a maximum and 367 * minimum allowable value for gain. However, because an audio signal 368 * might already be at a high amplitude, the maximum setting does not 369 * guarantee that the signal will be undistorted when the gain is 370 * applied to it (unless the maximum is zero or negative). To avoid 371 * numeric overflow from excessively large gain settings, a gain control 372 * can implement clipping, meaning that the signal's amplitude will be 373 * limited to the maximum value representable by its audio format, 374 * instead of wrapping around. 375 * <p> 376 * These comments apply to gain controls in general, not just master 377 * gain controls. A line can have more than one gain control. For 378 * example, a mixer (which is itself a line) might have a master gain 379 * control, an auxiliary return control, a reverb return control, and, 380 * on each of its source lines, an individual aux send and reverb send. 381 * 382 * @see #AUX_SEND 383 * @see #AUX_RETURN 384 * @see #REVERB_SEND 385 * @see #REVERB_RETURN 386 * @see #VOLUME 387 */ 388 public static final Type MASTER_GAIN = new Type("Master Gain"); 389 390 /** 391 * Represents a control for the auxiliary send gain on a line. 392 * 393 * @see #MASTER_GAIN 394 * @see #AUX_RETURN 395 */ 396 public static final Type AUX_SEND = new Type("AUX Send"); 397 398 /** 399 * Represents a control for the auxiliary return gain on a line. 400 * 401 * @see #MASTER_GAIN 402 * @see #AUX_SEND 403 */ 404 public static final Type AUX_RETURN = new Type("AUX Return"); 405 406 /** 407 * Represents a control for the pre-reverb gain on a line. This control 408 * may be used to affect how much of a line's signal is directed to a 409 * mixer's internal reverberation unit. 410 * 411 * @see #MASTER_GAIN 412 * @see #REVERB_RETURN 413 * @see EnumControl.Type#REVERB 414 */ 415 public static final Type REVERB_SEND = new Type("Reverb Send"); 416 417 /** 418 * Represents a control for the post-reverb gain on a line. This control 419 * may be used to control the relative amplitude of the signal returned 420 * from an internal reverberation unit. 421 * 422 * @see #MASTER_GAIN 423 * @see #REVERB_SEND 424 */ 425 public static final Type REVERB_RETURN = new Type("Reverb Return"); 426 427 /** 428 * Represents a control for the volume on a line. 429 */ 430 /* 431 * $$kk: 08.30.99: ISSUE: what units? linear or dB? 432 */ 433 public static final Type VOLUME = new Type("Volume"); 434 435 /** 436 * Represents a control for the relative pan (left-right positioning) of 437 * the signal. The signal may be mono; the pan setting affects how it is 438 * distributed by the mixer in a stereo mix. The valid range of values 439 * is -1.0 (left channel only) to 1.0 (right channel only). The default 440 * is 0.0 (centered). 441 * 442 * @see #BALANCE 443 */ 444 public static final Type PAN = new Type("Pan"); 445 446 /** 447 * Represents a control for the relative balance of a stereo signal 448 * between two stereo speakers. The valid range of values is -1.0 (left 449 * channel only) to 1.0 (right channel only). The default is 0.0 450 * (centered). 451 * 452 * @see #PAN 453 */ 454 public static final Type BALANCE = new Type("Balance"); 455 456 /** 457 * Represents a control that changes the sample rate of audio playback. 458 * The net effect of changing the sample rate depends on the 459 * relationship between the media's natural rate and the rate that is 460 * set via this control. The natural rate is the sample rate that is 461 * specified in the data line's {@code AudioFormat} object. For example, 462 * if the natural rate of the media is 11025 samples per second and the 463 * sample rate is set to 22050 samples per second, the media will play 464 * back at twice the normal speed. 465 * <p> 466 * Changing the sample rate with this control does not affect the data 467 * line's audio format. Also note that whenever you change a sound's 468 * sample rate, a change in the sound's pitch results. For example, 469 * doubling the sample rate has the effect of doubling the frequencies 470 * in the sound's spectrum, which raises the pitch by an octave. 471 */ 472 public static final Type SAMPLE_RATE = new Type("Sample Rate"); 473 474 /** 475 * Constructs a new float control type. 476 * 477 * @param name the name of the new float control type 478 */ 479 protected Type(final String name) { 480 super(name); 481 } 482 } 483 } |