Class 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 Detail

      • samples

        protected java.util.ArrayList samples
      • currentView

        protected View currentView
        Current View sound is being rendered
    • 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)
      • 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)
      • 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)
      • 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)
      • 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