auralattributesretained.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: AuralAttributesRetained.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.6 $
 * $Date: 2007/04/12 17:34:03 $
 * $State: Exp $
 */

package javax.media.j3d;

import java.util.Hashtable;
import javax.vecmath.Point2f;

/**
 * The AuralAttributesRetained object defines all rendering state that can
 * be set as a component object of a retained Soundscape node.
 */
class AuralAttributesRetained extends NodeComponentRetained {

     /**
      *  Gain Scale Factor applied to source with this attribute
      */
     float      attributeGain = 1.0f;      // Valid values are >= 0.0.
 
     /**
      * Atmospheric Rolloff - speed of sound - coeff
      *    Normal gain attenuation based on distance of sound from
      *    listener is scaled by a rolloff factor, which can increase
      *    or decrease the usual inverse-distance-square value.
      */
     float      rolloff = 1.0f;             // Valid values are >= 0.0
     static final float  SPEED_OF_SOUND  = 0.344f;  // in meters/milliseconds

     /*
      * Reverberation
      *
      *   Within Java 3D's model for auralization, the components to
      *   reverberation for a particular space are:
      *     Reflection and Reverb Coefficients - 
      *         attenuation of sound (uniform for all frequencies) due to 
      *         absorption of reflected sound off materials within the 
      *         listening space.
      *     Reflection and Reverb Delay - 
      *         approximating time from the start of the direct sound that
      *         initial early and late reflection waves take to reach listener.
      *     Reverb Decay - 
      *         approximating time from the start of the direct sound that
      *         reverberation is audible.
      */  

     /**
      *   Coefficients for reverberation
      *     The (early) Reflection and Reverberation coefficient scale factors
      *     are used to approximate the reflective/absorptive characteristics
      *     of the surfaces in this bounded Auralizaton environment.
      *     Theses scale factors is applied to sound's amplitude regardless
      *     of sound's position.
      *     Value of 1.0 represents complete (unattenuated) sound reflection.
      *     Value of 0.0 represents full absorption; reverberation is disabled.
      */
     float      reflectionCoefficient = 0.0f; // Range of values 0.0 to 1.0
     float      reverbCoefficient = 1.0f; // Range of values 0.0 to 1.0

     /**
       *  Time Delays in milliseconds
       *    Set with either explicitly with time, or impliciticly by supplying
       *    bounds volume and having the delay time calculated.
       *    Bounds of reverberation space does not have to be the same as
       *    Attribute bounds.
       */
     float      reflectionDelay = 20.0f;    // in milliseconds
     float      reverbDelay = 40.0f;        // in milliseconds
     Bounds     reverbBounds = null;

     /**
      *   Decay parameters
      *     Length and timbre of reverb decay tail 
      */
     float      decayTime = 1000.0f;        // in milliseconds
     float      decayFilter = 5000.0f;      // low-pass cutoff frequency
     
     /**
      *   Reverb Diffusion and Density ratios (0=min, 1=max)
      */
     float      diffusion = 1.0f;
     float      density = 1.0f;
     
     /**
      *   Reverberation order
      *     This limits the number of Reverberation iterations executed while
      *     sound is being reverberated.  As long as reflection coefficient is
      *     small enough, the reverberated sound decreases (as it would naturally)
      *     each successive iteration.
      *     Value of > zero defines the greatest reflection order to be used by
      *         the reverberator.
      *     All positive values are used as the number of loop iteration.
      *     Value of <= zero signifies that reverberation is to loop until reverb
      *         gain reaches zero (-60dB or 1/1000 of sound amplitude).
      */
     int      reverbOrder = 0;

     /**
      *   Distance Filter
      *   Each sound source is attenuated by a filter based on it's distance
      *   from the listener.
      *   For now the only supported filterType will be LOW_PASS frequency cutoff.
      *   At some time full FIR filtering will be supported.
      */  
     static final int  NO_FILTERING  = -1;
     static final int  LOW_PASS      =  1;

     int         filterType = NO_FILTERING;
     float[]     distance = null;
     float[]     frequencyCutoff = null;

