| The Java 3D API Specification |
    |
| The Java 3D API Specification |
|
C H A P T E R 12 |
|
Audio Devices |
12.1
The selection of this device driver is done through methods in the PhysicalEnvironment object (see Section C.9, "The PhysicalEnvironment Object"). The application queries how many audio devices are available. For each device, the user can get the AudioDevice object that describes it and query its characteristics. Once a decision is made about which of the available audio devices to use for a PhysicalEnvironment, the particular device is set into this PhysicalEnvironment's fields. Each PhysicalEnvironment object may use only a single audio device.AudioDevice Interface public static final int HEADPHONESSpecifies that audio playback will be through stereo headphones.public static final int MONO_SPEAKERSpecifies that audio playback will be through a single speaker some distance away from the listener.public static final int STEREO_SPEAKERSSpecifies that audio playback will be through stereo speakers some distance away from, and at some angle to, the listener.
12.1.1
Each audio device driver must be initialized. The chosen device driver should be initialized before any Java 3D Sound methods are executed because the implementation of the Sound methods, in general, is potentially device-driver dependent.Initialization public abstract boolean initialize()Initializes the audio device. Exactly what occurs during initialization is implementation dependent. This method provides explicit control by the user over when this initialization occurs. Initialization must be initiated before any other AudioDevice methods are called.public abstract boolean close()Closes the audio device, releasing resources associated with this device.
12.1.2
Methods to set and retrieve the audio playback parameters are part of the AudioDevice object. The audio playback information specifies that playback will be through one of the following:Audio Playback
- Stereo headphones.
- A monaural speaker.
The type of playback chosen affects the sound image generated. Cross-talk cancellation is applied to the audio image if playback over stereo speakers is selected.
- A pair of speakers, equally distant from the listener, both at some angle from the head coordinate system z-axis. It's assumed that the speakers are at the same elevation and oriented symmetrically about the listener.
Methods
The following methods affect the playback of sound processed by the Java 3D sound renderer:public abstract void setAudioPlaybackType(int type) public abstract int getAudioPlaybackType()These methods set and retrieve the type of audio playback device (HEADPHONES,MONO_SPEAKER, orSTEREO_SPEAKERS) used to output the analog audio from rendering Java 3D Sound nodes.public abstract void setCenterEarToSpeaker(float distance) public abstract float getCenterEarToSpeaker()These methods set and retrieve the distance in meters from the center ear (the midpoint between the left and right ears) and one of the speakers in the listener's environment. For monaural speaker playback, a typical distance from the listener to the speaker in a workstation cabinet is 0.76 meters. For stereo speakers placed at the sides of the display, this might be 0.82 meters.public abstract void setAngleOffsetToSpeaker(float angle) public abstract float getAngleOffsetToSpeaker()These methods set and retrieve the angle, in radians, between the vectors from the center ear to each of the speaker transducers and the vectors from the center ear parallel to the head coordinate's z-axis. Speakers placed at the sides of the computer display typically range between 0.175 and 0.350 radians (between 10 and 20 degrees).public abstract PhysicalEnvironment getPhysicalEnvironment()This method returns a reference to the AudioDevice's PhysicalEnvironment object.
12.1.3
While the sound image created for final output to the playback system is either only monaural or stereo (for this version of Java 3D), most device-driver implementations will mix the left and right image signals generated for each rendered sound source before outputting the final playback image. Each sound source will use N input channels of this internal mixer.Device-Driver-Specific Data public abstract int getTotalChannels()This method retrieves the maximum number of channels available for Java 3D sound rendering for all sound sources.public abstract int getChannelsAvailable()During rendering, when Sound nodes are playing, this method returns the number of channels still available to Java 3D for rendering additional Sound nodes.public abstract int getChannelsUsedForSound(Sound node)This method queries the number of channels that are used or would be used to render a particular sound node. This method returns the number of channels needed to render a particular Sound node. The return value is the same no matter if the Sound is currently active and enabled (being played) or is inactive.
12.1.4
It is illegal for an application to call any non-query AudioDevice method if the AudioDevice is created then explicitly assigned to a PhysicalEnvironment using theGeneral Rules for Calling AudioDevice Methods PhysicalEnvironment.setAudioDevice()method. When eitherPhysicalEnvironment.setAudioDevice()method is called-including when implicitly called bySimpleUniverse.getViewer().createAudioDevice()-the Core creates a SoundScheduler thread that makes calls to the AudioDevice.
12.2
The AudioDevice3D Class extends the AudioDevice interface by defining a 3D audio device that is used to set sound and aural attributes. The intent is for this interface to be implemented by AudioDevice driver developers (whether a Java 3D licensee or not) using a software or hardware sound engine of their choice.AudioDevice3D Interface
- Set up and clear the sound as a sample on the device.
- Start, stop, pause, unpause, mute, and unmute of sample on the device.
- Set parameters for each sample corresponding to the fields in the Sound node.
- Set the current active aural parameters that affect all positional samples.
Constants
public static final int BACKGROUND_SOUND public static final int POINT_SOUND public static final int CONE_SOUNDThese constants specify the sound types. Sound types match the Sound node classes defined for Java 3D core for BackgroundSound, PointSound, and ConeSound. The type of sound a sample is loaded as determines which methods affect it.public static final int STREAMING_AUDIO_DATA public static final int BUFFERED_AUDIO_DATAThese constants specify the sound data types. Samples can be processed as streaming or buffered data. Fully spatializing sound sources may require data to be buffered.public abstract void setView(View reference)This method accepts a reference to the current View and passes reference to the current View Object. The PhysicalEnvironment parameters (with playback type and speaker placement) and the PhysicalBody parameters (position and orientation of ears) can be obtained from this object and from the transformations to and from ViewPlatform coordinate (the space the listener's head is in) and Virtual World coordinates (the space the sounds are in).public abstract int prepareSound(int soundType, MediaContainer soundData)Prepares the sound. This method accepts a reference to the MediaContainer that contains a reference to sound data and information about the type of data it is. ThesoundTypeparameter defines the type of sound associated with this sample (Background, Point, or Cone).public abstract void clearSound(int index)Clears the sound. This method requests that the AudioDevice free all resources associated with the sample withindexid.public abstract long getSampleDuration(int index)Queries sample duration. If it can be determined, this method returns the duration in milliseconds of the sound sample. For noncached streams, this method returnsSound.DURATION_UNKNOWN.public abstract int getNumberOfChannelsUsed(int index) public abstract int getNumberOfChannelsUsed(int index, boolean muted)Query the number of channels used by Sound. These methods return the number of channels (on the executing audio device) that this sound is using if it is already playing or those it is expected to use if it were to begin playing. The first method takes the sound's current state (including whether it is muted or unmuted) into account. The second method uses themutedparameter to make the determination.For some AudioDevice3D implementations,
- Muted sounds take up channels on the systems mixer (because they're rendered as samples playing with gain zero).
- A single sound could be rendered using multiple samples, each taking up mixer channels.
public abstract int startSample(int index)Starts sample. This method begins a sound playing on the AudioDevice and returns a flag indicating whether the sample was started.public abstract int stopSample(int index)Stops sample. This method stops the sound on the AudioDevice and returns a flag indicating whether the sample was stopped.public abstract long getStartTime(int index)Queries the last start time for this sound on the device. This method returns the system time of when the sound was last "started." Note that this start time will be as accurate as the AudioDevice implementation can make it, but that it is not guaranteed to be exact.public abstract void setSampleGain(int index, float scaleFactor)Sets gain scale factor. This method sets the overall gain scale factor applied to data associated with this source to increase or decrease its overall amplitude. The gainscaleFactorvalue passed into this method is the combined value of the Sound node's initial gain and the current AuralAttribute gain scale factors.public abstract void setDistanceGain(int index, double[] frontDistance, float[] frontAttenuationScaleFactor, double[] backDistance, float[] backAttenuationScaleFactor)Sets distance gain. This method sets this sound's distance gain elliptical attenuation (not including the filter cutoff frequency) by defining corresponding arrays containing distances from the sound's origin and gain scale factors applied to all active positional sounds. The gain scale factor is applied to sound based on the distance the listener is from the sound source. These attenuation parameters are ignored for BackgroundSound nodes. ThebackAttenuationScaleFactorparameter is ignored for PointSound nodes.For a full description of the attenuation parameters, see Section 6.9.3, "ConeSound Node."
public abstract void setDistanceFilter(int filterType, double[] distance, float[] filterCutoff)Sets AuralAttributes distance filter. This method sets the distance filter corresponding arrays containing distances and frequency cutoff applied to all active positional sounds. The gain scale factor is applied to sound based on the distance the listener is from the sound source. For a full description of this parameter and how it is used, see Section 8.1.18, "AuralAttributes Object."public abstract void setLoop(int index, int count)Sets loop count. This method sets the number of times sound is looped during play. For a complete description of this method, see the description for theSound.setLoopmethod in Section 6.9, "Sound Node."public abstract void muteSample(int index) public abstract void unmuteSample(int index)These methods mute and unmute a playing sound sample. The first method makes a sample play silently. The second method makes a silently playing sample audible. Ideally, the muting of a sample is implemented by stopping a sample and freeing channel resources (rather than just setting the gain of the sample to zero). Ideally, the unmuting of a sample restarts the muted sample by offset from the beginning by the number of milliseconds since the time the sample began playing.public abstract void pauseSample(int index) public abstract void unpauseSample(int index)These methods pause and unpause a playing sound sample. The first method temporarily stops a cached sample from playing without resetting the sample's current pointer back to the beginning of the sound data so that at a later time it can be un-paused from the same location in the sample when the pause was initiated. The second method restarts the paused sample from the location in the sample where it was paused.public abstract void setPosition(int index, Point3d position)Sets position. This method sets this sound's location (in Local coordinates) from the providedposition.public abstract void setDirection(int index, Vector3d direction)Sets direction. This method sets this sound's direction from the local coordinate vector provided. For a full description of thedirectionparameter, see Section 6.9.3, "ConeSound Node."public abstract void setVworldXfrm(int index, Transform3D trans)Sets virtual world transform. This method passes a reference to the concatenated transformation to be applied to local sound position and direction parameters.public abstract void setRolloff(float rolloff)Sets AuralAttributes gain rolloff. This method sets the speed-of-sound factor. For a full description of this parameter and how it is used, see Section 8.1.18, "AuralAttributes Object."public abstract void setAngularAttenuation(int index, int filterType, double[] angle, float[] attenuationScaleFactor, float[] filterCutoff)Sets angular attenuation. This method sets this sound's angular gain attenuation (including filter) by defining corresponding arrays containing angular offsets from the sound's axis, gain scale factors, and frequency cutoff applied to all active directional sounds. Gain scale factor is applied to sound based on the angle between the sound's axis and the ray from the sound source origin to the listener. The form of the attenuation parameter is fully described in Section 6.9.3, "ConeSound Node."public abstract void setReflectionCoefficient(float coefficient)Sets AuralAttributes reverberation coefficient. This method sets the reflective coefficient scale factor applied to distinct low-order early reflections of sound off the surfaces in the region defined by the current listening region. For a full description of this parameter and how it is used, see Section 8.1.18, "AuralAttributes Object."public abstract void setReverbDelay(float reverbDelay)Sets AuralAttributes reverberation delay. This method sets the delay time between each order of late reflections (while reverberation is being rendered) explicitly given in milliseconds. A value for delay time of 0.0 disables reverberation. For a full description of this parameter and how it is used, see Section 8.1.18, "AuralAttributes Object."public abstract void setReverbOrder(int reverbOrder)Sets AuralAttributes reverberation order. This method sets the number of times reflections are added to reverberation being calculated. A value of -1 specifies an unbounded number of reverberations. For a full description of this parameter and how it is used, see Section 8.1.18, "AuralAttributes Object."public abstract void setFrequencyScaleFactor(float frequencyScaleFactor)Sets AuralAttributes frequency scale factor. This method specifies a scale factor applied to the frequency (or wavelength). This parameter can also be used to expand or contract the usual frequency shift applied to the sound source due to Doppler effect calculations. Valid values are0.0. A value greater than 1.0 will increase the playback rate. For a full description of this parameter and how it is used, see Section 8.1.18, "AuralAttributes Object."
public abstract void setVelocityScaleFactor(float velocityScaleFactor)Sets AuralAttributes velocity scale factor. This method specifies a velocity scale factor applied to the velocity of sound relative to the listener's position and movement in relation to the sound's position and movement. This scale factor is multiplied by the calculated velocity portion of Doppler effect equation used during sound rendering. For a full description of this parameter and how it is used, see Section 8.1.18, "AuralAttributes Object."public abstract void updateSample(int index)Explicitly updates a sample. This method is called when a Sound is to be explicitly updated. It is called only when all of a sound's parameters are known to have been passed to the audio device. In this way, an implementation can choose to perform lazy evaluation of a sample, rather than updating the rendering state of the sample after every individual parameter changed. This method can be left as a null method if the implementor so chooses.
12.3
The AudioDevice3DL2 interface extends the AudioDevice3D interface to include reverberation and environmental audio parameters that are defined in the MIDI Manufactures' Association Interactive Audio Special Interest Group (MMA IASIG) Level 2 Specification.AudioDevice3DL2 Interface The AudioDevice3DL2 reverberation methods augment the AudioDevice3D methods (see Section 12.2, "AudioDevice3D Interface").
public void pause()These methods pause and resume the audio device engine (thread/server). Pausing the device does not close the device, but causes all cached sounds to be paused and all streaming sounds to be stopped. The resume method causes all paused cached sounds to be resumed and all streaming sounds restarted. These methods will be implicitly called when the View (associated with this device) is deactivated or activated, respectively.public void resume()
public void setGain(float scaleFactor)This method sets the overall gain control of all sounds playing on the audio device. The default value is 1.0 (no attenuation).
public void setRateScaleFactor(int sampleId, float scaleFactor)This method sets the scale factor applied to the sample playback rate for a particular sound associated with the audio device. Changing the device sample rate affects both the pitch and speed. This scale factor is applied to all sound types. The scale factor changes (scales) the playback rate of a sound independent of Doppler rate changes. The default is 1.0 (original sample rate is unchanged).
12.3.1
The components applicable to reverberation are explained in Section 8.1.18.2, "Reverberation." The reverberation methods should not be called by any application if the audio device is associated with a Physical Environment used by Java3D Core.Reverberation public void setReverbCoefficient(float coefficient)This method sets the late reflection (referred to as reverb) attenuation. This scale factor is applied to iterative, indistinguishable late reflections that constitute the tail of reverberated sound in the aural environment. This parameter, along with the early reflection coefficient, defines the reflective and absorptive characteristic of the surfaces in the current listening region. A coefficient value of 0 disables reverberation (the default). Valid parameter values range from 0.0 to 1.0.
public void setReflectionDelay(float reflectionDelay)This method sets the early reflection delay time. In this form, the parameter specifies the delay time between each order of reflection (while reverberation is being rendered) explicitly given in milliseconds. Valid values are non-negative floats. There may be limitations imposed by the device on how small or large this value can be made. A value of 0.0 would result in early reflections being added as soon as possible after the sound begins.
public void setDecayTime(float decayTime)This method sets the reverberation decay time, which defines the reverberation decay curve. The
decayTimeparameter specifies the time in milliseconds the amplitude of late reflections takes to exponentially decay to effective zero. Valid values are non-negative floats. There may be limitations imposed by the device on how small or large this value can be made.public void setDiffusion(float diffusion)This method sets the reverberation diffusion, which defines the echo dispersement. The value of this reverberation parameter is expressed as a percentage of the audio device's minimum-to-maximum values.
public void setDensity(float diffusion)This method sets the reverberation density, which defines the modal density (also referred to as spectral coloration). The value of this density parameter is expressed as a percent of the audio device's minimum-to-maximum values for this reverb parameter.
public void setDecayFilter(float frequencyCutoff)This method sets the reverberation decay filter, which provides for frequencies above the given cutoff frequency to be attenuated during reverb decay at a different rate than frequencies below this value, thus defining a different reverb decay curve for frequencies above the cutoff value.
12.3.2
The AudioDevice3DL2 interface enables the reproduction of the effects of obstacles between the sound source and the listener in Java 3D applications. Sounds heard through walls, windows, or other obstructions are different from unobstructed sounds. Sounds that travel indirectly from the source to the listener, such as around corners or through openings (known as occlusion), also undergo changes. The object of the AudioDevice3DL2 interface is to reproduce those changes to provide the listener with a more realistic audio experience in an environment in which the audio source is not in the same room as the listener.Occlusion and Obstruction Filters The AudioDevice3DL2 interface supports filter and gain controls for implementing occlusion and obstruction of sound sources. For example, Figure 12-1 shows a listener, L1, and three sound sources, S1, S2, and S3, in the same scene. For listener L1
- Sound S1 is occluded (by the exterior walls of the room)
- Sound S3 is obstructed (by a barrier between the sound source and the listener)
- Sound S2 reaches the listener unaffected
Figure 12-1
Occlusion and Obstruction Defined
Both the occlusion and obstruction effects are produced by specifying the gain control (the
scaleFactorparameter in Figure 12-2) and the frequency at which attenuation is to begin (thefrequencyCutoffparameter in Figure 12-2). ThescaleFactorparameter defines the amount of frequency-independent attenuation applied to the sound waves traveling between the sound source and the listener occluded or obstructed by objects.
Figure 12-2
public void setObstructionGain(int sampleId, float scaleFactor)This method sets the obstruction gain control, which allows for attenuating sound waves traveling between the sound source and the listener obstructed by objects. Direct sound waves for obstructed sound sources are attenuated but not indirect (reflected) waves. The default value is 1.0 (gain is not attenuated, obstruction is not occurring).
public void setObstructionFilter(int sampleId,This method sets the obstruction filter control, which provides for frequencies above the given cutoff frequency to be attenuated, while the gain of an obstruction signal is being calculated, at a different rate than frequencies below this value. The default value is 1.0 (filtering is uniform for all frequencies).float frequencyCutoff)
public void setOcclusionGain(int sampleId, float scaleFactor)This method sets the occlusion gain control, which allows for attenuating sound waves traveling between the sound source and the listener occluded by objects. Both direct and indirect sound signals or waves for occluded sound sources are attenuated. The default value is 1.0 (gain is not attenuated, occlusion is not occurring).
public void setOcclusionFilter(int sampleId,This method sets the occlusion filter control, which provides for frequencies above the given cutoff frequency to be attenuated, while the gain of an occluded signal is being calculated, at a different rate than frequencies below this value. The default value is 1.0 (filtering is uniform for all frequencies).float frequencyCutoff)
12.4
A browser or applications developer must instantiate whatever system-specific audio devices that he or she needs and that exist on the system. This device information typically exists in a site configuration file. The browser or application will instantiate the physical environment as requested by the end user.Instantiating and Registering a New Device Once instantiated, the browser or application must register the device with the Java 3D sound scheduler by associating this device with a PhysicalEnvironment object. The
setAudioDevicemethod introduces new devices to the Java 3D environment, and theallAudioDevicesmethod produces an enumeration that allows examination of all available devices within a Java 3D environment. See Section C.9, "The PhysicalEnvironment Object," for more details.
| The Java 3D API Specification |
|
