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
26package 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 */
127public 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}
290