Sound streaming support. More...

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

Macros
#define	SND_STREAM_MAX 4
	The maximum number of streams that can be allocated at once. More...

#define	SND_STREAM_BUFFER_MAX 0x10000
	The maximum buffer size for a stream. More...

#define	SND_STREAM_INVALID -1
	Invalid stream handle. More...

Typedefs
typedef int	snd_stream_hnd_t
	Stream handle type. More...

typedef void (	snd_stream_callback_t )(snd_stream_hnd_t hnd, int smp_req, int *smp_recv)
	Stream get data callback type. More...

typedef void(*	snd_stream_filter_t )(snd_stream_hnd_t hnd, void obj, int hz, int channels, void buffer, int samplecnt)
	Stream filter callback type. More...

Functions
void	snd_stream_set_callback (snd_stream_hnd_t hnd, snd_stream_callback_t cb)
	Set the callback for a given stream. More...

void	snd_stream_filter_add (snd_stream_hnd_t hnd, snd_stream_filter_t filtfunc, void *obj)
	Add a filter to the specified stream. More...

void	snd_stream_filter_remove (snd_stream_hnd_t hnd, snd_stream_filter_t filtfunc, void *obj)
	Remove a filter from the specified stream. More...

void	snd_stream_prefill (snd_stream_hnd_t hnd)
	Prefill the stream buffers. More...

int	snd_stream_init ()
	Initialize the stream system. More...

void	snd_stream_shutdown ()
	Shut down the stream system. More...

snd_stream_hnd_t	snd_stream_alloc (snd_stream_callback_t cb, int bufsize)
	Allocate a stream. More...

int	snd_stream_reinit (snd_stream_hnd_t hnd, snd_stream_callback_t cb)
	Reinitialize a stream. More...

void	snd_stream_destroy (snd_stream_hnd_t hnd)
	Destroy a stream. More...

void	snd_stream_queue_enable (snd_stream_hnd_t hnd)
	Enable queueing on a stream. More...

void	snd_stream_queue_disable (snd_stream_hnd_t hnd)
	Disable queueing on a stream. More...

void	snd_stream_queue_go (snd_stream_hnd_t hnd)
	Start a stream after queueing the request. More...

void	snd_stream_start (snd_stream_hnd_t hnd, uint32 freq, int st)
	Start a stream. More...

void	snd_stream_stop (snd_stream_hnd_t hnd)
	Stop a stream. More...

int	snd_stream_poll (snd_stream_hnd_t hnd)
	Poll a stream. More...

void	snd_stream_volume (snd_stream_hnd_t hnd, int vol)
	Set the volume on the stream. More...

Detailed Description

Sound streaming support.

This file contains declarations for doing streams of sound. This underlies pretty much any decoded sounds you might use, including the Ogg Vorbis libraries. Note that this does not actually handle decoding, so you'll have to worry about that yourself (or use something in kos-ports).

Author: Dan Potter

Macro Definition Documentation

#define SND_STREAM_BUFFER_MAX 0x10000

The maximum buffer size for a stream.

#define SND_STREAM_INVALID -1

Invalid stream handle.

If a stream cannot be allocated, this will be returned.

#define SND_STREAM_MAX 4

The maximum number of streams that can be allocated at once.

Typedef Documentation

typedef void*(* snd_stream_callback_t)(snd_stream_hnd_t hnd, int smp_req, int *smp_recv)

Stream get data callback type.

Functions for providing stream data will be of this type, and can be registered with snd_stream_set_callback().

Parameters

hnd	The stream handle being referred to.
smp_req	The number of samples requested.
smp_recv	Used to return the number of samples available.

Returns: A pointer to the buffer of samples. If stereo, the samples should be interleaved.

typedef void(* snd_stream_filter_t)(snd_stream_hnd_t hnd, void *obj, int hz, int channels, void **buffer, int *samplecnt)

Stream filter callback type.

Functions providing filters over the stream data will be of this type, and can be set with snd_stream_filter_add().

Parameters

hnd	The stream being referred to.
obj	Filter user data.
hz	The frequency of the sound data.
channels	The number of channels in the sound data.
buffer	A pointer to the buffer to process. This is before any stereo separation is done. Can be changed by the filter, if appropriate.
samplecnt	A pointer to the number of samples. This can be modified by the filter, if appropriate.

typedef int snd_stream_hnd_t

Stream handle type.

Each stream will be assigned a handle, which will be of this type. Further operations on the stream will use the handle to identify which stream is being referred to.

Function Documentation

snd_stream_hnd_t snd_stream_alloc	(	snd_stream_callback_t	cb,
		int	bufsize
	)

Allocate a stream.

This function allocates a stream and sets its parameters.

Parameters

