com.sun.j3d.audioengines

Class AudioEngine3D

java.lang.Object

com.sun.j3d.audioengines.AudioEngine

com.sun.j3d.audioengines.AudioEngine3D

All Implemented Interfaces:

javax.media.j3d.AudioDevice, javax.media.j3d.AudioDevice3D

Direct Known Subclasses:

AudioEngine3DL2

public abstract class AudioEngine3D
extends AudioEngine
implements javax.media.j3d.AudioDevice3D

The AudioEngine3D Class defines an audio output device that generates sound 'image' from high-level sound parameters passed to it during scene graph.

The methods in this class are meant to be optionally overridden by an extended class. This extended class would provice device specific code.

Error checking on all parameters passed to these methods is already explicitly being done by the Java 3D core code that calls these methods.

NOTE: AudioEngine developers should not subclass this class directly. Subclass AudioEngine3DL2 instead.

Field Summary

Fields

Modifier and Type	Field and Description
protected AuralParameters	attribs
protected javax.media.j3d.View	currentView Current View sound is being rendered
protected ArrayList	samples

Fields inherited from interface javax.media.j3d.AudioDevice3D

BACKGROUND_SOUND, BUFFERED_AUDIO_DATA, CONE_SOUND, POINT_SOUND, STREAMING_AUDIO_DATA

Fields inherited from interface javax.media.j3d.AudioDevice

HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS

Constructor Summary

Constructors

Constructor and Description
AudioEngine3D(javax.media.j3d.PhysicalEnvironment physicalEnvironment) Construct a new AudioEngine with the specified PhysicalEnvironment.

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	clearSound(int index) Clear Sound.
AuralParameters	getAuralParameters()
int	getNumberOfChannelsUsed(int index) Get number of channels used by a particular sample on the audio device.
int	getNumberOfChannelsUsed(int index, boolean muteFlag) Get number of channels that would be used by a particular sample on the audio device given the mute flag passed in as a parameter.
Sample	getSample(int index) Get specific sample from indexed sample list Checks for valid index before attempting to get sample from list.
long	getSampleDuration(int index) Get length of time a sample would play if allowed to play to completion.
protected ArrayList	getSampleList() Deprecated. unsafe to get reference to samples list with this method. It's better to directly reference samples list within a synchronized block which also contains calls to .getSample(index).
int	getSampleListSize()
long	getStartTime(int index) Get time this sample begun playing on the audio device.
javax.media.j3d.View	getView() Get reference to the current View object.
abstract void	muteSample(int index) Mute sample.
abstract void	pauseSample(int index) Pause sample.
int	prepareSound(int soundType, javax.media.j3d.MediaContainer soundData) Prepare Sound in device.
void	setAngularAttenuation(int index, int filterType, double[] angle, float[] attenuationScaleFactor, float[] filterCutoff) Set angular attenuation arrays affecting angular amplitude attenuation and angular distance filtering.
void	setDirection(int index, javax.vecmath.Vector3d direction) Set direction vector of sample.
void	setDistanceFilter(int filterType, double[] dist, float[] filterCutoff) Set distance filter for current aural attribute applied to all samples.
void	setDistanceGain(int index, double[] frontDistance, float[] frontAttenuationScaleFactor, double[] backDistance, float[] backAttenuationScaleFactor)
void	setFrequencyScaleFactor(float scaleFactor) Set frequency scale factor for current aural attribute applied to all samples.
void	setLoop(int index, int count) Set number of times sample is looped.
void	setPosition(int index, javax.vecmath.Point3d position) Set location of sample.
void	setReflectionCoefficient(float coefficient) Set reverberation surface reflection coefficient value for current aural attribute applied to all samples.
void	setReverbDelay(float reverbDelay) Set reverberation delay time for current aural attribute applied to all samples.
void	setReverbOrder(int reverbOrder) Set reverberation order for current aural attribute applied to all samples.
void	setRolloff(float rolloff) Set rolloff value for current aural attribute applied to all samples.
void	setSampleGain(int index, float scaleFactor) Set gain scale factor applied to sample.
void	setVelocityScaleFactor(float scaleFactor) Set velocity scale factor for current aural attribute applied to all samples when Doppler is calculated.
void	setView(javax.media.j3d.View reference) Save a reference to the current View object.
void	setVworldXfrm(int index, javax.media.j3d.Transform3D trans) Set the transform for local to virtual world coordinate space
abstract int	startSample(int index) Start sample playing on audio device
abstract int	stopSample(int index) Stop sample playing on audio device
abstract void	unmuteSample(int index) Unmute sample.
abstract void	unpauseSample(int index) Unpause sample.
abstract void	updateSample(int index) Update sample.

