<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Using sound - samples and music - ClanLib Game SDK</title>
<link rel="stylesheet" type="text/css" href="../../default.css">
</head>
<body style="background-color: #a4daea; color: black; margin: 1em 3em 1em 3em;">
<div style="border-style: solid; border-width:thin; border-color: black;">
<div style="background-color: white; color: black; padding: .3em 1em .3em 1em; border-bottom-style: dotted; border-bottom-width: 2px;">
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td align="center">
<h1>
<a href="http://www.clanlib.org"><img style="border-style: none; padding-right: 130px;" src="../../gfx/clanlib.png" alt="ClanLib"></a>
</h1>
</td>
</tr>
</table>
<!--<div class="menu">
<a href="index.html">News</a>
<a href="intro.html">About</a>
<a href="download.html">Download</a>
<a href="cvs.html">CVS</a>
<a class="active" href="docs.html">Docs</a>
<a href="games.html">Games</a>
<a href="contact.html">Contact</a>
<a href="links.html">Links</a>
</div>-->
</div>
<div style="background-color: white; padding: 1em 3em 1em 3em;">
<!-- clanlib header end -->
<div style="border-bottom-style: dotted; border-bottom-width: 1px; margin-bottom: 1em;"><h2>Using sound - samples and music</h2></div>
<p>ClanSound provides you with easy-to-use and powerful sound functionality.</p>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Sound overview</h3></div>
<p>To play sound in ClanLib, you have to initialize <a href="../Reference/html/CL_SetupSound.html">CL_SetupSound</a> and also
create a <a href="../Reference/html/CL_SoundOutput.html">CL_SoundOutput</a>. CL_SoundOutput is the interface to a sound output device,
which is used to control the main mixer volume and other global settings. It is used as a singleton.</p>
<ul><pre><font face="Arial,Courier New,Courier"> #include <ClanLib/sound.h>
...
CL_SetupSound setup_sound;
CL_SoundOutput output(44100);
...
</font></pre></ul>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Playing wav samples</h3></div>
<p>A <a href="../Reference/html/CL_SoundBuffer.html">CL_SoundBuffer</a> contains a sample or music stream. To load and play
a WAV file, you do the following:</p>
<ul><pre><font face="Arial,Courier New,Courier"> // Load a sample from a wave file:
CL_SoundBuffer sample("beep.wav");
// Play sample
sample.play();
</font></pre></ul>
<p>You can set the volume and panning of soundbuffers. This will change
the default attributes of the soundbuffer, and will be effective on all
subsequent calls to play().</p>
<ul><pre><font face="Arial,Courier New,Courier"> // Turn down volume on this soundbuffer.
sample.set_volume(0.1f);
// Play only in left speaker.
sample.set_pan(-1.0f);
</font></pre></ul>
<p>Note that setting these attributes don't affect already playing soundbuffers,
only when you call play() again afterwards. To have individual control over each
playing sound, you need to use a sound session - read about that further down.</p>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Playing music streams</h3></div>
<p>There isn't much difference between playing wav samples and music stream. ClanSound itself
doesn't provide more than wav samples playback, so you'll need one or more additional
music modules. ClanLib currently has two, MikMod and Vorbis. They are initialized using
<a href="../Reference/html/CL_SetupMikMod.html">CL_SetupMikMod</a> and <a href="../Reference/html/CL_SetupVorbis.html">CL_SetupVorbis</a>.</p>
<ul><pre><font face="Arial,Courier New,Courier"> #include <ClanLib/sound.h>
#include <ClanLib/vorbis.h>
#include <ClanLib/mikmod.h>
CL_SetupSound setup_sound;
CL_SetupMikMod setup_mikmod;
CL_SetupVorbis setup_vorbis;
CL_SoundOutput output(44100);
</font></pre></ul>
<p>Then to play music, you use the same approach as with wav samples:</p>
<ul><pre><font face="Arial,Courier New,Courier"> // Load ogg file into a soundbuffer
CL_SoundBuffer vorbis("cheer1.ogg");
// Play vorbis stream
vorbis.play();
...
// Load an XM mod into a soundbuffer
CL_SoundBuffer mod("clanbeat.xm");
// Play mod
mod.play();
</font></pre></ul>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Resources</h3></div>
<p>TODO: Write about loading samples from resources.</p>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Sessions</h3></div>
<p>If you want to control the playback of sound, or want to know
if the sound is still playing, you use <a href="../Reference/html/CL_SoundBuffer_Session.html">CL_SoundBuffer_Session</a>.
This can be created in two ways, either by calling
CL_SoundBuffer::play() or CL_SoundBuffer::prepare().
The difference between prepare() and play() is that prepare will just load the sound,
but not play it. You can then call play() from your resulting CL_SoundBuffer_Session.</p>
<ul><pre><font face="Arial,Courier New,Courier"> // Load ogg file into a soundbuffer
CL_SoundBuffer vorbis("cheer1.ogg");
// Create a session from soundbuffer.
CL_SoundBuffer_Session playback = vorbis.play();
..
// Load ogg file into a soundbuffer
CL_SoundBuffer vorbis("cheer1.ogg");
// Create a session from soundbuffer.
CL_SoundBuffer_Session playback = vorbis.prepare();
playback.play();
</font></pre></ul>
<p>When you have a session object, you can modify the attributes of
the playing sound in many ways. These take effect immidiately, you
can change it while it is playing. You can set the volume, panning,
position, and frequency (speed). You can make it loop, and adding filters.
You can query if it is still playing, and you can ofcourse start and stop
it as you want.</p>
<ul><pre><font face="Arial,Courier New,Courier"> // Load ogg file into a soundbuffer
CL_SoundBuffer vorbis("cheer1.ogg");
// Create a session from soundbuffer.
CL_SoundBuffer_Session playback = vorbis.prepare();
playback.set_volume(0.5f);
playback.set_looping(true);
playback.play();
</font></pre></ul>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Filters</h3></div>
<p>If you want to modify sounds in special, dynamic ways, you
can apply a CL_SoundFilter to it.</p>
<p>ClanLib has three builtin filters: <a href="../Reference/html/CL_EchoFilter.html">CL_EchoFilter</a>, <a href="../Reference/html/CL_FadeFilter.html">CL_FadeFilter</a> and <a href="../Reference/html/CL_InverseEchoFilter.html">CL_InverseEchoFilter</a>.
The usefulness of an CL_InverseEchoFilter can be discussed :)</p>
<p>Example of the fade filter:</p>
<ul><pre><font face="Arial,Courier New,Courier"> // Load ogg file into a soundbuffer
CL_SoundBuffer vorbis("cheer1.ogg");
// Create a session from soundbuffer.
CL_SoundBuffer_Session playback = vorbis.prepare();
CL_FadeFilter fade(0.0f);
playback.add_filter(&fade);
playback.play();
fade.fade_to_volume(1.0f, 10*1000); // fade in, duration 10 seconds.
</font></pre></ul>
<p>Example of the echo filter:</p>
<ul><pre><font face="Arial,Courier New,Courier"> // Load ogg file into a soundbuffer
CL_SoundBuffer vorbis("cheer1.ogg");
// Create a session from soundbuffer.
CL_SoundBuffer_Session playback = vorbis.prepare();
playback.add_filter(new CL_EchoFilter(8*1024), true);
playback.play();
</font></pre></ul>
<p>You can ofcourse also code your own filters. Check the SoundFilters example
how do to that - it creates a CL_DistortFilter.</p>
<p>It is also possible to add filters on mixer level too. Ie fade all sound out alltogether.
Use CL_SoundOutput::add_filter() just like with CL_SoundBuffer_Session.</p>
<div style="border-bottom-style: dotted; border-bottom-width: 1px;"><h3>Sound providers</h3></div>
<p>It is also possible to create sound on-the-fly, or adding extra sound
providers. See the StreamSoundProvider example for code how to do this.</p>
<!-- clanlib footer begin -->
<div style="margin-top: 0em; text-align: center; color: #a0a0a0; border-top-style: dotted; border-top-width: 1px;">
Questions or comments, write to the <a href="http://clanlib.org/contact.html">ClanLib mailing list</a>.
</div>
</div>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
a2116f36018873d572acbcadddb8e994
>
files
>
40
