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