sound.java

JAVA3D矩陈的相关类

/*
 * $RCSfile: Sound.java,v $
 *
 * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.5 $
 * $Date: 2007/02/09 17:18:23 $
 * $State: Exp $
 */

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.