From 53ebfcc5ad5554b67d2287f8b02c22ec8405af0f Mon Sep 17 00:00:00 2001 From: kcr Date: Wed, 9 Jun 2004 03:28:13 +0000 Subject: Initial creation of j3d-examples sources in CVS repository --- src/Sound/README.release | 226 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 src/Sound/README.release (limited to 'src/Sound/README.release') 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. -- cgit v1.2.3