KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Macros | Typedefs | Functions
sfxmgr.h File Reference

Basic sound effect support. More...

#include <sys/cdefs.h>
#include <arch/types.h>

Go to the source code of this file.

Macros

#define SFXHND_INVALID   0
 Invalid sound effect handle value. More...
 

Typedefs

typedef uint32 sfxhnd_t
 Sound effect handle type. More...
 

Functions

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

Detailed Description

Basic sound effect support.

This file contains declarations for doing simple sound effects. This code is only usable for simple WAV files containing either 16-bit samples (stereo or mono) or Yamaha ADPCM (4-bits, stereo or mono). Also, all sounds played in this manner must be at most 65534 samples in length, as this does not handle buffer chaining or anything else complex. For more interesting stuff, you should probably look at the sound stream stuff instead.

Author
Dan Potter

Macro Definition Documentation

#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

typedef uint32 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

int snd_sfx_chn_alloc ( )

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.
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
chnThe channel to free.
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 16-bit uncompressed PCM samples or 4-bit Yamaha ADPCM.

Parameters
fnThe file to load.
Returns
A handle to the sound effect on success. On error, SFXHND_INVALID is returned.
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
idxThe handle to the sound effect to play.
volThe volume to play at (between 0 and 255).
panThe 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.
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
chnThe channel to play on (or in the case of stereo, the left channel).
idxThe handle to the sound effect to play.
volThe volume to play at (between 0 and 255).
panThe 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
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
chnThe channel to stop.
void snd_sfx_stop_all ( )

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

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
idxA handle to the sound effect to unload.
void snd_sfx_unload_all ( )

Unload all loaded sound effects.

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