com.sun.j3d.audioengines

## Class AudioEngine3D

- java.lang.Object
- - com.sun.j3d.audioengines.AudioEngine
  - - com.sun.j3d.audioengines.AudioEngine3D

- All Implemented Interfaces:
    AudioDevice, AudioDevice3D
  Direct Known Subclasses:
    AudioEngine3DL2

      public abstract class AudioEngine3D
      extends AudioEngine
      implements 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 View` | `currentView` Current View sound is being rendered
    `protected java.util.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(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 java.util.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.
    `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, 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, 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)` Sets this sound's distance gain elliptical attenuation (not including filter cutoff frequency) by defining corresponding arrays containing distances from the sound's origin and gain scale factors applied to all active positional sounds.
    `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, 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(View reference)` Save a reference to the current View object.
    `void` | `setVworldXfrm(int index, 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 java.util.ArrayList samples

    - #### currentView

          protected View currentView

      Current View sound is being rendered

    - #### attribs

          protected AuralParameters attribs

  - ### Constructor Detail

    - #### AudioEngine3D

          public AudioEngine3D(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(View reference)

      Save a reference to the current View object.
      Specified by:
        `setView` in interface `AudioDevice3D`
      Parameters:
        `reference` - to current view object

    - #### getView

          public View getView()

      Get reference to the current View object.
      Returns:
        reference to current view object

    - #### prepareSound

          public int prepareSound(int soundType,
                         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 `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 `AudioDevice3D`
      Parameters:
        `index` - device specific reference number to device driver sample

    - #### setVworldXfrm

          public void setVworldXfrm(int index,
                           Transform3D trans)

      Set the transform for local to virtual world coordinate space
      Specified by:
        `setVworldXfrm` in interface `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 `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 `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 `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 `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 `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 `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 `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 `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 `AudioDevice3D`
      Parameters:
        `index` - device specific reference number to device driver sample
        `count` - number of times sample is repeated
      See Also:
        `Sound.setLoop(int)`

    - #### setPosition

          public void setPosition(int index,
                         Point3d position)

      Set location of sample.
      Specified by:
        `setPosition` in interface `AudioDevice3D`
      Parameters:
        `index` - device specific reference number to device driver sample
        `position` - point location in virtual world coordinate of sample
      See Also:
        `PointSound.setPosition(float x, float y, float z)`, `PointSound.setPosition(Point3f position)`

    - #### setDistanceGain

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

      Description copied from interface: `AudioDevice3D`
      Sets this sound's distance gain elliptical attenuation (not including filter cutoff frequency) by defining corresponding arrays containing distances from the sound's origin and gain scale factors applied to all active positional sounds. Gain scale factor is applied to sound based on the distance the listener is from sound source. These attenuation parameters are ignored for BackgroundSound nodes. The back attenuation parameter is ignored for PointSound nodes.

      The form of the attenuation parameters match that of the ConeSound method of the same name. A full description of this parameter and how it is used is in the documentation for ConeSound class.

      This method should only be called by Java3D Core and NOT by any application.

      Specified by:
        `setDistanceGain` in interface `AudioDevice3D`
      Parameters:
        `index` - device specific reference number to device driver sample
        `frontDistance` - defines an array of distance along positive axis through which ellipses pass
        `frontAttenuationScaleFactor` - gain scale factors
        `backDistance` - defines an array of distance along the negative axis through which ellipses pass
        `backAttenuationScaleFactor` - gain scale factors
      See Also:
        `ConeSound.setDistanceGain(float[] frontDistance, float[] frontGain, float[] backDistance, float[] backGain)`, `ConeSound.setDistanceGain(Point2f[] frontAttenuation, Point2f[] backAttenuation)`

    - #### setDirection

          public void setDirection(int index,
                          Vector3d direction)

      Set direction vector of sample.
      Specified by:
        `setDirection` in interface `AudioDevice3D`
      Parameters:
        `index` - device specific reference number to device driver sample
        `direction` - vector in virtual world coordinate.
      See Also:
        `ConeSound.setDirection(float x, float y, float z)`, `ConeSound.setDirection(Vector3f direction)`

    - #### 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 `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.
      See Also:
        `ConeSound.setAngularAttenuation(float[] distance, float[] gain, float[] filter)`, `ConeSound.setAngularAttenuation(Point3f[] attenuation)`, `ConeSound.setAngularAttenuation(Point2f[] attenuation)`

    - #### setRolloff

          public void setRolloff(float rolloff)

      Set rolloff value for current aural attribute applied to all samples.
      Specified by:
        `setRolloff` in interface `AudioDevice3D`
      Parameters:
        `rolloff` - scale factor applied to standard speed of sound.
      See Also:
        `AuralAttributes.setRolloff(float)`

    - #### 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 `AudioDevice3D`
      Parameters:
        `coefficient` - applied to amplitude of reverbation added at each iteration of reverb processing.
      See Also:
        `AuralAttributes.setReflectionCoefficient(float)`

    - #### setReverbDelay

          public void setReverbDelay(float reverbDelay)

      Set reverberation delay time for current aural attribute applied to all samples.
      Specified by:
        `setReverbDelay` in interface `AudioDevice3D`
      Parameters:
        `reverbDelay` - amount of time in millisecond between each iteration of reverb processing.
      See Also:
        `AuralAttributes.setReverbDelay(float reverbDelay)`

    - #### setReverbOrder

          public void setReverbOrder(int reverbOrder)

      Set reverberation order for current aural attribute applied to all samples.
      Specified by:
        `setReverbOrder` in interface `AudioDevice3D`
      Parameters:
        `reverbOrder` - number of times reverb process loop is iterated.
      See Also:
        `AuralAttributes.setReverbOrder(int)`

    - #### 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 `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.
        `filterCutoff` - array of frequency cutoff
      See Also:
        `AuralAttributes.setDistanceFilter(float[] distance, float[] frequencyCutoff)`, `AuralAttributes.setDistanceFilter(Point2f[] attenuation)`

    - #### setFrequencyScaleFactor

          public void setFrequencyScaleFactor(float scaleFactor)

      Set frequency scale factor for current aural attribute applied to all samples.
      Specified by:
        `setFrequencyScaleFactor` in interface `AudioDevice3D`
      Parameters:
        `scaleFactor` - frequency scale factor applied to samples normal playback rate.
      See Also:
        `AuralAttributes.setFrequencyScaleFactor(float)`

    - #### 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 `AudioDevice3D`
      Parameters:
        `scaleFactor` - scale factor applied to postional samples' listener-to-soundSource velocity. playback rate.
      See Also:
        `AuralAttributes.setVelocityScaleFactor(float)`

    - #### getNumberOfChannelsUsed

          public int getNumberOfChannelsUsed(int index)

      Get number of channels used by a particular sample on the audio device.
      Specified by:
        `getNumberOfChannelsUsed` in interface `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 `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 `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 `AudioDevice3D`
      Parameters:
        `index` - device specific reference number to device driver sample
      Returns:
        system clock time sample started

    - #### getSampleList

          protected java.util.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()

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.