J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Copyright 1999-2003 Sun Microsystems, Inc. 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. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | |
| 26 | package javax.sound.sampled; |
| 27 | |
| 28 | |
| 29 | /** |
| 30 | * The <code>ReverbType</code> class provides methods for |
| 31 | * accessing various reverberation settings to be applied to |
| 32 | * an audio signal. |
| 33 | * <p> |
| 34 | * Reverberation simulates the reflection of sound off of |
| 35 | * the walls, ceiling, and floor of a room. Depending on |
| 36 | * the size of the room, and how absorbent or reflective the materials in the |
| 37 | * room's surfaces are, the sound might bounce around for a |
| 38 | * long time before dying away. |
| 39 | * <p> |
| 40 | * The reverberation parameters provided by <code>ReverbType</code> consist |
| 41 | * of the delay time and intensity of early reflections, the delay time and |
| 42 | * intensity of late reflections, and an overall decay time. |
| 43 | * Early reflections are the initial individual low-order reflections of the |
| 44 | * direct signal off the surfaces in the room. |
| 45 | * The late Relections are the dense, high-order reflections that characterize |
| 46 | * the room's reverberation. |
| 47 | * The delay times for the start of these two reflection types give the listener |
| 48 | * a sense of the overall size and complexity of the room's shape and contents. |
| 49 | * The larger the room, the longer the reflection delay times. |
| 50 | * The early and late reflections' intensities define the gain (in decibels) of the reflected |
| 51 | * signals as compared to the direct signal. These intensities give the |
| 52 | * listener an impression of the absorptive nature of the surfaces and objects |
| 53 | * in the room. |
| 54 | * The decay time defines how long the reverberation takes to exponentially |
| 55 | * decay until it is no longer perceptible ("effective zero"). |
| 56 | * The larger and less absorbent the surfaces, the longer the decay time. |
| 57 | * <p> |
| 58 | * The set of parameters defined here may not include all aspects of reverberation |
| 59 | * as specified by some systems. For example, the Midi Manufacturer's Association |
| 60 | * (MMA) has an Interactive Audio Special Interest Group (IASIG), which has a |
| 61 | * 3-D Working Group that has defined a Level 2 Spec (I3DL2). I3DL2 |
| 62 | * supports filtering of reverberation and |
| 63 | * control of reverb density. These properties are not included in the JavaSound 1.0 |
| 64 | * definition of a reverb control. In such a case, the implementing system |
| 65 | * should either extend the defined reverb control to include additional |
| 66 | * parameters, or else interpret the system's additional capabilities in a way that fits |
| 67 | * the model described here. |
| 68 | * <p> |
| 69 | * If implementing JavaSound on a I3DL2-compliant device: |
| 70 | * <ul> |
| 71 | * <li>Filtering is disabled (high-frequency attenuations are set to 0.0 dB) |
| 72 | * <li>Density parameters are set to midway between minimum and maximum |
| 73 | * </ul> |
| 74 | * <p> |
| 75 | * The following table shows what parameter values an implementation might use for a |
| 76 | * representative set of reverberation settings. |
| 77 | * <p> |
| 78 | * |
| 79 | * <b>Reverberation Types and Parameters</b> |
| 80 | * <p> |
| 81 | * <table border=1 cellpadding=5 summary="reverb types and params: decay time, late intensity, late delay, early intensity, and early delay"> |
| 82 | * |
| 83 | * <tr> |
| 84 | * <th>Type</th> |
| 85 | * <th>Decay Time (ms)</th> |
| 86 | * <th>Late Intensity (dB)</th> |
| 87 | * <th>Late Delay (ms)</th> |
| 88 | * <th>Early Intensity (dB)</th> |
| 89 | * <th>Early Delay(ms)</th> |
| 90 | * </tr> |
| 91 | * |
| 92 | * <tr> |
| 93 | * <td>Cavern</td> |
| 94 | * <td>2250</td> |
| 95 | * <td>-2.0</td> |
| 96 | * <td>41.3</td> |
| 97 | * <td>-1.4</td> |
| 98 | * <td>10.3</td> |
| 99 | * </tr> |
| 100 | * |
| 101 | * <tr> |
| 102 | * <td>Dungeon</td> |
| 103 | * <td>1600</td> |
| 104 | * <td>-1.0</td> |
| 105 | * <td>10.3</td> |
| 106 | * <td>-0.7</td> |
| 107 | * <td>2.6</td> |
| 108 | * </tr> |
| 109 | * |
| 110 | * <tr> |
| 111 | * <td>Garage</td> |
| 112 | * <td>900</td> |
| 113 | * <td>-6.0</td> |
| 114 | * <td>14.7</td> |
| 115 | * <td>-4.0</td> |
| 116 | * <td>3.9</td> |
| 117 | * </tr> |
| 118 | * |
| 119 | * <tr> |
| 120 | * <td>Acoustic Lab</td> |
| 121 | * <td>280</td> |
| 122 | * <td>-3.0</td> |
| 123 | * <td>8.0</td> |
| 124 | * <td>-2.0</td> |
| 125 | * <td>2.0</td> |
| 126 | * </tr> |
| 127 | * |
| 128 | * <tr> |
| 129 | * <td>Closet</td> |
| 130 | * <td>150</td> |
| 131 | * <td>-10.0</td> |
| 132 | * <td>2.5</td> |
| 133 | * <td>-7.0</td> |
| 134 | * <td>0.6</td> |
| 135 | * </tr> |
| 136 | * |
| 137 | * </table> |
| 138 | * |
| 139 | * @author Kara Kytle |
| 140 | * @since 1.3 |
| 141 | */ |
| 142 | public class ReverbType { |
| 143 | |
| 144 | /** |
| 145 | * Descriptive name of the reverb type.. |
| 146 | */ |
| 147 | private String name; |
| 148 | |
| 149 | /** |
| 150 | * Early reflection delay in microseconds. |
| 151 | */ |
| 152 | private int earlyReflectionDelay; |
| 153 | |
| 154 | /** |
| 155 | * Early reflection intensity. |
| 156 | */ |
| 157 | private float earlyReflectionIntensity; |
| 158 | |
| 159 | /** |
| 160 | * Late reflection delay in microseconds. |
| 161 | */ |
| 162 | private int lateReflectionDelay; |
| 163 | |
| 164 | /** |
| 165 | * Late reflection intensity. |
| 166 | */ |
| 167 | private float lateReflectionIntensity; |
| 168 | |
| 169 | /** |
| 170 | * Total decay time |
| 171 | */ |
| 172 | private int decayTime; |
| 173 | |
| 174 | |
| 175 | /** |
| 176 | * Constructs a new reverb type that has the specified reverberation |
| 177 | * parameter values. |
| 178 | * @param name the name of the new reverb type, or a zero-length <code>String</code> |
| 179 | * @param earlyReflectionDelay the new type's early reflection delay time in microseconds |
| 180 | * @param earlyReflectionIntensity the new type's early reflection intensity in dB |
| 181 | * @param lateReflectionDelay the new type's late reflection delay time in microseconds |
| 182 | * @param lateReflectionIntensity the new type's late reflection intensity in dB |
| 183 | * @param decayTime the new type's decay time in microseconds |
| 184 | */ |
| 185 | protected ReverbType(String name, int earlyReflectionDelay, float earlyReflectionIntensity, int lateReflectionDelay, float lateReflectionIntensity, int decayTime) { |
| 186 | |
| 187 | this.name = name; |
| 188 | this.earlyReflectionDelay = earlyReflectionDelay; |
| 189 | this.earlyReflectionIntensity = earlyReflectionIntensity; |
| 190 | this.lateReflectionDelay = lateReflectionDelay; |
| 191 | this.lateReflectionIntensity = lateReflectionIntensity; |
| 192 | this.decayTime = decayTime; |
| 193 | } |
| 194 | |
| 195 | |
| 196 | /** |
| 197 | * Obtains the name of this reverb type. |
| 198 | * @return the name of this reverb type |
| 199 | * @since 1.5 |
| 200 | */ |
| 201 | public String getName() { |
| 202 | return name; |
| 203 | } |
| 204 | |
| 205 | |
| 206 | /** |
| 207 | * Returns the early reflection delay time in microseconds. |
| 208 | * This is the amount of time between when the direct signal is |
| 209 | * heard and when the first early reflections are heard. |
| 210 | * @return early reflection delay time for this reverb type, in microseconds |
| 211 | */ |
| 212 | public final int getEarlyReflectionDelay() { |
| 213 | return earlyReflectionDelay; |
| 214 | } |
| 215 | |
| 216 | |
| 217 | /** |
| 218 | * Returns the early reflection intensity in decibels. |
| 219 | * This is the amplitude attenuation of the first early reflections |
| 220 | * relative to the direct signal. |
| 221 | * @return early reflection intensity for this reverb type, in dB |
| 222 | */ |
| 223 | public final float getEarlyReflectionIntensity() { |
| 224 | return earlyReflectionIntensity; |
| 225 | } |
| 226 | |
| 227 | |
| 228 | /** |
| 229 | * Returns the late reflection delay time in microseconds. |
| 230 | * This is the amount of time between when the first early reflections |
| 231 | * are heard and when the first late reflections are heard. |
| 232 | * @return late reflection delay time for this reverb type, in microseconds |
| 233 | */ |
| 234 | public final int getLateReflectionDelay() { |
| 235 | return lateReflectionDelay; |
| 236 | } |
| 237 | |
| 238 | |
| 239 | /** |
| 240 | * Returns the late reflection intensity in decibels. |
| 241 | * This is the amplitude attenuation of the first late reflections |
| 242 | * relative to the direct signal. |
| 243 | * @return late reflection intensity for this reverb type, in dB |
| 244 | */ |
| 245 | public final float getLateReflectionIntensity() { |
| 246 | return lateReflectionIntensity; |
| 247 | } |
| 248 | |
| 249 | |
| 250 | /** |
| 251 | * Obtains the decay time, which is the amount of time over which the |
| 252 | * late reflections attenuate to effective zero. The effective zero |
| 253 | * value is implementation-dependent. |
| 254 | * @return the decay time of the late reflections, in microseconds |
| 255 | */ |
| 256 | public final int getDecayTime() { |
| 257 | return decayTime; |
| 258 | } |
| 259 | |
| 260 | |
| 261 | /** |
| 262 | * Indicates whether the specified object is equal to this reverb type, |
| 263 | * returning <code>true</code> if the objects are identical. |
| 264 | * @param obj the reference object with which to compare |
| 265 | * @return <code>true</code> if this reverb type is the same as |
| 266 | * <code>obj</code>; <code>false</code> otherwise |
| 267 | */ |
| 268 | public final boolean equals(Object obj) { |
| 269 | return super.equals(obj); |
| 270 | } |
| 271 | |
| 272 | |
| 273 | /** |
| 274 | * Finalizes the hashcode method. |
| 275 | */ |
| 276 | public final int hashCode() { |
| 277 | return super.hashCode(); |
| 278 | } |
| 279 | |
| 280 | |
| 281 | /** |
| 282 | * Provides a <code>String</code> representation of the reverb type, |
| 283 | * including its name and its parameter settings. |
| 284 | * The exact contents of the string may vary between implementations of |
| 285 | * Java Sound. |
| 286 | * @return reverberation type name and description |
| 287 | */ |
| 288 | public final String toString() { |
| 289 | |
| 290 | //$$fb2001-07-20: fix for bug 4385060: The "name" attribute of class "ReverbType" is not accessible. |
| 291 | //return (super.toString() + ", early reflection delay " + earlyReflectionDelay + |
| 292 | return (name + ", early reflection delay " + earlyReflectionDelay + |
| 293 | " ns, early reflection intensity " + earlyReflectionIntensity + |
| 294 | " dB, late deflection delay " + lateReflectionDelay + |
| 295 | " ns, late reflection intensity " + lateReflectionIntensity + |
| 296 | " dB, decay time " + decayTime); |
| 297 | } |
| 298 | |
| 299 | } // class ReverbType |