Difference between revisions of "Development/Tutorials/Games/KALEngine"

Jump to: navigation, search
m (Text replace - "<code cppqt>" to "<syntaxhighlight lang="cpp-qt">")
m (The Code: try to update explanations, need more work)
 
(6 intermediate revisions by 3 users not shown)
Line 23: Line 23:
  
 
==Abstract==
 
==Abstract==
Phonon is not really designed to handle multiple sounds at the same time. KALEngine is made for games and create one thread per sound, using the openAL library. You also get all the other openAL goodness like 3D sounds, effects and multichannel.
+
Phonon is not really designed to handle multiple sounds at the same time. Gluon's audio module is made for games and create one thread per sound, using the openAL library. You also get all the other openAL goodness like 3D sounds, effects and multichannel.
  
==Installation==
+
== The Code ==
 +
In this example, we will play a simple sound file as "Hello Word".
  
1: You need to have the following libraries installed.
+
<syntaxhighlight lang="cpp-qt">
* openAL (sound api)
+
#include "audio/sound.h"
* alut (openAL toolkit)
+
* libSndFile (load sound file).
+
  
If you're using a Debian-based distribution, you can install them that way :
+
#include <QtCore/QDebug>
  
<code>sudo apt-get install libalut0-dev libopenal1-dev libsndfile1-dev libvorbis-dev libvorbisfile libogg-dev</code>
+
int main( int argc, char* argv[] )
 +
{
 +
    // create a sound object
 +
    GluonAudio::Sound* sound = new GluonAudio::Sound;
  
2: Build and install KALEngine from svn :
+
    // load KDE's log in sound to the object
<code>svn co svn://anonsvn.kde.org/home/kde/trunk/playground/games/KALEngine/</code>
+
    sound->load( "/usr/share/sounds/KDE-Sys-Log-In-Long.ogg" );
  
* cmake -DCMAKE_INSTALL_PREFIX=$(kde-config --prefix)
+
    // set sound volume, it can be between 0 and 1
* make
+
    sound->setVolume( 0.9 );
* sudo make install
+
  
== Hello Word ==
+
    // print the elapsed time until the sound has finished playing
 
+
    qDebug() << "Playing sound with duration" << sound->duration() << "seconds.";
In this example, we will play a "Hello Word". We don't need to specify any sound file, openAL provides a default sound itself.
+
 
+
<syntaxhighlight lang="cpp-qt">
+
 
+
#include <KALEngine>
+
#include <KALSource>
+
#include <KDebug>
+
 
+
int main(int argc, char **argv)
+
{
+
    // create an OpenAL object
+
    KALEngine soundEngine;
+
    // initialize OpenAL context and device
+
    soundEngine.init();
+
 
+
    // create a sound, since we haven't specified any filename in the constructor, it will play the "Hello World"
+
    KALSource *sound = new KALSource();
+
  
 
     // play the sound
 
     // play the sound
 
     sound->play();
 
     sound->play();
  
     // print the elapsed time until the sound has finished playing
+
     // wait until playing is finished
     while (sound->status() == AL_PLAYING)
+
     while( sound->isPlaying() );
    {
+
        kDebug() << sound->elapsedTime();
+
    }
+
  
 
     // clear the buffer
 
     // clear the buffer
 
     delete sound;
 
     delete sound;
    // ...and close the device
 
    soundEngine.shutdown();
 
  
 
     return 0;
 
     return 0;
 
}
 
}
 +
</syntaxhighlight>
  
 +
- First, we create a GluonAudio::Sound. GluonAudio::Sound can be used for playing small sounds (shoot, scream, tic, walk, etc). It will load the entire file inside a buffer, so be careful if you try to play a big file using it.
  
</code>
+
If you want to try playing something else than KDE's log in sound, you can download a sample [http://ktank.free.fr/kalengine/ocean.wav ocean sound] and replace the sound load definition by:
 
+
- First, we initialize the sound engine. The init() function can optionally takes one argument, the device name. You can retrieve the list of devices, using this static function :
+
  
 
<syntaxhighlight lang="cpp-qt">
 
<syntaxhighlight lang="cpp-qt">
QStringList devicesList().
+
    sound->load( "ocean.wav" );
</code>
+
</syntaxhighlight>
  
