0001: /*
0002: * $RCSfile: AuralAttributes.java,v $
0003: *
0004: * Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
0005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
0006: *
0007: * This code is free software; you can redistribute it and/or modify it
0008: * under the terms of the GNU General Public License version 2 only, as
0009: * published by the Free Software Foundation. Sun designates this
0010: * particular file as subject to the "Classpath" exception as provided
0011: * by Sun in the LICENSE file that accompanied this code.
0012: *
0013: * This code is distributed in the hope that it will be useful, but WITHOUT
0014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0016: * version 2 for more details (a copy is included in the LICENSE file that
0017: * accompanied this code).
0018: *
0019: * You should have received a copy of the GNU General Public License version
0020: * 2 along with this work; if not, write to the Free Software Foundation,
0021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
0022: *
0023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
0024: * CA 95054 USA or visit www.sun.com if you need additional information or
0025: * have any questions.
0026: *
0027: * $Revision: 1.7 $
0028: * $Date: 2008/02/28 20:17:19 $
0029: * $State: Exp $
0030: */
0031:
0032: package javax.media.j3d;
0033:
0034: import javax.vecmath.Point2f;
0035:
0036: /**
0037: * The AuralAttributes object is a component object of a Soundscape node that
0038: * defines environmental audio parameters that affect sound rendering. These
0039: * attributes include gain scale factor, atmospheric rolloff, and parameters
0040: * controlling reverberation, distance frequency filtering, and velocity-based
0041: * Doppler effect.
0042: *<P>
0043: * Attribute Gain
0044: * <P><UL>
0045: * Scale factor applied to all sound's amplitude active within this region.
0046: * This factor attenuates both direct and reflected/reverbered amplitudes.
0047: * Valid values are >= 0.0
0048: * </UL>
0049: *<P>
0050: * Attribute Gain Rolloff
0051: * <P><UL>
0052: * Rolloff scale factor is used to model atmospheric changes from normal
0053: * speed of sound. The base value, 0.344 meters/millisecond is used
0054: * to approximate the speed of sound through air at room temperature,
0055: * is multipled by this scale factor whenever the speed of sound is
0056: * applied during spatialization calculations.
0057: * Valid values are >= 0.0. Values > 1.0 increase the speed of sound,
0058: * while values < 1.0 decrease its speed. A value of zero makes sound
0059: * silent (but it continues to play).
0060: * </UL>
0061: *<P>
0062: * Auralization <P>
0063: *<UL>
0064: * Auralization is the environmental modeling of sound iteratively
0065: * reflecting off the surfaces of the bounded region the listener is in.
0066: * Auralization components include
0067: * early, distinct, low-order reflections and later, dense,
0068: * higher-order reflections referred to as reverberation.
0069: * These reflections are attenuated relative to the direct, unreflected
0070: * sound. The difference in gain between direct and reflected sound
0071: * gives the listener a sense of the surface material and
0072: * the relative distance of the sound.
0073: * The delay between the start of the direct sound and start of
0074: * reverberation (as detected by the listener),
0075: * as well as the length of time reverberation is audible as it
0076: * exponentially decays, give the listener a sense of the size of the
0077: * listening space.
0078: * <P>
0079: * In Java3D's model for auralization there are several parameters
0080: * that approximate sound reflection and reverberation for a particular
0081: * listening space:
0082: * <UL>Reflection Coefficient <UL>Gain attenuation of the initial
0083: * reflections across all frequencies.</UL></UL>
0084: * <UL>(Early) Reflection Delay <UL>The time it takes for the first
0085: * low-order reflected sound to reach the listener.</UL></UL>
0086: * <UL>Reverb Coefficient <UL>Gain attenuation of the late reflections
0087: * (referred to as 'reverb') across all frequencies.</UL></UL>
0088: * <UL>Reverb Delay <UL>The time it takes for reverbered sound
0089: * to reach the listener.</UL></UL>
0090: * <UL>Decay Time <UL>Describes the reverb decay curve by defining the
0091: * length of time reverb takes to decay to effective zero.
0092: * </UL></UL>
0093: * <UL>Decay Filter <UL>High-frequencies of the late reverberation
0094: * can be attenuated at a different rate. </UL></UL>
0095: * <UL>Density <UL>Modal density (spectral coloration) of
0096: * reverberation.</UL></UL>
0097: * <UL>Diffusion <UL>Echo dispersement of reverberation.</UL></UL>
0098: * <UL>Reverb Bounds <UL>Approximates the volume of the listening space.
0099: * If specified, it defines the reverberation delay.</UL></UL>
0100: * <UL>Reverb Order <UL>Optionally limits the amount of times during
0101: * reverb calculation that a sound is recursively reflected off the
0102: * bounding region.</UL></UL>
0103: * <P>
0104: * Reflection Coefficient
0105: * <P><UL>
0106: * The reflection coefficient is an amplitude scale factor used to
0107: * approximate the average reflective or absorptive characteristics
0108: * for early reflections
0109: * of the composite surfaces in the region the listener is in.
0110: * This scale factor is applied to the sound's amplitude regardless of the
0111: * sound's position.
0112: * The range of valid values is 0.0 to 1.0.
0113: * A value of 1.0 denotes that reflections are unattenuated -
0114: * the amplitude of reflected sound waves are not decreased.
0115: * A value of 0.0 represents full absorption of reflections
0116: * by the surfaces in the listening space (no reflections occur
0117: * thus reverberation is disabled).
0118: * </UL>
0119: * <P>
0120: * Reflection Delay
0121: * <P><UL>
0122: * The early reflection delay time (in milliseconds) can be explicitly
0123: * set. Well-defined values are floats > 0.0.
0124: * A value of 0.0 results in reverberation being added as soon as
0125: * possible after the sound begins.
0126: * </UL>
0127: * <P>
0128: * Reverberation Coefficient
0129: * <P><UL>
0130: * The reverb coefficient is an amplitude scale factor used to
0131: * approximate the average reflective or absorptive characteristics
0132: * of late reflections.
0133: * A value of 0.0 represents full absorption of reflections
0134: * by the surfaces in the listening space (no reflections occur
0135: * thus reverberation is disabled).
0136: * </UL>
0137: * <P>
0138: * Reverberation Delay
0139: * <P><UL>
0140: * The reverb delay time (in milliseconds) is set either explicitly,
0141: * or implicitly by supplying a reverb bounds volume (from which the
0142: * delay time can be calculated). Well-defined values are floats > 0.0.
0143: * A value of 0.0 results in reverberation being added as soon as
0144: * possible after the sound begins. Reverb delay, as calculated from non-
0145: * null reverb bounds, takes precedence over explicitly set delay time.
0146: * </UL>
0147: * <P>
0148: * Reverberation Bounds
0149: * <P><UL>
0150: * The reverb bounding region defines the overall size of space
0151: * that reverberation is calculated for.
0152: * This optional bounds does not have to be the same as the application
0153: * region of the Soundscape node referencing this AuralAttributes object.
0154: * If this bounding region is specified then reverb decay and delay are
0155: * internally calculated from this bounds.
0156: * </UL>
0157: * <P>
0158: * Reverberation Order
0159: * <P><UL>
0160: * The reverb order is a hint that can be used during reverberation
0161: * to limit the number of late reflections required in calculation of
0162: * reverb decay.
0163: * All positive values can be interpreted during reverb rendering
0164: * as the maximum order of reflections to be calculated.
0165: * A non-positive value signifies that no limit is placed on the order of
0166: * reflections calculated during reverberation rendering.
0167: * In the case where reverb order is not limited, reverb decay is defined
0168: * strictly by the Reverberation Decay Time parameter.
0169: * </UL>
0170: * <P>
0171: * Decay Time
0172: * <P><UL>
0173: * The reverberation decay time explicitly defines the length of time in
0174: * milliseconds it takes for the amplitude of late reflections to
0175: * exponentally decrease to effective zero.
0176: * In the case where reverb delay is set non-positive
0177: * the renderer will perform the shortest reverberation decay
0178: * possible.
0179: * If ReverbOrder is set, this parameter is clamped by the reverb
0180: * time calculated as time = reverb Delay * reverb Order.
0181: * If ReverbOrder is 0, the decay time parameter is not clamped.
0182: * </UL>
0183: * <P>
0184: * Decay Filter
0185: * <P><UL>
0186: * The reverberation decay filter defines how frequencies above a given
0187: * value are attenuated by the listening space. This allows for modelling
0188: * materials on surfaces that absorb high frequencies at a faster rate
0189: * than low frequencies.
0190: * </UL>
0191: * <P>
0192: * Reverberation Diffusion
0193: * <P><UL>
0194: * The reverberation diffusion explicitly defines echo dispersement
0195: * (sometimes refered to as echo density). The value for diffusion
0196: * is proportional to the number of echos per second heard in late
0197: * reverberation, especially noticable at the tail of the reverberation
0198: * decay. The greater the diffusion the more 'natural' the reverberation
0199: * decay sounds. Reducing diffusion makes the decay sound hollow as
0200: * produced in a small highly reflecive space (such as a bathroom).
0201: * </UL>
0202: * <P>
0203: * Reverberation Density
0204: * <P><UL>
0205: * The reverberation density explicitly defines modal reverb density
0206: * The value for this modal density is proportional to the number of
0207: * resonances heard in late reverberation perceived as spectral
0208: * coloration. The greater the density, the smoother, less grainy the
0209: * later reverberation decay.
0210: * </UL>
0211: *</UL>
0212: *<P>
0213: * Distance Filter
0214: * <P><UL>
0215: * This parameter specifies a (distance, filter) attenuation pairs array.
0216: * If this is not set, no distance filtering is performed (equivalent to
0217: * using a distance filter of Sound.NO_FILTER for all distances). Currently,
0218: * this filter is a low-pass cutoff frequency. This array of pairs defines
0219: * a piece-wise linear slope for range of values. This attenuation array is
0220: * similar to the PointSound node's distanceAttenuation pair array, except
0221: * paired with distances in this list are frequency values. Using these
0222: * pairs, distance-based low-pass frequency filtering can be applied during
0223: * sound rendering. Distances, specified in the local coordinate system in
0224: * meters, must be > 0. Frequencies (in Hz) must be > 0.
0225: *<P>
0226: * If the distance from the listener to the sound source is less than the
0227: * first distance in the array, the first filter is applied to the sound
0228: * source. This creates a spherical region around the listener within
0229: * which a sound is uniformly attenuated by the first filter in the array.
0230: * If the distance from the listener to the sound source is greater than
0231: * the last distance in the array, the last filter is applied to the sound
0232: * source.
0233: * <P>
0234: * Distance elements in these array of pairs is a monotonically-increasing
0235: * set of floating point numbers measured from the location of the sound
0236: * source. FrequencyCutoff elements in this list of pairs can be any
0237: * positive float. While for most applications this list of values will
0238: * usually be monotonically-decreasing, they do not have to be.
0239: * <P>
0240: * The getDistanceFilterLength method returns the length of the distance filter
0241: * arrays. Arrays passed into getDistanceFilter methods should all be at
0242: * least this size.</UL>
0243: * </UL><P>
0244: * Doppler Effect Model
0245: * <P><UL>
0246: * Doppler effect can be used to create a greater sense of movement of
0247: * sound sources, and can help reduce front-back localization errors.
0248: * The frequency of sound waves emanating from the source are raised or
0249: * lowered based on the speed of the source in relation to the listener,
0250: * and several AuralAttribute parameters.
0251: * <P>
0252: * The FrequencyScaleFactor can be used to increase or reduce the change
0253: * of frequency associated with normal Doppler calculation, or to shift
0254: * the pitch of the sound directly if Doppler effect is disabled.
0255: * Values must be > zero for sounds to be heard. If the value is zero,
0256: * sounds affected by this AuralAttribute object are paused.
0257: * <P>
0258: * To simulate Doppler effect, the relative velocity (change in
0259: * distance in the local coordinate system between the sound source and
0260: * the listener over time, in meters per second) is calculated. This
0261: * calculated velocity is multipled by the given VelocityScaleFactor.
0262: * Values must be >= zero. If is a scale factor value of zero is given,
0263: * Doppler effect is not calculated or applied to sound.</UL></UL>
0264: */
0265: public class AuralAttributes extends NodeComponent {
0266:
0267: /**
0268: *
0269: * Constants
0270: *
0271: * These flags, when enabled using the setCapability method, allow an
0272: * application to invoke methods that read or write its parameters.
0273: *
0274: */
0275: /**
0276: * For AuralAttributes component objects, specifies that this object
0277: * allows the reading of it's attribute gain scale factor information.
0278: */
0279: public static final int ALLOW_ATTRIBUTE_GAIN_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ATTRIBUTE_GAIN_READ;
0280:
0281: /**
0282: * For AuralAttributes component objects, specifies that this object
0283: * allows the writing of it's attribute gain scale factor information.
0284: */
0285: public static final int ALLOW_ATTRIBUTE_GAIN_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ATTRIBUTE_GAIN_WRITE;
0286:
0287: /**
0288: * For AuralAttributes component objects, specifies that this object
0289: * allows the reading of it's atmospheric rolloff.
0290: */
0291: public static final int ALLOW_ROLLOFF_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ROLLOFF_READ;
0292:
0293: /**
0294: * For AuralAttributes component objects, specifies that this object
0295: * allows the writing of it's atmospheric rolloff.
0296: */
0297: public static final int ALLOW_ROLLOFF_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_ROLLOFF_WRITE;
0298:
0299: /**
0300: * For AuralAttributes component objects, specifies that this object
0301: * allows the reading of it's reflection coefficient.
0302: */
0303: public static final int ALLOW_REFLECTION_COEFFICIENT_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_COEFFICIENT_READ;
0304:
0305: /**
0306: * For AuralAttributes component objects, specifies that this object
0307: * allows the writing of it's reflection coefficient.
0308: */
0309: public static final int ALLOW_REFLECTION_COEFFICIENT_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_COEFFICIENT_WRITE;
0310:
0311: /**
0312: * For AuralAttributes component objects, specifies that this object
0313: * allows the reading of it's reflection delay information.
0314: *
0315: * @since Java 3D 1.3
0316: */
0317: public static final int ALLOW_REFLECTION_DELAY_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_DELAY_READ;
0318:
0319: /**
0320: * For AuralAttributes component objects, specifies that this object
0321: * allows the writing of it's reflection delay information.
0322: *
0323: * @since Java 3D 1.3
0324: */
0325: public static final int ALLOW_REFLECTION_DELAY_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REFLECTION_DELAY_WRITE;
0326:
0327: /**
0328: * For AuralAttributes component objects, specifies that this object
0329: * allows the reading of it's reverb coefficient.
0330: *
0331: * @since Java 3D 1.3
0332: */
0333: public static final int ALLOW_REVERB_COEFFICIENT_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_COEFFICIENT_READ;
0334:
0335: /**
0336: * For AuralAttributes component objects, specifies that this object
0337: * allows the writing of it's reverb coefficient.
0338: *
0339: * @since Java 3D 1.3
0340: */
0341: public static final int ALLOW_REVERB_COEFFICIENT_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_COEFFICIENT_WRITE;
0342:
0343: /**
0344: * For AuralAttributes component objects, specifies that this object
0345: * allows the reading of it's reverberation delay information.
0346: */
0347: public static final int ALLOW_REVERB_DELAY_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_DELAY_READ;
0348:
0349: /**
0350: * For AuralAttributes component objects, specifies that this object
0351: * allows the writing of it's reverberation delay information.
0352: */
0353: public static final int ALLOW_REVERB_DELAY_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_DELAY_WRITE;
0354:
0355: /**
0356: * For AuralAttributes component objects, specifies that this object
0357: * allows the reading of it's reverb order (feedback loop) information.
0358: */
0359: public static final int ALLOW_REVERB_ORDER_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_ORDER_READ;
0360:
0361: /**
0362: * For AuralAttributes component objects, specifies that this object
0363: * allows the writing of it's reverb order (feedback loop) information.
0364: */
0365: public static final int ALLOW_REVERB_ORDER_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_REVERB_ORDER_WRITE;
0366:
0367: /**
0368: * For AuralAttributes component objects, specifies that this object
0369: * allows the reading of it's reverb decay time information.
0370: *
0371: * @since Java 3D 1.3
0372: */
0373: public static final int ALLOW_DECAY_TIME_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_TIME_READ;
0374:
0375: /**
0376: * For AuralAttributes component objects, specifies that this object
0377: * allows the writing of it's reverb decay time information.
0378: *
0379: * @since Java 3D 1.3
0380: */
0381: public static final int ALLOW_DECAY_TIME_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_TIME_WRITE;
0382:
0383: /**
0384: * For AuralAttributes component objects, specifies that this object
0385: * allows the reading of it's reverb decay filter information.
0386: *
0387: * @since Java 3D 1.3
0388: */
0389: public static final int ALLOW_DECAY_FILTER_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_FILTER_READ;
0390:
0391: /**
0392: * For AuralAttributes component objects, specifies that this object
0393: * allows the writing of it's reverb decay filter information.
0394: *
0395: * @since Java 3D 1.3
0396: */
0397: public static final int ALLOW_DECAY_FILTER_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DECAY_FILTER_WRITE;
0398:
0399: /**
0400: * For AuralAttributes component objects, specifies that this object
0401: * allows the reading of it's reverb diffusion information.
0402: *
0403: * @since Java 3D 1.3
0404: */
0405: public static final int ALLOW_DIFFUSION_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DIFFUSION_READ;
0406:
0407: /**
0408: * For AuralAttributes component objects, specifies that this object
0409: * allows the writing of it's reverb diffusion information.
0410: *
0411: * @since Java 3D 1.3
0412: */
0413: public static final int ALLOW_DIFFUSION_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DIFFUSION_WRITE;
0414:
0415: /**
0416: * For AuralAttributes component objects, specifies that this object
0417: * allows the reading of it's reverb density information.
0418: *
0419: * @since Java 3D 1.3
0420: */
0421: public static final int ALLOW_DENSITY_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DENSITY_READ;
0422:
0423: /**
0424: * For AuralAttributes component objects, specifies that this object
0425: * allows the writing of it's reverb density information.
0426: *
0427: * @since Java 3D 1.3
0428: */
0429: public static final int ALLOW_DENSITY_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DENSITY_WRITE;
0430:
0431: /**
0432: * For AuralAttributes component objects, specifies that this object
0433: * allows the reading of it's frequency cutoff information.
0434: */
0435: public static final int ALLOW_DISTANCE_FILTER_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DISTANCE_FILTER_READ;
0436:
0437: /**
0438: * For AuralAttributes component objects, specifies that this object
0439: * allows the writing of it's frequency cutoff information.
0440: */
0441: public static final int ALLOW_DISTANCE_FILTER_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_DISTANCE_FILTER_WRITE;
0442:
0443: /**
0444: * For AuralAttributes component objects, specifies that this object
0445: * allows the reading of it's frequency scale factor information.
0446: */
0447: public static final int ALLOW_FREQUENCY_SCALE_FACTOR_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_FREQUENCY_SCALE_FACTOR_READ;
0448:
0449: /**
0450: * For AuralAttributes component objects, specifies that this object
0451: * allows the writing of it's frequency scale factor information.
0452: */
0453: public static final int ALLOW_FREQUENCY_SCALE_FACTOR_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_FREQUENCY_SCALE_FACTOR_WRITE;
0454:
0455: /**
0456: * For AuralAttributes component objects, specifies that this object
0457: * allows the reading of it's velocity scale factor information.
0458: */
0459: public static final int ALLOW_VELOCITY_SCALE_FACTOR_READ = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_VELOCITY_SCALE_FACTOR_READ;
0460:
0461: /**
0462: * For AuralAttributes component objects, specifies that this object
0463: * allows the writing of it's velocity scale factor information.
0464: */
0465: public static final int ALLOW_VELOCITY_SCALE_FACTOR_WRITE = CapabilityBits.AURAL_ATTRIBUTES_ALLOW_VELOCITY_SCALE_FACTOR_WRITE;
0466:
0467: // Array for setting default read capabilities
0468: private static final int[] readCapabilities = {
0469: ALLOW_ATTRIBUTE_GAIN_READ, ALLOW_DECAY_FILTER_READ,
0470: ALLOW_DECAY_TIME_READ, ALLOW_DENSITY_READ,
0471: ALLOW_DIFFUSION_READ, ALLOW_DISTANCE_FILTER_READ,
0472: ALLOW_FREQUENCY_SCALE_FACTOR_READ,
0473: ALLOW_REFLECTION_COEFFICIENT_READ,
0474: ALLOW_REFLECTION_DELAY_READ, ALLOW_REVERB_COEFFICIENT_READ,
0475: ALLOW_REVERB_DELAY_READ, ALLOW_REVERB_ORDER_READ,
0476: ALLOW_ROLLOFF_READ, ALLOW_VELOCITY_SCALE_FACTOR_READ };
0477:
0478: /** *****************
0479: *
0480: * Constructors
0481: *
0482: * ******************/
0483: /**
0484: * Constructs and initializes a new AuralAttributes object using default
0485: * parameters. The following default values are used:
0486: * <ul>
0487: * attribute gain: 1.0<br>
0488: * rolloff: 1.0<br>
0489: * reflection coeff: 0.0<br>
0490: * reflection delay: 20.0<br>
0491: * reverb coeff: 1.0<br>
0492: * reverb delay: 40.0<br>
0493: * decay time: 1000.0<br>
0494: * decay filter: 5000.0<>
0495: * diffusion: 1.0<br>
0496: * density: 1.0<br>
0497: * reverb bounds: null<br>
0498: * reverb order: 0<br>
0499: * distance filtering: null (no filtering performed)<br>
0500: * frequency scale factor: 1.0<br>
0501: * velocity scale factor: 0.0<br>
0502: * </ul>
0503: */
0504: public AuralAttributes() {
0505: // Just use default values
0506: // set default read capabilities
0507: setDefaultReadCapabilities(readCapabilities);
0508: }
0509:
0510: /**
0511: * Constructs and initializes a new AuralAttributes object using specified
0512: * parameters including an array of Point2f for the distanceFilter.
0513: * @param gain amplitude scale factor
0514: * @param rolloff atmospheric (changing speed of sound) scale factor
0515: * @param reflectionCoefficient reflective/absorptive factor applied to reflections
0516: * @param reverbDelay delay time before start of reverberation
0517: * @param reverbOrder limit to number of reflections added to reverb signal
0518: * @param distanceFilter frequency cutoff
0519: * @param frequencyScaleFactor applied to change of pitch
0520: * @param velocityScaleFactor applied to velocity of sound in relation to listener
0521: */
0522: public AuralAttributes(float gain, float rolloff,
0523: float reflectionCoefficient, float reverbDelay,
0524: int reverbOrder, Point2f[] distanceFilter,
0525: float frequencyScaleFactor, float velocityScaleFactor) {
0526: // set default read capabilities
0527: setDefaultReadCapabilities(readCapabilities);
0528:
0529: ((AuralAttributesRetained) this .retained)
0530: .setAttributeGain(gain);
0531: ((AuralAttributesRetained) this .retained).setRolloff(rolloff);
0532: ((AuralAttributesRetained) this .retained)
0533: .setReflectionCoefficient(reflectionCoefficient);
0534: ((AuralAttributesRetained) this .retained)
0535: .setReverbDelay(reverbDelay);
0536: ((AuralAttributesRetained) this .retained)
0537: .setReverbOrder(reverbOrder);
0538: ((AuralAttributesRetained) this .retained)
0539: .setDistanceFilter(distanceFilter);
0540: ((AuralAttributesRetained) this .retained)
0541: .setFrequencyScaleFactor(frequencyScaleFactor);
0542: ((AuralAttributesRetained) this .retained)
0543: .setVelocityScaleFactor(velocityScaleFactor);
0544: }
0545:
0546: /**
0547: * Constructs and initializes a new AuralAttributes object using specified
0548: * parameters with separate float arrays for components of distanceFilter.
0549: * @param gain amplitude scale factor
0550: * @param rolloff atmospheric (changing speed of sound) scale factor
0551: * @param reflectionCoefficient reflection/absorption factor applied to reflections
0552: * @param reverbDelay delay time before start of reverberation
0553: * @param reverbOrder limit to number of reflections added to reverb signal
0554: * @param distance filter frequency cutoff distances
0555: * @param frequencyCutoff distance filter frequency cutoff
0556: * @param frequencyScaleFactor applied to velocity/wave-length
0557: * @param velocityScaleFactor applied to velocity of sound in relation to listener
0558: */
0559: public AuralAttributes(float gain, float rolloff,
0560: float reflectionCoefficient, float reverbDelay,
0561: int reverbOrder, float[] distance, float[] frequencyCutoff,
0562: float frequencyScaleFactor, float velocityScaleFactor) {
0563: // set default read capabilities
0564: setDefaultReadCapabilities(readCapabilities);
0565:
0566: ((AuralAttributesRetained) this .retained)
0567: .setAttributeGain(gain);
0568: ((AuralAttributesRetained) this .retained).setRolloff(rolloff);
0569: ((AuralAttributesRetained) this .retained)
0570: .setReflectionCoefficient(reflectionCoefficient);
0571: ((AuralAttributesRetained) this .retained)
0572: .setReverbDelay(reverbDelay);
0573: ((AuralAttributesRetained) this .retained)
0574: .setReverbOrder(reverbOrder);
0575: ((AuralAttributesRetained) this .retained).setDistanceFilter(
0576: distance, frequencyCutoff);
0577: ((AuralAttributesRetained) this .retained)
0578: .setFrequencyScaleFactor(frequencyScaleFactor);
0579: ((AuralAttributesRetained) this .retained)
0580: .setVelocityScaleFactor(velocityScaleFactor);
0581: }
0582:
0583: /**
0584: * Constructs and initializes a new AuralAttributes object using specified
0585: * parameters with separate float arrays for components of distanceFilter
0586: * and full reverb parameters.
0587: * @param gain amplitude scale factor
0588: * @param rolloff atmospheric (changing speed of sound) scale factor
0589: * @param reflectionCoefficient factor applied to early reflections
0590: * @param reflectionDelay delay time before start of early reflections
0591: * @param reverbCoefficient factor applied to late reflections
0592: * @param reverbDelay delay time before start of late reverberation
0593: * @param decayTime time (in milliseconds) reverb takes to decay to -60bD
0594: * @param decayFilter reverb decay filter frequency cutoff
0595: * @param diffusion percentage of echo dispersement between min and max
0596: * @param density percentage of modal density between min and max
0597: * @param distance filter frequency cutoff distances
0598: * @param frequencyCutoff distance filter frequency cutoff
0599: * @param frequencyScaleFactor applied to velocity/wave-length
0600: * @param velocityScaleFactor applied to velocity of sound in relation to listener
0601: * @since Java 3D 1.3
0602: */
0603: public AuralAttributes(float gain, float rolloff,
0604: float reflectionCoefficient, float reflectionDelay,
0605: float reverbCoefficient, float reverbDelay,
0606: float decayTime, float decayFilter, float diffusion,
0607: float density, float[] distance, float[] frequencyCutoff,
0608: float frequencyScaleFactor, float velocityScaleFactor) {
0609: // set default read capabilities
0610: setDefaultReadCapabilities(readCapabilities);
0611:
0612: ((AuralAttributesRetained) this .retained)
0613: .setAttributeGain(gain);
0614: ((AuralAttributesRetained) this .retained).setRolloff(rolloff);
0615: ((AuralAttributesRetained) this .retained)
0616: .setReflectionCoefficient(reflectionCoefficient);
0617: ((AuralAttributesRetained) this .retained)
0618: .setReflectionDelay(reflectionDelay);
0619: ((AuralAttributesRetained) this .retained)
0620: .setReverbCoefficient(reverbCoefficient);
0621: ((AuralAttributesRetained) this .retained)
0622: .setReverbDelay(reverbDelay);
0623: ((AuralAttributesRetained) this .retained)
0624: .setDecayTime(decayTime);
0625: ((AuralAttributesRetained) this .retained)
0626: .setDecayFilter(decayFilter);
0627: ((AuralAttributesRetained) this .retained)
0628: .setDiffusion(diffusion);
0629: ((AuralAttributesRetained) this .retained).setDensity(density);
0630: ((AuralAttributesRetained) this .retained).setDistanceFilter(
0631: distance, frequencyCutoff);
0632: ((AuralAttributesRetained) this .retained)
0633: .setFrequencyScaleFactor(frequencyScaleFactor);
0634: ((AuralAttributesRetained) this .retained)
0635: .setVelocityScaleFactor(velocityScaleFactor);
0636: }
0637:
0638: /**
0639: * Creates the retained mode AuralAttributesRetained object that this
0640: * component object will point to.
0641: */
0642: void createRetained() {
0643: this .retained = new AuralAttributesRetained();
0644: this .retained.setSource(this );
0645: }
0646:
0647: /** ****************************************
0648: *
0649: * Attribute Gain
0650: *
0651: * ****************************************/
0652: /**
0653: * Set Attribute Gain (amplitude) scale factor.
0654: * @param gain scale factor applied to amplitude of direct and reflected sound
0655: * @exception CapabilityNotSetException if appropriate capability is
0656: * not set and this object is part of live or compiled scene graph
0657: */
0658: public void setAttributeGain(float gain) {
0659: if (isLiveOrCompiled())
0660: if (!this .getCapability(ALLOW_ATTRIBUTE_GAIN_WRITE))
0661: throw new CapabilityNotSetException(J3dI18N
0662: .getString("AuralAttributes0"));
0663: ((AuralAttributesRetained) this .retained)
0664: .setAttributeGain(gain);
0665: }
0666:
0667: /**
0668: * Retrieve Attribute Gain (amplitude).
0669: * @return gain amplitude scale factor
0670: * @exception CapabilityNotSetException if appropriate capability is
0671: * not set and this object is part of live or compiled scene graph
0672: */
0673: public float getAttributeGain() {
0674: if (isLiveOrCompiled())
0675: if (!this .getCapability(ALLOW_ATTRIBUTE_GAIN_READ))
0676: throw new CapabilityNotSetException(J3dI18N
0677: .getString("AuralAttributes1"));
0678: return ((AuralAttributesRetained) this .retained)
0679: .getAttributeGain();
0680: }
0681:
0682: /**
0683: * Set Attribute Gain Rolloff.
0684: * @param rolloff atmospheric gain scale factor (changing speed of sound)
0685: * @exception CapabilityNotSetException if appropriate capability is
0686: * not set and this object is part of live or compiled scene graph
0687: */
0688: public void setRolloff(float rolloff) {
0689: if (isLiveOrCompiled())
0690: if (!this .getCapability(ALLOW_ROLLOFF_WRITE))
0691: throw new CapabilityNotSetException(J3dI18N
0692: .getString("AuralAttributes2"));
0693: ((AuralAttributesRetained) this .retained).setRolloff(rolloff);
0694: }
0695:
0696: /**
0697: * Retrieve Attribute Gain Rolloff.
0698: * @return rolloff atmospheric gain scale factor (changing speed of sound)
0699: * @exception CapabilityNotSetException if appropriate capability is
0700: * not set and this object is part of live or compiled scene graph
0701: */
0702: public float getRolloff() {
0703: if (isLiveOrCompiled())
0704: if (!this .getCapability(ALLOW_ROLLOFF_READ))
0705: throw new CapabilityNotSetException(J3dI18N
0706: .getString("AuralAttributes3"));
0707: return ((AuralAttributesRetained) this .retained).getRolloff();
0708: }
0709:
0710: /**
0711: * Set Reflective Coefficient.
0712: * Scales the amplitude of the early reflections of reverberated sounds
0713: * @param coefficient reflection/absorption factor applied to reflections
0714: * @exception CapabilityNotSetException if appropriate capability is
0715: * not set and this object is part of live or compiled scene graph
0716: */
0717: public void setReflectionCoefficient(float coefficient) {
0718: if (isLiveOrCompiled())
0719: if (!this .getCapability(ALLOW_REFLECTION_COEFFICIENT_WRITE))
0720: throw new CapabilityNotSetException(J3dI18N
0721: .getString("AuralAttributes4"));
0722: ((AuralAttributesRetained) this .retained)
0723: .setReflectionCoefficient(coefficient);
0724: }
0725:
0726: /**
0727: * Retrieve Reflective Coefficient.
0728: * @return reflection coeff reflection/absorption factor
0729: * @exception CapabilityNotSetException if appropriate capability is
0730: * not set and this object is part of live or compiled scene graph
0731: */
0732: public float getReflectionCoefficient() {
0733: if (isLiveOrCompiled())
0734: if (!this .getCapability(ALLOW_REFLECTION_COEFFICIENT_READ))
0735: throw new CapabilityNotSetException(J3dI18N
0736: .getString("AuralAttributes21"));
0737: return ((AuralAttributesRetained) this .retained)
0738: .getReflectionCoefficient();
0739: }
0740:
0741: /*********************
0742: *
0743: * Early Reflection Delay
0744: *
0745: ********************/
0746: /**
0747: * Set early Refection Delay Time.
0748: * In this form, the parameter specifies the time between the start of the
0749: * direct, unreflected sound and the start of first order early reflections.
0750: * In this method, this time is explicitly given in milliseconds.
0751: * @param reflectionDelay delay time before start of reverberation
0752: * @exception CapabilityNotSetException if appropriate capability is
0753: * not set and this object is part of live or compiled scene graph
0754: * @since Java 3D 1.3
0755: */
0756: public void setReflectionDelay(float reflectionDelay) {
0757: if (isLiveOrCompiled())
0758: if (!this .getCapability(ALLOW_REFLECTION_DELAY_WRITE))
0759: throw new CapabilityNotSetException(J3dI18N
0760: .getString("AuralAttributes22"));
0761: ((AuralAttributesRetained) this .retained)
0762: .setReflectionDelay(reflectionDelay);
0763: }
0764:
0765: /**
0766: * Retrieve Reflection Delay Time.
0767: * @return reflection delay time
0768: * @exception CapabilityNotSetException if appropriate capability is
0769: * not set and this object is part of live or compiled scene graph
0770: * @since Java 3D 1.3
0771: */
0772: public float getReflectionDelay() {
0773: if (isLiveOrCompiled())
0774: if (!this .getCapability(ALLOW_REFLECTION_DELAY_READ))
0775: throw new CapabilityNotSetException(J3dI18N
0776: .getString("AuralAttributes23"));
0777: return ((AuralAttributesRetained) this .retained)
0778: .getReflectionDelay();
0779: }
0780:
0781: /** ******************
0782: *
0783: * Reverb Coefficient
0784: *
0785: ********************/
0786: /**
0787: * Set Reverb Coefficient.
0788: * Scale the amplitude of the late reflections including the decaying tail
0789: * of reverberated sound.
0790: * @param coefficient reflective/absorptive factor applied to late reflections
0791: * @exception CapabilityNotSetException if appropriate capability is
0792: * not set and this object is part of live or compiled scene graph
0793: * @since Java 3D 1.3
0794: */
0795: public void setReverbCoefficient(float coefficient) {
0796: if (isLiveOrCompiled())
0797: if (!this .getCapability(ALLOW_REVERB_COEFFICIENT_WRITE))
0798: throw new CapabilityNotSetException(J3dI18N
0799: .getString("AuralAttributes24"));
0800: ((AuralAttributesRetained) this .retained)
0801: .setReverbCoefficient(coefficient);
0802: }
0803:
0804: /**
0805: * Retrieve Reverb Coefficient.
0806: * @return late reflection coeff. reflection/absorption factor
0807: * @exception CapabilityNotSetException if appropriate capability is
0808: * not set and this object is part of live or compiled scene graph
0809: * @since Java 3D 1.3
0810: */
0811: public float getReverbCoefficient() {
0812: if (isLiveOrCompiled())
0813: if (!this .getCapability(ALLOW_REVERB_COEFFICIENT_READ))
0814: throw new CapabilityNotSetException(J3dI18N
0815: .getString("AuralAttributes25"));
0816: return ((AuralAttributesRetained) this .retained)
0817: .getReverbCoefficient();
0818: }
0819:
0820: /*********************
0821: *
0822: * Reverberation Delay
0823: *
0824: ********************/
0825: /**
0826: * Set Reverberation Delay Time.
0827: * In this form, the parameter specifies the time between the start of the
0828: * direct, unreflected sound and the start of reverberation. In this
0829: * method, this time is explicitly given in milliseconds.
0830: * @param reverbDelay delay time before start of reverberation
0831: * @exception CapabilityNotSetException if appropriate capability is
0832: * not set and this object is part of live or compiled scene graph
0833: */
0834: public void setReverbDelay(float reverbDelay) {
0835: if (isLiveOrCompiled())
0836: if (!this .getCapability(ALLOW_REVERB_DELAY_WRITE))
0837: throw new CapabilityNotSetException(J3dI18N
0838: .getString("AuralAttributes5"));
0839: ((AuralAttributesRetained) this .retained)
0840: .setReverbDelay(reverbDelay);
0841: }
0842:
0843: /**
0844: * Retrieve Reverberation Delay Time.
0845: * @return reverb delay time
0846: * @exception CapabilityNotSetException if appropriate capability is
0847: * not set and this object is part of live or compiled scene graph
0848: */
0849: public float getReverbDelay() {
0850: if (isLiveOrCompiled())
0851: if (!this .getCapability(ALLOW_REVERB_DELAY_READ))
0852: throw new CapabilityNotSetException(J3dI18N
0853: .getString("AuralAttributes7"));
0854: return ((AuralAttributesRetained) this .retained)
0855: .getReverbDelay();
0856: }
0857:
0858: /** ******************
0859: *
0860: * Decay Time
0861: *
0862: ********************/
0863: /**
0864: * Set Decay Time
0865: * Length of time from the start of late reflections reverberation volume
0866: * takes to decay to effective zero (-60 dB of initial signal amplitude).
0867: * @param decayTime of late reflections (reverb) in milliseconds
0868: * @exception CapabilityNotSetException if appropriate capability is
0869: * not set and this object is part of live or compiled scene graph
0870: * @since Java 3D 1.3
0871: */
0872: public void setDecayTime(float decayTime) {
0873: if (isLiveOrCompiled())
0874: if (!this .getCapability(ALLOW_DECAY_TIME_WRITE))
0875: throw new CapabilityNotSetException(J3dI18N
0876: .getString("AuralAttributes28"));
0877: ((AuralAttributesRetained) this .retained)
0878: .setDecayTime(decayTime);
0879: }
0880:
0881: /**
0882: * Retrieve Decay Time.
0883: * @return reverb decay time
0884: * @exception CapabilityNotSetException if appropriate capability is
0885: * not set and this object is part of live or compiled scene graph
0886: * @since Java 3D 1.3
0887: */
0888: public float getDecayTime() {
0889: if (isLiveOrCompiled())
0890: if (!this .getCapability(ALLOW_DECAY_TIME_READ))
0891: throw new CapabilityNotSetException(J3dI18N
0892: .getString("AuralAttributes29"));
0893: return ((AuralAttributesRetained) this .retained).getDecayTime();
0894: }
0895:
0896: /** ******************
0897: *
0898: * Decay Filter
0899: *
0900: ********************/
0901: /**
0902: * Set Decay Filter
0903: * In this form, reverberation decay filtering is defined as a low-pass
0904: * filter, starting at the given reference frequency. This allows for
0905: * higher frequencies to be attenuated at a different (typically faster)
0906: * rate than lower frequencies.
0907: * @param frequencyCutoff of reverberation decay low-pass filter
0908: * @exception CapabilityNotSetException if appropriate capability is
0909: * not set and this object is part of live or compiled scene graph
0910: * @since Java 3D 1.3
0911: */
0912: public void setDecayFilter(float frequencyCutoff) {
0913: if (isLiveOrCompiled())
0914: if (!this .getCapability(ALLOW_DECAY_FILTER_WRITE))
0915: throw new CapabilityNotSetException(J3dI18N
0916: .getString("AuralAttributes30"));
0917: ((AuralAttributesRetained) this .retained)
0918: .setDecayFilter(frequencyCutoff);
0919: }
0920:
0921: /**
0922: * Retrieve Decay Filter.
0923: * @return reverb decay filter cutoff frequency
0924: * @exception CapabilityNotSetException if appropriate capability is
0925: * not set and this object is part of live or compiled scene graph
0926: * @since Java 3D 1.3
0927: */
0928: public float getDecayFilter() {
0929: if (isLiveOrCompiled())
0930: if (!this .getCapability(ALLOW_DECAY_FILTER_READ))
0931: throw new CapabilityNotSetException(J3dI18N
0932: .getString("AuralAttributes31"));
0933: return ((AuralAttributesRetained) this .retained)
0934: .getDecayFilter();
0935: }
0936:
0937: /** ******************
0938: *
0939: * Diffusion
0940: *
0941: ********************/
0942: /**
0943: * Set Diffusion.
0944: * Sets the echo dispersement of reverberation to an amount between
0945: * the minimum (0.0) to the maximum (1.0) available. Changing this
0946: * increases/decreases the 'smoothness' of reverb decay.
0947: * @param ratio reverberation echo dispersement factor
0948: * @exception CapabilityNotSetException if appropriate capability is
0949: * not set and this object is part of live or compiled scene graph
0950: * @since Java 3D 1.3
0951: */
0952: public void setDiffusion(float ratio) {
0953: if (isLiveOrCompiled())
0954: if (!this .getCapability(ALLOW_DIFFUSION_WRITE))
0955: throw new CapabilityNotSetException(J3dI18N
0956: .getString("AuralAttributes32"));
0957: ((AuralAttributesRetained) this .retained).setDiffusion(ratio);
0958: }
0959:
0960: /**
0961: * Retrieve Diffusion.
0962: * @return reverb diffusion ratio
0963: * @exception CapabilityNotSetException if appropriate capability is
0964: * not set and this object is part of live or compiled scene graph
0965: * @since Java 3D 1.3
0966: */
0967: public float getDiffusion() {
0968: if (isLiveOrCompiled())
0969: if (!this .getCapability(ALLOW_DIFFUSION_READ))
0970: throw new CapabilityNotSetException(J3dI18N
0971: .getString("AuralAttributes33"));
0972: return ((AuralAttributesRetained) this .retained).getDiffusion();
0973: }
0974:
0975: /** ******************
0976: *
0977: * Density
0978: *
0979: ********************/
0980: /**
0981: * Set Density.
0982: * Sets the density of reverberation to an amount between
0983: * the minimum (0.0) to the maximum (1.0) available. Changing this
0984: * effects the spectral coloration (timbre) of late reflections.
0985: * @param ratio reverberation modal density factor
0986: * @exception CapabilityNotSetException if appropriate capability is
0987: * not set and this object is part of live or compiled scene graph
0988: * @since Java 3D 1.3
0989: */
0990: public void setDensity(float ratio) {
0991: if (isLiveOrCompiled())
0992: if (!this .getCapability(ALLOW_DENSITY_WRITE))
0993: throw new CapabilityNotSetException(J3dI18N
0994: .getString("AuralAttributes34"));
0995: ((AuralAttributesRetained) this .retained).setDensity(ratio);
0996: }
0997:
0998: /**
0999: * Retrieve Density.
1000: * @return reverb density
1001: * @exception CapabilityNotSetException if appropriate capability is
1002: * not set and this object is part of live or compiled scene graph
1003: * @since Java 3D 1.3
1004: */
1005: public float getDensity() {
1006: if (isLiveOrCompiled())
1007: if (!this .getCapability(ALLOW_DENSITY_READ))
1008: throw new CapabilityNotSetException(J3dI18N
1009: .getString("AuralAttributes35"));
1010: return ((AuralAttributesRetained) this .retained).getDensity();
1011: }
1012:
1013: /**
1014: * @deprecated As of Java 3D version 1.2, replaced by
1015: * <code>setReverbBounds(Bounds)</code>
1016: */
1017: public void setReverbDelay(Bounds reverbVolume) {
1018: if (isLiveOrCompiled())
1019: if (!this .getCapability(ALLOW_REVERB_DELAY_WRITE))
1020: throw new CapabilityNotSetException(J3dI18N
1021: .getString("AuralAttributes5"));
1022: ((AuralAttributesRetained) this .retained)
1023: .setReverbBounds(reverbVolume);
1024: }
1025:
1026: /**
1027: * Set Reverberation Bounds volume.
1028: * In this form, the reverberation bounds volume parameter is used to
1029: * calculate the reverberation Delay and Decay times. Specification
1030: * of a non-null bounding volume causes the explicit values given for
1031: * Reverb Delay and Decay to be overridden by the implicit values
1032: * calculated from these bounds.
1033: * ALLOW_REVERB_DELAY_WRITE flag used setting capability of this method.
1034: * @param reverbVolume the bounding region
1035: * @exception CapabilityNotSetException if appropriate capability is
1036: * not set and this object is part of live or compiled scene graph
1037: * @since Java 3D 1.2
1038: */
1039: public void setReverbBounds(Bounds reverbVolume) {
1040: if (isLiveOrCompiled())
1041: if (!this .getCapability(ALLOW_REVERB_DELAY_WRITE))
1042: throw new CapabilityNotSetException(J3dI18N
1043: .getString("AuralAttributes26"));
1044: ((AuralAttributesRetained) this .retained)
1045: .setReverbBounds(reverbVolume);
1046: }
1047:
1048: /**
1049: * Retrieve Reverberation Delay Bounds volume.
1050: * @return reverb bounds volume that defines the Reverberation space and
1051: * indirectly the delay/decay
1052: * ALLOW_REVERB_DELAY_READ flag used setting capability of this method.
1053: * @exception CapabilityNotSetException if appropriate capability is
1054: * not set and this object is part of live or compiled scene graph
1055: * @since Java 3D 1.2
1056: */
1057: public Bounds getReverbBounds() {
1058: if (isLiveOrCompiled())
1059: if (!this .getCapability(ALLOW_REVERB_DELAY_READ))
1060: throw new CapabilityNotSetException(J3dI18N
1061: .getString("AuralAttributes27"));
1062: return ((AuralAttributesRetained) this .retained)
1063: .getReverbBounds();
1064: }
1065:
1066: /** *******************
1067: *
1068: * Reverberation Order
1069: *
1070: ********************/
1071: /**
1072: * Set Reverberation Order
1073: * This parameter limits the number of times reflections are added
1074: * to the reverberation being rendered.
1075: * A non-positive value specifies an unbounded number of reflections.
1076: * @param reverbOrder limit to the number of times reflections added to reverb signal
1077: * @exception CapabilityNotSetException if appropriate capability is
1078: * not set and this object is part of live or compiled scene graph
1079: */
1080: public void setReverbOrder(int reverbOrder) {
1081: if (isLiveOrCompiled())
1082: if (!this .getCapability(ALLOW_REVERB_ORDER_WRITE))
1083: throw new CapabilityNotSetException(J3dI18N
1084: .getString("AuralAttributes8"));
1085: ((AuralAttributesRetained) this .retained)
1086: .setReverbOrder(reverbOrder);
1087: }
1088:
1089: /**
1090: * Retrieve Reverberation Order
1091: * @return reverb order
1092: * @exception CapabilityNotSetException if appropriate capability is
1093: * not set and this object is part of live or compiled scene graph
1094: */
1095: public int getReverbOrder() {
1096: if (!this .getCapability(ALLOW_REVERB_ORDER_READ))
1097: if (isLiveOrCompiled())
1098: throw new CapabilityNotSetException(J3dI18N
1099: .getString("AuralAttributes9"));
1100: return ((AuralAttributesRetained) this .retained)
1101: .getReverbOrder();
1102: }
1103:
1104: /**
1105: * Set Distance Filter using a single array containing distances and
1106: * frequency cutoff as pairs of values as a single array of Point2f.
1107: * @param attenuation array of pairs of distance and frequency cutoff
1108: * @exception CapabilityNotSetException if appropriate capability is
1109: * not set and this object is part of live or compiled scene graph
1110: */
1111: public void setDistanceFilter(Point2f[] attenuation) {
1112: if (isLiveOrCompiled())
1113: if (!this .getCapability(ALLOW_DISTANCE_FILTER_WRITE))
1114: throw new CapabilityNotSetException(J3dI18N
1115: .getString("AuralAttributes10"));
1116: ((AuralAttributesRetained) this .retained)
1117: .setDistanceFilter(attenuation);
1118: }
1119:
1120: /**
1121: * Set Distance Filter using separate arrays for distances and frequency
1122: * cutoff. The distance and frequencyCutoff arrays should be of the same
1123: * length. If the frequencyCutoff array length is greater than the distance
1124: * array length, the frequencyCutoff array elements beyond the length of
1125: * the distance array are ignored. If the frequencyCutoff array is shorter
1126: * than the distance array, the last frequencyCutoff array value is repeated
1127: * to fill an array of length equal to distance array.
1128: * @param distance array of float distance with corresponding cutoff values
1129: * @param frequencyCutoff array of frequency cutoff values in Hertz
1130: * @exception CapabilityNotSetException if appropriate capability is
1131: * not set and this object is part of live or compiled scene graph
1132: */
1133: public void setDistanceFilter(float[] distance,
1134: float[] frequencyCutoff) {
1135: if (isLiveOrCompiled())
1136: if (!this .getCapability(ALLOW_DISTANCE_FILTER_WRITE))
1137: throw new CapabilityNotSetException(J3dI18N
1138: .getString("AuralAttributes10"));
1139: ((AuralAttributesRetained) this .retained).setDistanceFilter(
1140: distance, frequencyCutoff);
1141: }
1142:
1143: /**
1144: * Retrieve Distance Filter array length.
1145: * @return attenuation array length
1146: * @exception CapabilityNotSetException if appropriate capability is
1147: * not set and this object is part of live or compiled scene graph
1148: */
1149: public int getDistanceFilterLength() {
1150: if (isLiveOrCompiled())
1151: if (!this .getCapability(ALLOW_DISTANCE_FILTER_READ))
1152: throw new CapabilityNotSetException(J3dI18N
1153: .getString("AuralAttributes12"));
1154: return (((AuralAttributesRetained) this .retained)
1155: .getDistanceFilterLength());
1156: }
1157:
1158: /**
1159: * Retrieve Distance Filter as a single array containing distances
1160: * and frequency cutoff. The distance filter is copied into
1161: * the specified array.
1162: * The array must be large enough to hold all of the points.
1163: * The individual array elements must be allocated by the caller.
1164: * @param attenuation array of pairs of distance and frequency cutoff values
1165: * @exception CapabilityNotSetException if appropriate capability is
1166: * not set and this object is part of live or compiled scene graph
1167: */
1168: public void getDistanceFilter(Point2f[] attenuation) {
1169: if (isLiveOrCompiled())
1170: if (!this .getCapability(ALLOW_DISTANCE_FILTER_READ))
1171: throw new CapabilityNotSetException(J3dI18N
1172: .getString("AuralAttributes12"));
1173: ((AuralAttributesRetained) this .retained)
1174: .getDistanceFilter(attenuation);
1175: }
1176:
1177: /**
1178: * Retrieve Distance Filter in separate distance and frequency cutoff arrays.
1179: * The arrays must be large enough to hold all of the distance
1180: * and frequency cutoff values.
1181: * @param distance array
1182: * @param frequencyCutoff cutoff array
1183: * @exception CapabilityNotSetException if appropriate capability is
1184: * not set and this object is part of live or compiled scene graph
1185: */
1186: public void getDistanceFilter(float[] distance,
1187: float[] frequencyCutoff) {
1188: if (isLiveOrCompiled())
1189: if (!this .getCapability(ALLOW_DISTANCE_FILTER_READ))
1190: throw new CapabilityNotSetException(J3dI18N
1191: .getString("AuralAttributes12"));
1192: ((AuralAttributesRetained) this .retained).getDistanceFilter(
1193: distance, frequencyCutoff);
1194: }
1195:
1196: /**
1197: * This parameter specifies a scale factor applied to the frequency
1198: * of sound during rendering playback. If the Doppler effect is
1199: * disabled, this scale factor can be used to increase or
1200: * decrease the original pitch of the sound. During rendering,
1201: * this scale factor expands or contracts the usual frequency shift
1202: * applied to the sound source due to Doppler calculations.
1203: * Valid values are >= 0.0.
1204: * A value of zero causes playing sounds to pause.
1205: * @param frequencyScaleFactor factor applied to change of frequency
1206: * @exception CapabilityNotSetException if appropriate capability is
1207: * not set and this object is part of live or compiled scene graph
1208: */
1209: public void setFrequencyScaleFactor(float frequencyScaleFactor) {
1210: if (isLiveOrCompiled())
1211: if (!this .getCapability(ALLOW_FREQUENCY_SCALE_FACTOR_WRITE))
1212: throw new CapabilityNotSetException(J3dI18N
1213: .getString("AuralAttributes15"));
1214: ((AuralAttributesRetained) this .retained)
1215: .setFrequencyScaleFactor(frequencyScaleFactor);
1216: }
1217:
1218: /**
1219: * Retrieve Frequency Scale Factor.
1220: * @return scaleFactor factor applied to change of frequency
1221: * @exception CapabilityNotSetException if appropriate capability is
1222: * not set and this object is part of live or compiled scene graph
1223: */
1224: public float getFrequencyScaleFactor() {
1225: if (isLiveOrCompiled())
1226: if (!this .getCapability(ALLOW_FREQUENCY_SCALE_FACTOR_READ))
1227: throw new CapabilityNotSetException(J3dI18N
1228: .getString("AuralAttributes17"));
1229: return ((AuralAttributesRetained) this .retained)
1230: .getFrequencyScaleFactor();
1231: }
1232:
1233: /** ******************************
1234: *
1235: * Velocity Scale Factor
1236: *
1237: *********************************/
1238: /**
1239: * Set Velocity scale factor applied during Doppler Effect calculation.
1240: * This parameter specifies a scale factor applied to the velocity of
1241: * the sound relative to the listener's position and movement in relation
1242: * to the sound's position and movement. This scale factor is multipled
1243: * by the calculated velocity portion of the Doppler effect equation used
1244: * during sound rendering.
1245: * A value of zero disables Doppler calculations.
1246: * @param velocityScaleFactor applied to velocity of sound in relation
1247: * to listener
1248: * @exception CapabilityNotSetException if appropriate capability is
1249: * not set and this object is part of live or compiled scene graph
1250: */
1251: public void setVelocityScaleFactor(float velocityScaleFactor) {
1252: if (isLiveOrCompiled())
1253: if (!this .getCapability(ALLOW_VELOCITY_SCALE_FACTOR_WRITE))
1254: throw new CapabilityNotSetException(J3dI18N
1255: .getString("AuralAttributes19"));
1256: ((AuralAttributesRetained) this .retained)
1257: .setVelocityScaleFactor(velocityScaleFactor);
1258: }
1259:
1260: /**
1261: * Retrieve Velocity Scale Factor used to calculate Doppler Effect.
1262: * @return scale factor applied to Doppler velocity of sound
1263: * @exception CapabilityNotSetException if appropriate capability is
1264: * not set and this object is part of live or compiled scene graph
1265: */
1266: public float getVelocityScaleFactor() {
1267: if (isLiveOrCompiled())
1268: if (!this .getCapability(ALLOW_VELOCITY_SCALE_FACTOR_READ))
1269: throw new CapabilityNotSetException(J3dI18N
1270: .getString("AuralAttributes20"));
1271: return ((AuralAttributesRetained) this .retained)
1272: .getVelocityScaleFactor();
1273: }
1274:
1275: /**
1276: * @deprecated As of Java 3D version 1.2, replaced by
1277: * <code>cloneNodeComponent(boolean forceDuplicate)</code>
1278: */
1279: public NodeComponent cloneNodeComponent() {
1280: AuralAttributes a = new AuralAttributes();
1281: a.duplicateNodeComponent(this , this .forceDuplicate);
1282: return a;
1283: }
1284:
1285: /**
1286: * Copies all AuralAttributes information from <code>originalNodeComponent</code> into
1287: * the current node. This method is called from the
1288: * <code>duplicateNode</code> method. This routine does
1289: * the actual duplication of all "local data" (any data defined in
1290: * this object).
1291: *
1292: * @param originalNodeComponent the original node to duplicate.
1293: * @param forceDuplicate when set to <code>true</code>, causes the
1294: * <code>duplicateOnCloneTree</code> flag to be ignored. When
1295: * <code>false</code>, the value of each node's
1296: * <code>duplicateOnCloneTree</code> variable determines whether
1297: * NodeComponent data is duplicated or copied.
1298: *
1299: * @see Node#cloneTree
1300: * @see NodeComponent#setDuplicateOnCloneTree
1301: */
1302: void duplicateAttributes(NodeComponent originalNodeComponent,
1303: boolean forceDuplicate) {
1304: super
1305: .duplicateAttributes(originalNodeComponent,
1306: forceDuplicate);
1307:
1308: AuralAttributesRetained aural = (AuralAttributesRetained) originalNodeComponent.retained;
1309: AuralAttributesRetained rt = (AuralAttributesRetained) retained;
1310:
1311: rt.setAttributeGain(aural.getAttributeGain());
1312: rt.setRolloff(aural.getRolloff());
1313: rt.setReflectionCoefficient(aural.getReflectionCoefficient());
1314: rt.setReverbDelay(aural.getReverbDelay());
1315: rt.setReverbOrder(aural.getReverbOrder());
1316: rt.setReverbBounds(aural.getReverbBounds());
1317: rt.setFrequencyScaleFactor(aural.getFrequencyScaleFactor());
1318: rt.setVelocityScaleFactor(aural.getVelocityScaleFactor());
1319: int len = aural.getDistanceFilterLength();
1320: float distance[] = new float[len];
1321: float frequencyCutoff[] = new float[len];
1322: aural.getDistanceFilter(distance, frequencyCutoff);
1323: rt.setDistanceFilter(distance, frequencyCutoff);
1324: }
1325: }
|