The output of streaming sound and sound effects is one of the basic pieces that you will want for any demo/game program you write, and basically every target platform of KOS will have some method of doing that. This set of functions helps you interact with that hardware without necessarily knowing how it works underneath. Note that initializing and using this API will usually prevent lower-level access (or will contend with it in bad ways), though this is usually reversable by shutting it down.
Note that although this API is designed to be platform independent eventually, it is currently only implemented on the DC and its headers are located with the DC headers. This may change in the future, though, and if you include kos.h then you shouldn't have troubles.
Setup the sound allocation system. Generally allocates a buffer for sound usage and reserves reserve bytes at the front for system overhead. The value for reserve should never be zero because this would allow for valid sound mem handles to indicate an error condition in snd_mem_malloc.
Shut down the sound allocation system, and free any structures related to it.
Allocate a chunk of sound RAM and return a handle to it. This will generally be an offset into a pre-allocated sound buffer (or in the case of the DC, the SPU RAM). A zero return value signifies failure.
Frees a previously allocated chunk of sound RAM.
Returns the largest chunk of sound RAM available.
Initialize the overall sound system. This is generally preferred to calling snd_mem_init directly.
Shut down the overall sound system. This is generally preferred to calling snd_mem_shutdown directly.
Load the sound sample located on the VFS at fn. Currently this function only knows about RIFF WAV files, but this may change later. Returns a handle to the loaded effect.
Unload a single loaded sample. Call with the handle you got back above.
Unload all samples loaded with snd_sfx_load. This function is deprecated in favor of freeing individual samples.
Play the given sound effect at volume vol (0-255) and with panning pan (0 - 255, 128 is center).
Setup the sound system for streaming sound data. callback will be called whenever the system needs more data for output (see below for more info about the callback).
This function calls snd_init implicitly, so there is no need to call it beforehand.
Shuts down the sound streaming system.
This function calls snd_shutdown implicitly, so there is no need to call it afterwards.
Sets the callback function for the streaming mechanism. When we are running low on data in the circular output buffers, func will be called. It will receive a request for the number of samples we'd like to get. The function should return a pointer to where those samples are located and return via ret how many we actually got back. If the return value is NULL, then the stream is considered finished.
Enable sound stream queueing. This allows you to very finely tune when the playback will start in relation to other events in your program (for example, if you need music exactly timed to the graphics).
Disable queueing.
If queueing is enabled, calling this function will make it actually start playing instantly.
Start stream playback with the given frequency. If st is non-zero, then we are playing a stereo stream. If queueing is enabled, then the stream will not actually start but will just fill its buffers and get ready.
Stops any playing stream.
Polls the stream driver to see if we need more data. This may not be required on all platforms; on the DC it is currently required.
If the return value is -1, then there was an internal error (including a NULL callback. If -3, then the stream has ended. If zero, then everything is hunky dory.
Set the volume of the streaming output (0-255).