Development/Tutorials/Games/KALEngine: Difference between revisions

    From KDE TechBase
    No edit summary
    (Updated the code, improved the wording, ...)
    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. 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.


    ==Installation==
    ==Installation==


    1: Be sure you have installed dependent librairy.
    1: You need to have the following libraries installed.
    * openAL ( sound api)
    * openAL (sound api)
    * alut (openal toolkit)
    * alut (openAL toolkit)
    * libSndFile (load sound file).
    * 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>
    If you're using a Debian-based distribution, you can install them that way :


    2: compile and install kalengine from svn :
    <code>sudo apt-get install libalut0-dev libopenal1-dev libsndfile1-dev</code>
     
    2: Build and install KALEngine from svn :
    <code>svn co svn://anonsvn.kde.org/home/kde/trunk/playground/games/KALEngine/</code>
    <code>svn co svn://anonsvn.kde.org/home/kde/trunk/playground/games/KALEngine/</code>


    *cmake
    * cmake -DCMAKE_INSTALL_PREFIX=$(kde-config --prefix)
    *make
    * make
    *sudo make install
    * sudo make install


    == Hello Word ==
    == Hello Word ==


    In this exemple, we will play an "hello word". We don't need any sound, it's the default exemple of openAL.
    In this example, we will play a "Hello Word". We don't need to specify any sound file, openAL provides a default sound itself.


    <code cppqt>
    <code cppqt>
    Line 55: Line 55:
    int main(int argc, char **argv)
    int main(int argc, char **argv)
    {
    {
        // create an OpenAL object
        KALEngine soundEngine;
        // initialize OpenAL context and device
        soundEngine.init();


         KALEngine snd; //create an openAL object
         // create a sound, since we haven't specified any filename in the constructor, it will play the "Hello World"
         snd.init(); // Initialize OpenAL Context + Device!
         KALSource *sound = new KALSource();


         KALSource *son = new KALSource(); // create a sample, if no argument, It will play an "hello world"
         // play the sound
         son->play(); // play the sound!!
         sound->play();


        // print the elapsed time until the sound has finished playing
         while (son->getStatus() == AL_PLAYING) // wait while sound is playing
         while (sound->getStatus() == AL_PLAYING)
         {
         {
          kDebug()<<son->getElapsedTime(); //print the elapsed time.
            kDebug() << sound->getElapsedTime();
         }
         }


     
         // clear the buffer
         delete son; //when it finished! Don't forget to clear the buffer!!
         delete sound;
         snd.shutdown(); // and close the device!!
        // ...and close the device
     
        soundEngine.shutdown();


         return 0;
         return 0;
    Line 79: Line 83:
    </code>
    </code>


    -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 :  
    - 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 :


    <code cppqt>
    <code cppqt>
    QStringList KALEngine::getDevicesList().
    QStringList getDevicesList().
    </code>
    </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.
    - 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.
    If you play your own sound, download a short song : [[http://ktank.free.fr/kalengine/ocean.wav ocean.wav]] and do like this :  
     
    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:


    <code cppqt>
    <code cppqt>
      KALSource *son = new KALSource("ocean.wav");
        KALSource *sound = new KALSource("ocean.wav");
    </code >
    </code >


    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 wav file at the moment, but we hope to bring ogg support soon.
    If you want to play music, please wait tutorial for KALStream.
    For playing music, please wait until KALStream tutorial is up.
     
    -And now, we can play the sound by calling :
     
    <b>KALSource::play()</b>
     
    This work like a thread! It doesn't wait the end of the song, the programm continue to work.


    - 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, we must to create a loop for waiting the end of the song.
    - Then, to know when the sound has ended, we create a loop using <b>getStatus()</b> which returns ever <b>AL_PLAYING</b> or <b>AL_STOPED</b>.
    KALSource->getStatus() return the status of the song. <b>AL_PLAYING</b> or <b>AL_STOPED</b>.


    -For wait inside the loop, we can print the elapsed time of playing by call :
    - Inside the loop, we print the time since the sound started playing using <b>getElapsedTime()</b>. It returns an ALfloat with the elapsed time expressed in seconds.
    KALSource::getElapsedTime(). It return in second the duration.


    -At the end, we must clear the buffer of the KALSource , by calling :
    - Finally, we have to clear the KALSource buffer by deleting the KALSource pointer and close the device by calling <b>shutdown()</b>.
    delete son. And close the device by calling : KALEngine::shutdown().


    == Multi-channel ==
    == Multi-channel ==


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


    ..to develop
    ...to develop
    == 3d sound ==
    == 3d sound ==


    Line 123: Line 120:




    {{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 ]]}}
    {{tip|For more information on how OpenAL works, see the documentation [[http://connect.creativelabs.com/openal/Documentation/OpenAL_Programmers_Guide.pdf OpenAL programmers Guide ]]}}


    {{TODO|Create KALStream}}}
    {{TODO|Create KALStream}}}

    Revision as of 11:37, 14 February 2009

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

    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.

    Installation

    1: You need to have the following libraries installed.

    • openAL (sound api)
    • alut (openAL toolkit)
    • libSndFile (load sound file).

    If you're using a Debian-based distribution, you can install them that way :

    sudo apt-get install libalut0-dev libopenal1-dev libsndfile1-dev

    2: Build and install KALEngine from svn : svn co svn://anonsvn.kde.org/home/kde/trunk/playground/games/KALEngine/

    • cmake -DCMAKE_INSTALL_PREFIX=$(kde-config --prefix)
    • make
    • sudo make install

    Hello Word

    In this example, we will play a "Hello Word". We don't need to specify any sound file, openAL provides a default sound itself.

    1. include <KALEngine>
    2. include <KALSource>
    3. 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
       sound->play();
    
       // print the elapsed time until the sound has finished playing
       while (sound->getStatus() == AL_PLAYING)
       {
           kDebug() << sound->getElapsedTime();
       }
    
       // clear the buffer
       delete sound;
       // ...and close the device
       soundEngine.shutdown();
    
       return 0;
    

    }


    - 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 :

    QStringList getDevicesList().

    - 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.

    If you want to try playing something else than the default "Hello World", you can download this short simple : [ocean.wav] and replace the sound object definition by:

       KALSource *sound = new KALSource("ocean.wav");
    

    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 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 create a loop using getStatus() which returns ever AL_PLAYING or AL_STOPED.

    - Inside the loop, we print the time since the sound started playing using getElapsedTime(). 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 shutdown().

    Multi-channel

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

    ...to develop

    3d sound

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


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


    noframe
    noframe
     
    TODO
    Create KALStream

    }