Initial creation of j3d-examples sources in CVS repository

1 files changed, 226 insertions, 0 deletions

diff --git a/src/Sound/README.release b/src/Sound/README.release
new file mode 100644
index 0000000..25a8045
--- /dev/null
+++ b/src/Sound/README.release
@@ -0,0 +1,226 @@
+/*
+ *	@(#)README.release 1.7 01/10/14 09:42:38
+ *
+ * Copyright (c) 1996-2001 Sun Microsystems, Inc. All Rights Reserved.
+ */
+
+==========================================================================
+Java 3D(TM) Sound 1.3 Beta 1
+==========================================================================
+
+Java 3D sound is rendered via the use of a specific implementation
+of the AudioDevice3D interface.   This release includes two AudioDevice3DL2
+implementations.
+
+= = = = = = = = = = = = = = = = = = = = = = = 
+HeadspaceMixer AudioDevice3DL2 Implememtation
+= = = = = = = = = = = = = = = = = = = = = = = 
+
+   The HeadspaceMixer implementation is part of the Sun Java 3D 
+   com.sun.j3d.audioengines.headspace package.  This implementation
+   uses a version of the Headspace Audio Engine licensed from Beatnik
+   which does all rendering in software and pipes the stereo audio image 
+   to the platform's audio device.
+
+   The implemention that was called JavaSoundMixer in previous Sun 
+   releases of Java 3D has been renamed to HeadspaceMixer.
+   It was renamed in enticipation of the release of a new AudioDevice
+   implementation that uses JavaSound API which will be called JavaSoundMixer
+   (described below).
+
+   The HeadspaceMixer audio device will be created and initialized when the
+   utility SimpleUniverse.Viewer.createAudioDevice() method is called.
+   If your application uses this utility, no change will be required to
+   use the recommended HeadspaceMixer implementation.
+
+   If your application explicitly used the older JavaSoundMixer audio device 
+   implemention from the package com.sun.j3d.audioengines.javasound, you should
+   change the reference to JavaSoundMixer, at least for this Beta 1 release,
+   to HeadspaceMixer:
+
+          import com.sun.j3d.audioengines.headspace.HeadspaceMixer;
+             :
+          HeadspaceMixer mixer = new HeadspaceMixer(physicalEnvironment);
+
+   Most of the Java 3D Audio features have been implemented but there are
+   a few exceptions.  Additionally, some Java 3D Audio features are only
+   only partially implemented.
+
+   Hang under JDK 1.3 on Windows platforms
+   ---------------------------------------
+   Occationally, some applications when run under JDK 1.3 on Windows 
+   experienced window manager hangs.  This problem could not be produced
+   under JDK 1.4.  It is recommended that if this problem arrises with
+   your application that JDK 1.4 be used.
+
+   Audio Features Not Supported with this release:
+   -----------------------------------------------
+      - Cross-talk cancellation is not 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, distance and angular low-pass filtering of sound
+        sources is implemented with a very simple algorithm (that choose speed
+        over accuracy).
+      - For this release, Sound.POSITIVE_INFINITY is mapped to 2^15.
+
+   Supported MediaContainers data
+   ------------------------------
+      This engine supports 8- and 16- bit linear, and u-law and A-law formatted
+      files in mono and stereo AU, AIFF, WAV, and PCM file formats.
+      Compressed formats such as DVI, GSM, and MOD are not supported at this
+      time.  Encoded format such as MP3 are not supported.
+
+      MIDI and RMF files are supported but not fully spatialized.
+      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 due to the limitiation of the underlying technology
+        used in this implementation.
+
+      InputStreams as MediaContainers are not supported for Point or
+        ConeSounds in this implementation.
+
+   Reverberation
+   -------------
+      The Headspace 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 -
+      early and late reflection coefficient and delay time, reverb decay
+      time - are compared to choose one of these five software aural
+      environments offered as part of the Headspace engine. 
+      Decay speed, paired with the explicit or implicit size of the space,
+      determine the Headspace Reverb type that is set:
+
+                               |  Short:               Long:
+            Size    Delay Time |    Decay <= 1500ms      Decay > 1500ms
+           ---------------------------------------------------------------
+            small   (< 100ms)  |    2 "Closet"           4 "Acoustic Lab"
+            medium  (<=500ms)  |    3 "Garage"           6 "Dungeon"
+            large   (> 500ms)  |    6 "Dungeon"          5 "Cavern"
+
+      A "feature" of this engines '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'.
+
+= = = = = = = = = = = = = = = = = = = = = = = 
+JavaSoundMixer AudioDevice3DL2 Implememtation
+= = = = = = = = = = = = = = = = = = = = = = = 
+
+   The JavaSoundMixer implementation is part of the Sun Java 3D 
+   com.sun.j3d.audioengines.javasound package.  This implementation uses
+   the Java Sound API.  All low-level access to the platforms audio device
+   are dependent on the Java Sound mixer implementation(s) installed on
+   the machine you're running on.
+
+   The JavaSoundMixer Java 3D audio device implementation uses Java Sound
+   SourceDataLine streams for non-cached data and Java Sound Clips for
+   cached data.  Support for specific sound cards, the exact input formats
+   that can be passed as data to Java 3D MediaContainers, and which feature
+   are rendered in software verses accelleration hardware is dependent on
+   the Java Sound implementation installed on your machine.
+   There is guarenteed to be at least one Java Sound mixer implementation
+   available with all J2SE releases (such as Sun's JDK 1.3 and above).
+
+   Audio Features Not Supported with this release:
+   -----------------------------------------------
+      The JavaSoundMixer is a brand new implementation as of 1.3 Beta 1
+      release.  While much of the Java 3D Audio API has been implemented
+      but there are known problems and limitations. Additionally, some Java
+      3D Audio features are only partially implemented.
+
+      - Non-linear file formats (A-law and u-law) are not converted.
+      - MIDI files for all sound types are not implemented.
+      - There are several timing and channel synchronization problems
+        encountered when Point and Cone Sounds are rendered.
+      - Distance and angular low-pass filtering of sound source is not 
+        implemented.
+      - Spatialization of positional and directional sound is very rudimentary.
+        See notes above under HeadspaceMixer.
+      - Cross-talk cancellation for speaker playback is not performed.
+
+      Until these isues are fixed in next Beta 2 release it is recommended
+      that you use the the HeadspaceMixer implementation.
+
+   Supported MediaContainers data
+   ------------------------------
+      The intent is that all MediaContainer input data types supported by 
+      Java Sound will also be supported by the JavaSoundMixer implementation.
+      This implementation will not have the restrictions on InputStreams as
+      the HeadspaceMixer implementation has.
+
+   Reverberation
+   -------------
+      Java 3D reverberation parameters map to a corresponding set
+      reverb control parameters available thru JavaSound API for Clips
+      (cached MediaContainers).  The exact auralization rendering based
+      on these parameters is dependent on the Java Sound mixer implementation
+      choosen.
+
+= = = = = = = = = = = = = = = = = = = = = = = 
+Use
+= = = = = = = = = = = = = = = = = = = = = = = 
+Any Java 3D program that wants to render sounds must create and initialize
+an instance of either HeadspaceMixer or JavaSoundMixer directly or indirectly
+(using SimpleUniverse utilities).
+
+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 the HeadspaceMixer with the following code:
+
+        Canvas3D c = new Canvas3D(null);
+        SimpleUniverse u = new SimpleUniverse(c);
+        AudioDevice audioDev = u.getViewer().createAudioDevice();
+
+As application can initialize the HeadspaceMixer implementation directly
+with code like following:
+     
+    import com.sun.j3d.audioengines.headspace.HeadspaceMixer;
+           :
+    Canvas3D canvas = new Canvas3D(null);
+    SimpleUniverse univ = new SimpleUniverse(canvas);
+    univ.getViewingPlatform().setNominalViewingTransform();
+    PhysicalEnvironment physicalEnv = 
+           univ.getViewer().getPhysicalEnvironment();
+    if (physicalEnv != null) {
+        HeadspaceMixer mixer = new HeadspaceMixer(physicalEnv);
+        if (mixer == null) 
+            System.out.println("creation of audio device failed");
+        mixer.initialize();
+    }
+
+NOTE: Sun JDK has an implementation of the javax.sound.sampled.Mixer
+interface named 'HeadspaceMixer'.  If your application also imports the
+javax.sound.sampled package you'll need to explicitly differentiate by
+specifying the full Java 3D package when referencing HeadspaceMixer:
+             :
+        com.sun.j3d.audioengines.headspace.HeadspaceMixer mixer = 
+             new com.sun.j3d.audioengines.headspace.HeadspaceMixer(physicalEnv);
+             :
+
+
+==========================================================================
+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 engines used by both APIs may not yet be
+      robust enough to handle supporting both of these concurrently.