auralattributes.java

JAVA3D矩陈的相关类

     ********************/
    /**
     * 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 
     * <code>setReverbBounds(Bounds)</code>
     */
    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
     * <code>cloneNodeComponent(boolean forceDuplicate)</code>
     */
    public NodeComponent cloneNodeComponent() {
        AuralAttributes a = new AuralAttributes();
        a.duplicateNodeComponent(this, this.forceDuplicate);
        return a;
    }


   /**
     * Copies all AuralAttributes information from <code>originalNodeComponent</code> into
     * the current node.  This method is called from the
     * <code>duplicateNode</code> 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 <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     *
     * @see Node#cloneTree
     * @see NodeComponent#setDuplicateOnCloneTree
     */
     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);
    }
}