Gets Harvey's changes

1 files changed, 271 insertions, 0 deletions

diff --git a/src/javax/media/j3d/AudioDevice.java b/src/javax/media/j3d/AudioDevice.java
new file mode 100644
index 0000000..1aab9fc
--- /dev/null
+++ b/src/javax/media/j3d/AudioDevice.java
@@ -0,0 +1,271 @@
+/*
+ * 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;
+
+
+/**
+ * The AudioDevice Class defines and encapsulates the
+ * audio device's basic information and characteristics.
+ * <P>
+ * A Java3D application running on a particular machine could have one of
+ * several options available to it for playing the audio image created by the
+ * sound renderer. Perhaps the machine Java3D is executing on has more than
+ * one sound card (e.g., one that is a Wave Table Synthesis card and the other
+ * with accelerated sound spatialization hardware). Furthermore, suppose there
+ * are Java3D audio device drivers that execute Java3D audio methods on each of
+ * these specific cards. In such a case the application would have at least two
+ * audio device drivers through which the audio could be produced. For such a
+ * case the Java3D application must choose the audio device driver with which
+ * sound rendering is to be performed. Once this audio device is chosen, the
+ * application can additionally select the type of audio playback type the
+ * rendered sound image is to be output on. The playback device (headphones or
+ * speaker(s)) is physically connected to the port the selected device driver
+ * outputs to.
+ *<P>
+ * AudioDevice Interface
+ *<P>
+ *<UL> The selection of this device driver is done through methods in the
+ *     PhysicalEnvironment object - see PhysicalEnvironment class.
+ *     The application would query how many audio devices are available. For
+ *     each device, the user can get the AudioDevice object that describes it
+ *     and query its characteristics. Once a decision is made about which of
+ *     the available audio devices to use for a PhysicalEnvironment, the
+ *     particular device is set into this PhysicalEnvironment's fields. Each
+ *     PhysicalEnvironment object may use only a single audio device.
+ *<P>
+ *     The AudioDevice object interface specifies an abstract input device
+ *     that creators of Java3D class libraries would implement for a particular
+ *     device. Java3D's uses several methods to interact with specific devices.
+ *     Since all audio devices implement this consistent interface, the user
+ *     could have a portable means of initialize, set particular audio device
+ *     elements and query generic characteristics for any audio device.
+ *<P>
+ *Initialization
+ *<P><UL>
+ *  Each audio device driver must be initialized.
+ *  The chosen device driver should be initialized before any Java3D
+ *  Sound methods are executed because the implementation of the Sound
+ *  methods, in general, are potentially device driver dependent.</UL>
+ *<P>
+ * Audio Playback Type
+ *<P><UL>
+ *  These methods set and retrieve the audio playback type used to output
+ *  the analog audio from rendering Java3D Sound nodes.
+ *  The audio playback type specifies that playback will be through:
+ *  stereo headphones, a monaural speaker,  or a pair of speakers.
+ *  For the stereo speakers, it is assumed that the two output speakers are
+ *  equally distant from the listener, both at same angle from the head
+ *  axis (thus oriented symmetrically about the listener), and at the same
+ *  elevation.
+ *  The type of playback chosen affects the sound image generated.
+ *  Cross-talk cancellation is applied to the audio image if playback over
+ *  stereo speakers is selected.</UL>
+ *<P>
+ * Distance to Speaker
+ *<P><UL>
+ * These methods set and retrieve the distance in meters from the center
+ * ear (the midpoint between the left and right ears) and one of the
+ * speakers in the listener's environment. For monaural speaker playback,
+ * a typical distance from the listener to the speaker in a workstation
+ * cabinet is 0.76 meters. For stereo speakers placed at the sides of the
+ * display, this might be 0.82 meters.</UL>
+ *<P>
+ *  Angular Offset of Speakers
+ *<P><UL>
+ *  These methods set and retrieve the angle in radians between the vectors
+ *  from the center ear to each of the speaker transducers and the vectors
+ *  from the center ear parallel to the head coordinate's Z axis. Speakers
+ *  placed at the sides of the computer display typically range between
+ *  0.28 to 0.35 radians (between 10 and 20 degrees).</UL>
+ *<P>
+ *  Device Driver Specific Data
+ *<P><UL>
+ *  While the sound image created for final output to the playback system
+ *  is either only mono or stereo (for this version of Java3D) most device
+ *  driver implementations will mix the left and right image signals
+ *  generated for each rendered sound source before outputting the final
+ *  playback image. Each sound source will use N input channels of this
+ *  internal mixer. Each implemented Java3D audio device driver will have
+ *  its own limitations and driver-specific characteristics. These include
+ *  channel availability and usage (during rendering).  Methods for
+ *  querying these device-driver specific characteristics are provided.</UL></UL>
+ *<P>
+ * Instantiating and Registering a New Device
+ *<P>
+ *<UL> A browser or applications developer must instantiate whatever system-
+ *     specific audio devices that he or she needs and that exist on the system.
+ *     This device information typically exists in a site configuration file.
+ *     The browser or application will instantiate the physical environment as
+ *     requested by the end-user.
+ *<P>
+ *     The API for instantiating devices is site-specific, but it consists of
+ *     a device object with a constructor and at least all of the methods
+ *     specified in the AudioDevice interface.
+ *<P>
+ *     Once instantiated, the browser or application must register the device
+ *     with the Java3D sound scheduler by associating this device with a
+ *     PhysicalEnvironment.  The setAudioDevice method introduces new devices
+ *     to the Java3D environment and the allAudioDevices method produces an
+ *     enumeration that allows examining all available devices within a Java3D
+ *     environment. See PhysicalEnvironment class for more details.</UL>
+ * <P>
+ * General Rules for calling AudioDevice methods:
+ * It is illegal for an application to call any non-query AudioDevice method
+ * if the AudioDevice is created then explicitly assigned to a
+ * PhysicalEnvironment using PhysicalEnvironment.setAudioDevice();
+ * When either PhysicalEnvironment.setAudioDevice() is called - including
+ * when implicitly called by SimpleUniverse.getViewer().createAudioDevice()
+ * - the Core creates a SoundScheduler thread which makes calls to
+ * the AudioDevice.
+ * <P>
+ * If an application creates it's own instance of an AudioDevice and
+ * initializes it directly, rather than using PhysicalEnvironment.
+ * setAudioDevice(), that application may make <i>any</i> AudioDevice3D methods calls
+ * without fear of the Java 3D Core also trying to control the AudioDevice.
+ * Under this condition it is safe to call AudioDevice non-query methods.
+ */
+
+public interface AudioDevice {
+
+    /** *************
+     *
+     * Constants
+     *
+     ****************/
+    /**
+     *  Audio Playback Types
+     *
+     *  Types of audio output device Java3D sound is played over:
+     *     Headphones, MONO_SPEAKER, STEREO_SPEAKERS
+     */
+    /**
+     *     Choosing Headphones as the audio playback type
+     *     specifies that the audio playback will be through stereo headphones.
+     */
+    public static final int HEADPHONES = 0;
+
+    /**
+     *     Choosing a
+     *     single near-field monoaural speaker
+     *     as the audio playback type
+     *     specifies that the audio playback will be through a single speaker
+     *     some supplied distance away from the listener.
+     */
+    public static final int MONO_SPEAKER = 1;
+
+    /**
+     *     Choosing a
+     *     two near-field stereo speakers
+     *     as the audio playback type
+     *     specifies that the audio playback will be through stereo speakers
+     *     some supplied distance away from, and at some given angle to
+     *     the listener.
+     */
+    public static final int STEREO_SPEAKERS = 2;
+
+    /**
+     * Initialize the audio device.
+     * Exactly what occurs during initialization is implementation dependent.
+     * This method provides explicit control by the user over when this
+     * initialization occurs.
+     * Initialization must be initiated before any other AudioDevice
+     * methods are called.
+     * @return true if initialization was successful without errors
+     */
+    public abstract boolean initialize();
+
+    /**
+     * Code to close the device and release resources.
+     * @return true if close of device was successful without errors
+     */
+    public abstract boolean close();
+
+    /**
+     * Set Type of Audio Playback physical transducer(s) sound is output to.
+     *     Valid types are HEADPHONES, MONO_SPEAKER, STEREO_SPEAKERS
+     * @param type audio playback type
+     */
+    public abstract void setAudioPlaybackType(int type);
+
+    /**
+     * Get Type of Audio Playback Output Device.
+     * @return audio playback type
+     */
+    public abstract int getAudioPlaybackType();
+
+    /**
+     * Set Distance from interaural mid-point between Ears to a Speaker.
+     * @param distance from interaural midpoint between the ears to closest speaker
+     */
+    public abstract void setCenterEarToSpeaker(float distance);
+
+    /**
+     * Get Distance from interaural mid-point between Ears to a Speaker.
+     * @return distance from interaural midpoint between the ears to closest speaker
+     */
+    public abstract float getCenterEarToSpeaker();
+
+    /**
+     * Set Angle Offset (in radians) To Speaker.
+     * @param angle in radians from head Z axis and vector from center ear to speaker
+     */
+    public abstract void setAngleOffsetToSpeaker(float angle);
+
+    /**
+     * Get Angle Offset (in radians) To Speaker.
+     * @return angle in radians from head Z axis and vector from center ear to speaker
+     */
+    public abstract float getAngleOffsetToSpeaker();
+
+    /**
+     * Query total number of channels available for sound rendering
+     * for this audio device.  This returns the maximum number of channels
+     * available for Java3D sound rendering for all sound sources.
+     * @return total number of channels that can be used for this audio device
+     */
+     public abstract int getTotalChannels();
+
+    /**
+     * Query number of channels currently available for use.
+     * During rendering, when sound nodes are playing, this method returns the
+     * number of channels still available to Java3D for rendering additional
+     * sound nodes.
+     * @return total number of channels current available
+     */
+     public abstract int getChannelsAvailable();
+
+    /**
+     * Query number of channels that are used, or would be used to render
+     * a particular sound node.  This method returns the number of channels
+     * needed to render a particular Sound node.  The return value is the same
+     * no matter if the Sound is currently active and enabled (being played) or
+     * is inactive.
+     * @return number of channels a particular Sound node is using or would used
+     * if enabled and activated (rendered).
+     */
+     public abstract int getChannelsUsedForSound(Sound node);
+}