auralattributes.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: AuralAttributes.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.6 $
 * $Date: 2007/02/09 17:17:50 $
 * $State: Exp $
 */

package javax.media.j3d;

import javax.vecmath.Point2f;

/**
 * The AuralAttributes object is a component object of a Soundscape node that
 * defines environmental audio parameters that affect sound rendering. These
 * attributes include gain scale factor, atmospheric rolloff, and parameters
 * controlling reverberation, distance frequency filtering, and velocity-based
 * Doppler effect.
 *<P>
 * Attribute Gain
 *   <P><UL>
 *    Scale factor applied to all sound's amplitude active within this region.
 *    This factor attenuates both direct and reflected/reverbered amplitudes.
 *    Valid values are >= 0.0
 *  </UL>
 *<P>
 * Attribute Gain Rolloff
 *   <P><UL>
 *    Rolloff scale factor is used to model atmospheric changes from normal
 *    speed of sound.  The base value, 0.344 meters/millisecond is used
 *    to approximate the speed of sound through air at room temperature, 
 *    is multipled by this scale factor whenever the speed of sound is
 *    applied during spatialization calculations.
 *    Valid values are >= 0.0.  Values > 1.0 increase the speed of sound,
 *    while values < 1.0 decrease its speed. A value of zero makes sound
 *    silent (but it continues to play).
 *   </UL>
 *<P>
 * Auralization <P>
 *<UL>
 *    Auralization is the environmental modeling of sound iteratively
 *    reflecting off the surfaces of the bounded region the listener is in.
 *    Auralization components include 
 *    early, distinct, low-order reflections and later, dense,
 *    higher-order reflections referred to as reverberation.
 *    These reflections are attenuated relative to the direct, unreflected 
 *    sound.  The difference in gain between direct and reflected sound
 *    gives the listener a sense of the surface material and 
 *    the relative distance of the sound.
 *    The delay between the start of the direct sound and start of 
 *    reverberation (as detected by the listener), 
 *    as well as the length of time reverberation is audible as it
 *    exponentially decays, give the listener a sense of the size of the 
 *    listening space.
 *   <P>
 *    In Java3D's model for auralization there are several parameters
 *    that approximate sound reflection and reverberation for a particular
 *    listening space:
 *     <UL>Reflection Coefficient  <UL>Gain attenuation of the initial
 *         reflections across all frequencies.</UL></UL>
 *     <UL>(Early) Reflection Delay  <UL>The time it takes for the first
 *         low-order reflected sound to reach the listener.</UL></UL>
 *     <UL>Reverb Coefficient  <UL>Gain attenuation of the late reflections
 *         (referred to as 'reverb') across all frequencies.</UL></UL>
 *     <UL>Reverb Delay  <UL>The time it takes for reverbered sound
 *         to reach the listener.</UL></UL>
 *     <UL>Decay Time <UL>Describes the reverb decay curve by defining the
 *         length of time reverb takes to decay to effective zero.
 *         </UL></UL>
 *     <UL>Decay Filter  <UL>High-frequencies of the late reverberation
 *         can be attenuated at a different rate. </UL></UL>
 *     <UL>Density  <UL>Modal density (spectral coloration) of
 *         reverberation.</UL></UL>
 *     <UL>Diffusion  <UL>Echo dispersement of reverberation.</UL></UL>
 *     <UL>Reverb Bounds  <UL>Approximates the volume of the listening space.
 *         If specified, it defines the reverberation delay.</UL></UL>
 *     <UL>Reverb Order  <UL>Optionally limits the amount of times during 
 *         reverb calculation that a sound is recursively reflected off the 
 *         bounding region.</UL></UL>
 *   <P>
 *    Reflection Coefficient
 *   <P><UL>
 *       The reflection coefficient is an amplitude scale factor used to
 *       approximate the average reflective or absorptive characteristics
 *       for early reflections
 *       of the composite surfaces in the region the listener is in.
 *       This scale factor is applied to the sound's amplitude regardless of the
 *       sound's position.  
 *       The range of valid values is 0.0 to 1.0.
 *       A value of 1.0 denotes that reflections are unattenuated -
 *       the amplitude of reflected sound waves are not decreased.
 *       A value of 0.0 represents full absorption of reflections
 *       by the surfaces in the listening space (no reflections occur
 *       thus reverberation is disabled).
 *     </UL>
 *   <P>
 *    Reflection Delay
 *   <P><UL>
 *       The early reflection delay time (in milliseconds) can be explicitly
 *       set.  Well-defined values are floats > 0.0.
 *       A value of 0.0 results in reverberation being added as soon as
 *       possible after the sound begins.
 *     </UL>
 *   <P>
 *    Reverberation Coefficient
 *   <P><UL>
 *       The reverb coefficient is an amplitude scale factor used to
 *       approximate the average reflective or absorptive characteristics
 *       of late reflections.
 *       A value of 0.0 represents full absorption of reflections
 *       by the surfaces in the listening space (no reflections occur
 *       thus reverberation is disabled).
 *     </UL>
 *   <P>
 *    Reverberation Delay
 *   <P><UL>
 *       The reverb delay time (in milliseconds) is set either explicitly,
 *       or implicitly by supplying a reverb bounds volume (from which the
 *       delay time can be calculated).  Well-defined values are floats > 0.0.
 *       A value of 0.0 results in reverberation being added as soon as
 *       possible after the sound begins.  Reverb delay, as calculated from non-
 *       null reverb bounds, takes precedence over explicitly set delay time.
 *     </UL>
 *   <P>
 *    Reverberation Bounds
 *   <P><UL>
 *       The reverb bounding region defines the overall size of space
 *       that reverberation is calculated for.
 *       This optional bounds does not have to be the same as the application
 *       region of the Soundscape node referencing this AuralAttributes object.
 *       If this bounding region is specified then reverb decay and delay are
 *       internally calculated from this bounds.
 *     </UL>
 *   <P>
 *    Reverberation Order
 *   <P><UL>
 *       The reverb order is a hint that can be used during reverberation
 *       to limit the number of late reflections required in calculation of
 *       reverb decay.
 *       All positive values can be interpreted during reverb rendering
 *       as the maximum order of reflections to be calculated.
 *       A non-positive value signifies that no limit is placed on the order of
 *       reflections calculated during reverberation rendering.
 *       In the case where reverb order is not limited, reverb decay is defined
 *       strictly by the Reverberation Decay Time parameter.
 *     </UL>
 *   <P>
 *    Decay Time
 *   <P><UL>
 *       The reverberation decay time explicitly defines the length of time in
 *       milliseconds it takes for the amplitude of late reflections to 
 *       exponentally decrease to effective zero.
 *       In the case where reverb delay is set non-positive
 *       the renderer will perform the shortest reverberation decay
 *       possible.
 *       If ReverbOrder is set, this parameter is clamped by the reverb
 *       time calculated as time = reverb Delay * reverb Order.
 *       If ReverbOrder is 0, the decay time parameter is not clamped.
 *     </UL>
 *   <P>
 *    Decay Filter
 *   <P><UL>
 *       The reverberation decay filter defines how frequencies above a given
 *       value are attenuated by the listening space.  This allows for modelling
 *       materials on surfaces that absorb high frequencies at a faster rate 
 *       than low frequencies.
 *     </UL>
 *   <P>
 *    Reverberation Diffusion
 *   <P><UL>
 *       The reverberation diffusion explicitly defines echo dispersement
 *       (sometimes refered to as echo density).  The value for diffusion
 *       is proportional to the number of echos per second heard in late
 *       reverberation, especially noticable at the tail of the reverberation
 *       decay.  The greater the diffusion the more 'natural' the reverberation
 *       decay sounds.  Reducing diffusion makes the decay sound hollow as 
 *       produced in a small highly reflecive space (such as a bathroom).
 *     </UL>
 *   <P>
 *    Reverberation Density
 *   <P><UL>
 *       The reverberation density explicitly defines modal reverb density 
 *       The value for this modal density is proportional to the number of
 *       resonances heard in late reverberation perceived as spectral 
 *       coloration.  The greater the density, the smoother, less grainy the
 *       later reverberation decay.
 *     </UL>
 *</UL>
 *<P>
 * Distance Filter
 *   <P><UL>
 *  This parameter specifies a (distance, filter) attenuation pairs array.
 *  If this is not set, no distance filtering is performed (equivalent to
 *  using a distance filter of Sound.NO_FILTER for all distances). Currently,
 *  this filter is a low-pass cutoff frequency. This array of pairs defines
 *  a piece-wise linear slope for range of values. This attenuation array is
 *  similar to the PointSound node's distanceAttenuation pair array, except
 *  paired with distances in this list are frequency values.  Using these
 *  pairs, distance-based low-pass frequency filtering can be applied during
 *  sound rendering. Distances, specified in the local coordinate system in
 *  meters, must be > 0. Frequencies (in Hz) must be > 0.
 *<P>
 *  If the distance from the listener to the sound source is less than the
 *  first distance in the array, the first filter is applied to the sound
 *  source.  This creates a spherical region around the listener within
 *  which a sound is uniformly attenuated by the first filter in the array.
 *  If the distance from the listener to the sound source is greater than
 *  the last distance in the array, the last filter is applied to the sound
 *  source.
 *   <P>
 *  Distance elements in these array of pairs is a monotonically-increasing
 *  set of floating point numbers measured from the location of the sound
 *  source.  FrequencyCutoff elements in this list of pairs can be any
 *  positive float. While for most applications this list of values will
 *  usually be monotonically-decreasing, they do not have to be.
 *   <P>
 *  The getDistanceFilterLength method returns the length of the distance filter
 *  arrays. Arrays passed into getDistanceFilter methods should all be at
 *  least this size.</UL>
 *   </UL><P>
 *  Doppler Effect Model
 *   <P><UL>
 *  Doppler effect can be used to create a greater sense of movement of
 *  sound sources, and can help reduce front-back localization errors.
 *  The frequency of sound waves emanating from the source are raised or
 *  lowered based on the speed of the source in relation to the listener,
 *  and several AuralAttribute parameters.
 *   <P>
 *  The FrequencyScaleFactor can be used to increase or reduce the change
 *  of frequency associated with normal Doppler calculation, or to shift
 *  the pitch of the sound directly if Doppler effect is disabled.
 *  Values must be > zero for sounds to be heard.  If the value is zero,
 *  sounds affected by this AuralAttribute object are paused.
 *   <P>
 *  To simulate Doppler effect, the relative velocity (change in 
 *  distance in the local coordinate system between the sound source and 
 *  the listener over time, in meters per second) is calculated. This
 *  calculated velocity is multipled by the given VelocityScaleFactor.
 *  Values must be >= zero.  If is a scale factor value of zero is given,
 *  Doppler effect is not calculated or applied to sound.</UL></UL>
 */
