001: /*
002: * $RCSfile: AudioDevice.java,v $
003: *
004: * Copyright 1997-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: * The AudioDevice Class defines and encapsulates the
036: * audio device's basic information and characteristics.
037: * <P>
038: * A Java3D application running on a particular machine could have one of
039: * several options available to it for playing the audio image created by the
040: * sound renderer. Perhaps the machine Java3D is executing on has more than
041: * one sound card (e.g., one that is a Wave Table Synthesis card and the other
042: * with accelerated sound spatialization hardware). Furthermore, suppose there
043: * are Java3D audio device drivers that execute Java3D audio methods on each of
044: * these specific cards. In such a case the application would have at least two
045: * audio device drivers through which the audio could be produced. For such a
046: * case the Java3D application must choose the audio device driver with which
047: * sound rendering is to be performed. Once this audio device is chosen, the
048: * application can additionally select the type of audio playback type the
049: * rendered sound image is to be output on. The playback device (headphones or
050: * speaker(s)) is physically connected to the port the selected device driver
051: * outputs to.
052: *<P>
053: * AudioDevice Interface
054: *<P>
055: *<UL> The selection of this device driver is done through methods in the
056: * PhysicalEnvironment object - see PhysicalEnvironment class.
057: * The application would query how many audio devices are available. For
058: * each device, the user can get the AudioDevice object that describes it
059: * and query its characteristics. Once a decision is made about which of
060: * the available audio devices to use for a PhysicalEnvironment, the
061: * particular device is set into this PhysicalEnvironment's fields. Each
062: * PhysicalEnvironment object may use only a single audio device.
063: *<P>
064: * The AudioDevice object interface specifies an abstract input device
065: * that creators of Java3D class libraries would implement for a particular
066: * device. Java3D's uses several methods to interact with specific devices.
067: * Since all audio devices implement this consistent interface, the user
068: * could have a portable means of initialize, set particular audio device
069: * elements and query generic characteristics for any audio device.
070: *<P>
071: *Initialization
072: *<P><UL>
073: * Each audio device driver must be initialized.
074: * The chosen device driver should be initialized before any Java3D
075: * Sound methods are executed because the implementation of the Sound
076: * methods, in general, are potentially device driver dependent.</UL>
077: *<P>
078: * Audio Playback Type
079: *<P><UL>
080: * These methods set and retrieve the audio playback type used to output
081: * the analog audio from rendering Java3D Sound nodes.
082: * The audio playback type specifies that playback will be through:
083: * stereo headphones, a monaural speaker, or a pair of speakers.
084: * For the stereo speakers, it is assumed that the two output speakers are
085: * equally distant from the listener, both at same angle from the head
086: * axis (thus oriented symmetrically about the listener), and at the same
087: * elevation.
088: * The type of playback chosen affects the sound image generated.
089: * Cross-talk cancellation is applied to the audio image if playback over
090: * stereo speakers is selected.</UL>
091: *<P>
092: * Distance to Speaker
093: *<P><UL>
094: * These methods set and retrieve the distance in meters from the center
095: * ear (the midpoint between the left and right ears) and one of the
096: * speakers in the listener's environment. For monaural speaker playback,
097: * a typical distance from the listener to the speaker in a workstation
098: * cabinet is 0.76 meters. For stereo speakers placed at the sides of the
099: * display, this might be 0.82 meters.</UL>
100: *<P>
101: * Angular Offset of Speakers
102: *<P><UL>
103: * These methods set and retrieve the angle in radians between the vectors
104: * from the center ear to each of the speaker transducers and the vectors
105: * from the center ear parallel to the head coordinate's Z axis. Speakers
106: * placed at the sides of the computer display typically range between
107: * 0.28 to 0.35 radians (between 10 and 20 degrees).</UL>
108: *<P>
109: * Device Driver Specific Data
110: *<P><UL>
111: * While the sound image created for final output to the playback system
112: * is either only mono or stereo (for this version of Java3D) most device
113: * driver implementations will mix the left and right image signals
114: * generated for each rendered sound source before outputting the final
115: * playback image. Each sound source will use N input channels of this
116: * internal mixer. Each implemented Java3D audio device driver will have
117: * its own limitations and driver-specific characteristics. These include
118: * channel availability and usage (during rendering). Methods for
119: * querying these device-driver specific characteristics are provided.</UL></UL>
120: *<P>
121: * Instantiating and Registering a New Device
122: *<P>
123: *<UL> A browser or applications developer must instantiate whatever system-
124: * specific audio devices that he or she needs and that exist on the system.
125: * This device information typically exists in a site configuration file.
126: * The browser or application will instantiate the physical environment as
127: * requested by the end-user.
128: *<P>
129: * The API for instantiating devices is site-specific, but it consists of
130: * a device object with a constructor and at least all of the methods
131: * specified in the AudioDevice interface.
132: *<P>
133: * Once instantiated, the browser or application must register the device
134: * with the Java3D sound scheduler by associating this device with a
135: * PhysicalEnvironment. The setAudioDevice method introduces new devices
136: * to the Java3D environment and the allAudioDevices method produces an
137: * enumeration that allows examining all available devices within a Java3D
138: * environment. See PhysicalEnvironment class for more details.</UL>
139: * <P>
140: * General Rules for calling AudioDevice methods:
141: * It is illegal for an application to call any non-query AudioDevice method
142: * if the AudioDevice is created then explicitly assigned to a
143: * PhysicalEnvironment using PhysicalEnvironment.setAudioDevice();
144: * When either PhysicalEnvironment.setAudioDevice() is called - including
145: * when implicitly called by SimpleUniverse.getViewer().createAudioDevice()
146: * - the Core creates a SoundScheduler thread which makes calls to
147: * the AudioDevice.
148: * <P>
149: * If an application creates it's own instance of an AudioDevice and
150: * initializes it directly, rather than using PhysicalEnvironment.
151: * setAudioDevice(), that application may make <i>any</i> AudioDevice3D methods calls
152: * without fear of the Java 3D Core also trying to control the AudioDevice.
153: * Under this condition it is safe to call AudioDevice non-query methods.
154: */
155:
156: public interface AudioDevice {
157:
158: /** *************
159: *
160: * Constants
161: *
162: ****************/
163: /**
164: * Audio Playback Types
165: *
166: * Types of audio output device Java3D sound is played over:
167: * Headphones, MONO_SPEAKER, STEREO_SPEAKERS
168: */
169: /**
170: * Choosing Headphones as the audio playback type
171: * specifies that the audio playback will be through stereo headphones.
172: */
173: public static final int HEADPHONES = 0;
174:
175: /**
176: * Choosing a
177: * single near-field monoaural speaker
178: * as the audio playback type
179: * specifies that the audio playback will be through a single speaker
180: * some supplied distance away from the listener.
181: */
182: public static final int MONO_SPEAKER = 1;
183:
184: /**
185: * Choosing a
186: * two near-field stereo speakers
187: * as the audio playback type
188: * specifies that the audio playback will be through stereo speakers
189: * some supplied distance away from, and at some given angle to
190: * the listener.
191: */
192: public static final int STEREO_SPEAKERS = 2;
193:
194: /**
195: * Initialize the audio device.
196: * Exactly what occurs during initialization is implementation dependent.
197: * This method provides explicit control by the user over when this
198: * initialization occurs.
199: * Initialization must be initiated before any other AudioDevice
200: * methods are called.
201: * @return true if initialization was successful without errors
202: */
203: public abstract boolean initialize();
204:
205: /**
206: * Code to close the device and release resources.
207: * @return true if close of device was successful without errors
208: */
209: public abstract boolean close();
210:
211: /**
212: * Set Type of Audio Playback physical transducer(s) sound is output to.
213: * Valid types are HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS
214: * @param type audio playback type
215: */
216: public abstract void setAudioPlaybackType(int type);
217:
218: /**
219: * Get Type of Audio Playback Output Device.
220: * @return audio playback type
221: */
222: public abstract int getAudioPlaybackType();
223:
224: /**
225: * Set Distance from interaural mid-point between Ears to a Speaker.
226: * @param distance from interaural midpoint between the ears to closest speaker
227: */
228: public abstract void setCenterEarToSpeaker(float distance);
229:
230: /**
231: * Get Distance from interaural mid-point between Ears to a Speaker.
232: * @return distance from interaural midpoint between the ears to closest speaker
233: */
234: public abstract float getCenterEarToSpeaker();
235:
236: /**
237: * Set Angle Offset (in radians) To Speaker.
238: * @param angle in radians from head Z axis and vector from center ear to speaker
239: */
240: public abstract void setAngleOffsetToSpeaker(float angle);
241:
242: /**
243: * Get Angle Offset (in radians) To Speaker.
244: * @return angle in radians from head Z axis and vector from center ear to speaker
245: */
246: public abstract float getAngleOffsetToSpeaker();
247:
248: /**
249: * Query total number of channels available for sound rendering
250: * for this audio device. This returns the maximum number of channels
251: * available for Java3D sound rendering for all sound sources.
252: * @return total number of channels that can be used for this audio device
253: */
254: public abstract int getTotalChannels();
255:
256: /**
257: * Query number of channels currently available for use.
258: * During rendering, when sound nodes are playing, this method returns the
259: * number of channels still available to Java3D for rendering additional
260: * sound nodes.
261: * @return total number of channels current available
262: */
263: public abstract int getChannelsAvailable();
264:
265: /**
266: * Query number of channels that are used, or would be used to render
267: * a particular sound node. This method returns the number of channels
268: * needed to render a particular Sound node. The return value is the same
269: * no matter if the Sound is currently active and enabled (being played) or
270: * is inactive.
271: * @return number of channels a particular Sound node is using or would used
272: * if enabled and activated (rendered).
273: */
274: public abstract int getChannelsUsedForSound(Sound node);
275: }
|