Sound

Overview

This guide provides an overview of loading and playing sound in AppGameKit Studio.

What formats are supported?

AppGameKit Studio supports the Wave file format. No other formats are currently supported.

How do I load a sound?

The command LoadSound allows you to load a sound. A sound can be loaded using the LoadSound command:

LoadSound ( id, file )
id = LoadSound ( file )

void LoadSound ( UINT id, uString file );
UINT LoadSound ( uString file );

A sound file can be loaded by either assigning an ID number manually or having it provided to you automatically. The next step is to let AppGameKit Studio know which file you want to load e.g. "mySound.wav". Please note that ID numbers are unique for a command set. Therefore it's feasible to have a sound loaded with an ID number of 1 and a sprite with an ID of 1.

Here's one approach to loading a sound. The command LoadSound is called, an ID number of 1 is specified and the file to load is "mySound.wav":

LoadSound ( 1, "mySound.wav" )

agk::LoadSound ( 1, "mySound.wav" );

This alternative method demonstrates how a sound can be loaded with an automatically assigned ID number:

sound = LoadSound ( "mySound.wav" )

sound = agk::LoadSound ( "mySound.wav" )

How can I play a sound?

Once a sound has been loaded it can be played with the PlaySound command. Several variants of this command exist:

PlaySound ( id )
playSound ( id, volume )
PlaySound ( id, volume, loop )
PlaySound ( id, volume, loop, priority )

agk::PlaySound ( UINT id, int vol = 100, int loop = 0, int priority = 0 );

The parameters for this command are as follows:

• ID
• volume
• loop
• priority

The ID number refers to the ID of the sound you want to play. The volume is a value between 0 and 100. By default the volume is set at 100, which will result in the sound being played at the maximum volume. Reducing this to a lower value will result in a quieter sound. The loop parameter controls whether the sound will be looped. A value of 0 will only play the sound once, while a value of 1 will loop playback. The final parameter is used to control whether the sound has priority for playback over other sounds, by default this is 0, changing this to 1 will give this sound priority. The priority value is used in instances where multiple sounds are playing at once.

The following lines of code demonstrate a sound being loaded with an ID of 1, and then the sound is played with a volume of 50 and set to loop:

LoadSound ( 1, "mySound.wav" )
PlaySound ( 1, 50, 1 )

agk::LoadSound ( 1, "mySound.wav" );
agk::PlaySound ( 1, 50, 1 );

How do I stop a sound from playing?

To stop a particular sound from playing call the StopSound command. This command only requires one parameter, and that is the ID number of the sound. This example shows a sound being loaded, played and then immediately stopped:

LoadSound ( 1, "mySound.wav" )
PlaySound ( 1, 50, 1 )
StopSound ( 1 )

agk::LoadSound ( 1, "mySound.wav" );
agk::PlaySound ( 1, 50, 1 );
agk::StopSound ( 1 );

How do I delete a sound?

It may be necessary to delete previously loaded sound and free up available memory. To delete a sound entity call the command DeleteSound:

DeleteSound ( id )

void DeleteSound ( UINT id );

This command only requires the ID number of the sound you want to delete.

Here's an example of loading a sound and then deleting it:

LoadSound ( 1, "mySound.wav" )
DeleteSound ( 1 )

agk::LoadSound ( 1, "mySound.wav" );
agk::DeleteSound ( 1 );