MODULA is, fast and easy to use, audio engine for PalmOS, Windows Mobile PocketPC and Smartphone and SymbianOS Series 60 (S60) devices.

MODULA can play multi channel music, sound effects and samples, mix huge number of sound channels, in both mono and stereo, on various output frequencies, with minimal processor overload.

1) Copy MODULA.c, MODULA.h, MODULAapi.h, palmostypes.h and sharktypes.h to your source code directory.

2) Add MODULA.c to your project.

3) Set CHANNELS in MODULA.h to desired number of channels (min 4, max 64 channels, channel number must be even!) .

3) Choose apropriate callback ARM routine depending on the number of channels you set. If you have set 4, 8, 16, 32 or 64 use MixMode 0 callback routine (Modu1a00.bin_ZERO). If you have set any other even number of channels, for example 6, 10, 18, etc., use MixMode 1 callback routine (Modu1a00.bin_ONE). Copy the correct file into your source code directory and rename it "Modu1a00.bin". Add this file to your project as a resource file. Notice that it has resource ID 'Modu" and resource number 0x1a00.

4) Use MODsplit utility to cut MOD songs to its header, patterns and samples files, so they can be added to the project as resources. Using MODsplit utility can look like this:

MODsplit music.mod Mdla 5000

This command will cut music.mod file to header, patterns and samples files, and you will get files named like Mdla5000.bin (header), Mdla5010.bin (patterns1), Mdla5011.bin (patterns2), Mdla5012.bin (patterns2), Mdla5021.bin (sample1), Mdla5022.bin (sample2), Mdla5023.bin (sample3), .... Mdla502a.bin (sample10) and so on.

5) Add those MOD resources (for example, Mdla50xx.bin files) to your project.

6) Include MODULAapi.h in source code files you where you will call functions from MODULA API, for example:

#include "MODULAapi.h"

7) Call MODULAInit to initialize MODULA. This function will most probably be called only once at the start of your application.

8) Load MOD song from resources using MODLoadRsrc function. In our case it should look like:

MODLoadRsrc('Mdla', 0x5000);

After this function is executed succesfully music will start playing.

9) Before quiting your application you must call MODULAKill function to stop playing the music and free all the memory, system and hardware resources MODULA was using.

10) You're done, you have a working MODULA audio engine in your application!

MODULAInit function

Initialize MODULA audio engine, allocates required memory and system resources required for MODULA to work.

prototype: UInt16 MODULAInit(UInt8 mode, UInt8 freq)

parameters:
mode - Audio output mode. Can be snd_stereo for stereo output and snd_mono for mono output.
freq - Desired output frequency of audio. Values can snd_44khz for 44KHz, snd_22khz for 22KHz, snd_11khz for 11KHz and snd_8khz for 8KHz.

returns:
MODULA_NOERROR - If MODULA initialized sucessfully.
MODULA_ERR_NOSNDSTREAM - If there is no SndStream API available
MODULA_ERR_NOTENOUGHMEMORY - If there is not enough memory to allocate stucture required for MODULA to function
MODULA_ERR_CANNOTSTARTSNDSTREAM - If can not create sound stream
MODULA_ERR_NOCALLBACKRESOURCE - If there is no MODULA SndStream callback routine in specified resource
MODULA_ERR_CANNOTLOCKCALLBACKRESOURCE - If callback resource can not be locked
MODULA_ERR_NOARM - If it's not currently running on ARM processor. MODULA requires ARM processer in order to run.

---

MODULAKill function

Deallocates all the memory, system and hardware resources MODULA allocated using MODULAInit function. This function first calls MODFreeRsrc function, which stops playing MOD and deallocates its resources.

prototype: void MODULAKill(void)

parameters: none

returns: nothing

---

MODLoadRsrc function

This function will load, initialize and setup all the necessary pointers and varibles for playing MOD song. It will "load" MOD song from resources.

prototype: void MODLoadRsrc(UInt32 id, UInt16 res)

parameters:
id - Resource type. All the MOD resources got to have the same resource type.
res - First resource number (ID in PalmOS). Data stored in resources has to have these resource numbers:

res = header data
res + 0x10 = patterns 1
res + 0x11 = patterns 2
res + 0x12 = patterns 3
res + 0x21 = sample 1
res + 0x22 = sample 2
res + 0x23 = sample 3
...and so on.

returns: nothing

---

MODFreeRsrc function

Stops MOD music if it is playing and unloads the music, frees the resources allocated by MODLoadRsrc function.

prototype: void MODFreeRsrc(void)

parameters: none