Methods inherited from class com.sun.j3d.audioengines.AudioEngine

close, getAngleOffsetToSpeaker, getAudioPlaybackType, getCenterEarToSpeaker, getChannelsAvailable, getChannelsUsedForSound, getTotalChannels, initialize, setAngleOffsetToSpeaker, setAudioPlaybackType, setCenterEarToSpeaker

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.media.j3d.AudioDevice

close, getAngleOffsetToSpeaker, getAudioPlaybackType, getCenterEarToSpeaker, getChannelsAvailable, getChannelsUsedForSound, getTotalChannels, initialize, setAngleOffsetToSpeaker, setAudioPlaybackType, setCenterEarToSpeaker

Field Detail

samples

protected ArrayList samples

currentView

protected javax.media.j3d.View currentView

Current View sound is being rendered

attribs

protected AuralParameters attribs

Constructor Detail

AudioEngine3D

public AudioEngine3D(javax.media.j3d.PhysicalEnvironment physicalEnvironment)

Construct a new AudioEngine with the specified PhysicalEnvironment.

Parameters:

physicalEnvironment - the physical environment object where we want access to this device.

Method Detail

setView

public void setView(javax.media.j3d.View reference)

Save a reference to the current View object.

Specified by:

setView in interface javax.media.j3d.AudioDevice3D

Parameters:

reference - to current view object

getView

public javax.media.j3d.View getView()

Get reference to the current View object.

Returns:

reference to current view object

prepareSound

public int prepareSound(int soundType,
               javax.media.j3d.MediaContainer soundData)

Prepare Sound in device. Makes sound assessible to device - in this case attempts to load sound Stores sound type and data.

Specified by:

prepareSound in interface javax.media.j3d.AudioDevice3D

Parameters:

soundType - denotes type of sound: Background, Point or Cone

soundData - descrition of sound source data

Returns:

index into sample vector of Sample object for sound

clearSound

public abstract void clearSound(int index)

Clear Sound. Removes/clears associated sound data with this sound source node

Specified by:

clearSound in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

setVworldXfrm

public void setVworldXfrm(int index,
                 javax.media.j3d.Transform3D trans)

Set the transform for local to virtual world coordinate space

Specified by:

setVworldXfrm in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

trans - is a reference to virtual world composite transform

startSample

public abstract int startSample(int index)

Start sample playing on audio device

Specified by:

startSample in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

Returns:

status: < 0 denotes an error

stopSample

public abstract int stopSample(int index)

Stop sample playing on audio device

Specified by:

stopSample in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

Returns:

status: < 0 denotes an error

updateSample

public abstract void updateSample(int index)

Update sample. Implies that some parameters affecting rendering have been modified.

Specified by:

updateSample in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

muteSample

public abstract void muteSample(int index)

Mute sample.

Specified by:

muteSample in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

unmuteSample

public abstract void unmuteSample(int index)

Unmute sample.

Specified by:

unmuteSample in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

pauseSample

public abstract void pauseSample(int index)

Pause sample.

Specified by:

pauseSample in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

unpauseSample

public abstract void unpauseSample(int index)

Unpause sample.

Specified by:

unpauseSample in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

setSampleGain

public void setSampleGain(int index,
                 float scaleFactor)

Set gain scale factor applied to sample.

Specified by:

setSampleGain in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

scaleFactor - floating point multiplier applied to sample amplitude

setLoop

public void setLoop(int index,
           int count)

Set number of times sample is looped.

Specified by:

setLoop in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

count - number of times sample is repeated

setPosition

public void setPosition(int index,
               javax.vecmath.Point3d position)

Set location of sample.

Specified by:

setPosition in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

position - point location in virtual world coordinate of sample

setDistanceGain

public void setDistanceGain(int index,
                   double[] frontDistance,
                   float[] frontAttenuationScaleFactor,
                   double[] backDistance,
                   float[] backAttenuationScaleFactor)

Specified by:

setDistanceGain in interface javax.media.j3d.AudioDevice3D

setDirection

public void setDirection(int index,
                javax.vecmath.Vector3d direction)

Set direction vector of sample.

Specified by:

setDirection in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

direction - vector in virtual world coordinate.

setAngularAttenuation

public void setAngularAttenuation(int index,
                         int filterType,
                         double[] angle,
                         float[] attenuationScaleFactor,
                         float[] filterCutoff)