     /**
      *   Doppler Effect parameters
      *     Between two snapshots of the head and sound source positions some
      *     delta time apart, the distance between head and source is compared.
      *     If there has been no change in the distance between head and sound
      *     source over this delta time:
      *         f' = f
      *      
      *     If there has been a change in the distance between head and sound:
      *         f' = f * Af * v
      *      
      *     When head and sound are moving towards each other then
      *                |  (S * Ar)  +  (deltaV(h,t) * Av) |
      *         v  =   | -------------------------------- |
      *                |  (S * Ar)  -  (deltaV(s,t) * Av)  |
      *     
      *     When head and sound are moving away from each other then
      *                |  (S * Ar)  -  (deltaV(h,t) * Av) |
      *         v  =   | -------------------------------- |
      *                |  (S * Ar)  +  (deltaV(s,t) * Av) |
      *     
      *     
      *     Af = AuralAttribute frequency scalefactor
      *     Ar = AuralAttribute rolloff scalefactor
      *     Av = AuralAttribute velocity scalefactor
      *     deltaV = delta velocity
      *     f = frequency of sound
      *     h = Listeners head position
      *     v = Ratio of delta velocities
      *     Vh = Vector from center ear to sound source
      *     S = Speed of sound
      *     s = Sound source position
      *     t = time
      *     
      *     If adjusted velocity of head or adjusted velocity of sound is 
      *     greater than adjusted speed of sound, f' is undefined.
      */
     /**
      *   Frequency Scale Factor
      *     used to increase or reduce the change of frequency associated
      *     with normal rate of playback.
      *     Value of zero causes sounds to be paused.
      */
     float      frequencyScaleFactor = 1.0f;
     /**
      *   Velocity Scale Factor
      *     Float value applied to the Change of distance between Sound Source 
      *     and Listener over some delta time.  Non-zero if listener moving 
      *     even if sound is not.  Value of zero implies no Doppler applied.
      */
     float      velocityScaleFactor = 0.0f;

     /**
      * This boolean is set when something changes in the attributes
      */
     boolean         aaDirty = true;

     /**
      * The mirror copy of this AuralAttributes.
      */
     AuralAttributesRetained mirrorAa = null;

    /**
     ** Debug print mechanism for Sound nodes
     **/ 
    static final // 'static final' so compiler doesn't include debugPrint calls
    boolean  debugFlag = false;

    static final  // 'static final' so internal error message are not compiled
    boolean internalErrors = false; 

    void debugPrint(String message) {
        if (debugFlag) // leave test in in case debugFlag made non-static final
            System.err.println(message);
    }


    // ****************************************
    //
    // Set and Get individual attribute values
    //
    // ****************************************

    /**
     * Set Attribute Gain (amplitude)
     * @param gain scale factor applied to amplitude 
     */
    void setAttributeGain(float gain) {
        this.attributeGain = gain;
	this.aaDirty = true;
	notifyUsers();
    }
    /**
     * Retrieve Attribute Gain (amplitude)
     * @return gain amplitude scale factor
     */
    float getAttributeGain() {
        return this.attributeGain;
    }

    /**
     * Set Attribute Gain Rolloff
     * @param rolloff atmospheric gain scale factor (changing speed of sound)
     */
    void setRolloff(float rolloff) {
        this.rolloff = rolloff;
	this.aaDirty = true;
	notifyUsers();
    }
    /**
     * Retrieve Attribute Gain Rolloff
     * @return rolloff atmospheric gain scale factor (changing speed of sound)
     */
    float getRolloff() {
        return this.rolloff;
    }

    /**
     * Set Reflective Coefficient
     * @param reflectionCoefficient reflection/absorption factor applied to 
     * early reflections.
     */
    void setReflectionCoefficient(float reflectionCoefficient) {
        this.reflectionCoefficient = reflectionCoefficient;
	this.aaDirty = true;
	notifyUsers();
    }
    /**
     * Retrieve Reflective Coefficient
     * @return reflection coeff reflection/absorption factor applied to 
     * early reflections.
     */
    float getReflectionCoefficient() {
        return this.reflectionCoefficient;
    }

    /**
     * Set Reflection Delay Time
     * @param reflectionDelay time before the start of early (first order)
     * reflections.
     */
    void setReflectionDelay(float reflectionDelay) {
        this.reflectionDelay = reflectionDelay;
	this.aaDirty = true;
	notifyUsers();
    }
    /**
     * Retrieve Reflection Delay Time
     * @return reflection delay time 
     */
    float getReflectionDelay() {
        return this.reflectionDelay;
    }

    /**
     * Set Reverb Coefficient
     * @param reverbCoefficient reflection/absorption factor applied to 
     * late reflections.
     */
    void setReverbCoefficient(float reverbCoefficient) {
        this.reverbCoefficient = reverbCoefficient;
	this.aaDirty = true;
	notifyUsers();
    }
    /**
     * Retrieve Reverb Coefficient
     * @return reverb coeff reflection/absorption factor applied to late
     * reflections.
     */
    float getReverbCoefficient() {
        return this.reverbCoefficient;
    }

    /**
     * Set Revereration Delay Time
     * @param reverbDelay time between each order of reflection
     */
    void setReverbDelay(float reverbDelay) {
        this.reverbDelay = reverbDelay;
	this.aaDirty = true;
	notifyUsers();
    }
    /**
     * Retrieve Revereration Delay Time
     * @return reverb delay time between each order of reflection
     */
    float getReverbDelay() {
        return this.reverbDelay;
    }
    /**
     * Set Decay Time
     * @param decayTime length of time reverb takes to decay
     */
    void setDecayTime(float decayTime) {
        this.decayTime = decayTime;
	this.aaDirty = true;
	notifyUsers();
    }
    /**
     * Retrieve Revereration Decay Time
     * @return reverb delay time 
     */
    float getDecayTime() {
        return this.decayTime;
    }

    /**
     * Set Decay Filter
     * @param decayFilter frequency referenced used in low-pass filtering