Sound Effects

Sound Effect Playback and Management. More...

Files
file	sfxmgr.h
	Basic sound effect support.

Macros
#define	SFXHND_INVALID   0
	Invalid sound effect handle value.

Typedefs
typedef uint32_t	sfxhnd_t
	Sound effect handle type.

Functions
sfxhnd_t	snd_sfx_load (const char *fn)
	Load a sound effect.
void	snd_sfx_unload (sfxhnd_t idx)
	Unload a sound effect.
void	snd_sfx_unload_all (void)
	Unload all loaded sound effects.
int	snd_sfx_play (sfxhnd_t idx, int vol, int pan)
	Play a sound effect.
int	snd_sfx_play_chn (int chn, sfxhnd_t idx, int vol, int pan)
	Play a sound effect on a specific channel.
void	snd_sfx_stop (int chn)
	Stop a single channel of sound.
void	snd_sfx_stop_all (void)
	Stop all channels playing sound effects.
int	snd_sfx_chn_alloc (void)
	Allocate a sound channel for use outside the sound effect system.
void	snd_sfx_chn_free (int chn)
	Free a previously allocated channel.

Detailed Description

Sound Effect Playback and Management.

Macro Definition Documentation

SFXHND_INVALID

#define SFXHND_INVALID   0

Invalid sound effect handle value.

If a sound effect cannot be loaded, this value will be returned as the error condition.

Typedef Documentation

sfxhnd_t

typedef uint32_t sfxhnd_t

Sound effect handle type.

Each loaded sound effect will be assigned one of these, which is to be used for operations related to the effect, including playing it or unloading it.

Function Documentation

snd_sfx_chn_alloc()

int snd_sfx_chn_alloc

(

void

)

Allocate a sound channel for use outside the sound effect system.

This function finds and allocates a channel for use for things other than sound effects. This is useful for, for instance, the streaming code.

Returns

The allocated channel on success, -1 on failure.

snd_sfx_chn_free()

void snd_sfx_chn_free

(

int

chn

)

Free a previously allocated channel.

This function frees a channel that was allocated with snd_sfx_chn_alloc(), returning it to the pool of available channels for sound effect use.

Parameters

chn	The channel to free.

snd_sfx_load()

sfxhnd_t snd_sfx_load

(

const char *

fn

)

Load a sound effect.

This function loads a sound effect from a WAV file and returns a handle to it. The sound effect can be either stereo or mono, and must either be 8-bit or 16-bit uncompressed PCM samples, or 4-bit Yamaha ADPCM.

Warning

The sound effect you are loading must be at most 65534 samples in length.

Parameters

fn	The file to load.

Returns

A handle to the sound effect on success. On error, SFXHND_INVALID is returned.

snd_sfx_play()

int snd_sfx_play	(	sfxhnd_t	idx,
		int	vol,
		int	pan
	)

Play a sound effect.

This function plays a loaded sound effect with the specified volume (for both stereo or mono) and panning values (for mono sounds only).

Parameters

idx	The handle to the sound effect to play.
vol	The volume to play at (between 0 and 255).
pan	The panning value of the sound effect. 0 is all the way to the left, 128 is center, 255 is all the way to the right.

Returns

The channel used to play the sound effect (or the left channel in the case of a stereo sound, the right channel will be the next one) on success, or -1 on failure.

snd_sfx_play_chn()

int snd_sfx_play_chn	(	int	chn,
		sfxhnd_t	idx,
		int	vol,
		int	pan
	)

Play a sound effect on a specific channel.

This function works similar to snd_sfx_play(), but allows you to specify the channel to play on. No error checking is done with regard to the channel, so be sure its safe to play on that channel before trying.

Parameters

chn	The channel to play on (or in the case of stereo, the left channel).
idx	The handle to the sound effect to play.
vol	The volume to play at (between 0 and 255).
pan	The panning value of the sound effect. 0 is all the way to the left, 128 is center, 255 is all the way to the right.

Returns

chn

snd_sfx_stop()

void snd_sfx_stop

(

int

chn

)

Stop a single channel of sound.

This function stops the specified channel of sound from playing. It does no checking to make sure that a sound effect is playing on the channel specified, and thus can be used even if you're using the channel for some other purpose than sound effects.

Parameters

chn	The channel to stop.

snd_sfx_stop_all()

void snd_sfx_stop_all

(

void

)

Stop all channels playing sound effects.

This function stops all channels currently allocated to sound effects from playing. It does not affect channels allocated for use by something other than sound effects..

snd_sfx_unload()

void snd_sfx_unload

(

sfxhnd_t

idx

)

Unload a sound effect.

This function unloads a previously loaded sound effect, and frees the memory associated with it.

Parameters

idx	A handle to the sound effect to unload.

snd_sfx_unload_all()

void snd_sfx_unload_all

(

void

)

Unload all loaded sound effects.

This function unloads all previously loaded sound effect, and frees the memory associated with them.