Set angular attenuation arrays affecting angular amplitude attenuation and angular distance filtering.

Specified by:

setAngularAttenuation in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

filterType - denotes type of filtering (on no filtering) applied to sample.

angle - array containing angular distances from sound axis

attenuationScaleFactor - array containing gain scale factor

filterCutoff - array containing filter cutoff frequencies. The filter values for each tuples can be set to Sound.NO_FILTER.

setRolloff

public void setRolloff(float rolloff)

Set rolloff value for current aural attribute applied to all samples.

Specified by:

setRolloff in interface javax.media.j3d.AudioDevice3D

Parameters:

rolloff - scale factor applied to standard speed of sound.

setReflectionCoefficient

public void setReflectionCoefficient(float coefficient)

Set reverberation surface reflection coefficient value for current aural attribute applied to all samples.

Specified by:

setReflectionCoefficient in interface javax.media.j3d.AudioDevice3D

Parameters:

coefficient - applied to amplitude of reverbation added at each iteration of reverb processing.

setReverbDelay

public void setReverbDelay(float reverbDelay)

Set reverberation delay time for current aural attribute applied to all samples.

Specified by:

setReverbDelay in interface javax.media.j3d.AudioDevice3D

Parameters:

reverbDelay - amount of time in millisecond between each iteration of reverb processing.

setReverbOrder

public void setReverbOrder(int reverbOrder)

Set reverberation order for current aural attribute applied to all samples.

Specified by:

setReverbOrder in interface javax.media.j3d.AudioDevice3D

Parameters:

reverbOrder - number of times reverb process loop is iterated.

setDistanceFilter

public void setDistanceFilter(int filterType,
                     double[] dist,
                     float[] filterCutoff)

Set distance filter for current aural attribute applied to all samples.

Specified by:

setDistanceFilter in interface javax.media.j3d.AudioDevice3D

Parameters:

filterType - denotes type of filtering (on no filtering) applied to all sample based on distance between listener and sound.

dist - is an attenuation array of distance and low-pass filter values.

setFrequencyScaleFactor

public void setFrequencyScaleFactor(float scaleFactor)

Set frequency scale factor for current aural attribute applied to all samples.

Specified by:

setFrequencyScaleFactor in interface javax.media.j3d.AudioDevice3D

Parameters:

scaleFactor - frequency scale factor applied to samples normal playback rate.

setVelocityScaleFactor

public void setVelocityScaleFactor(float scaleFactor)

Set velocity scale factor for current aural attribute applied to all samples when Doppler is calculated.

Specified by:

setVelocityScaleFactor in interface javax.media.j3d.AudioDevice3D

Parameters:

scaleFactor - scale factor applied to postional samples' listener-to-soundSource velocity. playback rate.

getNumberOfChannelsUsed

public int getNumberOfChannelsUsed(int index)

Get number of channels used by a particular sample on the audio device.

Specified by:

getNumberOfChannelsUsed in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

Returns:

number of channels currently being used by this sample.

getNumberOfChannelsUsed

public int getNumberOfChannelsUsed(int index,
                          boolean muteFlag)

Get number of channels that would be used by a particular sample on the audio device given the mute flag passed in as a parameter.

Specified by:

getNumberOfChannelsUsed in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

muteFlag - denotes the mute state to assume while executing this query. This mute value does not have to match the current mute state of the sample.

Returns:

number of channels that would be used by this sample if it were playing.

getSampleDuration

public long getSampleDuration(int index)

Get length of time a sample would play if allowed to play to completion.

Specified by:

getSampleDuration in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

Returns:

length of sample in milliseconds

getStartTime

public long getStartTime(int index)

Get time this sample begun playing on the audio device.

Specified by:

getStartTime in interface javax.media.j3d.AudioDevice3D

Parameters:

index - device specific reference number to device driver sample

Returns:

system clock time sample started

getSampleList

protected ArrayList getSampleList()

Deprecated. unsafe to get reference to samples list with this method. It's better to directly reference samples list within a synchronized block which also contains calls to .getSample(index).

Get reference to the array list of samples

Returns:

reference to samples list

getSampleListSize

public int getSampleListSize()

getSample

public Sample getSample(int index)

Get specific sample from indexed sample list Checks for valid index before attempting to get sample from list.

Parameters:

index - device specific reference number to device driver sample

Returns:

reference to sample; returns null if index out of range.

Since:

Java 3D 1.2.1

getAuralParameters

public AuralParameters getAuralParameters()