returns: nothing

---

MODPlay function

Starts to play MOD music.

prototype: void MODPlay(void)

parameters: none

returns: nothing

---

MODStop function

Stops the MOD music.

prototype: void MODStop(void)

parameters: none

returns: nothing

---

MODPause function

Pause playing of the MOD music or continues playing of already paused song.

prototype: void MODPause(void)

parameters: none

returns: nothing

---

MODSetVolume function

Sets the volume of MOD music. This function does not affect the volume of sound samples.

prototype: void MODSetVolume(int8 volume)

parameters:
volume - Sound volume can have values from 0 (mute - no sound) to 64 (loudest volume)

returns: nothing

---

MODGetVolume function

Reads the current volume level of MOD music.

prototype: UInt8 MODGetVolume(void)

parameters: none

returns: Current MOD music volume level in range between 0 (mute - no sound) to 64 (loudest volume)

---

MODIsFinished function

Checks if MOD song reached the end of song while playing.

prototype: Boolean MODIsFinished(void)

parameters: none

returns:
true - if song reached the end
false - if song still did not reach the end

---

MODSetLoop function

Sets the MOD song playing loop mode. When song reaches the end it can loop again from the start or it can simply stop. Use this function to set that behaviour.

prototype: void MODSetLoop(Boolean loop)

parameters:
loop - set it to true to enable MOD song looping or to false to disable looping

returns: nothing

---

MODGetLoop function

Reads the MOD song loop mode status.

prototype: Boolean MODGetLoop(void)

parameters: none

returns:
true - if MOD song looping is enabled
false - if MOD song looping is disabled

---

SFXPlaySample function

Initiate playing of sound sample on the first free audio channel at desired frequency.

prototype: void SFXPlaySample(UInt8 *sample, UInt16 size, UInt16 freq, UInt8 vol)

parameters:
sample - Pointer to start of sample. Sample must be in unsigned 8bit format.
size - Size of sample, in bytes.
freq - Frequency of sample in herz (Hz).
vol - Volume of sample in range from 0 (mute) to 64 (loudest).

returns: nothing

---

SFXSetVolume function

Sets the volume of sound samples. This function does not affect the volume of MOD music.

prototype: void SFXSetVolume(int8 volume)

parameters:
volume - Sound volume can have values from 0 (mute - no sound) to 64 (loudest volume)

returns: nothing

---

SFXGetVolume function

Reads the current volume level of sound samples.

prototype: void MODULAKill(void)

parameters: none

returns: Current sound samples volume level in range between 0 (mute - no sound) to 64 (loudest volume)

---

MODULASetBoost function

This function sets to boost level of volume. Use this function with care. Setting boost to too big values can cause unexpected sound effect, like distortion, tone modification, loosing sound etc. Boost can be set to higher values as the number of audio channels mixed is higher. For example, setting the volume boost level to 200 percent can be too much in the case of 4 channel mixing. Be cautious when using this function.

prototype: void MODULASetBoost(UInt16 boost)

parameters:
boost - Level of volume boost in percents. Boost can have values in range from 0% to 1000%. Setting boost to values equal to 100% or lower turns off boosting.

returns: nothing

---

MODULAGetBoost function

Reads the current level of volume boost.

prototype: UInt16 MODULAGetBoost(void)

parameters: none

returns: The current level of sound volume boost in percents. Returns zero (0) if boosting is turned off.

---

IsStreamingSoundAvailable function

Checks if PalmOS SndStream API is available. Because of bug in Tungsten T's ROM, this PDA does not correctly returns the state of sysFileCSoundMgr feature. This function checks if the application is running on Tungsten T using its companyID and deviceID.

prototype: Boolean IsStreamingSoundAvailable(void)

parameters: none

returns:
true - If SndStream API is available
false - If SndStream API is not available

• Metrowerks CodeWarrior
• PRC-Tools
• PalmSource PalmOS Developer Suite

MODULA can play songs in MOD format. MOD format has been used for years already in games, scene demos and other types of programs that needed high quality multichannel music. Programs used for MOD music composing are called trackers and there are many trackers available for different platforms and operating systems. Most of them are freeware, so you won't have to invest more money into music composing software. Some of well known quality trackers are: SkaleTracker (PC/Windows/Linux), Modplug Tracker (PC/Windows), Octamed Sound Studio (Amiga/PC), FastTracker (PC/DOS), ScreamTracker (PC/DOS), ImpulseTracker (PC/DOS), ProTracker (Amiga), NoiseTracker (Amiga), DigiBooster (Amiga) and many others.