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
  79  *     <th>Decay Time (ms)
  80  *     <th>Late Intensity (dB)
  81  *     <th>Late Delay (ms)
  82  *     <th>Early Intensity (dB)
  83  *     <th>Early Delay(ms)
  84  * </thead>
  85  * <tbody>
  86  *   <tr>
  87  *     <td>Cavern
  88  *     <td>2250
  89  *     <td>-2.0
  90  *     <td>41.3
  91  *     <td>-1.4
  92  *     <td>10.3
  93  *   <tr>
  94  *     <td>Dungeon
  95  *     <td>1600
  96  *     <td>-1.0
  97  *     <td>10.3
  98  *     <td>-0.7
  99  *     <td>2.6
 100  *   <tr>
 101  *     <td>Garage
 102  *     <td>900
 103  *     <td>-6.0
 104  *     <td>14.7
 105  *     <td>-4.0
 106  *     <td>3.9
 107  *   <tr>
 108  *     <td>Acoustic Lab
 109  *     <td>280
 110  *     <td>-3.0
 111  *     <td>8.0
 112  *     <td>-2.0
 113  *     <td>2.0
 114  *   <tr>
 115  *     <td>Closet
 116  *     <td>150
 117  *     <td>-10.0
 118  *     <td>2.5
 119  *     <td>-7.0
 120  *     <td>0.6
 121  * </tbody>
 122  * </table>
 123  *
 124  * @author Kara Kytle
 125  * @since 1.3
 126  */
 127 public class ReverbType {
 128 
 129     /**
 130      * Descriptive name of the reverb type.
 131      */
 132     private final String name;
 133 
 134     /**
 135      * Early reflection delay in microseconds.
 136      */
 137     private final int earlyReflectionDelay;
 138 
 139     /**
 140      * Early reflection intensity.
 141      */
 142     private final float earlyReflectionIntensity;
 143 
 144     /**
 145      * Late reflection delay in microseconds.
 146      */
 147     private final int lateReflectionDelay;
 148 
 149     /**
 150      * Late reflection intensity.
 151      */
 152     private final float lateReflectionIntensity;
 153 
 154     /**
 155      * Total decay time.
 156      */
 157     private final int decayTime;
 158 
 159     /**
 160      * Constructs a new reverb type that has the specified reverberation
 161      * parameter values.
 162      *
 163      * @param  name the name of the new reverb type, or a zero-length
 164      *         {@code String}
 165      * @param  earlyReflectionDelay the new type's early reflection delay time
 166      *         in microseconds
 167      * @param  earlyReflectionIntensity the new type's early reflection
 168      *         intensity in dB
 169      * @param  lateReflectionDelay the new type's late reflection delay time in
 170      *         microseconds
 171      * @param  lateReflectionIntensity the new type's late reflection intensity
 172      *         in dB
 173      * @param  decayTime the new type's decay time in microseconds
 174      */
 175     protected ReverbType(String name, int earlyReflectionDelay, float earlyReflectionIntensity, int lateReflectionDelay, float lateReflectionIntensity, int decayTime) {
 176 
 177         this.name = name;
 178         this.earlyReflectionDelay = earlyReflectionDelay;
 179         this.earlyReflectionIntensity = earlyReflectionIntensity;
 180         this.lateReflectionDelay = lateReflectionDelay;
 181         this.lateReflectionIntensity = lateReflectionIntensity;
 182         this.decayTime = decayTime;
 183     }
 184 
 185     /**
 186      * Obtains the name of this reverb type.
 187      *
 188      * @return the name of this reverb type
 189      * @since 1.5
 190      */
 191     public String getName() {
 192         return name;
 193     }
 194 
 195     /**
 196      * Returns the early reflection delay time in microseconds. This is the
 197      * amount of time between when the direct signal is heard and when the first
 198      * early reflections are heard.
 199      *
 200      * @return early reflection delay time for this reverb type, in microseconds
 201      */
 202     public final int getEarlyReflectionDelay() {
 203         return earlyReflectionDelay;
 204     }
 205 
 206     /**
 207      * Returns the early reflection intensity in decibels. This is the amplitude
 208      * attenuation of the first early reflections relative to the direct signal.
 209      *
 210      * @return early reflection intensity for this reverb type, in dB
 211      */
 212     public final float getEarlyReflectionIntensity() {
 213         return earlyReflectionIntensity;
 214     }
 215 
 216     /**
 217      * Returns the late reflection delay time in microseconds. This is the
 218      * amount of time between when the first early reflections are heard and
 219      * when the first late reflections are heard.
 220      *
 221      * @return late reflection delay time for this reverb type, in microseconds
 222      */
 223     public final int getLateReflectionDelay() {
 224         return lateReflectionDelay;
 225     }
 226 
 227     /**
 228      * Returns the late reflection intensity in decibels. This is the amplitude
 229      * attenuation of the first late reflections relative to the direct signal.
 230      *
 231      * @return late reflection intensity for this reverb type, in dB
 232      */
 233     public final float getLateReflectionIntensity() {
 234         return lateReflectionIntensity;
 235     }
 236 
 237     /**
 238      * Obtains the decay time, which is the amount of time over which the late
 239      * reflections attenuate to effective zero. The effective zero value is
 240      * implementation-dependent.
 241      *
 242      * @return the decay time of the late reflections, in microseconds
 243      */
 244     public final int getDecayTime() {
 245         return decayTime;
 246     }
 247 
 248     /**
 249      * Indicates whether the specified object is equal to this reverb type,
 250      * returning {@code true} if the objects are the same.
 251      *
 252      * @param  obj the reference object with which to compare
 253      * @return {@code true} if the specified object is equal to this reverb
 254      *         type; {@code false} otherwise
 255      */
 256     @Override
 257     public final boolean equals(Object obj) {
 258         return super.equals(obj);
 259     }
 260 
 261     /**
 262      * Returns a hash code value for this reverb type.
 263      *
 264      * @return a hash code value for this reverb type
 265      */
 266     @Override
 267     public final int hashCode() {
 268         return super.hashCode();
 269     }
 270 
 271     /**
 272      * Provides a {@code String} representation of the reverb type, including
 273      * its name and its parameter settings. The exact contents of the string may
 274      * vary between implementations of Java Sound.
 275      *
 276      * @return reverberation type name and description
 277      */
 278     @Override
 279     public final String toString() {
 280 
 281         //$$fb2001-07-20: fix for bug 4385060: The "name" attribute of class "ReverbType" is not accessible.
 282         //return (super.toString() + ", early reflection delay " + earlyReflectionDelay +
 283         return (name + ", early reflection delay " + earlyReflectionDelay +
 284                 " ns, early reflection intensity " + earlyReflectionIntensity +
 285                 " dB, late deflection delay " + lateReflectionDelay +
 286                 " ns, late reflection intensity " + lateReflectionIntensity +
 287                 " dB, decay time " +  decayTime);
 288     }
 289 }