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
|
<h2>OpenSceneGraph Audio Library (osgAL)</h2>
<p>osgAL is a toolkit for handling spatial (3D) sound in the <a href="http://www.openscenegraph.org">OpenSceneGraph</a>
rendering library. It utilizes <a href="http://sf.net/projects/alpp">OpenAL++</a>
which is an portable object oriented toolkit ontop of <a href="http://www.openal.org">OpenAL</a>.
It has been compiled and tested under Windows (.NET2003) and Linux (gcc3.2).
</p>
<h2> </h2>
<h2>Dependencies</h2>
<p>osgAL depends on OpenAL++ and OpenSceneGraph. It has been compiled with <a href="http://www.openscenegraph.org">OSG
0.9.9</a>. Download and build <a href="http://sf.net/projects/alpp">OpenAL++</a>
and OSG and install header files and library files where the compiler can find
them. </p>
<p>Under Windows, you have
to setup the INCLUDE, LIB and PATH path, which can be done with the Environment
variables </p>
<p> DOS> set INCLUDE=%INCLUDE%;c:\tools\openalpp\include<br>
DOS> set LIB=%LIB%;c:\tools\openalpp\lib<br>
DOS> set PATH=%PATH%;c:\tools\openalpp\bin</p>
<p> respectively.
</p>
<h2>Basic Concepts</h2>
<p>There are five main classes:</p>
<ul>
<li>SoundManager</li>
<li>SoundState</li>
<li>SoundNode</li>
<li>SoundRoot</li>
<li>SoundOccluder</li>
</ul>
<h3>SoundState</h3>
<p>A <i>SoundState</i> is
a small lightweight class that contains a reference to a <i>osgAL::Sample</i>
and the settings for a <i>Sample</i>. This class does nothing more than keeping
this <i>Sample</i> and its associated attributes together. It can either have
a <i>osgAL::SoundSource</i> (usually a limited resources, 32 or more) associated
to it. Sometimes it is necessary to allocate a hardware soundsource to a soundstate,
for example looping sounds with ambient sound or music.</p>
<h3>SoundNode</h3>
<p>SoundSource is derived
from osg::Node and can be inserted into the scenegraph wherever one wants it
to be. During update traversal it will calculate its world position and position
the associated SoundState to right orientation and position. No culling is done
currently.</p>
<h3>SoundManager</h3>
<p>The SoundManager is responsible
for handling queued SoundStates (for sound events described below) and to store
all SoundStates to make it possible to find them later on.</p>
<h3>SoundRoot</h3>
<p>A node that during cull
traversal updates the SoundManager and updates the transformation for the current
listener from the current modelView matrix. This could be done manually, but
this node makes it all happen automatically during the cull traversal, which
reduces the need of inserting code in the viewer run loop.</p>
<h3>OccludeCallback</h3>
<p>This is a callback class,
called during the update of the transformation of the SoundNode. If enabled
this callback will shoot a ray from the listener to this SoundNode. If this
ray is unoccluded nothing will happen. But if this ray is occluded by some geometry,
the gain of the SoundState associated to this node will be reduced by some amount.
The functionality of this callback can be extended by inheriting from OccludeCallback
and attaching it to the SoundNode.</p>
<p></p>
<p> </p>
<h2>Sound Events</h2>
<p>There is a concept that
I call event, for example an explosion is a typical event where a short sound
is played once. Another example is the contact sound generated from two colliding
objects. When using for example rigid body dynamics, there can be a lot of sound
events when objects collides, therefore, the osgAL::SoundManager has a method
called <i>pushSoundEvent(osgAL::SoundState *, int priority)</i></p>
<p>This method takes a SoundState
as argument. By making a copy of this SoundState (it uses an internal flyweight
pattern to avoid creating new SoundStates on the fly) it builds up a queue of
SoundStates. Theese SoundStates are played one by one by the SoundManager during
its update() call. This makes it possible to have a lot of SoundStates "playing"
when there is a real shortage of hardware sound sources (usually 32 or so).</p>
<h2>IO Support</h2>
<p>Thanks to a great contribution of Alberto Jaspe, videaLAB, University of La
Coruña (jaspe@udc.es), osgAL now also support IO.<br>
This is easily tested by running one of the sample application, (i.e. osgal)
and press 'o' to save the current scene to a file named saved_model.osg.<br>
The file saved_model.osg will then also contain the information from osgAL regarding
soundnodes, soundstates etc...</p>
<p>This means that scenes containing sound can also be authored through the .osg
file format.<br>
The best documentation for the file format is to look into an existing file,
in the /data subdirectory there are a few sample scenes.</p>
<h2>Documentation</h2>
<p><a href="html/index.html">API
reference</a></p>
<h2>Example</h2>
<p>osgal.cpp - Code for testapplication. </p>
<p>osgalmultiple.cpp - Shows dynamic allocation/deallocation of samples.</p>
<p>osgalocclude.cpp - Demonstrates a simple sound occlusion example.</p>
<h4>To run the examples: </h4>
<p>Change directory to the
data sub-directory that contains the bee.wav sample file (<i>data</i>). Start
the test application with osgal (make sure you have the path to the dynamic
libraries (OSG, Producer, OpenThreads, OpenAL++ and osgAL).</p>
<h4>Keybindings</h4>
<i>space</i> - Pushes a SoundState
as an Event (non-looping). Results in a sound that plays once at the position
of the listener. Pressing it repeatedly will add even more SoundStates...
<p>The examples demonstrates
the basic functionality of the OSGAL toolkit:</p>
<ul>
<li>Creating an osgal::Sample
(which holds the .wav sample file)</li>
<li>Creating an osgAL::SoundState
(which holds a Sample and settings)</li>
<li>Creating an osgAL::SoundNode
(which holds a SoundState) and attaching it to a transformation node to make
it move.</li>
<li>Creating an osgAL::SoundRoot
(which updates the SoundManager and the transformation of the listener according
to the modelViewMatrix).</li>
<li>Accessing the osgAL::SoundManager
to add SoundStates and pushing SoundStates as events.</li>
<li>Handling occlusions
of geometry in the scene</li>
</ul>
<h2>Comments</h2>
Direct your comments, bug
reports to <a href="mailto:andersb@cs.umu.se">andersb@cs.umu.se</a>
|
