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; /** * Sound node is an abstract class that defines the properties common to all * sound sources. A scene graph can contain multiple sounds. Associated with each * sound source are: a reference to sound data, an amplitude scale factor, a release * flag denoting that the sound associated with this node is to play to end when * it is disabled, the number of times sound is to be repeated, the sound's state * (on or off), a scheduling region, and a flag denoting if the sound is to * continue playing "silently" even while it is inactive. Whenever the listener * is within a sound node's scheduling bounds this sound is potentially audible. *<P> * Sound Data * * <UL>Associated with each Sound node is a MediaContainer * which includes audio data and information about this data. * This data can be cached (buffered) or non-cached (unbuffered or streaming). * If an AudioDevice has been attached to the PhysicalEnvironment, the sound * data is made ready to begin playing. * Certain functionality can not be applied to true streaming sound data:<p> * 1) querying the sound's duration (Sound.DURATION_UNKNOWN will be returned),<br> * 2) looping over a range of the streaming data; and<br> * 3) restart a previously played portion of the data.<p> * Depending on the implementation of the AudioDevice used, streamed, non- * cached data may not be fully spatialized.</UL> *<P> * Initial Gain * * <UL>This gain is a scale factor applied to the sound data associated * with this sound source to increase or decrease its overall amplitude.</UL> *<P> * Loop * * <UL>Data for non-streaming sound (such as a sound sample) can contain two * loop points marking a section of the data that is to be looped a specific * number of times. Thus sound data can be divided into three segments: * the attack (before the begin loop point), the sustain (between the begin * and end loop points), and the release (after the end loop point). If * there are no loop begin and end points defined as part of the sound data, * the begin loop point is set at the beginning of the sound data, * and the end loop point at the end of the sound data. * If this is the case, looping the sound would mean repeating the whole * sound. However, these allow a portion in the middle of the sound to * be looped. *<P> * A sound can be looped a specified number of times after it is activated * before it is completed. The loop count value explicitly sets the number * of times the sound is looped. Any non-negative number is a valid value. * A value of zero denotes that the looped section is not repeated, but is * played only once. A value of -1 denotes that the loop is repeated * indefinitely. *<P> * Changing loop count of a sound after the sound has been started will not * dynamically affect the loop count currently used by the sound playing. * The new loop count will be used the next time the sound is enabled.</UL> * <P> * Release Flag * * <UL>When a sound is disabled, its playback would normally stop immediately * no matter what part of the sound data was currently being played. By * setting the Release Flag to true for nodes with non-streaming sound data, * the sound is allowed to play from its current position in the sound data * to the end of the data (without repeats), thus playing the release portion * of the sound before stopping.</UL> *<P> * Continuous Flag * * <UL>For some applications, it's useful to turn a sound source "off" but to * continue "silently" playing the sound so that when it is turned back "on" * the sound picks up playing in the same location (over time) as it would * have been if the sound had never been disabled (turned off). Setting the * Continuous flag true causes the sound renderer to keep track of where * (over time) the sound would be playing even when the sound is disabled.</UL> *<P> * Enable Sound * * <UL>When enabled, the sound source is started * playing and thus can potentially be heard, depending on its activation * state, gain control parameters, continuation state, and spatialization * parameters. If the continuous state is true, even if the sound is not * active, enabling the sound starts the sound silently "playing," so that * when the sound is activated, the sound is (potentially) heard from * somewhere in the middle of the sound data. Activation state can change * from active to inactive any number of times without stopping or starting * the sound. To re-start a sound at the beginning of its data, re-enable * the sound by calling setEnable with true. *<P> * Setting the enable flag to true during construction acts as a request * to start the sound playing "as soon as it can" be started. * This could be close to immediately in limited cases, but several conditions, * detailed below, must be met for a sound to be ready to be played.</UL> *<P> * Mute Sound * * <UL>When the mute state is set true, a playing sound is made to play silently. *</UL><P> * Pause Sound * * <UL>When the pause state is set true, a playing sound is paused. *<P> * Setting the enable flag to true during construction acts as a request * to start the sound playing "as soon as it can" be started. * This could be close to immediately in limited cases, but several conditions, * detailed below, must be met for a sound to be ready to be played.</UL> * <P> * Scheduling Bounds * * <UL> * A Sound is scheduled for activation when its scheduling region intersects * the ViewPlatform's activation volume. This is used when the scheduling * bounding leaf is set to null.</UL> *<P> * Scheduling Bounding Leaf * * <UL>When set to a value other than null, the scheduling bounding leaf * region overrides the scheduling bounds * object.</UL> *<P> * Prioritize Sound * * <UL>Sound Priority is used * to rank concurrently playing sounds in order of importance during playback. * When more sounds are started than the AudioDevice * can handle, the sound node with the lowest priority ranking is * deactivated (but continues playing silently). If a sound is deactivated * (due to a sound with a higher * priority being started), it is automatically re-activated when * resources become available (e.g., when a sound with a higher priority * finishes playing), or when the ordering of sound nodes are changed due to * a change in a sound node's priority. * <P> * Sounds with a lower priority than sound that can * not be played due to lack of channels will be played. * For example, assume we have eight channels available for playing sounds. * After ordering four sounds, we begin playing them in order, checking if * the number of channels required to play a given sound are actually available * before the sound is played. Furthermore, say the first sound needs three * channels * to play, the second sound needs four channels, the third sound needs three * channels * and the fourth sound needs only one channel. The first and second sounds * can be started because they require seven of the eight available channels. The * third sound can not be audibly started because it requires three channels and * only one is still available. Consequently, the third sound starts playing * 'silently.' The fourth sound can and will be started since it only requires * one channel. The third sound will be made audible when three channels become * available (i.e., when the first or second sound finishes playing). * <P> * Sounds given the same priority are ordered randomly. If the application * wants a specific ordering, it must assign unique priorities to each sound. * <P> * Methods to determine what audio output resources are required for playing * a Sound node on a particular AudioDevice and to determine the currently * available audio output resources are described in the AudioDevice class.</UL> * <P> * Duration * * <UL>Each sound has a length of time in milliseconds that it * can run (including repeating loop section) * if it plays to completion. If the sound * media type is streaming, or if the sound is looped indefinitely, then a * value of -1 (implying infinite length) is returned.</UL> *<P> * Number of Channels used on Audio Device to Play Sound * * <UL>When a sound is started, it could use more than one channel on the * selected AudioDevice it is to be played on. The number of Audio Device * channels currently used for a sound can be queried using * getNumberOfChannelsUsed().</UL> *<P> * Preparing a Sound to be Played * * <UL>Sound data associated with a Sound node, either during construction * (when the MediaContainer is passed into the constructor as a parameter) * or by calling setSoundData(), it can be prepared to begin playing * only after the following conditions are satisfied:<p> * 1) the Sound node has non-null sound data associated with it<br> * 2) the Sound node is live<br> * 3) there is an active View in the Universe and<br> * 4) there is an initialized AudioDevice associated with the * PhysicalEnvironment.<p> * Depending on the type of MediaContainer the sound data is and on the * implementation of the AudioDevice used, sound data preparation could consist * of opening, attaching, loading, or copying into memory the associated sound data. * The query method, isReady() returns true when the sound is fully preprocessed * so that it is playable (audibly if active, silently if not active).</UL> *<P> * Playing Status * * <UL>A sound source will not be heard unless it is:<p> * 1) enabled/started<br> * 2) activated<br> * 3) not muted<br> * 4) not paused<p> * While these conditions are meet, the sound is potentially audible * and the method isPlaying() will return a status of true. *<P> * isPlaying returns false but isPlayingSilently returns true if a sound:<p> * 1) is enabled before it is activated; it is begun playing silently.<br> * 2) is enabled then deactivated while playing; it continues playing silently<br> * 3) is enabled while it mute state is true *<P> * When the sound finishes playing it's sound data (including all loops), it * is implicitly disabled.</UL> *<P> * @see AudioDevice */ public abstract class Sound extends Leaf { // Constants for Sound object. // // These flags, when enabled using the setCapability method, allow an // application to invoke methods that respectively read and write the // sound fields. // 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 sound data * information. */ public static final int ALLOW_SOUND_DATA_READ = CapabilityBits.SOUND_ALLOW_SOUND_DATA_READ; /** * Specifies that this node allows writing to its object's sound data * information. */ public static final int ALLOW_SOUND_DATA_WRITE = CapabilityBits.SOUND_ALLOW_SOUND_DATA_WRITE; /** * Specifies that this node allows access to its object's initial gain * information. */ public static final int ALLOW_INITIAL_GAIN_READ = CapabilityBits.SOUND_ALLOW_INITIAL_GAIN_READ; /** * Specifies that this node allows writing to its object's initial gain * information. */ public static final int ALLOW_INITIAL_GAIN_WRITE = CapabilityBits.SOUND_ALLOW_INITIAL_GAIN_WRITE; /** * Specifies that this node allows access to its object's loop * information. */ public static final int ALLOW_LOOP_READ = CapabilityBits.SOUND_ALLOW_LOOP_READ; /** * Specifies that this node allows writing to its object's loop * information. */ public static final int ALLOW_LOOP_WRITE = CapabilityBits.SOUND_ALLOW_LOOP_WRITE; /** * Specifies that this node allows access to its object's release flag * information. */ public static final int ALLOW_RELEASE_READ = CapabilityBits.SOUND_ALLOW_RELEASE_READ; /** * Specifies that this node allows writing to its object's release flag * information. */ public static final int ALLOW_RELEASE_WRITE = CapabilityBits.SOUND_ALLOW_RELEASE_WRITE; /** * Specifies that this node allows access to its object's continuous * play information. */ public static final int ALLOW_CONT_PLAY_READ = CapabilityBits.SOUND_ALLOW_CONT_PLAY_READ; /** * Specifies that this node allows writing to its object's continuous * play information. */ public static final int ALLOW_CONT_PLAY_WRITE = CapabilityBits.SOUND_ALLOW_CONT_PLAY_WRITE; /** * Specifies that this node allows access to its object's sound on * information. */ public static final int ALLOW_ENABLE_READ = CapabilityBits.SOUND_ALLOW_ENABLE_READ; /** * Specifies that this node allows writing to its object's sound on * information. */ public static final int ALLOW_ENABLE_WRITE = CapabilityBits.SOUND_ALLOW_ENABLE_WRITE; /** * Specifies that this node allows read access to its scheduling bounds * information. */ public static final int ALLOW_SCHEDULING_BOUNDS_READ = CapabilityBits.SOUND_ALLOW_SCHEDULING_BOUNDS_READ; /** * Specifies that this node allows write access to its scheduling bounds * information. */ public static final int ALLOW_SCHEDULING_BOUNDS_WRITE = CapabilityBits.SOUND_ALLOW_SCHEDULING_BOUNDS_WRITE; /** * Specifies that this node allows read access to its priority order * value. */ public static final int ALLOW_PRIORITY_READ = CapabilityBits.SOUND_ALLOW_PRIORITY_READ; /** * Specifies that this node allows write access to its priority order * value. */ public static final int ALLOW_PRIORITY_WRITE = CapabilityBits.SOUND_ALLOW_PRIORITY_WRITE; /** * Specifies that this node allows access to its object's sound duration * information. */ public static final int ALLOW_DURATION_READ = CapabilityBits.SOUND_ALLOW_DURATION_READ; /** * Specifies that this node allows access to its object's sound status * denoting if it is ready to be played 'immediately'. */ public static final int ALLOW_IS_READY_READ = CapabilityBits.SOUND_ALLOW_IS_READY_READ; /** * Specifies that this node allows access to its object's sound audibly * playing or playing silently status. */ public static final int ALLOW_IS_PLAYING_READ = CapabilityBits.SOUND_ALLOW_IS_PLAYING_READ; /** * Specifies that this node allows access to its number of channels * used by this sound. */ public static final int ALLOW_CHANNELS_USED_READ = CapabilityBits.SOUND_ALLOW_CHANNELS_USED_READ; /** * Specifies that this node allows access to its object's mute flag * information. * * @since Java 3D 1.3 */ public static final int ALLOW_MUTE_READ = CapabilityBits.SOUND_ALLOW_MUTE_READ; /** * Specifies that this node allows writing to its object's mute flag * information. * * @since Java 3D 1.3 */ public static final int ALLOW_MUTE_WRITE = CapabilityBits.SOUND_ALLOW_MUTE_WRITE; /** * Specifies that this node allows access to its object's pause flag * information. * * @since Java 3D 1.3 */ public static final int ALLOW_PAUSE_READ = CapabilityBits.SOUND_ALLOW_PAUSE_READ; /** * Specifies that this node allows writing to its object's pause flag * information. * * @since Java 3D 1.3 */ public static final int ALLOW_PAUSE_WRITE = CapabilityBits.SOUND_ALLOW_PAUSE_WRITE; /** * Specifies that this node allows access to its object's sample rate scale * factor information. * * @since Java 3D 1.3 */ public static final int ALLOW_RATE_SCALE_FACTOR_READ = CapabilityBits.SOUND_ALLOW_RATE_SCALE_FACTOR_READ; /** * Specifies that this node allows writing to its object's sample rate scale * factor information. * * @since Java 3D 1.3 */ public static final int ALLOW_RATE_SCALE_FACTOR_WRITE = CapabilityBits.SOUND_ALLOW_RATE_SCALE_FACTOR_WRITE; /** * Denotes that there is no filter value associated with object's distance * or angular attenuation array. */ public static final float NO_FILTER = -1.0f; /** * Denotes that the sound's duration could not be calculated. * A fall back for getDuration of a non-cached sound. */ public static final int DURATION_UNKNOWN = -1; /** * When used as a loop count sound will loop an infinite number of time * until explicitly stopped (setEnabled(false)). */ public static final int INFINITE_LOOPS = -1; // Array for setting default read capabilities private static final int[] readCapabilities = { ALLOW_CHANNELS_USED_READ, ALLOW_CONT_PLAY_READ, ALLOW_DURATION_READ, ALLOW_ENABLE_READ, ALLOW_INITIAL_GAIN_READ, ALLOW_IS_PLAYING_READ, ALLOW_IS_READY_READ, ALLOW_LOOP_READ, ALLOW_MUTE_READ, ALLOW_PAUSE_READ, ALLOW_PRIORITY_READ, ALLOW_RATE_SCALE_FACTOR_READ, ALLOW_RELEASE_READ, ALLOW_SCHEDULING_BOUNDS_READ, ALLOW_SOUND_DATA_READ }; /** * Constructs and initializes a new Sound node using default * parameters. The following defaults values are used: * <ul> * sound data: null<br> * initial gain: 1.0<br> * loop: 0<br> * release flag: false<br> * continuous flag: false<br> * enable flag: false<br> * scheduling bounds : null<br> * scheduling bounding leaf : null<br> * priority: 1.0<br> * rate scale factor: 1.0<br> * mute state: false<br> * pause state: false<br> * </ul> */ public Sound() { // set default read capabilities setDefaultReadCapabilities(readCapabilities); } /** * Constructs and initializes a new Sound node object using the provided * data and gain parameter values, and defaults for all other fields. This * constructor implicitly loads the sound data associated with this node if * the implementation uses sound caching. * @param soundData description of JMF source data used by this sound source * @param initialGain overall amplitude scale factor applied to sound source */ public Sound(MediaContainer soundData, float initialGain) { // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((SoundRetained) this.retained).setSoundData(soundData); ((SoundRetained) this.retained).setInitialGain(initialGain); } /** * Constructs and initializes a new Sound node using provided parameter * values. * @param soundData description of JMF source data used by this sound source * @param initialGain overall amplitude scale factor applied to sound source * @param loopCount number of times sound is looped when played * @param release flag specifying whether the sound is to be played * to end when stopped * @param continuous flag specifying whether the sound silently plays * when disabled * @param enable flag specifying whether the sound is enabled * @param region scheduling bounds * @param priority defines playback priority if too many sounds started */ public Sound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority) { // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((SoundRetained) this.retained).setSoundData(soundData); ((SoundRetained) this.retained).setInitialGain(initialGain); ((SoundRetained) this.retained).setLoop(loopCount); ((SoundRetained) this.retained).setReleaseEnable(release); ((SoundRetained) this.retained).setContinuousEnable(continuous); ((SoundRetained) this.retained).setEnable(enable); ((SoundRetained) this.retained).setSchedulingBounds(region); ((SoundRetained) this.retained).setPriority(priority); } /** * Constructs and initializes a new Sound node using provided parameter * values. * @param soundData description of JMF source data used by this sound source * @param initialGain overall amplitude scale factor applied to sound source * @param loopCount number of times sound is looped when played * @param release flag specifying whether the sound is to be played * to end when stopped * @param continuous flag specifying whether the sound silently plays * when disabled * @param enable flag specifying whether the sound is enabled * @param region scheduling bounds * @param priority defines playback priority if too many sounds started * @param rateFactor defines playback sample rate scale factor * @since Java 3D 1.3 */ public Sound(MediaContainer soundData, float initialGain, int loopCount, boolean release, boolean continuous, boolean enable, Bounds region, float priority, float rateFactor) { // set default read capabilities setDefaultReadCapabilities(readCapabilities); ((SoundRetained) this.retained).setSoundData(soundData); ((SoundRetained) this.retained).setInitialGain(initialGain); ((SoundRetained) this.retained).setLoop(loopCount); ((SoundRetained) this.retained).setReleaseEnable(release); ((SoundRetained) this.retained).setContinuousEnable(continuous); ((SoundRetained) this.retained).setEnable(enable); ((SoundRetained) this.retained).setSchedulingBounds(region); ((SoundRetained) this.retained).setPriority(priority); ((SoundRetained) this.retained).setRateScaleFactor(rateFactor); } /** * Sets fields that define the sound source data of this node. * @param soundData description of JMF source data used by this sound source * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setSoundData(MediaContainer soundData) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SOUND_DATA_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound0")); if (this instanceof BackgroundSound) ((SoundRetained) this.retained).setSoundData(soundData); else // instanceof PointSound or ConeSound ((PointSoundRetained) this.retained).setSoundData(soundData); } /** * Retrieves description/data associated with this sound source. * @return soundData description of JMF source data used by this sound source * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public MediaContainer getSoundData() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SOUND_DATA_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound1")); return ((SoundRetained) this.retained).getSoundData(); } /** * Set the overall gain scale factor applied to data associated with this * source to increase or decrease its overall amplitude. * @param amplitude (gain) scale factor * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setInitialGain(float amplitude) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_INITIAL_GAIN_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound2")); ((SoundRetained) this.retained).setInitialGain(amplitude); } /** * Get the overall gain applied to the sound data associated with source. * @return overall gain scale factor applied to sound source data. * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public float getInitialGain() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_INITIAL_GAIN_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound3")); return ((SoundRetained) this.retained).getInitialGain(); } /** * Sets a sound's loop count. * @param loopCount number of times sound is looped during play * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setLoop(int loopCount) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_LOOP_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound4")); ((SoundRetained) this.retained).setLoop(loopCount); } /** * Retrieves loop count for this sound * @return loop count * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public int getLoop() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_LOOP_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound5")); return ((SoundRetained) this.retained).getLoop(); } /** * Enables or disables the release flag for the sound associated with * this sound. * @param state release flag * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setReleaseEnable(boolean state) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_RELEASE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound6")); ((SoundRetained) this.retained).setReleaseEnable(state); } /** * Retrieves the release flag for sound associated with sound. * @return sound's release flag * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public boolean getReleaseEnable() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_RELEASE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound7")); return ((SoundRetained) this.retained).getReleaseEnable(); } /** * Enables or disables continuous play flag. * @param state denotes if deactivated sound silently continues playing * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setContinuousEnable(boolean state) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_CONT_PLAY_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound8")); ((SoundRetained) this.retained).setContinuousEnable(state); } /** * Retrieves sound's continuous play flag. * @return flag denoting if deactivated sound silently continues playing * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public boolean getContinuousEnable() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_CONT_PLAY_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound9")); return ((SoundRetained) this.retained).getContinuousEnable(); } /** * Enable or disable sound. * @param state enable (on/off) flag denotes if active sound is heard * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setEnable(boolean state) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_ENABLE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound10")); if (this instanceof BackgroundSound) ((SoundRetained) this.retained).setEnable(state); else // instanceof PointSound or ConeSound ((PointSoundRetained) this.retained).setEnable(state); } /** * Retrieves sound's enabled flag. * @return sound enabled flag * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public boolean getEnable() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_ENABLE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound21")); return ((SoundRetained) this.retained).getEnable(); } /** * Set the Sound's scheduling region to the specified bounds. * This is used when the scheduling bounding leaf is set to null. * @param region the bounds that contains the Sound's new scheduling * region. * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setSchedulingBounds(Bounds region) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SCHEDULING_BOUNDS_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound11")); ((SoundRetained) this.retained).setSchedulingBounds(region); } /** * Retrieves the Sound node's scheduling bounds. * @return this Sound's scheduling bounds information * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public Bounds getSchedulingBounds() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SCHEDULING_BOUNDS_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound12")); return ((SoundRetained) this.retained).getSchedulingBounds(); } /** * Set the Sound's scheduling region to the specified bounding leaf. * When set to a value other than null, this overrides the scheduling * bounds object. * @param region the bounding leaf node used to specify the Sound * node's new scheduling region. * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setSchedulingBoundingLeaf(BoundingLeaf region) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SCHEDULING_BOUNDS_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound11")); ((SoundRetained) this.retained).setSchedulingBoundingLeaf(region); } /** * Retrieves the Sound node's scheduling bounding leaf. * @return this Sound's scheduling bounding leaf information * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public BoundingLeaf getSchedulingBoundingLeaf() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_SCHEDULING_BOUNDS_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound12")); return ((SoundRetained) this.retained).getSchedulingBoundingLeaf(); } /** * Set sound's priority value. * @param priority value used to order sound's importance for playback. * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public void setPriority(float priority) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_PRIORITY_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound15")); ((SoundRetained) this.retained).setPriority(priority); } /** * Retrieves sound's priority value. * @return sound priority value * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public float getPriority() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_PRIORITY_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound16")); return ((SoundRetained) this.retained).getPriority(); } /** * Get the Sound's duration * @return this Sound's duration in milliseconds including repeated * loops * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public long getDuration() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_DURATION_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound17")); return ((SoundRetained) this.retained).getDuration(); } /** * Retrieves sound's 'ready' status. If this sound is fully * prepared to begin playing (audibly or silently) on all * initialized audio devices, this method returns true. * @return flag denoting if sound is immediate playable or not * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public boolean isReady() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IS_READY_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound22")); return ((SoundRetained) this.retained).isReady(); } /** * Retrieves sound's 'ready' status. If this sound is fully * prepared to begin playing (audibly or silently) on the audio * device associated with this view, this method returns true. * @param view the view on which to query the ready status. * @return flag denoting if sound is immediate playable or not * @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 boolean isReady(View view) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IS_READY_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound22")); return ((SoundRetained) this.retained).isReady(view); } /** * Retrieves sound's play status. If this sound is audibly playing on any * initialized audio device, this method returns true. * @return flag denoting if sound is playing (potentially audible) or not * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public boolean isPlaying() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IS_PLAYING_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound18")); return ((SoundRetained) this.retained).isPlaying(); } /** * Retrieves sound's play status. If this sound is audibly playing on the * audio device associated with the given view, this method returns * true. * @param view the view on which to query the isPlaying status. * @return flag denoting if sound is playing (potentially audible) or not * @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 boolean isPlaying(View view) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IS_PLAYING_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound18")); return ((SoundRetained) this.retained).isPlaying(view); } /** * Retrieves sound's silent status. If this sound is silently playing on * any initialized audio device, this method returns true. * @return flag denoting if sound is silently playing (enabled but not active) * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public boolean isPlayingSilently() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IS_PLAYING_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound18")); return ((SoundRetained) this.retained).isPlayingSilently(); } /** * Retrieves sound's silent status. If this sound is silently playing on * the audio device associated with the given view, this method returns * true. * The isPlayingSilently state is affected by enable, mute, and continuous * states as well as active status of sound. * @param view the view on which to query the isPlayingSilently status. * @return flag denoting if sound is silently playing (enabled but not active) * @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 boolean isPlayingSilently(View view) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_IS_PLAYING_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound18")); return ((SoundRetained) this.retained).isPlayingSilently(view); } /** * Retrieves number of channels that are being used to render this sound * on the audio device associated with the Virtual Universe's primary view. * @return number of channels used by sound; returns 0 if not playing * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph */ public int getNumberOfChannelsUsed() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_CHANNELS_USED_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound20")); return ((SoundRetained) this.retained).getNumberOfChannelsUsed(); } /** * Retrieves number of channels that are being used to render this sound * on the audio device associated with given view. * @param view the view on which to query the number of channels used. * @return number of channels used by sound; returns 0 if not playing * @exception CapabilityNotSetException if appropriate capability is * @since Java 3D 1.3 * not set and this object is part of live or compiled scene graph */ public int getNumberOfChannelsUsed(View view) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_CHANNELS_USED_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound20")); return ((SoundRetained) this.retained).getNumberOfChannelsUsed(view); } /** * Set mute state flag. If the sound is playing it will be set to * play silently * @param state flag * @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 setMute(boolean state) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_MUTE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound23")); ((SoundRetained) this.retained).setMute(state); } /** * Retrieves sound Mute state. * A return value of true does not imply that the sound has * been started playing or is still playing silently. * @return mute state flag * @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 boolean getMute() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_MUTE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound24")); return ((SoundRetained) this.retained).getMute(); } /** * Pauses or resumes (paused) playing sound. * @param state pause flag * @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 setPause(boolean state) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_PAUSE_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound25")); ((SoundRetained) this.retained).setPause(state); } /** * Retrieves the value of the Pause state flag. * A return value of true does not imply that the sound was * started playing and then paused. * @return pause state * @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 boolean getPause() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_PAUSE_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound26")); return ((SoundRetained) this.retained).getPause(); } /** * Sets Sample Rate. * Changes (scales) the playback rate of a sound independent of * Doppler rate changes - applied to ALL sound types. * Affects device sample rate playback and thus affects both pitch and speed * @param scaleFactor %%% describe this. * @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 setRateScaleFactor(float scaleFactor) { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_RATE_SCALE_FACTOR_WRITE)) throw new CapabilityNotSetException(J3dI18N.getString("Sound27")); ((SoundRetained) this.retained).setRateScaleFactor(scaleFactor); } /** * Retrieves Sample Rate. * @return sample rate scale factor * @exception CapabilityNotSetException if appropriate capability is * not set and this object is part of live or compiled scene graph * @since Java 3D 1.3 */ public float getRateScaleFactor() { if (isLiveOrCompiled()) if (!this.getCapability(ALLOW_RATE_SCALE_FACTOR_READ)) throw new CapabilityNotSetException(J3dI18N.getString("Sound28")); return ((SoundRetained) this.retained).getRateScaleFactor(); } /** * Copies all Sound 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); SoundRetained orgRetained = (SoundRetained) originalNode.retained; SoundRetained thisRetained = (SoundRetained) this.retained; thisRetained.setSoundData((MediaContainer) getNodeComponent(orgRetained.getSoundData(), forceDuplicate, originalNode.nodeHashtable)); thisRetained.setInitialGain(orgRetained.getInitialGain()); thisRetained.setLoop(orgRetained.getLoop()); thisRetained.setReleaseEnable(orgRetained.getReleaseEnable()); thisRetained.setContinuousEnable(orgRetained.getContinuousEnable()); thisRetained.setSchedulingBounds(orgRetained.getSchedulingBounds()); thisRetained.setPriority(orgRetained.getPriority()); thisRetained.setEnable(orgRetained.getEnable()); // updateNodeReferences will set the following correctly thisRetained.setSchedulingBoundingLeaf(orgRetained.getSchedulingBoundingLeaf()); } /** * Callback used to allow a node to check if any scene graph objects * referenced * by that node have been duplicated via a call to <code>cloneTree</code>. * This method is called by <code>cloneTree</code> after all nodes in * the sub-graph have been duplicated. The cloned Leaf node's method * will be called and the Leaf node can then look up any object references * by using the <code>getNewObjectReference</code> method found in the * <code>NodeReferenceTable</code> object. If a match is found, a * reference to the corresponding object in the newly cloned sub-graph * is returned. If no corresponding reference is found, either a * DanglingReferenceException is thrown or a reference to the original * object is returned depending on the value of the * <code>allowDanglingReferences</code> parameter passed in the * <code>cloneTree</code> call. * <p> * NOTE: Applications should <i>not</i> call this method directly. * It should only be called by the cloneTree method. * * @param referenceTable a NodeReferenceTableObject that contains the * <code>getNewObjectReference</code> method needed to search for * new object instances. * @see NodeReferenceTable * @see Node#cloneTree * @see DanglingReferenceException */ @Override public void updateNodeReferences(NodeReferenceTable referenceTable) { super.updateNodeReferences(referenceTable); SoundRetained rt = (SoundRetained) retained; BoundingLeaf bl = rt.getSchedulingBoundingLeaf(); if (bl != null) { Object o = referenceTable.getNewObjectReference(bl); rt.setSchedulingBoundingLeaf((BoundingLeaf) o); } MediaContainer sd = rt.getSoundData(); if (sd != null) { rt.setSoundData(sd); } } }