- Then, we create a KALsource. KALSource can be used for playing small sounds(shoot, scream, tic, walk, etc). It will load the entire file inside a buffer, so be careful if you try to play a big file using it.
+
You can only use it to play ogg or wav file at the moment, but we hope to bring more audio support soon.
 
+
If you want to try playing something else than the default "Hello World", you can download this short simple : [[http://ktank.free.fr/kalengine/ocean.wav ocean.wav]] and replace the sound object definition by:
+
 
+
<syntaxhighlight lang="cpp-qt">
+
    KALSource *sound = new KALSource("ocean.wav");
+
</code >
+
 
+
You can only use it to play wav file at the moment, but we hope to bring ogg support soon.
+
For playing music, please wait until KALStream tutorial is up.
+
  
 
- The sound can now be played by simply calling <b>play()</b>. This function is asynchronous, meaning your program doesn't have to wait until the sound has finished playing to continue.
 
- The sound can now be played by simply calling <b>play()</b>. This function is asynchronous, meaning your program doesn't have to wait until the sound has finished playing to continue.
  
- Then, to know when the sound has ended, we create a loop using <b>status()</b> which returns ever <b>AL_PLAYING</b> or <b>AL_STOPED</b>.
+
- Then, to know when the sound has ended, we use <b>sound->isPlaying()</b>.
 
+
- Inside the loop, we print the time since the sound started playing using <b>elapsedTime()</b>. It returns an ALfloat with the elapsed time expressed in seconds.
+
  
- Finally, we have to clear the KALSource buffer by deleting the KALSource pointer and close the device by calling <b>shutdown()</b>.
+
- Finally, we have to clear the GluonAudio::Sound buffer by deleting the GluonAudio::Sound pointer.
  
 
== Multi-channel ==
 
== Multi-channel ==

Latest revision as of 20:00, 13 May 2013

KALEngine tutorial
Tutorial Series   KALEngine developement
Prerequisites   None
What's Next   Nothing at the moment
Further Reading   KGLEngine2d's code

Contents

[edit] Abstract

Phonon is not really designed to handle multiple sounds at the same time. Gluon's audio module is made for games and create one thread per sound, using the openAL library. You also get all the other openAL goodness like 3D sounds, effects and multichannel.

[edit] The Code

In this example, we will play a simple sound file as "Hello Word".

#include "audio/sound.h"
 
#include <QtCore/QDebug>
 
int main( int argc, char* argv[] )
{
    // create a sound object
    GluonAudio::Sound* sound = new GluonAudio::Sound;
 
    // load KDE's log in sound to the object
    sound->load( "/usr/share/sounds/KDE-Sys-Log-In-Long.ogg" );
 
    // set sound volume, it can be between 0 and 1
    sound->setVolume( 0.9 );
 
    // print the elapsed time until the sound has finished playing
    qDebug() << "Playing sound with duration" << sound->duration() << "seconds.";
 
    // play the sound
    sound->play();
 
    // wait until playing is finished
    while( sound->isPlaying() );
 
    // clear the buffer
    delete sound;
 
    return 0;
}

- First, we create a GluonAudio::Sound. GluonAudio::Sound can be used for playing small sounds (shoot, scream, tic, walk, etc). It will load the entire file inside a buffer, so be careful if you try to play a big file using it.

If you want to try playing something else than KDE's log in sound, you can download a sample ocean sound and replace the sound load definition by:

    sound->load( "ocean.wav" );

You can only use it to play ogg or wav file at the moment, but we hope to bring more audio support soon.

- The sound can now be played by simply calling play(). This function is asynchronous, meaning your program doesn't have to wait until the sound has finished playing to continue.

- Then, to know when the sound has ended, we use sound->isPlaying().

- Finally, we have to clear the GluonAudio::Sound buffer by deleting the GluonAudio::Sound pointer.

[edit] Multi-channel

sound1->play(); sound2->play();

...to develop

[edit] 3d sound

KALSource->setPosition(x,y,z) ...to develop


Ktip.png
 
Tip
For more information on how OpenAL works, see the documentation [OpenAL programmers Guide ]


noframe
 
TODO
Create KALStream

This page was last modified on 13 May 2013, at 20:00. This page has been accessed 7,194 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal