==============================================================================
Java 3D(TM) 1.2 Sound
==============================================================================

A system's Audio device is accessed by Java 3D via the use of a specific
Java 3D AudioDevice3D implementation.  Exactly one AudioDevice3D
implementation is included in this release - it is named JavaSoundMixer
and it is in the package com.sun.j3d.audioengines.javasound.

The sound program examples use this JavaSoundMixer audio device.
A program can create and initialize an instance of JavaSoundMixer
directly with code like following:
        Canvas3D canvas = new Canvas3D(null);
        SimpleUniverse univ = new SimpleUniverse(canvas);
        univ.getViewingPlatform().setNominalViewingTransform();
        PhysicalEnvironment physicalEnv = 
                      univ.getViewer().getPhysicalEnvironment();
        if (physicalEnv != null) {
            JavaSoundMixer javaSoundMixer = new JavaSoundMixer(physicalEnv);
            if (javaSoundMixer == null) 
                System.out.println("create of audiodevice failed");
            javaSoundMixer.initialize();
        }

All of the sound example programs included in this release use the 
com.sun.j3d.utils.universe.SimpleUniverse class to create and initialize
an instance of this JavaSoundMixer:
        Canvas3D c = new Canvas3D(null);
        SimpleUniverse u = new SimpleUniverse(c);
        AudioDevice audioDev = u.getViewer().createAudioDevice();

= = = = = = = = = = = = = = = = = = = = = =
JavaSoundMixer AudioDevice3D Implememtation
= = = = = = = = = = = = = = = = = = = = = =

      The JavaSoundMixer audio device uses a preliminary version of the
      Java Sound mixing engine (licensed from Headspace Audio Engineering).

      The Java Sound engine supports the following 8- and 16- bit,
      linear and u-law, mono and stereo sound sample file formats: AU,
      AIFF, WAV, and PCM.  MIDI and RMF files are supported but not
      fully spatialized.  Neither compressed formats (DVI, GSM, MOD) 
      nor A-law formatted files are supported at this time.

      Audio Features Not Supported with this release:
      ---------------------------------------------
      Most of the Java 3D Audio API has been implemented but there are a
      few exceptions.  Additionally, some Java 3D Audio features are
      only partially implemented.

      - No cross-talk cancellation is performed when rendered audio output
        on speakers.
      - Spatialization of positional and directional sound is very rudimentary.
        Point and Cone sound will simply be panned (approximating interaural
        intensity difference)  and left-right output signals delayed
        (approximating interaural delay difference) applying gain attenuation.
        The filtering of sound source (that would aid in Elevation or Front/
        Back differentiation cues) is not implemented with this AudioDevice.
      - For this release, Sound.POSITIVE_INFINITY is mapped to 2^15.

      Reverberation in JavaSoundMixer implementation:
      -----------------------------------------------
          The JavaSound engine supports these 5 reverberation environments:
               "Closet"         very small area, very absorptive surfaces
               "Acoustic Lab"   med. small area,  equally absorptive/reflective
               "Garage"         med. large area, somewhat reflective surfaces
               "Dungeon"        medium area, reflective surfaces
               "Cavern"         large area, highly reflective surfaces

	  The AuralAttributes parameters dealing with reverb -
	reflection coefficient, delay and order - are combined to
	choose one of these five reverberant environments.  Order is
	NOT controllable, nor does it have a natural parallel.  For
	this reason Order and Reflection are combined to determine a
	'Decay Speed'.  This speed, paired with the size of the space
	implied by the Delay parameter determine the JavaSound Reverb
	type that is set:

                                     |  Short:               Long:
                         Decay Speed |    Coeff <= 0.9         Coeff > 0.9
               Room Size             |    Order <= 8           Order > 8
               --------------------------------------------------------------
               small (<100ms)        |    "Closet"             "Acoustic Lab"
               medium  (<500ms)      |    "Garage"             "Dungeon"
               large   (>500ms)      |    "Dungeon"            "Cavern"

	   For this release, region does NOT affect the size of the
	reverberant space.  Size must be set via the Reverb Delay
	parameter.  The size (delay) parameter takes precedence over
	all others.
	   Last changed Reflection Coeff or Order is what is used for
	determining decay speed.  If both Coefficient and Order changed,
	coefficient takes precedence.
	   A "feature" of JavaSound 'dungeon' reverb type is that the
	reverberation is added to the opposite pan position from the
	sound's position.  This creates an aural effect that sounds
	like the reverberation is bouncing off the opposite wall of
	the 'dungeon'.

      Using MIDI/RMF MediaContainersL
      -------------------------------
      MIDI file playback as BackgroundSound and attenuated Point/ConeSounds
      is at least partially supported with the following limitations:
      - For this release MIDI data is automatically cached.
      - Point/ConeSound nodes that use MIDI MediaContainers can not be 
        panned or delayed to simulate Interaural Intensity or Time 
        Differences using the JavaSoundMixer AudioDevice3D implementation
        in this release due to the limitiation of the underlying
        technology used in the JavaSoundMixer AD3D implementation.

      General Installation Notes:
      --------------------------
      - If your Java 3D application has trouble acquiring the AudioDevice
        ("Audio Device unavailable" exception occurs) you may need to exit
        other applications that use sound.  NOTE: If this occurs we would
        appreciate being informed as to which sound application Java 3D had
        problems running simultaneously with.
      - Combining calls to JMF 1.0 methods in your Java 3D sound application
        is still dangerous.  The Java Sound engine used by both APIs is not
        yet robust enough to handle supporting both of these concurrently.

==============================================================================
Known Problems
==============================================================================

      -	Cross-talk cancellation for sound playback in not implemented
      -	Sounds are stopped when the window is iconified; they should
	keep playing
      - Sounds are not stopped when pressing browser back button
      -	Filtering causes loud, sweeping resonance to be added to most sounds
      - Occational spikes in Doppler calculation causes wild exaggerated
        pitch shifting
      -	Multiple sample channels are not always synchronized when started
      - Sound performance on native threads is bad
