/* * @(#)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.