001: /*
002: * $RCSfile: AudioEngine.java,v $
003: *
004: * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * - Redistribution of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * - Redistribution in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * Neither the name of Sun Microsystems, Inc. or the names of
019: * contributors may be used to endorse or promote products derived
020: * from this software without specific prior written permission.
021: *
022: * This software is provided "AS IS," without a warranty of any
023: * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
024: * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
025: * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
026: * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
027: * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
028: * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
029: * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
030: * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
031: * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
032: * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
033: * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
034: * POSSIBILITY OF SUCH DAMAGES.
035: *
036: * You acknowledge that this software is not designed, licensed or
037: * intended for use in the design, construction, operation or
038: * maintenance of any nuclear facility.
039: *
040: * $Revision: 1.5 $
041: * $Date: 2007/02/09 17:20:02 $
042: * $State: Exp $
043: */
044:
045: package com.sun.j3d.audioengines;
046:
047: import javax.media.j3d.*;
048:
049: /**
050: * The AudioEngine Class defines an audio output device that generates
051: * sound 'image' from scene graph.
052: * An AudioEngine object encapsulates the AudioDevice's basic information.
053: *
054: * <p>
055: * NOTE: AudioEngine developers should not subclass this class directly.
056: * Subclass AudioEngine3DL2 instead.
057: */
058: public abstract class AudioEngine implements AudioDevice {
059:
060: /*
061: * This device's UNIX file descriptor
062: */
063: int fileDescriptor;
064:
065: /*
066: * Type of audio output device J3D sound is played over:
067: * HEADPHONE, MONO_SPEAKER, STEREO_SPEAKERS
068: */
069: int audioPlaybackType = HEADPHONES;
070:
071: /*
072: * Distance from center ear (midpoint between ears) to physical speaker.
073: * Default reflects distance for headphones.
074: * For two speakers it is assumed that the speakers are the same
075: * distance from the listener and that
076: */
077: float distanceToSpeaker = 0.0f;
078:
079: /*
080: * Angle between the vector from center ear parallel to head coordiate
081: * Z axis and the vector from the center ear to the speaker.
082: * For two speakers it is assumed that the speakers are placed at the
083: * same angular offset from the listener.
084: */
085: float angleOffsetToSpeaker = 0.0f;
086:
087: /*
088: * Channels currently available
089: */
090: int channelsAvailable = 8;
091:
092: /*
093: * Total number of Channels ever available
094: */
095: int totalChannels = 8;
096:
097: /**
098: * Construct a new AudioEngine with the specified P.E.
099: * @param physicalEnvironment the physical environment object where we
100: * want access to this device.
101: */
102: public AudioEngine(PhysicalEnvironment physicalEnvironment) {
103: physicalEnvironment.setAudioDevice(this );
104: }
105:
106: /**
107: * Code to initialize the device
108: * @return flag: true is initialized sucessfully, false if error
109: */
110: public abstract boolean initialize();
111:
112: /**
113: * Code to close the device
114: * @return flag: true is closed sucessfully, false if error
115: */
116: public abstract boolean close();
117:
118: /*
119: * Audio Playback Methods
120: */
121: /**
122: * Set Type of Audio Playback physical transducer(s) sound is output to.
123: * Valid types are HEADPHONE, MONO_SPEAKER, STEREO_SPEAKERS
124: * @param type of audio output device
125: */
126: public void setAudioPlaybackType(int type) {
127: audioPlaybackType = type;
128: }
129:
130: /**
131: * Get Type of Audio Playback Output Device
132: * returns audio playback type to which sound is currently output
133: */
134: public int getAudioPlaybackType() {
135: return audioPlaybackType;
136: }
137:
138: /**
139: * Set Distance from the Center Ear to a Speaker
140: * @param distance from the center ear and to the speaker
141: */
142: public void setCenterEarToSpeaker(float distance) {
143: distanceToSpeaker = distance;
144: }
145:
146: /**
147: * Get Distance from Ear to Speaker
148: * returns value set as distance from listener's ear to speaker
149: */
150: public float getCenterEarToSpeaker() {
151: return distanceToSpeaker;
152: }
153:
154: /**
155: * Set Angle Offset To Speaker
156: * @param angle in radian between head coordinate Z axis and vector to speaker */
157: public void setAngleOffsetToSpeaker(float angle) {
158: angleOffsetToSpeaker = angle;
159: }
160:
161: /**
162: * Get Angle Offset To Speaker
163: * returns value set as angle between vector to speaker and Z head axis
164: */
165: public float getAngleOffsetToSpeaker() {
166: return angleOffsetToSpeaker;
167: }
168:
169: /**
170: * Query total number of channels available for sound rendering
171: * for this audio device.
172: * returns number of maximum sound channels you can run with this
173: * library/device-driver.
174: */
175: public int getTotalChannels() {
176: // this method should be overridden by a device specific implementation
177: return (totalChannels);
178: }
179:
180: /**
181: * Query number of channels currently available for use by the
182: * returns number of sound channels currently available (number
183: * not being used by active sounds.
184: */
185: public int getChannelsAvailable() {
186: return (channelsAvailable);
187: }
188:
189: /**
190: * Query number of channels that would be used to render a particular
191: * sound node.
192: * @param sound refenence to sound node that query to be performed on
193: * returns number of sound channels used by a specific Sound node
194: * @deprecated This method is now part of the Sound class
195: */
196: public int getChannelsUsedForSound(Sound sound) {
197: if (sound != null)
198: return sound.getNumberOfChannelsUsed();
199: else
200: return -1;
201: }
202: }
|