001: /*
002: * $RCSfile: AudioDevice3DL2.java,v $
003: *
004: * Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.5 $
028: * $Date: 2008/02/28 20:17:19 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: /**
035: * Extends AudioDevice3D to include reverb and environmental audio parameters
036: * that are defined in the MIDI Manufactures' Association Interactive Audio
037: * Special Interest Group (MMA IASIG) Level 2 Specification.
038: *<P>
039: * The reverberation methods of AudioDevice3DL2 interface augment the
040: * reverberation methods defined in AudioDevice3D.
041: *<P>
042: * The intent is for this interface to be implemented by AudioDevice Driver
043: * developers using a software or hardware sound engine of their choice.
044: *<P>
045: * Methods in this interface provide the Java3D Core a generic way to
046: * set and query the audio device the application has chosen audio rendering
047: * to be performed on.
048: *<P>
049: * The non-query methods of this interface should only be called by
050: * an application if the AudioDevice instance
051: * is not referenced by any PhysicalEnvironment
052: * explicitly with .setAudioDevice() or implicitly through Universe
053: * utility method in which case these are called by Core Java 3D
054: * Sound classes and Sound Scheduler thread(s).
055: *<P>
056: * After the application chooses the AudioDevice3DL2 implementation
057: * that Java3D sound is to be rendered on, the Java 3D Sound Scheduler
058: * will call these methods for all active sounds to render them on the
059: * audio device.
060: *<P>
061: * The AudioDevice3DL2 methods should not be call by any application if the
062: * audio device is associated with a Physical Environment and thus used by
063: * Java3D Core.
064: *<P>
065: * Filtering for this extended AudioDevice interface is defined uniformly as
066: * a simple low-pass filter defined by a cutoff frequency. This will allow the
067: * same type of high-frequency attenuation that the MMA IASIG Level 2 filtering
068: * model with its 'reference frequency' and 'attenuation ratio' parameters
069: * affords. Use of a cutoff frequency is consistent with the filtering type
070: * for distance and angular attenuation for ConeSound and AuralAttributes.
071: * The filter methods will likely be overloaded in some future extension of this
072: * interface.
073: *
074: * @see Sound
075: * @see AuralAttributes
076: * @see AudioDevice3D
077: * @since Java 3D 1.3
078: */
079:
080: public interface AudioDevice3DL2 extends AudioDevice3D {
081:
082: /**
083: * Pause audio device engine (thread/server) without closing the device.
084: * Causes all cached sounds to be paused and all streaming sounds to be
085: * stopped.
086: * <P>
087: * This method should NOT be called by any application if the audio device
088: * is associated with a Physical Environment used by Java3D Core.
089: * This method will be implicitly called when View (associated with this
090: * device) is deactivated.
091: */
092: public abstract void pause();
093:
094: /**
095: * Resumes audio device engine (if previously paused) without reinitializing
096: * the device.
097: * Causes all paused cached sounds to be resumed and all streaming sounds
098: * restarted.
099: * <P>
100: * This method should NOT be called by any application if the audio device
101: * is associated with a Physical Environment used by Java3D Core.
102: * This method will be implicitly called when View (associated with this
103: * device) is actived.
104: */
105: public abstract void resume();
106:
107: /**
108: * Set overall gain control of all sounds playing on the audio device.
109: * Default: 1.0f = no attenuation.
110: * <P>
111: * This method should NOT be called by any application if the audio device
112: * is associated with a Physical Environment used by Java3D Core.
113: * @param scaleFactor scale factor applied to calculated amplitudes for
114: * all sounds playing on this device
115: */
116: public abstract void setGain(float scaleFactor);
117:
118: /**
119: * Set scale factor applied to sample playback rate for a particular sound
120: * associated with the audio device.
121: * Changing the device sample rate affects both the pitch and speed.
122: * This scale factor is applied to ALL sound types.
123: * Changes (scales) the playback rate of a sound independent of
124: * Doppler rate changes.
125: * Default: 1.0f = original sample rate is unchanged
126: * <P>
127: * This method should NOT be called by any application if the audio device
128: * is associated with a Physical Environment used by Java3D Core.
129: * @param sampleId device specific reference number to device driver sample
130: * @param scaleFactor non-negative factor applied to calculated
131: * amplitudes for all sounds playing on this device
132: */
133: public abstract void setRateScaleFactor(int sampleId,
134: float scaleFactor);
135:
136: /**
137: * Set late reflection (referred to as 'reverb') attenuation.
138: * This scale factor is applied to iterative, indistinguishable
139: * late reflections that constitute the tail of reverberated sound in
140: * the aural environment.
141: * This parameter, along with the early reflection coefficient, defines
142: * the reflective/absorptive characteristic of the surfaces in the
143: * current listening region.
144: * A coefficient value of 0 disables reverberation.
145: * Valid values of parameters range from 0.0 to 1.0.
146: * Default: 0.0f.
147: * <P>
148: * A full description of this parameter and how it is used is in
149: * the documentation for the AuralAttributes class.
150: * <P>
151: * This method should NOT be called by any application if the audio device
152: * is associated with a Physical Environment used by Java3D Core.
153: * @param coefficient late reflection attenuation factor
154: * @see AuralAttributes#setReverbCoefficient
155: */
156: public abstract void setReverbCoefficient(float coefficient);
157:
158: /**
159: * Sets the early reflection delay time.
160: * In this form, the parameter specifies the delay time between each order
161: * of reflection (while reverberation is being rendered) explicitly given
162: * in milliseconds.
163: * Valid values are non-negative floats.
164: * There may be limitations imposed by the device on how small or large this
165: * value can be made.
166: * A value of 0.0 would result in early reflections being added as soon as
167: * possible after the sound begins.
168: * Default = 20.0 milliseconds.
169: * <P>
170: * A full description of this parameter and how it is used is in
171: * the documentation for the AuralAttributes class.
172: * <P>
173: * This method should NOT be called by any application if the audio device
174: * is associated with a Physical Environment used by Java3D Core.
175: * @param reflectionDelay time between each order of early reflection
176: * @see AuralAttributes#setReflectionDelay
177: */
178: public abstract void setReflectionDelay(float reflectionDelay);
179:
180: /**
181: * Set reverb decay time.
182: * Defines the reverberation decay curve.
183: * Default: 1000.0 milliseconds.
184: * <P>
185: * A full description of this parameter and how it is used is in
186: * the documentation for the AuralAttributes class.
187: * <P>
188: * This method should NOT be called by any application if the audio device
189: * is associated with a Physical Environment used by Java3D Core.
190: * @param time decay time in milliseconds
191: * @see AuralAttributes#setDecayTime
192: */
193: public abstract void setDecayTime(float time);
194:
195: /**
196: * Set reverb decay filter.
197: * This provides for frequencies above the given cutoff frequency to be
198: * attenuated during reverb decay at a different rate than frequencies
199: * below this value. Thus, defining a different reverb decay curve for
200: * frequencies above the cutoff value.
201: * Default: 1.0 decay is uniform for all frequencies.
202: * <P>
203: * There is no corresponding Core AuralAttributes method at this time.
204: * Until high frequency attenuation is supported by new Core API,
205: * this will be set by the Core with the value 1.0.
206: * It is highly recommended that this method should NOT be
207: * called by any application if the audio device is associated with
208: * a Physical Environment used by Java3D Core.
209: * @param frequencyCutoff value of frequencies in Hertz above which a
210: * low-pass filter is applied.
211: * @see AuralAttributes#setDecayFilter
212: */
213: public abstract void setDecayFilter(float frequencyCutoff);
214:
215: /**
216: * Set reverb diffusion.
217: * This defines the echo dispersement (also referred to as 'echo density').
218: * The value of this reverb parameter is expressed as a percent of the
219: * audio device's minimum-to-maximum values.
220: * Default: 1.0f - maximum diffusion on device.
221: * <P>
222: * A full description of this parameter and how it is used is in
223: * the documentation for the AuralAttributes class.
224: * <P>
225: * This method should NOT be called by any application if the audio device
226: * is associated with a Physical Environment used by Java3D Core.
227: * @param diffusion percentage expressed within the range of 0.0 and 1.0
228: * @see AuralAttributes#setDiffusion
229: */
230: public abstract void setDiffusion(float diffusion);
231:
232: /**
233: * Set reverb density.
234: * This defines the modal density (also referred to as 'spectral
235: * coloration').
236: * The value of this parameter is expressed as a percent of the audio
237: * device's minimum-to-maximum values for this reverb parameter.
238: * Default: 1.0f - maximum density on device.
239: * <P>
240: * A full description of this parameter and how it is used is in
241: * the documentation for the AuralAttributes class.
242: * <P>
243: * This method should NOT be called by any application if the audio device
244: * is associated with a Physical Environment used by Java3D Core.
245: * @param density reverb density expressed as a percentage,
246: * within the range of 0.0 and 1.0
247: * @see AuralAttributes#setDensity
248: */
249: public abstract void setDensity(float density);
250:
251: /**
252: * Set the obstruction gain control. This method allows for attenuating
253: * sound waves traveling between the sound source and the listener
254: * obstructed by objects. Direct sound signals/waves for obstructed sound
255: * source are attenuated but not indirect (reflected) waves.
256: * Default: 1.0 - gain is not attenuated; obstruction is not occurring.
257: * <P>
258: * There is no corresponding Core AuralAttributes method at this time.
259: * Even so, this method should NOT be called by any application if the
260: * audio device is associated with a Physical Environment used by Java3D
261: * Core.
262: * @param sampleId device specific reference number to device driver sample
263: * @param scaleFactor non-negative factor applied to direct sound gain
264: */
265: public abstract void setObstructionGain(int sampleId,
266: float scaleFactor);
267:
268: /**
269: * Set the obstruction filter control.
270: * This provides for frequencies above the given cutoff frequency
271: * to be attenuated, during while the gain of an obstruction signal
272: * is being calculated, at a different rate than frequencies
273: * below this value.
274: * Default: 1.0 - filtering is uniform for all frequencies.
275: * <P>
276: * There is no corresponding Core AuralAttributes method at this time.
277: * Until high frequency attenuation is supported by new Core API
278: * this will be set by the Core with the value 1.0.
279: * It is highly recommended that this method should NOT be
280: * called by any application if the audio device is associated with
281: * a Physical Environment used by Java3D Core.
282: * @param frequencyCutoff value of frequencies in Hertz above which a
283: * low-pass filter is applied.
284: */
285:
286: public abstract void setObstructionFilter(int sampleId,
287: float frequencyCutoff);
288:
289: /**
290: * Set the occlusion gain control. This method allows for attenuating
291: * sound waves traveling between the sound source and the listener
292: * occluded by objects. Both direct and indirect sound signals/waves
293: * for occluded sound sources are attenuated.
294: * Default: 1.0 - gain is not attenuated; occlusion is not occurring.
295: * <P>
296: * There is no corresponding Core AuralAttributes method at this time.
297: * Even so, this method should NOT be called by any application if the
298: * audio device is associated with a Physical Environment used by Java3D
299: * Core.
300: * @param sampleId device specific reference number to device driver sample
301: * @param scaleFactor non-negative factor applied to direct sound gain
302: */
303: public abstract void setOcclusionGain(int sampleId,
304: float scaleFactor);
305:
306: /**
307: * Set the occlusion filter control.
308: * This provides for frequencies above the given cutoff frequency
309: * to be attenuated, during while the gain of an occluded signal
310: * is being calculated, at a different rate than frequencies below
311: * this value.
312: * Default: 1.0 - filtering is uniform for all frequencies.
313: * <P>
314: * There is no corresponding Core AuralAttributes method at this time.
315: * Until high frequency attenuation is supported by new Core API
316: * this will be set by the Core with the value 1.0.
317: * It is highly recommended that this method should NOT be
318: * called by any application if the audio device is associated with
319: * a Physical Environment used by Java3D Core.
320: * @param frequencyCutoff value of frequencies in Hertz above which a
321: * low-pass filter is applied.
322: */
323: public abstract void setOcclusionFilter(int sampleId,
324: float frequencyCutoff);
325: }
|