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