Java tutorial
/* * 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; import javax.vecmath.Point3f; /** * The PointSound node (a sub-class of the Sound node) defines a spatially * located sound source whose waves radiate uniformly in all directions from * a given location in space. It has the same attributes as a Sound object * with the addition of a location and the specification of distance-based * gain attenuation for listener positions between an array of distances. *<P> * A sound's amplitude is attenuated based on the distance between the listener * and the sound source position. A piecewise linear curve (defined in terms of * pairs of distance and gain scale factor) specifies the gain scale factor slope. * * The PointSound's location and attenuation distances are defined in the local * coordinate system of the node. *<P> * Distance Gain Attenuation * <UL> * Associated with distances from the listener to the sound source via an * array of (distance, gain-scale-factor) pairs. The gain scale factor * applied to the sound source is the linear interpolated gain value between * the distance value range that includes the current distance from * the listener to the sound source. If the distance from the listener to * the sound source is less than the first distance in the array, the first * gain scale factor is applied to the sound source. This creates a * spherical region around the listener within which all sound gain is * uniformly scaled by the first gain in the array. If the distance from * the listener to the sound source is greater than the last distance in * the array, the last gain scale factor is applied to the sound source. *<P> * Distance elements in this array of Point2f is a monotonically-increasing * set of floating point numbers measured from the location of the sound * source. Gain scale factors elements in this list of pairs can be any * positive floating point numbers. While for most applications this list * of gain scale factors will usually be monotonically-decreasing, they * do not have to be. * If this * is not set, no distance gain attenuation is performed (equivalent to * using a distance gain of 1.0 for all distances). *<P> * getDistanceGainLength method returns the length of the distance gain * attenuation arrays. Arrays passed into getDistanceGain methods should all * be at least this size. *<P> * There are two methods for getDistanceGain, one returning an array of * points, the other returning separate arrays for each attenuation * component.</UL> */ public class PointSound extends Sound { // Constants // // These flags, when enabled using the setCapability method, allow an // application to invoke methods that respectively read and write the position // and the distance gain array. These capability flags are enforced only when // the node is part of a live or compiled scene graph /** * Specifies that this node allows access to its object's position * information. */ public static final int ALLOW_POSITION_READ = CapabilityBits.POINT_SOUND_ALLOW_POSITION_READ; /** * Specifies that this node allows writing to its object's position * information. */ public static final int ALLOW_POSITION_WRITE = CapabilityBits.POINT_SOUND_ALLOW_POSITION_WRITE; /** * Specifies that this node allows access to its object's distance * gain attenuation information. */ public static final int ALLOW_DISTANCE_GAIN_READ = CapabilityBits.POINT_SOUND_ALLOW_DISTANCE_GAIN_READ; /** * Specifies that this node allows writing to its object's distance * gain attenuation information. */ public static final int ALLOW_DISTANCE_GAIN_WRITE = CapabilityBits.POINT_SOUND_ALLOW_DISTANCE_GAIN_WRITE; // Array for setting default read capabilities private static final int[] readCapabilities = { ALLOW_POSITION_READ, ALLOW_DISTANCE_GAIN_READ }; /** * Constructs and initializes a new PointSound node using default * parameters. The following default values are used: * <ul> * position vector: (0.0, 0.0, 0.0)<br> * Back attenuation: null<br> * distance gain attenuation: null (no attenuation performed)<br> * </ul> */ public PointSound() { // Uses default values defined for Sound and PointSound nodes super(); // set default read capabilities setDefaultReadCapabilities(readCapabilities); } /** * Constructs a PointSound node object using only the provided parameter * values for sound data, sample gain, and position. The remaining fields * are set to the above default values. This form uses a point as input for * its position. * @param soundData sound data associated with this sound source node * @param initialGain amplitude scale factor applied to sound source * @param position 3D location of source */ public PointSound(MediaContainer soundData, float initialGain, Point3f position) { super(soundData, initialGain); // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((PointSoundRetained) this.retained).setPosition(position); } /** * Constructs a PointSound node object using only the provided parameter * values for sound data, sample gain, and position. The remaining fields * are set to to the above default values. This form uses individual float * parameters for the elements of the position point. * @param soundData sound data associated with this sound source node * @param initialGain amplitude scale factor applied to sound source data * @param posX x coordinate of location of source * @param posY y coordinate of location of source * @param posZ z coordinate of location of source */ public PointSound(MediaContainer soundData, float initialGain, float posX, float posY, float posZ) { super(soundData, initialGain); // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((PointSoundRetained) this.retained).setPosition(posX, posY, posZ); } // The next four constructors fill all this classes fields with the provided // arguments values. // See the header for the setDistanceGain method for details on how the // those arrays are interpreted. /** * Construct a PointSound object accepting Point3f as input for the position * and accepting an array of Point2f for the distance attenuation values * where each pair in the array contains a distance and a gain scale factor. * @param soundData sound data associated with this sound source node * @param initialGain amplitude scale factor applied to sound source * @param loopCount number of times loop is looped * @param release flag denoting playing sound data to end * @param continuous denotes that sound silently plays when disabled * @param enable sound switched on/off * @param region scheduling bounds * @param priority playback ranking value * @param position 3D location of source * @param distanceGain array of (distance,gain) pairs controling attenuation */ public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, Point3f position, Point2f[] distanceGain) { super(soundData, initialGain, loopCount, release, continuous, enable, region, priority); // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((PointSoundRetained) this.retained).setPosition(position); ((PointSoundRetained) this.retained).setDistanceGain(distanceGain); } /** * Construct a PointSound object accepting individual float parameters for * the elements of the position point, and accepting an array of Point2f for * the distance attenuation values where each pair in the array contains a * distance and a gain scale factor. * @param soundData sound data associated with this sound source node * @param initialGain amplitude scale factor applied to sound source * @param loopCount number of times loop is looped * @param release flag denoting playing sound to end * @param continuous denotes that sound silently plays when disabled * @param enable sound switched on/off * @param region scheduling bounds * @param priority playback ranking value * @param posX x coordinate of location of source * @param posY y coordinate of location of source * @param posZ z coordinate of location of source * @param distanceGain array of (distance,gain) pairs controling attenuation */ public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, Point2f[] distanceGain) { super(soundData, initialGain, loopCount, release, continuous, enable, region, priority); // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((PointSoundRetained) this.retained).setPosition(posX, posY, posZ); ((PointSoundRetained) this.retained).setDistanceGain(distanceGain); } /** * Construct a PointSound object accepting points as input for the position. * and accepting separate arrays for the distance and gain scale factors * components of distance attenuation. * @param soundData sound data associated with this sound source node * @param initialGain amplitude scale factor applied to sound source * @param loopCount number of times loop is looped * @param release flag denoting playing sound data to end * @param continuous denotes that sound silently plays when disabled * @param enable sound switched on/off * @param region scheduling bounds * @param priority playback ranking value * @param position 3D location of source * @param attenuationDistance array of distance values used for attenuation * @param attenuationGain array of gain scale factors used for attenuation */ public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, Point3f position, float[] attenuationDistance, float[] attenuationGain) { super(soundData, initialGain, loopCount, release, continuous, enable, region, priority); // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((PointSoundRetained) this.retained).setPosition(position); ((PointSoundRetained) this.retained).setDistanceGain(attenuationDistance, attenuationGain); } /** * Construct a PointSound object accepting individual float parameters for * the elements of the position points, and accepting separate arrays for * the distance and gain scale factors components of distance attenuation. * @param soundData sound data associated with this sound source node * @param initialGain amplitude scale factor applied to sound source * @param loopCount number of times loop is looped * @param release flag denoting playing sound to end * @param continuous denotes that sound silently plays when disabled * @param enable sound switched on/off * @param region scheduling bounds * @param priority playback ranking value * @param posX x coordinate of location of source * @param posY y coordinate of location of source * @param posZ z coordinate of location of source * @param attenuationDistance array of distance values used for attenuation * @param attenuationGain array of gain scale factors used for attenuation */ public PointSound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float posX, float posY, float posZ, float[] attenuationDistance, float[] attenuationGain) { super(soundData, initialGain, loopCount, release, continuous, enable, region, priority); // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((PointSoundRetained) this.retained).setPosition(posX, posY, posZ); ((PointSoundRetained) this.retained).setDistanceGain(attenuationDistance, attenuationGain); } /** * Creates the retained mode PointSoundRetained object that this * PointSound object will point to. */ @Override void createRetained() { this.retained = new PointSoundRetained(); this.retained.setSource(this); } /** * Sets this sound's location from the vector provided. * @param position the new location * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setPosition(Point3f position) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_POSITION_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound0")); ((PointSoundRetained) this.retained).setPosition(position); } /** * Sets this sound's position from the three values provided. * @param x the new x position * @param y the new y position * @param z the new z position * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setPosition(float x, float y, float z) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_POSITION_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound0")); ((PointSoundRetained) this.retained).setPosition(x, y, z); } /** * Retrieves this sound's direction and places it in the * vector provided. * @param position the variable to receive the direction vector * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void getPosition(Point3f position) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_POSITION_READ)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound2")); ((PointSoundRetained) this.retained).getPosition(position); } /** * Sets this sound's distance gain attenuation - where gain scale factor * is applied to sound based on distance listener is from sound source. * This form of setDistanceGain takes these pairs of values as an array of * Point2f. * @param attenuation defined by pairs of (distance,gain-scale-factor) * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setDistanceGain(Point2f[] attenuation) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DISTANCE_GAIN_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound3")); ((PointSoundRetained) this.retained).setDistanceGain(attenuation); } /** * Sets this sound's distance gain attenuation as an array of Point2fs. * This form of setDistanceGain accepts two separate arrays for these values. * The distance and gainScale arrays should be of the same length. If the * gainScale array length is greater than the distance array length, the * gainScale array elements beyond the length of the distance array are * ignored. If the gainScale array is shorter than the distance array, the * last gainScale array value is repeated to fill an array of length equal * to distance array. * @param distance array of monotonically-increasing floats * @param gain array of non-negative scale factors * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setDistanceGain(float[] distance, float[] gain) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DISTANCE_GAIN_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound3")); ((PointSoundRetained) this.retained).setDistanceGain(distance, gain); } /** * Get the length of this node's distance gain attenuation arrays. * @return distance gain attenuation array length * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public int getDistanceGainLength() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DISTANCE_GAIN_READ)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound4")); return (((PointSoundRetained) this.retained).getDistanceGainLength()); } /** * Gets this sound's distance attenuation. The distance attenuation * pairs are 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 arrays containing distance attenuation pairs * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void getDistanceGain(Point2f[] attenuation) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DISTANCE_GAIN_READ)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound4")); ((PointSoundRetained) this.retained).getDistanceGain(attenuation); } /** * Gets this sound's distance gain attenuation values in separate arrays. * The arrays must be large enough to hold all of the values. * @param distance array of float distance from sound source * @param gain array of non-negative scale factors associated with * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void getDistanceGain(float[] distance, float[] gain) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DISTANCE_GAIN_READ)) throw new CapabilityNotSetException(J3dI18N.getString("PointSound4")); ((PointSoundRetained) this.retained).getDistanceGain(distance, gain); } /** * Creates a new instance of the node. This routine is called * by <code>cloneTree</code> to duplicate the current node. * @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 Node#cloneNode * @see Node#duplicateNode * @see NodeComponent#setDuplicateOnCloneTree */ @Override public Node cloneNode(boolean forceDuplicate) { PointSound p = new PointSound(); p.duplicateNode(this, forceDuplicate); return p; } /** * Copies all node information from <code>originalNode</code> into * the current node. This method is called from the * <code>cloneNode</code> method which is, in turn, called by the * <code>cloneTree</code> method. * <P> * For any <code>NodeComponent</code> objects * contained by the object being duplicated, each <code>NodeComponent</code> * object's <code>duplicateOnCloneTree</code> value is used to determine * whether the <code>NodeComponent</code> should be duplicated in the new node * or if just a reference to the current node should be placed in the * new node. This flag can be overridden by setting the * <code>forceDuplicate</code> parameter in the <code>cloneTree</code> * method to <code>true</code>. * <br> * NOTE: Applications should <i>not</i> call this method directly. * It should only be called by the cloneNode method. * * @param originalNode 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. * @exception ClassCastException if originalNode is not an instance of * <code>PointSound</code> * * @see Node#cloneTree * @see Node#cloneNode * @see NodeComponent#setDuplicateOnCloneTree */ @Override public void duplicateNode(Node originalNode, boolean forceDuplicate) { checkDuplicateNode(originalNode, forceDuplicate); } /** * Copies all PointSound information from * <code>originalNode</code> into * the current node. This method is called from the * <code>cloneNode</code> method which is, in turn, called by the * <code>cloneTree</code> method.<P> * * @param originalNode 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. * * @exception RestrictedAccessException if this object is part of a live * or compiled scenegraph. * * @see Node#duplicateNode * @see Node#cloneTree * @see NodeComponent#setDuplicateOnCloneTree */ @Override void duplicateAttributes(Node originalNode, boolean forceDuplicate) { super.duplicateAttributes(originalNode, forceDuplicate); PointSoundRetained orgRetained = (PointSoundRetained) originalNode.retained; PointSoundRetained thisRetained = (PointSoundRetained) this.retained; Point3f p = new Point3f(); orgRetained.getPosition(p); thisRetained.setPosition(p); int len = orgRetained.getDistanceGainLength(); float distance[] = new float[len]; float gain[] = new float[len]; orgRetained.getDistanceGain(distance, gain); thisRetained.setDistanceGain(distance, gain); } }