Debian Codegraph @

Documentation/Overview/sound_overview.xml

raw
1 <xml>
2 <head>
3 <title>Using sound - samples and music</title>
4 </head>
5 <body>
6
7 <p>ClanSound provides you with easy-to-use and powerful sound functionality.</p>
8
9 <h3>Sound overview</h3>
10
11 <p>To play sound in ClanLib, you have to initialize <codelink>CL_SetupSound</codelink> and also
12 create a <codelink>CL_SoundOutput</codelink>. CL_SoundOutput is the interface to a sound output device,
13 which is used to control the main mixer volume and other global settings. It is used as a singleton.</p>
14
15 <code>
16 #include <ClanLib/sound.h>
17
18 ...
19
20 CL_SetupSound setup_sound;
21 CL_SoundOutput output(44100);
22
23 ...
24 </code>
25
26 <h3>Playing wav samples</h3>
27
28 <p>A <codelink>CL_SoundBuffer</codelink> contains a sample or music stream. To load and play
29 a WAV file, you do the following:</p>
30
31 <code>
32 // Load a sample from a wave file:
33 CL_SoundBuffer sample("beep.wav");
34
35 // Play sample
36 sample.play();
37 </code>
38
39 <p>You can set the volume and panning of soundbuffers. This will change
40 the default attributes of the soundbuffer, and will be effective on all
41 subsequent calls to play().</p>
42
43 <code>
44 // Turn down volume on this soundbuffer.
45 sample.set_volume(0.1f);
46
47 // Play only in left speaker.
48 sample.set_pan(-1.0f);
49 </code>
50
51 <p>Note that setting these attributes don't affect already playing soundbuffers,
52 only when you call play() again afterwards. To have individual control over each
53 playing sound, you need to use a sound session - read about that further down.</p>
54
55 <h3>Playing music streams</h3>
56
57 <p>There isn't much difference between playing wav samples and music stream. ClanSound itself
58 doesn't provide more than wav samples playback, so you'll need one or more additional
59 music modules. ClanLib currently has two, MikMod and Vorbis. They are initialized using
60 <codelink>CL_SetupMikMod</codelink> and <codelink>CL_SetupVorbis</codelink>.</p>
61
62 <code>
63 #include <ClanLib/sound.h>
64 #include <ClanLib/vorbis.h>
65 #include <ClanLib/mikmod.h>
66
67 CL_SetupSound setup_sound;
68 CL_SetupMikMod setup_mikmod;
69 CL_SetupVorbis setup_vorbis;
70
71 CL_SoundOutput output(44100);
72 </code>
73
74 <p>Then to play music, you use the same approach as with wav samples:</p>
75
76 <code>
77 // Load ogg file into a soundbuffer
78 CL_SoundBuffer vorbis("cheer1.ogg");
79
80 // Play vorbis stream
81 vorbis.play();
82
83 ...
84
85 // Load an XM mod into a soundbuffer
86 CL_SoundBuffer mod("clanbeat.xm");
87
88 // Play mod
89 mod.play();
90 </code>
91
92 <h3>Resources</h3>
93
94 <p>TODO: Write about loading samples from resources.</p>
95
96 <h3>Sessions</h3>
97
98 <p>If you want to control the playback of sound, or want to know
99 if the sound is still playing, you use <codelink>CL_SoundBuffer_Session</codelink>.
100 This can be created in two ways, either by calling
101 CL_SoundBuffer::play() or CL_SoundBuffer::prepare().
102 The difference between prepare() and play() is that prepare will just load the sound,
103 but not play it. You can then call play() from your resulting CL_SoundBuffer_Session.</p>
104
105 <code>
106 // Load ogg file into a soundbuffer
107 CL_SoundBuffer vorbis("cheer1.ogg");
108
109 // Create a session from soundbuffer.
110 CL_SoundBuffer_Session playback = vorbis.play();
111
112 ..
113
114 // Load ogg file into a soundbuffer
115 CL_SoundBuffer vorbis("cheer1.ogg");
116
117 // Create a session from soundbuffer.
118 CL_SoundBuffer_Session playback = vorbis.prepare();
119
120 playback.play();
121 </code>
122
123 <p>When you have a session object, you can modify the attributes of
124 the playing sound in many ways. These take effect immidiately, you
125 can change it while it is playing. You can set the volume, panning,
126 position, and frequency (speed). You can make it loop, and adding filters.
127 You can query if it is still playing, and you can ofcourse start and stop
128 it as you want.</p>
129
130 <code>
131 // Load ogg file into a soundbuffer
132 CL_SoundBuffer vorbis("cheer1.ogg");
133
134 // Create a session from soundbuffer.
135 CL_SoundBuffer_Session playback = vorbis.prepare();
136
137 playback.set_volume(0.5f);
138 playback.set_looping(true);
139 playback.play();
140 </code>
141
142 <h3>Filters</h3>
143
144 <p>If you want to modify sounds in special, dynamic ways, you
145 can apply a CL_SoundFilter to it.</p>
146
147 <p>ClanLib has three builtin filters: <codelink>CL_EchoFilter</codelink>, <codelink>CL_FadeFilter</codelink> and <codelink>CL_InverseEchoFilter</codelink>.
148 The usefulness of an CL_InverseEchoFilter can be discussed :)</p>
149
150 <p>Example of the fade filter:</p>
151
152 <code>
153 // Load ogg file into a soundbuffer
154 CL_SoundBuffer vorbis("cheer1.ogg");
155
156 // Create a session from soundbuffer.
157 CL_SoundBuffer_Session playback = vorbis.prepare();
158
159 CL_FadeFilter fade(0.0f);
160
161 playback.add_filter(&fade);
162 playback.play();
163
164 fade.fade_to_volume(1.0f, 10*1000); // fade in, duration 10 seconds.
165 </code>
166
167 <p>Example of the echo filter:</p>
168
169 <code>
170 // Load ogg file into a soundbuffer
171 CL_SoundBuffer vorbis("cheer1.ogg");
172
173 // Create a session from soundbuffer.
174 CL_SoundBuffer_Session playback = vorbis.prepare();
175
176 playback.add_filter(new CL_EchoFilter(8*1024), true);
177 playback.play();
178 </code>
179
180 <p>You can ofcourse also code your own filters. Check the SoundFilters example
181 how do to that - it creates a CL_DistortFilter.</p>
182
183 <p>It is also possible to add filters on mixer level too. Ie fade all sound out alltogether.
184 Use CL_SoundOutput::add_filter() just like with CL_SoundBuffer_Session.</p>
185
186 <h3>Sound providers</h3>
187
188 <p>It is also possible to create sound on-the-fly, or adding extra sound
189 providers. See the StreamSoundProvider example for code how to do this.</p>
190
191 </body>
192 </xml>