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

Jump to: navigation, search
m (The Code: try to update explanations, need more work)
 
(18 intermediate revisions by 6 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 excellent openAL librairy. 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: Be sure you have installed dependent librairy.
+
<syntaxhighlight lang="cpp-qt">
* openAL ( sound api)
+
#include "audio/sound.h"
* alut (openal toolkit)
+
* libSndFile (load sound file).
+
You can install them, from your package manager.
+
for exemple in kubuntu :
+
  
<code> sudo apt-get install libalut0-dev libopenal1-dev libsndfile1-dev </code>
+
#include <QtCore/QDebug>
  
2: compile and install kalengine from svn :
+
int main( int argc, char* argv[] )
<code>svn co svn://anonsvn.kde.org/home/kde/trunk/playground/games/KALEngine/</code>
+
 
+
*cmake
+
*make
+
*sudo make install
+
 
+
== Hello Word ==
+
 
+
In this exemple, we will play an "hello word". We don't need any sound, it's the default exemple of openAL.
+
 
+
<code cppqt>
+
 
+
#include <KALEngine>
+
#include <KALSource>
+
#include <KDebug>
+
 
+
int main(int argc, char **argv)
+
 
{
 
{
 +
    // create a sound object
 +
    GluonAudio::Sound* sound = new GluonAudio::Sound;
  
     KALEngine snd; //create an openAL object
+
     // load KDE's log in sound to the object
     snd.init(); // Initialize OpenAL Context + Device!
+
     sound->load( "/usr/share/sounds/KDE-Sys-Log-In-Long.ogg" );
  
     KALSource *son = new KALSource(); // create a sample, if no argument, It will play an "hello world"
+
     // set sound volume, it can be between 0 and 1
     son->play(); // play the sound!!
+
     sound->setVolume( 0.9 );
  
+
     // print the elapsed time until the sound has finished playing
     while (son->getStatus() == AL_PLAYING) // wait while sound is playing
+
     qDebug() << "Playing sound with duration" << sound->duration() << "seconds.";
     {
+
      kDebug()<<son->getElapsedTime(); //print the elapsed time.
+
    }
+
  
 +
    // play the sound
 +
    sound->play();
  
     delete son; //when it finished! Don't forget to clear the buffer!!
+
     // wait until playing is finished
     snd.shutdown(); // and close the device!!
+
     while( sound->isPlaying() );
  
 +
    // clear the buffer
 +
    delete sound;
  
 
     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:
 
+
-At the first line, we initialize the sound engine. KALengine::init(QString device) take in arguments the deviceName. If you want recover the list of device, you can call the static function :
+
 
+
<code cppqt>
+
QStringList KALEngine::getDevicesList().
+
</code>
+
 
+
-At the second time, we create a KALsource. KALSource is the base of openAL, for playing small sound, like shoot, scream, tic, walk ..... It load all the file sound inside a buffer! Then, be carefull if you try to load a Big music with it.
+
If you play your own sound, download a short song : [[http://ktank.free.fr/kalengine/ocean.wav ocean.wav]] and do like this :  
+
  
<code cppqt>
+
<syntaxhighlight lang="cpp-qt">
  KALSource *son = new KALSource("ocean.wav");
+
    sound->load( "ocean.wav" );
</code >
+
</syntaxhighlight>
  
So, currently, it can only play wav file. But, in few time, maybe 1 day..., it will play ogg files.
+
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 play music, please wait tutorial for KALStream.
+
  
- And now, we can play the sound by calling :
+
- 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.
  
<b>KALSource::play()</b>
+
- Then, to know when the sound has ended, we use <b>sound->isPlaying()</b>.
  
This work like a thread! It doesn't wait the end of the song, the programm continue to work.
+
- Finally, we have to clear the GluonAudio::Sound buffer by deleting the GluonAudio::Sound pointer.
  
 +
== Multi-channel ==
  
Then, we must to create a loop for waiting the end of the song.
+
sound1->play();
KALSource->getStatus() return the status of the song. <b>AL_PLAYING</b> or <b>AL_STOPED</b>.
+
sound2->play();
  
-For wait inside the loop, we can print the elapsed time of playing by call :
+
...to develop
KALSource::getElapsedTime(). It return in second the duration.
+
== 3d sound ==
  
- At the end, we must clear the buffer of the KALSource , by calling :
+
KALSource->setPosition(x,y,z)
delete son. And close the device by calling : KALEngine::shutdown().
+
...to develop
  
  
 +
{{tip|For more information on how OpenAL works, see the documentation [[http://connect.creativelabs.com/openal/Documentation/OpenAL_Programmers_Guide.pdf OpenAL programmers Guide ]]}}
  
{{tip|For more information on how the openAL works, look the documentation [[http://connect.creativelabs.com/openal/Documentation/OpenAL_Programmers_Guide.pdf openAL programmers Guide ]]}}
+
{{TODO|Create KALStream}}

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,206 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