/*
* Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*
*/
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.
*
* Attribute Gain
*
* 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
*
*
* Attribute Gain Rolloff
*
* 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).
*
*
* Auralization
*
* 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.
*
* In Java3D's model for auralization there are several parameters
* that approximate sound reflection and reverberation for a particular
* listening space:
*
Reflection Coefficient Gain attenuation of the initial
* reflections across all frequencies.
* (Early) Reflection Delay The time it takes for the first
* low-order reflected sound to reach the listener.
* Reverb Coefficient Gain attenuation of the late reflections
* (referred to as 'reverb') across all frequencies.
* Reverb Delay The time it takes for reverbered sound
* to reach the listener.
* Decay Time Describes the reverb decay curve by defining the
* length of time reverb takes to decay to effective zero.
*
* Decay Filter High-frequencies of the late reverberation
* can be attenuated at a different rate.
* Density Modal density (spectral coloration) of
* reverberation.
* Diffusion Echo dispersement of reverberation.
* Reverb Bounds Approximates the volume of the listening space.
* If specified, it defines the reverberation delay.
* Reverb Order Optionally limits the amount of times during
* reverb calculation that a sound is recursively reflected off the
* bounding region.
*
* Reflection Coefficient
*
* 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).
*
*
* Reflection Delay
*
* 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.
*
*
* Reverberation Coefficient
*
* 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).
*
*
* Reverberation Delay
*
* 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.
*
*
* Reverberation Bounds
*
* 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.
*
*
* Reverberation Order
*
* 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.
*
*
* Decay Time
*
* 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.
*
*
* Decay Filter
*
* 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.
*
*
* Reverberation Diffusion
*
* 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).
*
*
* Reverberation Density
*
* 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.
*
*
*
* Distance Filter
*
* 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.
*
* 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.
*
* 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.
*
* The getDistanceFilterLength method returns the length of the distance filter
* arrays. Arrays passed into getDistanceFilter methods should all be at
* least this size.
*
* Doppler Effect Model
*
* 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.
*
* 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.
*
* 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.
*/
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;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's reverb coefficient.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_REVERB_COEFFICIENT_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_COEFFICIENT_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's reverberation delay information.
*/
public static final int
ALLOW_REVERB_DELAY_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_DELAY_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's reverberation delay information.
*/
public static final int
ALLOW_REVERB_DELAY_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_DELAY_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's reverb order (feedback loop) information.
*/
public static final int
ALLOW_REVERB_ORDER_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_ORDER_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's reverb order (feedback loop) information.
*/
public static final int
ALLOW_REVERB_ORDER_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_ORDER_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's reverb decay time information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DECAY_TIME_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_TIME_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's reverb decay time information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DECAY_TIME_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_TIME_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's reverb decay filter information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DECAY_FILTER_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_FILTER_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's reverb decay filter information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DECAY_FILTER_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_FILTER_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's reverb diffusion information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DIFFUSION_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DIFFUSION_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's reverb diffusion information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DIFFUSION_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DIFFUSION_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's reverb density information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DENSITY_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DENSITY_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's reverb density information.
*
* @since Java 3D 1.3
*/
public static final int
ALLOW_DENSITY_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DENSITY_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's frequency cutoff information.
*/
public static final int
ALLOW_DISTANCE_FILTER_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DISTANCE_FILTER_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's frequency cutoff information.
*/
public static final int
ALLOW_DISTANCE_FILTER_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DISTANCE_FILTER_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's frequency scale factor information.
*/
public static final int
ALLOW_FREQUENCY_SCALE_FACTOR_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_FREQUENCY_SCALE_FACTOR_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's frequency scale factor information.
*/
public static final int
ALLOW_FREQUENCY_SCALE_FACTOR_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_FREQUENCY_SCALE_FACTOR_WRITE;
/**
* For AuralAttributes component objects, specifies that this object
* allows the reading of it's velocity scale factor information.
*/
public static final int
ALLOW_VELOCITY_SCALE_FACTOR_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_VELOCITY_SCALE_FACTOR_READ;
/**
* For AuralAttributes component objects, specifies that this object
* allows the writing of it's velocity scale factor information.
*/
public static final int
ALLOW_VELOCITY_SCALE_FACTOR_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_VELOCITY_SCALE_FACTOR_WRITE;
// Array for setting default read capabilities
private static final int[] readCapabilities = {
ALLOW_ATTRIBUTE_GAIN_READ,
ALLOW_DECAY_FILTER_READ,
ALLOW_DECAY_TIME_READ,
ALLOW_DENSITY_READ,
ALLOW_DIFFUSION_READ,
ALLOW_DISTANCE_FILTER_READ,
ALLOW_FREQUENCY_SCALE_FACTOR_READ,
ALLOW_REFLECTION_COEFFICIENT_READ,
ALLOW_REFLECTION_DELAY_READ,
ALLOW_REVERB_COEFFICIENT_READ,
ALLOW_REVERB_DELAY_READ,
ALLOW_REVERB_ORDER_READ,
ALLOW_ROLLOFF_READ,
ALLOW_VELOCITY_SCALE_FACTOR_READ
};
/** *****************
*
* Constructors
*
* ******************/
/**
* Constructs and initializes a new AuralAttributes object using default
* parameters. The following default values are used:
*
* attribute gain: 1.0
* rolloff: 1.0
* reflection coeff: 0.0
* reflection delay: 20.0
* reverb coeff: 1.0
* reverb delay: 40.0
* decay time: 1000.0
* decay filter: 5000.0<>
* diffusion: 1.0
* density: 1.0
* reverb bounds: null
* reverb order: 0
* distance filtering: null (no filtering performed)
* frequency scale factor: 1.0
* velocity scale factor: 0.0
*
*/
public AuralAttributes() {
// Just use default values
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
}
/**
* Constructs and initializes a new AuralAttributes object using specified
* parameters including an array of Point2f for the distanceFilter.
* @param gain amplitude scale factor
* @param rolloff atmospheric (changing speed of sound) scale factor
* @param reflectionCoefficient reflective/absorptive factor applied to reflections
* @param reverbDelay delay time before start of reverberation
* @param reverbOrder limit to number of reflections added to reverb signal
* @param distanceFilter frequency cutoff
* @param frequencyScaleFactor applied to change of pitch
* @param velocityScaleFactor applied to velocity of sound in relation to listener
*/
public AuralAttributes(float gain,
float rolloff,
float reflectionCoefficient,
float reverbDelay,
int reverbOrder,
Point2f[] distanceFilter,
float frequencyScaleFactor,
float velocityScaleFactor) {
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
((AuralAttributesRetained)this.retained).setAttributeGain(gain);
((AuralAttributesRetained)this.retained).setRolloff(rolloff);
((AuralAttributesRetained)this.retained).setReflectionCoefficient(
reflectionCoefficient);
((AuralAttributesRetained)this.retained).setReverbDelay(reverbDelay);
((AuralAttributesRetained)this.retained).setReverbOrder(reverbOrder);
((AuralAttributesRetained)this.retained).setDistanceFilter(
distanceFilter);
((AuralAttributesRetained)this.retained).setFrequencyScaleFactor(
frequencyScaleFactor);
((AuralAttributesRetained)this.retained).setVelocityScaleFactor(
velocityScaleFactor);
}
/**
* Constructs and initializes a new AuralAttributes object using specified
* parameters with separate float arrays for components of distanceFilter.
* @param gain amplitude scale factor
* @param rolloff atmospheric (changing speed of sound) scale factor
* @param reflectionCoefficient reflection/absorption factor applied to reflections
* @param reverbDelay delay time before start of reverberation
* @param reverbOrder limit to number of reflections added to reverb signal
* @param distance filter frequency cutoff distances
* @param frequencyCutoff distance filter frequency cutoff
* @param frequencyScaleFactor applied to velocity/wave-length
* @param velocityScaleFactor applied to velocity of sound in relation to listener
*/
public AuralAttributes(float gain,
float rolloff,
float reflectionCoefficient,
float reverbDelay,
int reverbOrder,
float[] distance,
float[] frequencyCutoff,
float frequencyScaleFactor,
float velocityScaleFactor) {
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
((AuralAttributesRetained)this.retained).setAttributeGain(gain);
((AuralAttributesRetained)this.retained).setRolloff(rolloff);
((AuralAttributesRetained)this.retained).setReflectionCoefficient(
reflectionCoefficient);
((AuralAttributesRetained)this.retained).setReverbDelay(reverbDelay);
((AuralAttributesRetained)this.retained).setReverbOrder(reverbOrder);
((AuralAttributesRetained)this.retained).setDistanceFilter(distance,
frequencyCutoff);
((AuralAttributesRetained)this.retained).setFrequencyScaleFactor(
frequencyScaleFactor);
((AuralAttributesRetained)this.retained).setVelocityScaleFactor(
velocityScaleFactor);
}
/**
* Constructs and initializes a new AuralAttributes object using specified
* parameters with separate float arrays for components of distanceFilter
* and full reverb parameters.
* @param gain amplitude scale factor
* @param rolloff atmospheric (changing speed of sound) scale factor
* @param reflectionCoefficient factor applied to early reflections
* @param reflectionDelay delay time before start of early reflections
* @param reverbCoefficient factor applied to late reflections
* @param reverbDelay delay time before start of late reverberation
* @param decayTime time (in milliseconds) reverb takes to decay to -60bD
* @param decayFilter reverb decay filter frequency cutoff
* @param diffusion percentage of echo dispersement between min and max
* @param density percentage of modal density between min and max
* @param distance filter frequency cutoff distances
* @param frequencyCutoff distance filter frequency cutoff
* @param frequencyScaleFactor applied to velocity/wave-length
* @param velocityScaleFactor applied to velocity of sound in relation to listener
* @since Java 3D 1.3
*/
public AuralAttributes(float gain,
float rolloff,
float reflectionCoefficient,
float reflectionDelay,
float reverbCoefficient,
float reverbDelay,
float decayTime,
float decayFilter,
float diffusion,
float density,
float[] distance,
float[] frequencyCutoff,
float frequencyScaleFactor,
float velocityScaleFactor) {
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
((AuralAttributesRetained)this.retained).setAttributeGain(gain);
((AuralAttributesRetained)this.retained).setRolloff(rolloff);
((AuralAttributesRetained)this.retained).setReflectionCoefficient(
reflectionCoefficient);
((AuralAttributesRetained)this.retained).setReflectionDelay(
reflectionDelay);
((AuralAttributesRetained)this.retained).setReverbCoefficient(
reverbCoefficient);
((AuralAttributesRetained)this.retained).setReverbDelay(
reverbDelay);
((AuralAttributesRetained)this.retained).setDecayTime(decayTime);
((AuralAttributesRetained)this.retained).setDecayFilter(decayFilter);
((AuralAttributesRetained)this.retained).setDiffusion(diffusion);
((AuralAttributesRetained)this.retained).setDensity(density);
((AuralAttributesRetained)this.retained).setDistanceFilter(distance,
frequencyCutoff);
((AuralAttributesRetained)this.retained).setFrequencyScaleFactor(
frequencyScaleFactor);
((AuralAttributesRetained)this.retained).setVelocityScaleFactor(
velocityScaleFactor);
}
/**
* Creates the retained mode AuralAttributesRetained object that this
* component object will point to.
*/
@Override
void createRetained() {
this.retained = new AuralAttributesRetained();
this.retained.setSource(this);
}
/** ****************************************
*
* Attribute Gain
*
* ****************************************/
/**
* Set Attribute Gain (amplitude) scale factor.
* @param gain scale factor applied to amplitude of direct and reflected sound
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setAttributeGain(float gain) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_ATTRIBUTE_GAIN_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes0"));
((AuralAttributesRetained)this.retained).setAttributeGain(gain);
}
/**
* Retrieve Attribute Gain (amplitude).
* @return gain amplitude scale factor
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public float getAttributeGain() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_ATTRIBUTE_GAIN_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes1"));
return ((AuralAttributesRetained)this.retained).getAttributeGain();
}
/**
* Set Attribute Gain Rolloff.
* @param rolloff atmospheric gain scale factor (changing speed of sound)
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setRolloff(float rolloff) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_ROLLOFF_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes2"));
((AuralAttributesRetained)this.retained).setRolloff(rolloff);
}
/**
* Retrieve Attribute Gain Rolloff.
* @return rolloff atmospheric gain scale factor (changing speed of sound)
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public float getRolloff() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_ROLLOFF_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes3"));
return ((AuralAttributesRetained)this.retained).getRolloff();
}
/**
* Set Reflective Coefficient.
* Scales the amplitude of the early reflections of reverberated sounds
* @param coefficient reflection/absorption factor applied to reflections
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setReflectionCoefficient(float coefficient) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REFLECTION_COEFFICIENT_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes4"));
((AuralAttributesRetained)this.retained).setReflectionCoefficient(coefficient);
}
/**
* Retrieve Reflective Coefficient.
* @return reflection coeff reflection/absorption factor
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public float getReflectionCoefficient() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REFLECTION_COEFFICIENT_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes21"));
return ((AuralAttributesRetained)this.retained).getReflectionCoefficient();
}
/*********************
*
* Early Reflection Delay
*
********************/
/**
* Set early Refection Delay Time.
* In this form, the parameter specifies the time between the start of the
* direct, unreflected sound and the start of first order early reflections.
* In this method, this time is explicitly given in milliseconds.
* @param reflectionDelay delay time before start of reverberation
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public void setReflectionDelay(float reflectionDelay) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REFLECTION_DELAY_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes22"));
((AuralAttributesRetained)this.retained).setReflectionDelay(reflectionDelay);
}
/**
* Retrieve Reflection Delay Time.
* @return reflection delay time
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public float getReflectionDelay() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REFLECTION_DELAY_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes23"));
return ((AuralAttributesRetained)this.retained).getReflectionDelay();
}
/** ******************
*
* Reverb Coefficient
*
********************/
/**
* Set Reverb Coefficient.
* Scale the amplitude of the late reflections including the decaying tail
* of reverberated sound.
* @param coefficient reflective/absorptive factor applied to late reflections
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public void setReverbCoefficient(float coefficient) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_COEFFICIENT_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes24"));
((AuralAttributesRetained)this.retained).setReverbCoefficient(coefficient);
}
/**
* Retrieve Reverb Coefficient.
* @return late reflection coeff. reflection/absorption factor
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public float getReverbCoefficient() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_COEFFICIENT_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes25"));
return ((AuralAttributesRetained)this.retained).getReverbCoefficient();
}
/*********************
*
* Reverberation Delay
*
********************/
/**
* Set Reverberation Delay Time.
* In this form, the parameter specifies the time between the start of the
* direct, unreflected sound and the start of reverberation. In this
* method, this time is explicitly given in milliseconds.
* @param reverbDelay delay time before start of reverberation
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setReverbDelay(float reverbDelay) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_DELAY_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes5"));
((AuralAttributesRetained)this.retained).setReverbDelay(reverbDelay);
}
/**
* Retrieve Reverberation Delay Time.
* @return reverb delay time
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public float getReverbDelay() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_DELAY_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes7"));
return ((AuralAttributesRetained)this.retained).getReverbDelay();
}
/** ******************
*
* Decay Time
*
********************/
/**
* Set Decay Time
* Length of time from the start of late reflections reverberation volume
* takes to decay to effective zero (-60 dB of initial signal amplitude).
* @param decayTime of late reflections (reverb) in milliseconds
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public void setDecayTime(float decayTime) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DECAY_TIME_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes28"));
((AuralAttributesRetained)this.retained).setDecayTime(decayTime);
}
/**
* Retrieve Decay Time.
* @return reverb decay time
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public float getDecayTime() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DECAY_TIME_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes29"));
return ((AuralAttributesRetained)this.retained).getDecayTime();
}
/** ******************
*
* Decay Filter
*
********************/
/**
* Set Decay Filter
* In this form, reverberation decay filtering is defined as a low-pass
* filter, starting at the given reference frequency. This allows for
* higher frequencies to be attenuated at a different (typically faster)
* rate than lower frequencies.
* @param frequencyCutoff of reverberation decay low-pass filter
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public void setDecayFilter(float frequencyCutoff) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DECAY_FILTER_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes30"));
((AuralAttributesRetained)this.retained).setDecayFilter(frequencyCutoff);
}
/**
* Retrieve Decay Filter.
* @return reverb decay filter cutoff frequency
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public float getDecayFilter() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DECAY_FILTER_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes31"));
return ((AuralAttributesRetained)this.retained).getDecayFilter();
}
/** ******************
*
* Diffusion
*
********************/
/**
* Set Diffusion.
* Sets the echo dispersement of reverberation to an amount between
* the minimum (0.0) to the maximum (1.0) available. Changing this
* increases/decreases the 'smoothness' of reverb decay.
* @param ratio reverberation echo dispersement factor
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public void setDiffusion(float ratio) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DIFFUSION_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes32"));
((AuralAttributesRetained)this.retained).setDiffusion(ratio);
}
/**
* Retrieve Diffusion.
* @return reverb diffusion ratio
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public float getDiffusion() {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_DIFFUSION_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes33"));
return ((AuralAttributesRetained)this.retained).getDiffusion();
}
/** ******************
*
* Density
*
********************/
/**
* Set Density.
* Sets the density of reverberation to an amount between
* the minimum (0.0) to the maximum (1.0) available. Changing this
* effects the spectral coloration (timbre) of late reflections.
* @param ratio reverberation modal density factor
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public void setDensity(float ratio) {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_DENSITY_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes34"));
((AuralAttributesRetained)this.retained).setDensity(ratio);
}
/**
* Retrieve Density.
* @return reverb density
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.3
*/
public float getDensity() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DENSITY_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes35"));
return ((AuralAttributesRetained)this.retained).getDensity();
}
/**
* @deprecated As of Java 3D version 1.2, replaced by
* setReverbBounds(Bounds)
*/
public void setReverbDelay(Bounds reverbVolume) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_DELAY_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes5"));
((AuralAttributesRetained)this.retained).setReverbBounds(reverbVolume);
}
/**
* Set Reverberation Bounds volume.
* In this form, the reverberation bounds volume parameter is used to
* calculate the reverberation Delay and Decay times. Specification
* of a non-null bounding volume causes the explicit values given for
* Reverb Delay and Decay to be overridden by the implicit values
* calculated from these bounds.
* ALLOW_REVERB_DELAY_WRITE flag used setting capability of this method.
* @param reverbVolume the bounding region
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.2
*/
public void setReverbBounds(Bounds reverbVolume) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_DELAY_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes26"));
((AuralAttributesRetained)this.retained).setReverbBounds(reverbVolume);
}
/**
* Retrieve Reverberation Delay Bounds volume.
* @return reverb bounds volume that defines the Reverberation space and
* indirectly the delay/decay
* ALLOW_REVERB_DELAY_READ flag used setting capability of this method.
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @since Java 3D 1.2
*/
public Bounds getReverbBounds() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_DELAY_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes27"));
return ((AuralAttributesRetained)this.retained).getReverbBounds();
}
/** *******************
*
* Reverberation Order
*
********************/
/**
* Set Reverberation Order
* This parameter limits the number of times reflections are added
* to the reverberation being rendered.
* A non-positive value specifies an unbounded number of reflections.
* @param reverbOrder limit to the number of times reflections added to reverb signal
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setReverbOrder(int reverbOrder) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_REVERB_ORDER_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes8"));
((AuralAttributesRetained)this.retained).setReverbOrder(reverbOrder);
}
/**
* Retrieve Reverberation Order
* @return reverb order
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public int getReverbOrder() {
if (!this.getCapability(ALLOW_REVERB_ORDER_READ))
if (isLiveOrCompiled())
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes9"));
return ((AuralAttributesRetained)this.retained).getReverbOrder();
}
/**
* Set Distance Filter using a single array containing distances and
* frequency cutoff as pairs of values as a single array of Point2f.
* @param attenuation array of pairs of distance and frequency cutoff
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setDistanceFilter(Point2f[] attenuation) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DISTANCE_FILTER_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes10"));
((AuralAttributesRetained)this.retained).setDistanceFilter(attenuation);
}
/**
* Set Distance Filter using separate arrays for distances and frequency
* cutoff. The distance and frequencyCutoff arrays should be of the same
* length. If the frequencyCutoff array length is greater than the distance
* array length, the frequencyCutoff array elements beyond the length of
* the distance array are ignored. If the frequencyCutoff array is shorter
* than the distance array, the last frequencyCutoff array value is repeated
* to fill an array of length equal to distance array.
* @param distance array of float distance with corresponding cutoff values
* @param frequencyCutoff array of frequency cutoff values in Hertz
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setDistanceFilter(float[] distance,
float[] frequencyCutoff) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DISTANCE_FILTER_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes10"));
((AuralAttributesRetained)this.retained).setDistanceFilter(
distance, frequencyCutoff );
}
/**
* Retrieve Distance Filter array length.
* @return attenuation array length
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public int getDistanceFilterLength() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DISTANCE_FILTER_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes12"));
return (((AuralAttributesRetained)this.retained).getDistanceFilterLength());
}
/**
* Retrieve Distance Filter as a single array containing distances
* and frequency cutoff. The distance filter is copied into
* the specified array.
* The array must be large enough to hold all of the points.
* The individual array elements must be allocated by the caller.
* @param attenuation array of pairs of distance and frequency cutoff values
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void getDistanceFilter(Point2f[] attenuation) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DISTANCE_FILTER_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes12"));
((AuralAttributesRetained)this.retained).getDistanceFilter(attenuation);
}
/**
* Retrieve Distance Filter in separate distance and frequency cutoff arrays.
* The arrays must be large enough to hold all of the distance
* and frequency cutoff values.
* @param distance array
* @param frequencyCutoff cutoff array
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void getDistanceFilter(float[] distance,
float[] frequencyCutoff) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_DISTANCE_FILTER_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes12"));
((AuralAttributesRetained)this.retained).getDistanceFilter(
distance, frequencyCutoff);
}
/**
* This parameter specifies a scale factor applied to the frequency
* of sound during rendering playback. If the Doppler effect is
* disabled, this scale factor can be used to increase or
* decrease the original pitch of the sound. During rendering,
* this scale factor expands or contracts the usual frequency shift
* applied to the sound source due to Doppler calculations.
* Valid values are >= 0.0.
* A value of zero causes playing sounds to pause.
* @param frequencyScaleFactor factor applied to change of frequency
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setFrequencyScaleFactor(float frequencyScaleFactor) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_FREQUENCY_SCALE_FACTOR_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes15"));
((AuralAttributesRetained)this.retained).setFrequencyScaleFactor(
frequencyScaleFactor);
}
/**
* Retrieve Frequency Scale Factor.
* @return scaleFactor factor applied to change of frequency
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public float getFrequencyScaleFactor() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_FREQUENCY_SCALE_FACTOR_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes17"));
return ((AuralAttributesRetained)this.retained).getFrequencyScaleFactor();
}
/** ******************************
*
* Velocity Scale Factor
*
*********************************/
/**
* Set Velocity scale factor applied during Doppler Effect calculation.
* This parameter specifies a scale factor applied to the velocity of
* the sound relative to the listener's position and movement in relation
* to the sound's position and movement. This scale factor is multipled
* by the calculated velocity portion of the Doppler effect equation used
* during sound rendering.
* A value of zero disables Doppler calculations.
* @param velocityScaleFactor applied to velocity of sound in relation
* to listener
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setVelocityScaleFactor(float velocityScaleFactor) {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_VELOCITY_SCALE_FACTOR_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes19"));
((AuralAttributesRetained)this.retained).setVelocityScaleFactor(
velocityScaleFactor);
}
/**
* Retrieve Velocity Scale Factor used to calculate Doppler Effect.
* @return scale factor applied to Doppler velocity of sound
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public float getVelocityScaleFactor() {
if (isLiveOrCompiled())
if (!this.getCapability(ALLOW_VELOCITY_SCALE_FACTOR_READ))
throw new CapabilityNotSetException(J3dI18N.getString("AuralAttributes20"));
return ((AuralAttributesRetained)this.retained).getVelocityScaleFactor();
}
/**
* @deprecated As of Java 3D version 1.2, replaced by
* cloneNodeComponent(boolean forceDuplicate)
*/
@Override
public NodeComponent cloneNodeComponent() {
AuralAttributes a = new AuralAttributes();
a.duplicateNodeComponent(this, this.forceDuplicate);
return a;
}
/**
* Copies all AuralAttributes information from originalNodeComponent into
* the current node. This method is called from the
* duplicateNode method. This routine does
* the actual duplication of all "local data" (any data defined in
* this object).
*
* @param originalNodeComponent the original node to duplicate.
* @param forceDuplicate when set to true, causes the
* duplicateOnCloneTree flag to be ignored. When
* false, the value of each node's
* duplicateOnCloneTree variable determines whether
* NodeComponent data is duplicated or copied.
*
* @see Node#cloneTree
* @see NodeComponent#setDuplicateOnCloneTree
*/
@Override
void duplicateAttributes(NodeComponent originalNodeComponent,
boolean forceDuplicate) {
super.duplicateAttributes(originalNodeComponent,
forceDuplicate);
AuralAttributesRetained aural = (AuralAttributesRetained) originalNodeComponent.retained;
AuralAttributesRetained rt = (AuralAttributesRetained) retained;
rt.setAttributeGain(aural.getAttributeGain());
rt.setRolloff(aural.getRolloff());
rt.setReflectionCoefficient(aural.getReflectionCoefficient());
rt.setReverbDelay(aural.getReverbDelay());
rt.setReverbOrder(aural.getReverbOrder());
rt.setReverbBounds(aural.getReverbBounds());
rt.setFrequencyScaleFactor(aural.getFrequencyScaleFactor());
rt.setVelocityScaleFactor(aural.getVelocityScaleFactor());
int len = aural.getDistanceFilterLength();
float distance[] = new float[len];
float frequencyCutoff[] = new float[len];
aural.getDistanceFilter(distance, frequencyCutoff);
rt.setDistanceFilter(distance, frequencyCutoff);
}
}