audiodevice3d.java

JAVA3D矩陈的相关类

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

package javax.media.j3d;

import javax.vecmath.*;


/**
 * The AudioDevice3D class defines a 3D audio device that is used to set
 * sound and aural attributes.
 *<P>
 * After the application chooses the AudioDevice3D that Java3D sound
 * is to be rendered on, the Java 3D Sound Scheduler will call these
 * methods for all active sounds to render them on the audio device.
 *<P>
 * The intent is for this interface to be implemented by AudioDevice Driver
 * developers using a software or hardware sound engine of their choice.
 *<P>
 * Methods in this interface provide the Java3D Core a generic way to
 * set and query the audio device the application has chosen audio rendering
 * to be performed on.  Methods in this interface include:
 * <UL>
 *    Set up and clear the sound as a sample on the device.
 * <P>
 *    Start, stop, pause, unpause, mute, and unmute of sample on the device.
 * <P>
 *    Set parameters for each sample corresponding to the fields in the 
 *    Sound node.
 * <P>
 *    Set the current active aural parameters that affect all positional samples.
 * </UL>
 * <P>
 * Sound Types
 * <P>
 * Sound types match the Sound node classes defined for Java 3D core
 * for BackgroundSound, PointSound, and ConeSound.  The type of sound
 * a sample is loaded as determines which methods affect it.
 * 
 * <P>
 * Sound Data Types
 * <P>
 * Samples can be processed as streaming or buffered data.
 * Fully spatializing sound sources may require data to be buffered.
 * 
 */

public interface AudioDevice3D extends AudioDevice {

     /**
      *  Specifies the sound type as background sound.
      */  
     public static final int BACKGROUND_SOUND = 1;

     /**
      *  Specifies the sound type as point sound.
      */
     public static final int POINT_SOUND      = 2;

     /**
      *  Specifies the sound type as cone sound.
      */

     public static final int CONE_SOUND       = 3;

     /**
      *  Sound data specified as Streaming is not copied by the AudioDevice
      *  driver implementation.  It is up to the application to ensure that
      *  this data is continuously accessible during sound rendering.
      *  Furthermore, full sound spatialization may not be possible, for
      *  all AudioDevice3D implementations on unbuffered sound data.
      */
     public static final int STREAMING_AUDIO_DATA = 1;
     /**
      *  Sound data specified as Buffered is copied by the AudioDevice
      *  driver implementation.
      */
     public static final int BUFFERED_AUDIO_DATA = 2;


    /**
     * Accepts a reference to the current View.
     * Passes reference to current View Object.  The PhysicalEnvironment
     * parameters (with playback type and speaker placement), and the 
     * PhysicalBody parameters (position/orientation of ears)
     * can be obtained from this object, and the transformations to/from
     * ViewPlatform coordinate (space the listener's head is in) and
     * Virtual World coordinates (space sounds are in).
     * <P>
     * This method should only be called by Java3D Core and NOT by any application.
     * @param reference the current View
     */
    public abstract void  setView(View reference);

    /**
     * Accepts a reference to the MediaContainer
     * which contains a reference to sound data and information about the
     * type of data it is.  A "sound type" input parameter denotes if the
     * Java 3D sound associated with this sample is a Background, Point, or
     * Cone Sound node.
     * 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, or loading sound data into the device.
     * Unless the cached flag is true, this sound data should NOT be copied,
     * if possible, into host or device memory.
     *<P>
     * Once this preparation is complete for the sound sample, an AudioDevice
     * specific index, used to reference the sample in future method calls,
     * is returned.  All the rest of the methods described below require
     * this index as a parameter.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param soundType defines the type of Sound Node: Background, Point, and 
     * Cone
     * @param soundData reference to MediaContainer sound data and cached flag
     * @return device specific sample index used for referencing this sound
     */
    public abstract int   prepareSound(int soundType, MediaContainer soundData);

    /**
     * Requests that the AudioDevice free all
     * resources associated with sample with index id.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     */
    public abstract void   clearSound(int index);

    /**
     * Returns the duration in milliseconds of the sound sample,
     * if this information can be determined.
     * For non-cached
     * streams, this method returns Sound.DURATION_UNKNOWN.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @return sound duration in milliseconds if this can be determined,
     * otherwise (for non-cached streams) Sound.DURATION_UNKNOWN is returned
     */
    public abstract long   getSampleDuration(int index);

    /**
     *   
     * Retrieves the number of channels (on executing audio device) that 
     * this sound is using, if it is playing, or is expected to use 
     * if it were begun to be played.  This form of this method takes the
     * sound's current state (including whether it is muted or unmuted)
     * into account.
     *<P>
     * For some AudioDevice3D implementations: 
     *<UL>
     *     Muted sound take channels up on the systems mixer (because they're
     *         rendered as samples playing with gain zero.
     *<P>
     *     A single sound could be rendered using multiple samples, each taking 
     *         up mixer channels.
     *</UL>
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @return number of channels used by sound if it were playing
     */  
    public abstract int    getNumberOfChannelsUsed(int index);

    /**
     *   
     * Retrieves the number of channels (on executing audio device) that 
     * this sound is using, if it is playing, or is projected to use if
     * it were to be started playing.  Rather than using the actual current
     * muted/unmuted state of the sound, the muted parameter is used in
     * making the determination.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @param muted flag to use as the current muted state ignoring current
     * mute state
     * @return number of channels used by sound if it were playing
     */  
    public abstract int    getNumberOfChannelsUsed(int index, boolean muted);

    /**
     * Begins a sound playing on the AudioDevice.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @return flag denoting if sample was started; 1 if true, 0 if false
     */
    public abstract int    startSample(int index);

    /**
     * Returns the system time of when the sound
     * was last "started".  Note that this start time will be as accurate
     * as the AudioDevice implementation can make it - but that it is not
     * guaranteed to be exact.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @return system time in milliseconds of the last time sound was started
     */
    public abstract long   getStartTime(int index);

    /**
     * Stops the sound on the AudioDevice.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * associated with sound data to be played
     * @return flag denoting if sample was stopped; 1 if true, 0 if false
     */
    public abstract int    stopSample(int index);

    /**
     * Sets the overall gain scale factor applied to data associated with this 
     * source to increase or decrease its overall amplitude.
     * The gain scale factor value passed into this method is the combined value
     * of the Sound node's Initial Gain and the current AuralAttribute Gain
     * scale factors.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @param scaleFactor amplitude (gain) scale factor
     */
    public abstract void   setSampleGain(int index, float scaleFactor);

    /**
     * Sets a sound's loop count.
     * A full description of this parameter and how it is used is in 
     * the documentation for Sound.setLoop.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @param count number of times sound is looped during play
     * @see Sound#setLoop
     */
    public abstract void   setLoop(int index, int count);

    /**
     * Passes a reference to the concatenated transformation to be applied to
     * local sound position and direction parameters.
     * <P> 
     * This method should only be called by Java3D Core and NOT by any application.
     * @param index device specific reference number to device driver sample
     * @param trans transformation matrix applied to local coordinate parameters
     */
    public abstract void  setVworldXfrm(int index, Transform3D trans);


    /**
     * Sets this sound's location (in Local coordinates) from specified