aboutsummaryrefslogtreecommitdiffstats
path: root/src/Sound/README.release
blob: 25a80454156577f75388c50081dbaa6bcb6f0c3c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
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.