public class AuralAttributes extends NodeComponent {

     /**
      *
      *  Constants
      *
      * These flags, when enabled using the setCapability method, allow an
      * application to invoke methods that read or write its parameters.
      *
      */
     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the reading of it's attribute gain scale factor information.
      */
     public static final int
    ALLOW_ATTRIBUTE_GAIN_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ATTRIBUTE_GAIN_READ;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the writing of it's attribute gain scale factor information.
      */
     public static final int
    ALLOW_ATTRIBUTE_GAIN_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ATTRIBUTE_GAIN_WRITE;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the reading of it's atmospheric rolloff.
      */
     public static final int
    ALLOW_ROLLOFF_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ROLLOFF_READ;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the writing of it's atmospheric rolloff.
      */
     public static final int
    ALLOW_ROLLOFF_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ROLLOFF_WRITE;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the reading of it's reflection coefficient.
      */
     public static final int
    ALLOW_REFLECTION_COEFFICIENT_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_COEFFICIENT_READ;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the writing of it's reflection coefficient.
      */
     public static final int
    ALLOW_REFLECTION_COEFFICIENT_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_COEFFICIENT_WRITE;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the reading of it's reflection delay information.
      *
      * @since Java 3D 1.3
      */
     public static final int
    ALLOW_REFLECTION_DELAY_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_DELAY_READ;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the writing of it's reflection delay information.
      *
      * @since Java 3D 1.3
      */
     public static final int
    ALLOW_REFLECTION_DELAY_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_DELAY_WRITE;

     /**
      * For AuralAttributes component objects, specifies that this object
      * allows the reading of it's reverb coefficient.
      *
      * @since Java 3D 1.3
      */
     public static final int
    ALLOW_REVERB_COEFFICIENT_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_COEFFICIENT_READ;