cb	The get data callback for the stream.
bufsize	The size of the buffer for the stream.

Returns: A handle to the new stream on success, SND_STREAM_INVALID on failure.

void snd_stream_destroy ( snd_stream_hnd_t hnd )

Destroy a stream.

This function destroys a previously created stream, freeing all memory associated with it.

Parameters

hnd	The stream to clean up.

void snd_stream_filter_add	(	snd_stream_hnd_t	hnd,
		snd_stream_filter_t	filtfunc,
		void *	obj
	)

Add a filter to the specified stream.

This function adds a filter to the specified stream. The filter will be called on each block of data input to the stream from then forward.

Parameters

hnd	The stream to add the filter to.
filtfunc	A pointer to the filter function.
obj	Filter function user data.

void snd_stream_filter_remove	(	snd_stream_hnd_t	hnd,
		snd_stream_filter_t	filtfunc,
		void *	obj
	)

Remove a filter from the specified stream.

This function removes a filter that was previously added to the specified stream.

Parameters

hnd	The stream to remove the filter from.
filtfunc	A pointer to the filter function to remove.
obj	The filter function's user data. Must be the same as what was passed as obj to snd_stream_filter_add().

int snd_stream_init ( )

Initialize the stream system.

This function initializes the sound stream system and allocates memory for it as needed. Note, this is not done by the default init, so if you're using the streaming support and not using something like the kos-ports Ogg Vorbis library, you'll need to call this yourself. This will implicitly call snd_init(), so it will potentially overwrite anything going on the AICA.

Return values

-1	On failure.
0	On success.

int snd_stream_poll ( snd_stream_hnd_t hnd )

Poll a stream.

This function polls the specified stream to load more data if necessary. If using the streaming support, you must call this function periodically (most likely in a thread), or you won't get any sound output.

Parameters

hnd	The stream to poll.

Return values

-3	If NULL was returned from the callback.
-1	If no callback is set, or if the state has been corrupted.
0	On success.

void snd_stream_prefill ( snd_stream_hnd_t hnd )

Prefill the stream buffers.

This function prefills the stream buffers before starting it. This is implicitly called by snd_stream_start(), so there's probably no good reason to call this yourself.

Parameters

hnd	The stream to prefill buffers on.

void snd_stream_queue_disable ( snd_stream_hnd_t hnd )

Disable queueing on a stream.

This function disables queueing on the specified stream. This does not imply that a previously queued start on the stream will be fired if queueing was enabled before.

Parameters

hnd	The stream to disable queueing on.

void snd_stream_queue_enable ( snd_stream_hnd_t hnd )

Enable queueing on a stream.

This function enables queueing on the specified stream. This will make it so that you must call snd_stream_queue_go() to actually start the stream, after scheduling the start. This is useful for getting something ready but not firing it right away.

Parameters

hnd	The stream to enable queueing on.

void snd_stream_queue_go ( snd_stream_hnd_t hnd )

Start a stream after queueing the request.

This function makes the stream start once a start request has been queued, if queueing mode is enabled on the stream.

Parameters

hnd	The stream to start the queue on.

int snd_stream_reinit	(	snd_stream_hnd_t	hnd,
		snd_stream_callback_t	cb
	)

Reinitialize a stream.

This function reinitializes a stream, resetting its callback function.

Parameters

hnd	The stream handle to reinit.
cb	The new get data callback for the stream.

Returns: hnd

void snd_stream_set_callback	(	snd_stream_hnd_t	hnd,
		snd_stream_callback_t	cb
	)

Set the callback for a given stream.

This function sets the get data callback function for a given stream, overwriting any old callback that may have been in place.

Parameters

hnd	The stream handle for the callback.
cb	A pointer to the callback function.

void snd_stream_shutdown ( )

Shut down the stream system.

This function shuts down the stream system and frees the memory associated with it. This does not call snd_shutdown().

void snd_stream_start	(	snd_stream_hnd_t	hnd,
		uint32	freq,
		int	st
	)

Start a stream.

This function starts processing the given stream, prefilling the buffers as necessary. In queueing mode, this will not start playback.

Parameters

hnd	The stream to start.
freq	The frequency of the sound.
st	1 if the sound is stereo, 0 if mono.

void snd_stream_stop ( snd_stream_hnd_t hnd )

Stop a stream.

This function stops a stream, stopping any sound playing from it. This will happen immediately, regardless of whether queueing is enabled or not.

Parameters

hnd	The stream to stop.

void snd_stream_volume	(	snd_stream_hnd_t	hnd,
		int	vol
	)

Set the volume on the stream.

This function sets the volume of the specified stream.

Parameters

hnd	The stream to set volume on.
vol	The volume to set. Valid values are 0-255.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation