001 /*
002 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sound.sampled;
027
028 /**
029 * The <code>ReverbType</code> class provides methods for
030 * accessing various reverberation settings to be applied to
031 * an audio signal.
032 * <p>
033 * Reverberation simulates the reflection of sound off of
034 * the walls, ceiling, and floor of a room. Depending on
035 * the size of the room, and how absorbent or reflective the materials in the
036 * room's surfaces are, the sound might bounce around for a
037 * long time before dying away.
038 * <p>
039 * The reverberation parameters provided by <code>ReverbType</code> consist
040 * of the delay time and intensity of early reflections, the delay time and
041 * intensity of late reflections, and an overall decay time.
042 * Early reflections are the initial individual low-order reflections of the
043 * direct signal off the surfaces in the room.
044 * The late Relections are the dense, high-order reflections that characterize
045 * the room's reverberation.
046 * The delay times for the start of these two reflection types give the listener
047 * a sense of the overall size and complexity of the room's shape and contents.
048 * The larger the room, the longer the reflection delay times.
049 * The early and late reflections' intensities define the gain (in decibels) of the reflected
050 * signals as compared to the direct signal. These intensities give the
051 * listener an impression of the absorptive nature of the surfaces and objects
052 * in the room.
053 * The decay time defines how long the reverberation takes to exponentially
054 * decay until it is no longer perceptible ("effective zero").
055 * The larger and less absorbent the surfaces, the longer the decay time.
056 * <p>
057 * The set of parameters defined here may not include all aspects of reverberation
058 * as specified by some systems. For example, the Midi Manufacturer's Association
059 * (MMA) has an Interactive Audio Special Interest Group (IASIG), which has a
060 * 3-D Working Group that has defined a Level 2 Spec (I3DL2). I3DL2
061 * supports filtering of reverberation and
062 * control of reverb density. These properties are not included in the JavaSound 1.0
063 * definition of a reverb control. In such a case, the implementing system
064 * should either extend the defined reverb control to include additional
065 * parameters, or else interpret the system's additional capabilities in a way that fits
066 * the model described here.
067 * <p>
068 * If implementing JavaSound on a I3DL2-compliant device:
069 * <ul>
070 * <li>Filtering is disabled (high-frequency attenuations are set to 0.0 dB)
071 * <li>Density parameters are set to midway between minimum and maximum
072 * </ul>
073 * <p>
074 * The following table shows what parameter values an implementation might use for a
075 * representative set of reverberation settings.
076 * <p>
077 *
078 * <b>Reverberation Types and Parameters</b>
079 * <p>
080 * <table border=1 cellpadding=5 summary="reverb types and params: decay time, late intensity, late delay, early intensity, and early delay">
081 *
082 * <tr>
083 * <th>Type</th>
084 * <th>Decay Time (ms)</th>
085 * <th>Late Intensity (dB)</th>
086 * <th>Late Delay (ms)</th>
087 * <th>Early Intensity (dB)</th>
088 * <th>Early Delay(ms)</th>
089 * </tr>
090 *
091 * <tr>
092 * <td>Cavern</td>
093 * <td>2250</td>
094 * <td>-2.0</td>
095 * <td>41.3</td>
096 * <td>-1.4</td>
097 * <td>10.3</td>
098 * </tr>
099 *
100 * <tr>
101 * <td>Dungeon</td>
102 * <td>1600</td>
103 * <td>-1.0</td>
104 * <td>10.3</td>
105 * <td>-0.7</td>
106 * <td>2.6</td>
107 * </tr>
108 *
109 * <tr>
110 * <td>Garage</td>
111 * <td>900</td>
112 * <td>-6.0</td>
113 * <td>14.7</td>
114 * <td>-4.0</td>
115 * <td>3.9</td>
116 * </tr>
117 *
118 * <tr>
119 * <td>Acoustic Lab</td>
120 * <td>280</td>
121 * <td>-3.0</td>
122 * <td>8.0</td>
123 * <td>-2.0</td>
124 * <td>2.0</td>
125 * </tr>
126 *
127 * <tr>
128 * <td>Closet</td>
129 * <td>150</td>
130 * <td>-10.0</td>
131 * <td>2.5</td>
132 * <td>-7.0</td>
133 * <td>0.6</td>
134 * </tr>
135 *
136 * </table>
137 *
138 * @author Kara Kytle
139 * @version 1.20, 07/05/05
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 * Constructs a new reverb type that has the specified reverberation
176 * parameter values.
177 * @param name the name of the new reverb type, or a zero-length <code>String</code>
178 * @param earlyReflectionDelay the new type's early reflection delay time in microseconds
179 * @param earlyReflectionIntensity the new type's early reflection intensity in dB
180 * @param lateReflectionDelay the new type's late reflection delay time in microseconds
181 * @param lateReflectionIntensity the new type's late reflection intensity in dB
182 * @param decayTime the new type's decay time in microseconds
183 */
184 protected ReverbType(String name, int earlyReflectionDelay,
185 float earlyReflectionIntensity, int lateReflectionDelay,
186 float lateReflectionIntensity, int decayTime) {
187
188 this .name = name;
189 this .earlyReflectionDelay = earlyReflectionDelay;
190 this .earlyReflectionIntensity = earlyReflectionIntensity;
191 this .lateReflectionDelay = lateReflectionDelay;
192 this .lateReflectionIntensity = lateReflectionIntensity;
193 this .decayTime = decayTime;
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 * Returns the early reflection delay time in microseconds.
207 * This is the amount of time between when the direct signal is
208 * heard and when the first early reflections are heard.
209 * @return early reflection delay time for this reverb type, in microseconds
210 */
211 public final int getEarlyReflectionDelay() {
212 return earlyReflectionDelay;
213 }
214
215 /**
216 * Returns the early reflection intensity in decibels.
217 * This is the amplitude attenuation of the first early reflections
218 * relative to the direct signal.
219 * @return early reflection intensity for this reverb type, in dB
220 */
221 public final float getEarlyReflectionIntensity() {
222 return earlyReflectionIntensity;
223 }
224
225 /**
226 * Returns the late reflection delay time in microseconds.
227 * This is the amount of time between when the first early reflections
228 * are heard and when the first late reflections are heard.
229 * @return late reflection delay time for this reverb type, in microseconds
230 */
231 public final int getLateReflectionDelay() {
232 return lateReflectionDelay;
233 }
234
235 /**
236 * Returns the late reflection intensity in decibels.
237 * This is the amplitude attenuation of the first late reflections
238 * relative to the direct signal.
239 * @return late reflection intensity for this reverb type, in dB
240 */
241 public final float getLateReflectionIntensity() {
242 return lateReflectionIntensity;
243 }
244
245 /**
246 * Obtains the decay time, which is the amount of time over which the
247 * late reflections attenuate to effective zero. The effective zero
248 * value is implementation-dependent.
249 * @return the decay time of the late reflections, in microseconds
250 */
251 public final int getDecayTime() {
252 return decayTime;
253 }
254
255 /**
256 * Indicates whether the specified object is equal to this reverb type,
257 * returning <code>true</code> if the objects are identical.
258 * @param obj the reference object with which to compare
259 * @return <code>true</code> if this reverb type is the same as
260 * <code>obj</code>; <code>false</code> otherwise
261 */
262 public final boolean equals(Object obj) {
263 return super .equals(obj);
264 }
265
266 /**
267 * Finalizes the hashcode method.
268 */
269 public final int hashCode() {
270 return super .hashCode();
271 }
272
273 /**
274 * Provides a <code>String</code> representation of the reverb type,
275 * including its name and its parameter settings.
276 * The exact contents of the string may vary between implementations of
277 * Java Sound.
278 * @return reverberation type name and description
279 */
280 public final String toString() {
281
282 //$$fb2001-07-20: fix for bug 4385060: The "name" attribute of class "ReverbType" is not accessible.
283 //return (super.toString() + ", early reflection delay " + earlyReflectionDelay +
284 return (name + ", early reflection delay "
285 + earlyReflectionDelay
286 + " ns, early reflection intensity "
287 + earlyReflectionIntensity
288 + " dB, late deflection delay " + lateReflectionDelay
289 + " ns, late reflection intensity "
290 + lateReflectionIntensity + " dB, decay time " + decayTime);
291 }
292
293 } // class ReverbType
|