The Hekkus sound system is a cross

a beginner's guide
chapter 5 - Sound using
Hekkus Sound System

Chapter 1

Chapter 2

Chapter 3

Chapter 4

The Hekkus sound system is a cross-platform utility for playing .mod music files and .wav sound effects. Hekkus is the work of Thomas 'Gersen' Maniero. You can support Thomas via a PAYPAL donation. If you use Hekkus in a game which you sell for profit you should make a realistic payment via the donation system. When you make a donation the source code will be made available to you.
This tutorial concentrates on using Hekkus from within PocketFrog however it's really easy to use with any application (such as PocketHAL, GapiDraw etc). For the purpose of the tutorial I assume you are using a PC with the embedded Visual tools and/or Visual C++ targeting a Microsoft PocketPC application. You can also use Hekkus for Symbian devices.
To use Hekkus you must first obtain the software. Go to the website http://www.shlzero.com and download the latest stable version. The link for the downloads page is http://www.shlzero.com/modules.php?name=Content&pa=showpage&pid=1 Unzip the download and you will see some files and folders. The history.txt file always gives up-to-date information about the latest updates and fixes. At time of writing the latest stable version is 0.99.3 though there is also a later beta which is not yet stable.
Here are a few concepts explaining how the package is integrated into your app: The header file: This file is found in the top level HekkusSoundSystem folder and is called HSS.h. Within PocketFrog this file is included at the top of your main game include file (mygame.h) as follows:- #include "HekkusSoundSystem\\HSS.h" Place this above the 'using namespace Frog;' line. The library file: This contains the actual Hekkus code which will be linked with your application. You can find the correct library file by looking in the sub-folder HekkusSoundSystem\lib. You will see several folders here each containing a lib for a specific platform. For example, if you are building your game using eVC3++ for a PocketPC2002 device you would use the library from HEKKUSSOUNDSYSTEM\LIB\PPC-ARM. IMPORTANT NOTE: You need to tell eVC3++ where to find the header file and lib file. Do the following 3 steps:- In eVC choose the menu option Project, then Settings the choose the link tab. In the line Object/Library Modules add HSS.lib to the text
Now choose Tools from the menu then Options and ensure the 'show directories for' box shows include files. You now need to add the path to where the HekkusSoundSystem .HSS.h include file is. Use the [...] on a new line to browse to the place where you downloaded and unzipped Hekkus.
Now do the same thing but choose the Library files option from 'Show directories for'. Add an entry for the required .lib file. This is going to be 2 folders down from the .h file's location. Ensure you choose the correct one for the targeted device.
When you build your application and you get lots of nice 'Hekkus, what's that, never heard of it' messages it's because you did not do the steps above correctly. As Hekkus needs some variables set up to allow it to work we need to add these in to the PocketFrog header file inside the 'MyGame' class. Note that the title 'MyGame' can be replaced in your own game by your own program name so long as you change it everywhere. In the Hekkus sample you can download the class is called 'HekkusSample' instead of 'MyGame'. Note: Between versions Hekkus classes have been renamed. You may come across old sample code elsewhere and get confused. Old name: Sound - New name hssSpeaker Old name: Channel - New name hssChannel Old name: Module - New name hssMusic Old name: SoundFX - New name hssSound // Hekkus : Sound object, our MOD files and WAVs hssSpeaker m_speaker; // eg: make ourselves an 'hssSpeaker' and call it m_speaker. Our variable is m_speaker and it's an instance of hssSpeaker. hssMusic m_music; hssSound m_sfx[4];//allow for 4 wavs (more about this later) // eg: make ourselves a table containing 4 instances of hssSound for our .wavs.
Ok, with the Hekkus software correctly included in our application we need to initialize Hekkus and play something. The initialize code goes in the MyGame::GameInit() function. If not using PocketFrog this would be in the one time game setup code.
Initializing Hekkus: The sound system is initialized using the function below. There are 5 parameters which are explained in the comments.
// Initialize the Hekkus Sound System m_speaker.open(22050, 16, true, 1, 16);//sets up our 'hssSpeaker' with required parameters /* // Hekkus Parameters: freqmix output rate in hz, only 11025, 22050 and 44100 are supported. bps select 16 or 8 bit output. stereo enable stereo output (true == stereo, false == mono). maxmodchannels maximum number of ProTracker channels available. maxsfxchannels maximum number of Wave channels available. */
These settings allow one tune and up to 16 .wav's to be going all at once. You can vary the settings to suit your requirements.
Now that the sound system is initialised it needs a .mod tune and some wavs to play. If you don't want to create your own sound files you can search the web and download literally hundreds of different music files and sound effects for free. In this article I am including a sample .mod and a few .wav's to get you going.
Depending on the way you structure your game the way you load files may vary but for this tutorial I assume that the .mod file will be held as a separate file outwith your main game .exe while the .wav's will be stored as resources inside the main game .exe. Typically the .mod files will be much larger than the .wav's unless you need some large speech samples etc.
On the assumption that you are loading a .mod file from storage memory use the function as follows m_music.load(TEXT("spacetune1.mod")); //m_music is our 'hss_Music' class Note: as you probably know PocketPCs don't use relative paths. You need to supply the full path for loading files. Fortunately Hekkus includes a function for this to save you the trouble. Assuming your .mod file is in the main game folder you just need to pass the function your file name. Also note that the 'TEXT()' function is required to ensure the name is correctly understood. You can of course pass the name as a variable rather than as literal text. Having loaded the tune we tell Hekkus to play it forever using loop(true) and then choose which tune to play with playMusic. m_music.loop(true); m_speaker.playMusic(&m_music);//pass playMusic a pointer to the tune we loaded. m_speaker.volumeMusics(game_music_vol);//set the volume at which we play the music using an int variable game_music_vol. Note: Volume control in Hekkus obeys your master device settings so you won't get unexpected load bangs if you don't want them. More about volumes later.
Ok, so now we have a tune playing in the background. Time to load up some .wav files and look at how these can be used within a game.
As the .wavs being used are loaded from resources you need to know how to do this. Within eVC++ you will notice that there are 3 panes on the left headed ClassView, ResourceView and FileView. Select ResourceView and expand the resources folder. Look at the sub folders. You should see one called Wave. Right click on this folder and select Import... You can now browse to the folder where your wav files live and select one. This imports the wav file inside your program and gives it a default name which you should change to something meaningful by right clicking on the item you imported (called something like IRD_WAVE1), choose properties and change the ID. Once you have imported all required wavs you can go back to the FileView tab to edit your source code.
Although the wavs are already in your program you need to load them into the game's own variables for use. Expanding on sound effect variable definition as mentioned above I suggest creating a table of sound effects which you can then call for as required. Remember that if you have 4 wavs you have to define an array with 4 elements and these are referred to as tablename[0],[1],[2] and [3]. In a real game you could have many more sound effects so it's important to have them in a manageable structure like this. In the game's header file where we define all our global variables we added the table:- SoundFX m_sfx[4];//set up the sound effects variables for later use. With the table defined we can now load the wavs into the table elements. This is done in the GameInit() function. m_sfx[0].load(_Module.GetModuleInstance(),IDR_WAVE0); m_sfx[1].load(_Module.GetModuleInstance(),IDR_WAVE1); m_sfx[2].load(_Module.GetModuleInstance(),IDR_WAVE2); m_sfx[3].load(_Module.GetModule Instance(),IDR_WAVE3);
Now we can fire off sound effects. We can mix effects and control their volumes. eg:- m_sfx[3].volume(40);//causes the volume to be 40/64ths of the max volume. Playing a sound effect is done as follows:- m_speaker.playSound(&m_sfx[2]); You can add a test using a Boolean flag so the effect only goes off if your game settings want it to if(game_sfx_on==1)m_speaker.playSound(&m_sfx[0]);
There are circumstances when you program may not be active and Hekkus needs to be suspended and resumed later. PocketFrog provides functions where this kind of code can be placed. These functions and the Hekkus code are shown below:- // Called when your application is being suspended, like when a low battery message appears. void MyGame::GameSuspend() { // Suspend the Hekkus Sound System m_speaker.suspend(); } // Called when your application is being resumed, like after a low battery warning message has been dismissed void MyGame::GameResume() { // Resume the Hekkus Sound System m_speaker.resume(); }
When your game exits Hekkus needs to be shut down. This happens in the GameEnd() function. // Shut down the Hekkus Sound System m_speaker.close(); (This is also the place where we clean up so that we release memory utilized by our program)
Downloads to accompany this tutorial:- Hekkus website downloads page http://www.shlzero.com/modules.php?name=Content&pa=showpage&pid=1 Link to the PocketFrog Hekkus sample from the Hekkus website:- PocketFrog / Hekkus demo Some sample wav files: download a bunch of files to get you started here:- WAVS.ZIP Mod files are easily obtained from the internet via a Google search so I have not included any here.
Fun with Wav files Windows XP has a built-in mini wav file editor. If you right click on a wav file and choose record the program sndrec32.exe will run. This allows various manipulations such as chopping up the wav, changing the way it is saved, adding volume and echo and others. This can be really useful to manipulate the wav or reduce the size of the file by changing the format it's saved in. You may lose some quality but also many K off your game size. sndrec32.exe lives in windows/system32.

disclaimer: This article is the work of Conan of SundialSoft, a user of PocketFrog. I, Conan, have no connection with the PocketFrog toolkit author Thierry Tremblay nor with the Hekkus author Thomas Maniero . I hope this page turns out to be useful & helps people get into this really good toolkit/sound system but accept no responsibility for misleading mistakes which waste your valuable time.